反射式模型加载：多 Provider 动态适配

反射式模型加载：多 Provider 动态适配

1. 概念定义

反射式模型加载是一种通过配置动态实例化 LLM Provider 的技术。与传统硬编码的模型选择不同，它允许用户通过配置文件指定任意的模型类路径，系统在运行时通过反射机制加载并实例化。

核心优势：

• 零代码改动支持新模型：新增模型只需配置，无需修改代码
• 统一接口：所有模型通过统一的 ChatModel 接口调用
• 特性适配：思考模式、视觉理解、reasoning effort 等特性通过配置开关

2. 配置驱动加载

典型的模型配置：

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    supports_thinking: false
    supports_vision: true

  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        chat_template_kwargs:
          enable_thinking: true

加载流程：

1. 解析 use 字段（module.path:ClassName 格式）
2. 通过反射加载模块和类
3. 验证类是否继承自预期的基类
4. 传入配置参数实例化

3. 特性开关

3.1 思考模式

思考模式（Extended Thinking / Reasoning）允许模型在回答前进行”思考”。不同模型的启用方式不同：

模型	思考启用方式
OpenAI o1/o3	supports_thinking: true
Qwen (vLLM)	when_thinking_enabled.extra_body.chat_template_kwargs.enable_thinking
Claude	supports_thinking: true + max_tokens 配置

3.2 视觉理解

模型通过 supports_vision: true 声明支持图片理解。Agent 框架据此注入 view_image 工具和图片数据。

3.3 Reasoning Effort

部分模型（如 GPT-5.x 系列）支持 reasoning_effort 参数，控制模型投入的思考深度。

4. vLLM 本地部署

vLLM 是一个高性能本地推理引擎，提供 OpenAI 兼容的 API。

4.1 vLLM Provider 的特殊处理

• 非标准 reasoning 字段：vLLM 在多轮工具调用对话中返回的 reasoning 字段需要保留和传递
• 思考开关的向后兼容：旧版配置使用 thinking 字段，新版使用 when_thinking_enabled，自动归一化
• 服务端解析器：Qwen 等模型可能需要服务端启动时指定 --reasoning-parser

5. 陷阱与规避

5.1 模块缺失错误

配置的模型类路径对应的模块未安装。

规避：缺失模块时提供可操作的安装提示（如 uv add langchain-google-genai）。

5.2 思考模式与工具调用的冲突

部分模型在思考模式下可能改变工具调用的行为。

规避：在系统提示中明确工具调用的期望格式，不依赖模型的默认行为。

参考来源

• LangChain Chat Models 文档
• vLLM 文档

补充：LangChain 的统一模型初始化协议

LangChain 提供了一种更为简洁的统一模型初始化方式 init_chat_model()，将 20+ 供应商的模型调用收敛到一行代码：

# 统一入口，自动推断 provider
model = init_chat_model("gpt-5.5")          # 自动识别为 openai
model = init_chat_model("claude-opus-4-7")  # 自动识别为 anthropic
model = init_chat_model("openai:gpt-5.5")   # 显式指定 provider

Provider 前缀推断机制：通过模型名称前缀映射到供应商（如 gpt- → openai、claude → anthropic、gemini → google_vertexai）。推断失败时提供明确的错误提示和安装建议。

延迟初始化模式：当不指定模型名称时，返回 _ConfigurableModel 对象，在实际调用时才根据 config["configurable"]["model"] 参数动态加载模型。这使得同一套 Agent 代码可以在运行时切换模型，无需重新实例化。

声明式操作排队：_ConfigurableModel 支持在模型未实例化时调用 bind_tools() 和 with_structured_output()，这些操作被记录在队列中，在实际模型加载时按顺序应用。