第 21 章 国产与开源大模型适配

21.1 模型层接口规范与通用接入模式

LangGraph 本身不绑定具体模型，所有 ChatModel 必须实现 LangChain 的 BaseChatModel（基础聊天模型）抽象类。该接口规定三类能力：其一，bind_tools(tools) 将工具 schema 绑定到模型，使模型在推理时返回 tool_calls；其二，with_structured_output(schema) 返回直接符合给定 JSON Schema/Pydantic 模型的结构化对象；其三，astream 提供异步流式输出，返回 AIMessageChunk 序列，支撑图的流式边和 Token 级事件推送。

版本基线为 LangGraph 1.2.x 搭配 langchain-core ≥ 0.3。不支持原生 tool_calls 的模型需走 prompt-based tool calling（基于提示词的工具调用）：将工具描述以 Function Calling 风格拼入 system prompt，要求模型输出固定 JSON，由自定义解析节点把文本转成 ToolMessage 喂回 ToolNode。该路径会显著降低工具调用准确率，仅作为兜底。

通用接入模式为 OpenAI 兼容协议。任何厂商只要暴露 /v1/chat/completions 端点，即可通过 langchain-openai 的 ChatOpenAI 直接接入：

# pip install langchain-openai langgraph
import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    api_key=os.getenv("PROVIDER_API_KEY"),
    base_url=os.getenv("PROVIDER_BASE_URL"),  # 例：https://api.deepseek.com/v1
    model=os.getenv("PROVIDER_MODEL"),
    temperature=0,
)

init_chat_model(model_provider, model, **kwargs) 是 langchain 提供的统一加载器，可根据字符串标识选择厂商实现，适合多模型路由场景。

21.2 主流国产模型接入实践

DeepSeek（深度求索） 提供 deepseek-chat（V3 通用对话）与 deepseek-reasoner（R1 推理模型）。接入可使用官方 SDK 集成 langchain-deepseek 的 ChatDeepSeek，也可通过 OpenAI 兼容端点 https://api.deepseek.com/v1。V3 支持并行 tool calling，tool_choice="auto" 行为与 OpenAI 一致；R1 由于采用长思维链推理，不支持工具调用，若把 R1 绑定到 ReAct Agent 将导致工具节点收不到 tool_calls 而报错。示例：

# pip install langchain-deepseek
from langchain_deepseek import ChatDeepSeek
llm_v3 = ChatDeepSeek(model="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY"))

通义千问（Qwen，阿里云） 模型矩阵包含 qwen-plus、qwen-max、qwen-turbo、qwen2.5-72b-instruct 等。接入方式有两种：langchain-community 的 ChatTongyi（走 DashScope 原生协议），或 DashScope 提供的 OpenAI 兼容端点 https://dashscope.aliyuncs.com/compatible-mode/v1。API Key 在阿里云 DashScope 控制台创建，环境变量名通常为 DASHSCOPE_API_KEY。示例：

# pip install langchain-community dashscope
from langchain_community.chat_models import ChatTongyi
llm_qwen = ChatTongyi(model="qwen-plus", dashscope_api_key=os.getenv("DASHSCOPE_API_KEY"))

智谱 GLM 提供 glm-4-flash、glm-4-plus、glm-4-long（长上下文 1M）。推荐使用 langchain-community 的 ChatZhipuAI，或通过智谱 OpenAI 兼容端点 https://open.bigmodel.cn/api/paas/v4。GLM-4 的工具调用返回字段与 OpenAI 对齐度较高，但并行工具数量建议限制在 3 个以内。

字节豆包（Doubao / 火山方舟） 通过火山方舟 OpenAI 兼容接口接入，关键差异在于 model 字段需填入方舟控制台创建的 Endpoint ID（接入点 ID，格式 ep-xxxxxxxx）而非通用模型名；base_url 为 https://ark.cn-beijing.volces.com/api/v3。

月之暗面 Kimi（Moonshot） 走 https://api.moonshot.cn/v1，支持 moonshot-v1-8k/32k/128k/256k（对应 kimi-k2 系列），长上下文场景适合做文档问答型 Agent。

百度文心（ERNIE / 千帆平台） 推荐使用千帆 OpenAI 兼容端点 https://qianfan.baidubce.com/v2，或 langchain-qianfan 的 ChatQianfan。千帆模型名以 ERNIE- 前缀为主，需在控制台先完成应用创建与模型授权。

21.3 本地开源模型与多模型路由

本地部署首选 Ollama。启动 ollama serve 后通过 ollama pull qwen2.5:7b 拉取模型；langchain-ollama 的 ChatOllama 直接对接 http://localhost:11434。支持原生 tool calling 的模型包括 qwen2.5 系列、llama3.1、mistral-nemo、firefunction-v2；不支持的模型仍可走 prompt-based 路径。本地模型的结构化输出对 temperature 敏感，建议设为 0 并配合 with_structured_output(method="json_mode")。ReAct Agent 完整示例：

# pip install langchain-ollama langgraph
from langchain_ollama import ChatOllama
from langgraph.prebuilt import create_react_agent
from langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    """查询指定城市天气"""
    return f"{city} 今日晴 23℃"

llm_local = ChatOllama(model="qwen2.5:7b", temperature=0)
agent = create_react_agent(llm_local, [get_weather])
print(agent.invoke({"messages": [("user", "北京天气如何？")]}))

Xinference / vLLM / LocalAI 均暴露 OpenAI 兼容端点，将 base_url 指向其 /v1 路径即可复用 ChatOpenAI，无需单独封装。

多模型路由推荐两种方式：其一，在图的 config schema 中声明 model_name 字段，节点内通过 init_chat_model() 或工厂字典动态实例化；其二，在编译图时通过 configurable_fields 将 llm 暴露为可配置项，调用方 invoke(..., config={"configurable":{"model":"qwen-plus"}}) 即切换。

不同模型工具调用差异如表所示：

维度	DeepSeek V3	Qwen Plus	GLM-4	Doubao(方舟)	Kimi	Ollama qwen2.5
并行工具	支持，建议 ≤5	支持	建议 ≤3	支持	支持	支持，≤4
tool_choice="required"	支持	支持	部分版本忽略	支持	不支持	不支持
JSON mode	支持	支持	支持	支持	支持	method=json_mode
流式 tool_calls	支持	支持	支持	支持	不支持	需升级到 0.3+
R1/推理模型 tool_calls	不支持	—	—	—	—	—

本章小结：模型层的合规接口是 BaseChatModel 的三件套能力；OpenAI 兼容端点是接入国产与本地模型最稳定的路径；各厂商在 tool calling 细节上存在差异，必须以兼容性表为准做适配。

常见错误：base_url 末尾 /v1 遗漏或多写导致 404；豆包场景误将模型名填成 doubao-pro 而非 Endpoint ID；把 R1 等推理模型绑定到 Agent 节点造成 tool_calls 为空；Ollama 服务未启动即调用出现连接拒绝；不同模型返回的 tool_calls schema（如参数是字符串还是对象）未做归一化导致 ToolNode 解析失败。

生产建议：上线前对候选模型做工具调用基准测试（准确率、并行稳定性、流式完整性）；主模型 + 备用模型 fallback 链；记录各厂商的 RPM/TPM 频控与计费阶梯，在 Semaphore 层做并发治理；本地模型需单独评估显存与首字延迟，避免与云端模型混用同一超时配置。