LangChain v1.0 模型选型：静态还是动态？一文看懂 Agent 的正确打开方式

• 静态模型：在创建 Agent 或独立调用时一次性指定模型，执行期间不变。
• 动态模型：在运行时依据上下文与状态选择最合适的模型，通过中间件（middleware）实现。
• 统一的模型初始化与消息表示：
• 提供统一的模型初始化入口（如 init_chat_model 与 create_agent），便于跨提供商切换。
• 标准化消息内容块（content_blocks）统一表示推理、工具调用、多模态输出等高级特性，降低跨提供商差异带来的复杂度。

核心优势：为什么选择 LangChain v1.0 的模型架构？

• 统一初始化与接口一致性：
• create_agent 成为 v1.0 推荐的建 Agent 方式；模型既可用字符串（ provider + model 标识），也可用具体模型实例，接口更简洁。
• init_chat_model 提供标准化初始化与参数传递（如 temperature、timeout、max_tokens、max_retries），提升跨提供商一致性。
• 动态模型选择提升灵活性：
• 可在同一条业务链路中按需切换模型，实现成本优化、能力路由与降级策略。
• 标准消息内容块带来跨提供商一致体验：
• 在 v1.0 中引入的 content_blocks 标准化表示推理、工具调用、多模态数据与引用，统一解析不同提供商的原生响应。
• 代理（Agent）开发体验更可扩展：
• 通过中间件开放 before_model/after_model/wrap_model_call/wrap_tool_call 等钩子，动态提示词、状态管理、人工审核与错误处理更自然。
• 解决跨提供商差异与接口碎片化：
• v1.0 通过统一初始化与标准消息内容块，降低了在 OpenAI、Anthropic 等不同提供商之间切换的心智负担。
• 解决 Agent 组合能力的可扩展性问题：
• 旧式 pre/post hooks 被中间件替代，更易复用与组合，适合复杂的上下文工程实践（摘要、审查、脱敏等）。
• 解决模型选择的刚性问题：
• 过去常在一次 Agent 生命周期内固定模型；现在可在运行时根据状态选择模型，提升成本/能力权衡的灵活度。

核心概念与基础实现

静态模型（Static Model）：固定与高效

• 定义：在创建 Agent 时或直接调用模型时，固定选择一个模型实例或模型名称，整个执行过程中保持不变。
• 典型使用：
• 快速建 Agent：create_agent("gpt-4o", tools) 或传入模型实例。
• 独立调用：使用 init_chat_model 初始化模型后直接 invoke/stream/batch。

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

# 方式一：用模型名称（字符串）
agent = create_agent(
    "gpt-4o",  # 具体模型标识，按你的提供商可替换
    tools=[]
)

# 方式二：用模型实例（更细粒度参数控制）
model = ChatOpenAI(
    model="gpt-4o",
    temperature=0.1,
    max_tokens=1000,
    timeout=30,
)
agent = create_agent(model, tools=[])

动态模型（Dynamic Model）：灵活与智能

• 定义：在运行时根据会话状态（如消息数量、任务复杂度等）选择不同模型，常见于成本、能力与稳定性的动态权衡。
• 实现方式：通过中间件，在模型调用前拦截并替换请求中的模型（wrap_model_call）。

from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse

basic_model = ChatOpenAI(model="gpt-4o-mini")
advanced_model = ChatOpenAI(model="gpt-4o")

@wrap_model_call
def dynamic_model_selection(request: ModelRequest, handler) -> ModelResponse:
    # 示例逻辑：依据消息条数切换模型
    message_count = len(request.state["messages"]) if"messages"in request.state else0
    request.model = advanced_model if message_count > 10else basic_model
    return handler(request)

agent = create_agent(
    model=basic_model,  # 默认模型
    tools=[],
    middleware=[dynamic_model_selection]
)

在 dynamic_model_selection 示例中，我们通过 request.state["messages"] 获取了会话历史。这里的 request.state 是一个关键概念，它通常由上层的执行器（如 LangGraph）在图的流转过程中负责填充和传递。state 本质上是一个字典，包含了当前执行步骤的所有上下文信息，例如历史消息、中间步骤的输出等。中间件正是通过访问这个 state，才能实现依赖于当前对话状态的复杂逻辑。

中间件（Middleware）：Agent 的“插件”系统

中间件是 LangChain v1.0 架构的核心，它允许在模型或工具调用前后注入自定义逻辑，实现了类似 AOP（面向切面编程）的强大功能。

中间件不仅限于模型选择，还可以用于实现横切关注点（Cross-Cutting Concerns），如日志记录、监控或请求修改。以下是一个简单的日志记录中间件，它会在模型调用前后打印信息。

import logging
from langchain.agents.middleware import before_model, after_model

logging.basicConfig(level=logging.INFO)

@before_model
def log_before_model_call(request: ModelRequest):
    logging.info(f"即将调用模型: {request.model.model}")
    return request

@after_model
def log_after_model_call(: ModelResponse):
    logging.info(f"模型调用完成。")
    return response

