LangChain 初始化模型的几种方法总结

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 → 需要调优或接入本地模型时切换到直接实例化 → 复杂场景用动态选择或自定义模型。