LangChain 作为大模型应用的开发框架，模型初始化是第一步。面对多种初始化方式，很多开发者会感到困惑：该选哪种？有什么区别？
本文按 API → 入参解释 → 示例 的结构，按使用频率从高到低逐一介绍每种方法，帮你快速选型。
1. create_react_agent（字符串简写）
API 签名
from langchain.chat_models import init_chat_model
def init_chat_model(
model: str,
model_provider: str | None = None,
**kwargs
) -> BaseChatModel
入参解释
| 参数 | 类型 | 必填 | 说明 |
|---|
model | str | 是 | 模型标识符，格式为 provider:model_name，如 "openai:gpt-4.1" |
model_provider | str | None | 否 | 当模型名有歧义时指定提供商，如 "bedrock_converse" |
**kwargs | dict | 否 | 传递给模型构造函数的额外参数，如 temperature、max_tokens 等 |
支持的模型标识符
openai:gpt-4.1
anthropic:claude-3-5-sonnet-latest
google_genai:gemini-2.0-flash
azure_openai:gpt-4.1
bedrock:anthropic.claude-3-5-sonnet-20240620-v1:0
示例
import os
from langchain.chat_models import init_chat_model
# 基础用法：一行代码搞定
os.environ["OPENAI_API_KEY"] = "sk-..."
llm = init_chat_model("openai:gpt-4.1")
# 指定参数
llm = init_chat_model("openai:gpt-4.1", temperature=0.7, max_tokens=2048)
# Azure OpenAI（需要额外配置）
os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..."
llm = init_chat_model(
"azure_openai:gpt-4.1",
azure_deployment="my-deployment"
)
# AWS Bedrock（需要指定 model_provider）
llm = init_chat_model(
"anthropic.claude-3-5-sonnet-20240620-v1:0",
model_provider="bedrock_converse"
)
适用场景
- 快速原型开发，不想纠结导入哪个类
- 需要统一管理多个模型的配置
- 初期开发阶段，后续可能需要切换模型提供商
2. init_chat_model
API 签名
from langchain_anthropic import ChatAnthropic
from langchain_openai import ChatOpenAI
class ChatAnthropic(BaseChatModel):
def __init__(
self,
model: str = "claude-2.1",
temperature: float = 0,
max_tokens: int | None = None,
max_retries: int = 5,
parent_run_id: str | None = None,
streaming: bool = False,
api_key: str | None = None,
base_url: str | None = None,
client: Any | None = None,
**kwargs: Any
) -> None:
class ChatOpenAI(BaseChatModel):
def __init__(
self,
model: str = "gpt-4o-mini",
temperature: float = 0,
max_tokens: int | None = None,
timeout: int | float | None = None,
max_retries: int = 2,
base_url: str | None = None,
api_key: str | None = None,
streaming: bool = False,
**kwargs: Any
) -> None:
入参解释（通用参数）
| 参数 | 类型 | 必填 | 说明 |
|---|
model | str | 否 | 模型名称，默认使用厂商默认模型 |
temperature | float | 否 | 采样温度，0~1，越高越随机 |
max_tokens | int | 否 | 最大输出 token 数 |
max_retries | int | 否 | 请求失败最大重试次数 |
streaming | bool | 否 | 是否启用流式输出 |
api_key | str | 否 | API 密钥，不传则从环境变量读取 |
base_url | str | 否 | 自定义 API 端点 URL |
timeout | int | float | 否 | 请求超时时间（秒，仅 OpenAI） |
示例
from langchain_anthropic import ChatAnthropic
from langchain_openai import ChatOpenAI
# Anthropic：精细控制推理行为
claude = ChatAnthropic(
model="claude-3-7-sonnet-latest",
temperature=0, # 确定性输出
max_tokens=2048, # 限制输出长度
top_p=0.9, # 核采样参数
)
# OpenAI：完整控制请求参数
gpt = ChatOpenAI(
model="gpt-4o",
temperature=0.7, # 创造性输出
max_tokens=4096,
timeout=30, # 30 秒超时
max_retries=3, # 失败重试 3 次
base_url="https://your-proxy.com/v1", # 自定义代理
)
# 使用自定义 API Key（不依赖环境变量）
llm = ChatOpenAI(
model="gpt-4o",
api_key="sk-your-key-here"
)
# 兼容 OpenAI API 的第三方服务（本地模型）
# Ollama / LM Studio / vLLM / LocalAI 等服务，只需改 base_url
llm = ChatOpenAI(
model="llama-3.1",
base_url="http://localhost:11434/v1", # Ollama
api_key="not-needed"
)
llm = ChatOpenAI(
model="gpt-4o",
base_url="http://localhost:8000/v1", # vLLM / LM Studio
api_key="fake-key"
)
适用场景
- 需要完全控制模型底层参数
- 使用特定厂商的高级功能
init_chat_model 尚未支持的模型- 本地部署的模型服务（Ollama、LM Studio、vLLM 等）
- 生产环境调优，需要精确控制推理行为
3. ChatAnthropic / ChatOpenAI（直接实例化）
API 签名
from langgraph.prebuilt import create_react_agent
def create_react_agent(
app_state: Any,
model: str | BaseChatModel, # ← 支持字符串或模型实例
tools: list[Callable] | None = None,
**kwargs
) -> Agent
入参解释
| 参数 | 类型 | 必填 | 说明 |
|---|
app_state | Any | 是 | 智能体的状态管理对象（通常传配置字典） |
model | str | BaseChatModel | 是 | 模型名称字符串（如 "openai:gpt-4o"）或已实例化的模型对象 |
tools | list[Callable] | 否 | 智能体可用的工具列表 |
**kwargs | dict | 否 | 其他智能体配置参数 |
示例
from langgraph.prebuilt import create_react_agent
from langchain_core.tools import tool
@tool
def get_weather(city: str) -> str:
"""获取指定城市的天气"""
return f"{city} 晴，25°C"
# 方式一：直接传字符串（最简写法，推荐）
agent = create_react_agent(
state=None,
model="anthropic:claude-3-7-sonnet-latest",
tools=[get_weather]
)
# 方式二：显式实例化后传入（等价，代码更多）
from langchain_anthropic import ChatAnthropic
model = ChatAnthropic(model="claude-3-7-sonnet-latest")
agent = create_react_agent(
state=None,
model=model,
tools=[get_weather]
)
# 调用智能体
result = agent.invoke({"messages": [{"role": "user", "content": "北京天气怎么样？"}]})
print(result["messages"][-1].content)
适用场景
- 构建标准 ReAct 或对话型智能体
- 快速搭建 Agent，不想写多余代码
- 调试阶段快速迭代
4. 动态模型选择函数
API 签名
from typing import Callable
from langgraph.prebuilt import create_react_agent
from langgraph.prebuilt.chat_agent_executor import AgentState
from langgraph.runtime import Runtime
from langchain_core.language_models import BaseChatModel
# 选择函数签名
ModelSelector = Callable[[AgentState, Runtime], BaseChatModel]
def create_react_agent(
app_state: Any,
model: ModelSelector | BaseChatModel | str, # ← 可以传入函数
tools: list[Callable] | None = None,
**kwargs
) -> Agent
入参解释
| 参数 | 类型 | 必填 | 说明 |
|---|
ModelSelector | Callable | 是 | 接收 (AgentState, Runtime)，返回 BaseChatModel 的函数 |
AgentState | dict | - | 当前智能体的状态（包含消息历史等） |
Runtime | Runtime | - | 运行时上下文（包含自定义上下文数据） |
model | ModelSelector | 是 | 传入选择函数，而非具体模型 |
示例
from dataclasses import dataclass
from typing import Literal
from langchain.chat_models import init_chat_model
from langchain_core.language_models import BaseChatModel
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from langgraph.prebuilt.chat_agent_executor import AgentState
from langgraph.runtime import Runtime
# 定义工具
@tool
def weather() -> str:
"""获取天气"""
return "晴，25°C"
# 定义运行时上下文
@dataclass
class CustomContext:
provider: Literal["anthropic", "openai"]
tier: Literal["free", "paid"]
# 预初始化模型（避免每次请求都创建）
openai_free = init_chat_model("openai:gpt-4o-mini")
openai_paid = init_chat_model("openai:gpt-4.1")
anthropic_paid = init_chat_model("anthropic:claude-3-7-sonnet-latest")
# 定义选择逻辑
def select_model(state: AgentState, runtime: Runtime[CustomContext]) -> BaseChatModel:
"""根据运行时上下文动态选择模型"""
provider = runtime.context.provider
tier = runtime.context.tier
if provider == "openai":
# 免费用户用小模型，付费用户用大模型
model = openai_free if tier == "free" else openai_paid
elif provider == "anthropic":
model = anthropic_paid
else:
raise ValueError(f"不支持的提供商: {provider}")
# 重要：动态选择时必须手动绑定工具
return model.bind_tools([weather])
# 创建智能体
agent = create_react_agent(
state=None,
model=select_model, # ← 传入函数
tools=[weather]
)
# 运行时指定使用哪个模型
result = agent.invoke(
{"messages": [{"role": "user", "content": "今天天气如何？"}]},
context=CustomContext(provider="openai", tier="paid")
)
适用场景
- 多租户 SaaS 平台，不同用户用不同模型
- 根据订阅等级路由（免费用户用小模型，付费用户用旗舰模型）
- A/B 测试不同模型的效果
- 根据任务复杂度动态选择
- 合规要求（某些数据必须用特定区域的模型）
5. 自定义模型类（Bring Your Own Model）
API 签名
from langchain_core.language_models import BaseChatModel
from langchain_core.messages import AIMessage
from langchain_core.callbacks import CallbackManagerForLLMRun
from typing import Any, List, Optional
class CustomModel(BaseChatModel):
def __init__(
self,
custom_param: str = "default",
api_key: str | None = None,
**kwargs: Any
) -> None:
super().__init__(**kwargs)
self.custom_param = custom_param
def _call(
self,
messages: List,
stop: Optional[List[str]] = None,
run_manager: Optional[CallbackManagerForLLMRun] = None,
**kwargs: Any
) -> str:
"""实现核心推理逻辑"""
# 调用你的自定义模型 API
response = self._call_your_api(messages)
return response
def _llm_type(self) -> str:
"""返回模型类型名称"""
return "custom_model"
入参解释
| 方法/参数 | 类型 | 必填 | 说明 |
|---|
__init__ | method | 是 | 初始化自定义参数，如 custom_param、api_key |
_call | method | 是 | 核心推理方法，接收消息列表，返回字符串响应 |
messages | List | 是 | 输入的消息列表（包含 user/assistant/system 角色） |
stop | Optional[List[str]] | 否 | 停止词列表 |
run_manager | Optional[CallbackManagerForLLMRun] | 否 | 回调管理器，用于追踪和日志 |
_llm_type | method | 是 | 返回模型类型名称，用于调试和日志 |
示例
from langchain_core.language_models import BaseChatModel
from langchain_core.messages import AIMessage
from langchain_core.callbacks import CallbackManagerForLLMRun
from typing import Any, List, Optional
import requests
class MyCustomModel(BaseChatModel):
"""自定义模型：调用私有 API"""
def __init__(
self,
api_url: str,
api_key: str,
timeout: int = 30,
**kwargs: Any
) -> None:
super().__init__(**kwargs)
self.api_url = api_url
self.api_key = api_key
self.timeout = timeout
def _call(
self,
messages: List,
stop: Optional[List[str]] = None,
run_manager: Optional[CallbackManagerForLLMRun] = None,
**kwargs: Any
) -> str:
# 构造请求
payload = {
"messages": messages,
"timeout": self.timeout
}
headers = {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json"
}
# 调用私有 API
response = requests.post(
self.api_url,
json=payload,
headers=headers,
timeout=self.timeout
)
response.raise_for_status()
return response.json()["content"]
def _llm_type(self) -> str:
return "my_custom_model"
# 使用自定义模型
custom_llm = MyCustomModel(
api_url="https://internal-api.company.com/chat",
api_key="your-api-key"
)
# 与 LangChain 其他组件无缝集成
from langchain_core.prompts import ChatPromptTemplate
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个助手"),
("user", "{question}")
])
chain = prompt | custom_llm
result = chain.invoke({"question": "你好"})
print(result)
适用场景
- 企业内部私有化部署的模型
- 新兴厂商模型，LangChain 尚未支持
- 具有特殊推理逻辑或安全策略的定制模型
高级配置：通用选项
无论使用哪种初始化方式，都可以结合以下配置优化性能与稳定性。
禁用流式传输
llm = init_chat_model("openai:gpt-4.1", disable_streaming=True)
| 参数 | 类型 | 说明 |
|---|
disable_streaming | bool | 设为 True 禁用流式输出，适用于需要一次性获取完整响应的场景 |
添加模型回退
from langchain.chat_models import init_chat_model
# 主模型 + 备用模型
primary = init_chat_model("openai:gpt-4.1")
fallback = init_chat_model("openai:gpt-4o")
# 创建带回退的模型
robust_llm = primary.with_fallbacks([fallback])
# 当主模型失败时自动降级
result = robust_llm.invoke("你好")
内置速率限制器
from langchain.chat_models import init_chat_model
from langchain_core.rate_limiters import InMemoryRateLimiter
# 配置速率限制器
rate_limiter = InMemoryRateLimiter(
requests_per_second=0.1, # 每秒最多 0.1 个请求
max_queue_size=100 # 最大排队大小
)
llm = init_chat_model(
"openai:gpt-4.1",
rate_limiter=rate_limiter
)
| 参数 | 类型 | 必填 | 说明 |
|---|
requests_per_second | float | 是 | 每秒最大请求数 |
max_queue_size | int | 否 | 请求排队最大大小 |
总结：选型决策树
需要搭建 Agent？
├─ 是 → create_react_agent 字符串简写（最常用）
└─ 否 → 需要快速原型？
├─ 是 → init_chat_model（一行代码）
└─ 否 → 需要精确控制或本地模型？
├─ 是 → 直接实例化（ChatAnthropic / ChatOpenAI）
└─ 否 → 需要运行时切换模型？
├─ 是 → 动态选择函数
└─ 否 → 私有模型？
├─ 是 → 自定义模型类
└─ 否 → init_chat_model
| 方法 | 复杂度 | 灵活性 | 使用频率 | 推荐场景 |
|---|
create_react_agent 字符串简写 | ⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | 标准 Agent 快速搭建 |
init_chat_model | ⭐ | ⭐⭐ | ⭐⭐⭐⭐ | 快速开发、多模型统一管理 |
| 直接实例化 | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | 生产环境调优、特殊参数需求、本地模型 |
| 动态选择函数 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | 多租户、A/B 测试、业务路由 |
| 自带模型 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐ | 私有化部署、未支持的厂商 |
推荐路径： 搭建 Agent 先用字符串简写快速跑通 → 需要统一管理用 init_chat_model → 需要调优或接入本地模型时切换到直接实例化 → 复杂场景用动态选择或自定义模型。
