-
静态模型：在创建 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 的演进
核心差异一览表
|
|
|
|
|---|---|---|
|
|
model
|
wrap_model_call 标准化路由 |
|
|
prompt |
system_prompt/user_prompt |
|
|
config["configurable"] |
invoke/stream
context（静态上下文不计入 token） |
|
|
|
agent，模型流统一 model |
|
|
|
|
实现对比：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与速率限制器（如内存速率限制器）以平衡吞吐与稳定性。 -
中间件分层：将提示词裁剪、隐私脱敏、人工审核、错误处理等逻辑分别封装为中间件，便于复用与组合。 -
观测与回滚：对动态模型选择建立监控指标（成功率、时延、成本），出现异常时回退至静态模型或安全模型。