# 在创建 Agent 时加入这些中间件
agent_with_logging = create_agent(
    model=basic_model,
    tools=[],
    middleware=[
        dynamic_model_selection,
        log_before_model_call,
        log_after_model_call
    ]
)

统一的模型接口：init_chat_model

除了在 Agent 中使用模型，LangChain v1.0 也提供了统一的独立模型调用接口，方便进行简单的、非代理式的调用。

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "gpt-4o",  # 具体模型名称视提供商而定
    temperature=0.7,
    timeout=30,
    max_tokens=1000,
)

# 单次调用
response = model.invoke("Why do parrots have colorful feathers?")
print(response)

# 内容块（content_blocks）可用于查看更细粒度结构（如工具调用、多模态引用）
try:
    print(getattr(response, "content_blocks", None))
 Exception:
    pass

# 流式
for chunk in model.stream("Explain photosynthesis in one paragraph."):
    print(chunk)

版本对比：从 v0.x 到 v1.0 的演进

核心差异一览表

实现对比：create_react_agent vs create_agent

旧版主要依赖 langgraph.prebuilt.create_react_agent，其动态模型选择和上下文注入方式与 v1.0 有明显不同。

# 旧版示例：create_react_agent（来自 langgraph.prebuilt）
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

basic_model = ChatOpenAI(model="gpt-4o-mini")
advanced_model = ChatOpenAI(model="gpt-4o")

def select_model(state):
    """依据会话状态选择模型：消息较多走更强模型。"""
    count = len(state.get("messages", []))
    return advanced_model if count > 10else basic_model

agent = create_react_agent(
    model=select_model,            # 旧版：model 支持 callable 实现动态选择
    tools=[],
    prompt="You are a helpful assistant."# 旧版：静态提示参数名为 prompt
)

# 运行时上下文注入（旧式）：使用 config["configurable"]
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Hello"}]},
    config={"configurable": {"tenant": "demo", "user_id": "u-001"}}
)
print(result)

可视化流程对比

旧版（create_react_agent）动态模型选择

v1.0（create_agent + middleware）动态模型选择

结构化输出与 pre-bound 限制（v1.0）

迁移要点总结

• 动态模型实现:
• 旧版: 通过为 model 参数提供一个可调用对象（callable）实现。
• v1.0: 通过 middleware 中的 wrap_model_call 钩子实现，更标准化、可组合。
• 静态提示词:
• 旧版: 使用 prompt 参数。
• v1.0: 更名为 system_prompt，并推荐通过中间件管理动态提示。
• 上下文注入:
• 旧版: 依赖 config["configurable"] 字典。
• v1.0: 统一使用 invoke 或 stream 方法的 context 参数，实现标准化的依赖注入。

进阶实践与策略

典型应用场景与策略

• 成本/能力路由：短对话走基础模型，长对话或复杂任务走高能力模型。
• 稳定性与降级：遇到速率限制或暂时性故障时，自动切换到备选模型以保障 SLA（可在中间件中实现）。
• 多模态任务：当输入包含图像/音频等内容时，路由至支持多模态的模型；输出可通过 content_blocks 统一处理。
• 风险管控与人工审核：对敏感工具调用启用 human-in-the-loop 中间件，必要时切换至更保守模型。
• 实验与 A/B：在中间件中按会话或用户标签切换模型，进行对比评估与灰度发布。

优雅处理错误：工具与中间件的协作

中间件不仅可以作用于模型，也可以包装工具调用，实现统一的错误处理、日志记录或权限校验。

from langchain_openai import ChatOpenAI
from langchain.tools import tool
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_tool_call

@tool
def add(a: int, b: int) -> int:
    """Return a + b."""
    return a + b

@wrap_tool_call
def handle_tool_errors(request, handler):
    # 捕获工具调用异常并返回可用消息，避免整条链崩溃
    try:
        return handler(request)
    except Exception as e:
        from langchain_core.messages import ToolMessage
        return ToolMessage(content=f"Tool error: {e}", tool_call_id=request.tool_call.get("id", "unknown"))

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o-mini"),
    tools=[add],
    middleware=[handle_tool_errors],
)

print(agent.invoke({"messages": [{"role": "user", "content": "调用加法工具，计算 12 与 30 的和。"}]}))

上下文注入（Context Injection）的最佳实践

在 v1.0 中，可直接通过 context 传递非提示的静态上下文（不计入 token），常用于租户、用户画像或灰度标识。

ctx = {"tenant": "demo", "user_id": "u-001", "ab": "bucket-a"}
result = agent.invoke({"messages": [{"role": "user", "content": "生成 1 段问候语。"}]}, context=ctx)
print(result)

生产环境落地建议

• 参数与速率控制：结合 max_retries 与速率限制器（如内存速率限制器）以平衡吞吐与稳定性。
• 中间件分层：将提示词裁剪、隐私脱敏、人工审核、错误处理等逻辑分别封装为中间件，便于复用与组合。
• 观测与回滚：对动态模型选择建立监控指标（成功率、时延、成本），出现异常时回退至静态模型或安全模型。