LangChain v1 重大更新讲解⚠⚠⚠

LangChain v1 重大更新讲解

为什么没有先发布demo教学而是先发布一个什么重大更新

因为langchain更新了，更新还挺多的所以建议大家还是从新版本开始学习

作者：吴佳浩

最后更新：2025-11-22

适用版本：LangChain v1.0+

目录

• 📌 一、LangChain v1 为什么是一次"大版本革命"？
• 🚀 二、v0.1 → v1.0：差异对照表（核心必读）
• 🧱 三、LangChain v1 架构总览
• 🧰 四、create_agent：全新的 Agent 创建方式
• 🔧 五、Middleware：核心扩展机制（洋葱模型）
• 📦 六、content_blocks：跨模型统一输出
• 📐 七、结构化输出（Structured Output）
• 📚 八、命名空间重构 + langchain-classic
• 🛠 九、v0 → v1 迁移指南（实战版）
• 🏗 十、推荐的生产级项目结构图
• 🧪 十一、真实企业级案例：多步骤任务 Agent
• 📄 十二、可运行综合示例代码
• 📍 十三、总结

---

0. 环境准备

在开始之前，请确保 Python 版本 ≥ 3.9，并安装以下核心包：

# 安装 v1 核心包、经典兼容包和图运行时
pip install -U langchain langchain-classic langgraph

# 安装适配的模型提供商包 (以 OpenAI 为例)
pip install -U langchain-openai

---

一、LangChain v1 为什么是一次"大版本革命"？

LangChain v1 不再仅仅是一个"LLM 调用工具箱"，而是正式转向构建生产级 Agent 系统的工程框架。

核心变化包括：

1. create_agent：正式成为 Agent 的标准构建方式（底层基于 LangGraph）。
2. Middleware (中间件)：允许在任意阶段（模型调用前、工具执行时、输出后）拦截并修改逻辑。
3. content_blocks：所有模型输出（推理/文本/工具调用）统一为标准格式，不再依赖正则解析。
4. 结构化输出：Pydantic Schema 成为一等公民，极大提升稳定性。
5. 命名空间拆分 ：旧 API（如 Chains）全部迁入 langchain-classic，主包只保留 Agent 核心。

---

二、v0.1 → v1.0：差异对照表（核心必读）

这是理解 v1 最重要的一张表，展示了从"脚本思维"到"工程思维"的转变。

项目	LangChain v0.x (旧版)	LangChain v1.0 (新版)	核心差异
中心思想	Chains (链式调用)	Agents (智能体)	从线性执行转向循环图执行 (Graph)
构建入口	initialize_agent	create_agent	统一的新标准接口
底层引擎	AgentExecutor (硬编码循环)	LangGraph	支持持久化、流式、分支、循环的图运行时
流式能力	部分支持 (Token级)	全链路流式	支持 Token、中间步骤、推理过程的实时流
扩展机制	无 (需修改源码或Prompt)	Middleware	完整的生命周期钩子 (Hooks)
工具定义	Tool + func	Tool + Pydantic Schema	类型更安全，参数定义更清晰
结构化输出	JSON Parser + Regex	Structured Output	直接绑定 Pydantic 类，由模型底层保证格式
输出解析	纯文本 + 正则匹配	content_blocks	标准化对象 (推理块、文本块、工具块)
包管理	langchain.*	langchain-classic	旧功能移至 classic 包，保持主包轻量

---

三、LangChain v1 架构总览

💡 核心提示 ：LangChain v1 的底层引擎实际上是 LangGraph 。create_agent 本质上是为你预构建了一个标准的 LangGraph 图。

flowchart TD subgraph AgentRuntime ["LangGraph 运行时"] direction TB A["用户输入 (Messages)"] --> B[" 模型推理 (LLM)"] B --> C{"决策节点"} C -->|需要工具| D[" 工具执行 (Tool Execution)"] D --> E[" 工具结果反馈"] E --> B C -->|无需工具/结束| F[" 生成最终回答"] end style A fill:#e1f5fe,stroke:#01579b style B fill:#fff9c4,stroke:#fbc02d style D fill:#e8f5e9,stroke:#2e7d32

---

四、create_agent：全新的 Agent 创建方式

为什么废弃 initialize_agent？

因为 v1 统一使用图架构（Graph Architecture）。所有的 Agent 本质上都是：推理 → 工具 → 再推理 的循环。create_agent 是这个标准循环的工厂函数。

基本用法：

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

# 1. 定义模型
model = ChatOpenAI(model="gpt-4o")

# 2. 创建 Agent
agent = create_agent(
    model=model,
    tools=[search_tool, calculator_tool],
    system_prompt="你是一个乐于助人的金融分析师。"
)

# 3. 运行 (Invoke)
result = agent.invoke({"messages": [{"role": "user", "content": "分析 AAPL 股价"}]})

---

五、Middleware：核心扩展机制（洋葱模型）

中间件是 v1 最强大的功能，允许你在 Agent 生命周期的任意节点插入逻辑（如鉴权、日志、路由）。

生命周期时序图：

sequenceDiagram participant User participant MW as Middleware (中间件层) participant Agent as Agent Runtime participant Model as LLM User->>Agent: invoke(input) Agent->>MW: 1. before_agent_start MW-->>Agent: (清洗后的输入) loop 思考与执行循环 Agent->>MW: 2. before_model Note right of MW: 动态修改 Prompt / 路由模型 rect rgb(240,240,240) MW->>Model: 3. wrap_model_call Model-->>MW: 返回原始结果 end MW-->>Agent: 4. after_model (校验输出) opt 工具调用 Agent->>MW: 5. wrap_tool_call Note right of MW: 敏感操作审批 / 审计 MW-->>Agent: 工具结果 end end Agent->>MW: 6. after_agent MW-->>User: 最终响应

---

六、content_blocks：跨模型统一输出

解决"不同模型返回格式不同"的痛点。

模型输出现在包含统一的 .content_blocks 属性：

• reasoning: 模型的思考过程（如 Chain of Thought）。
• tool_call: 结构化的工具调用请求。
• text: 最终回复文本。

---

七、结构化输出（Structured Output）

v1 推荐使用 Pydantic Schema 来强制模型输出特定格式，而不是在 Prompt 里写"请返回 JSON"。

三种策略：

1. SchemaBasedStructurer (推荐)：直接传入 Pydantic 类。
2. ToolStrategy：利用 Tool Calling 机制输出结构。
3. ProviderStrategy：利用模型原生 JSON Mode（如 OpenAI JSON Object）。

---

八、命名空间重构 + langchain-classic

为了给 Agent 让路，旧的"链式"组件被移入 classic 包。

迁移对照：

组件	旧引入方式	v1 新引入方式
Memory	from langchain.memory import ...	from langchain_classic.memory import ...
Chains	from langchain.chains import ...	from langchain_classic.chains import ...
Retrievers	from langchain.retrievers import ...	from langchain_classic.retrievers import ...

---

🛠 九、v0 → v1 迁移指南（实战版）

1. ConversationChain → create_agent

• ❌ 旧 (v0)：

  from langchain.chains import ConversationChain
  chain = ConversationChain(llm=llm)
  chain.run("Hi")

• ✔ 新 (v1)：

  from langchain.agents import create_agent
  # create_agent 自带记忆管理 (通过 LangGraph checkpoint)
  agent = create_agent(model=llm, tools=[])
  agent.invoke({"messages": [...]})

2. LLMChain → model.invoke

• ❌ 旧 (v0)：

  chain = LLMChain(prompt=prompt, llm=llm)
  chain.run(variable="value")

• ✔ 新 (v1)：

  # 直接使用 LCEL (LangChain Expression Language)
  chain = prompt | llm
  chain.invoke({"variable": "value"})

3. Tool 定义方式

• ❌ 旧 (v0) ：依赖 func 和文档字符串解析。
• ✔ 新 (v1) ：强烈建议使用 @tool 装饰器并配合 Pydantic 类型的参数注解，或者使用 create_tool(schema=MySchema)。

---

十、推荐的生产级项目结构图

在 v1 时代，推荐采用分层架构来管理 Agent 项目：

graph TD Root[" my_agent_project/"] --> A[" app/"] A --> B[" agent.py
(create_agent 组装入口)"] A --> C["middleware/
(中间件层)"] C --> C1[" auth_middleware.py"] C --> C2[" risk_control.py"] A --> D[" schemas/
(数据结构)"] D --> D1[" user_context.py"] D --> D2[" output_schema.py"] A --> E[" tools/
(工具集)"] E --> E1[" search_tool.py"] E --> E2[" db_tool.py"] A --> F[" main.py
(FastAPI/Streamlit 入口)"]

---

十一、真实企业级案例：多步骤任务 Agent

场景：自动代码修复 Agent。

流程：写代码 → 运行测试 → 失败则分析日志 → 修复代码 → 循环直至成功。

flowchart TD Start(("开始")) --> Gen["生成初版代码"] Gen --> Run["🔧 工具: 运行代码/测试"] Run --> Check{"测试通过?"} Check -->|失败| Debug[" LLM: 分析错误日志"] Debug --> Gen Check -->|成功| Output["输出最终代码"] Output --> End(("结束"))

这在 v1 中通过 create_agent 天然支持，因为底层 Graph 支持循环，且可以通过中间件记录每次尝试的详细日志。

---

十二、可运行综合示例代码

这是一个包含了 中间件 (Middleware) 和 结构化输出 的完整 v1 示例。

import asyncio
from typing import Any, Dict
from pydantic import BaseModel, Field

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain.tools import tool
from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse

# 1. 定义工具
@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    # 模拟 API 返回
    return f"{city} 天气晴朗, 25°C"

# 2. 定义结构化输出 Schema
class WeatherReport(BaseModel):
    city: str = Field(description="城市名称")
    temperature: float = Field(description="温度数值")
    summary: str = Field(description="一句话天气总结")

# 3. 定义自定义中间件 (示例：自动添加礼貌用语)
class PolitenessMiddleware(AgentMiddleware):
    def wrap_model_call(self, request: ModelRequest, handler) -> ModelResponse:
        # 在发送给模型前，修改 System Prompt
        print("🕵️ Middleware: 正在注入礼貌指令...")
        if request.messages:
            last_msg = request.messages[-1]
            if last_msg.role == "user":
                last_msg.content += " (请用非常礼貌的语气回答)"
        return handler(request)

# 4. 构建 Agent
async def main():
    agent = create_agent(
        model=ChatOpenAI(model="gpt-4o-mini"),
        tools=[get_weather],
        middleware=[PolitenessMiddleware()],
        # 强制结构化输出 (v1 特性)
        # response_format=ToolStrategy(WeatherReport) # 若需强制结构化可开启此行
    )

    print("🚀 Agent 启动...")
    result = await agent.ainvoke({
        "messages": [{"role": "user", "content": "帮我查一下北京的天气"}]
    })

    # v1 的 result 包含完整的执行状态
    print("\n💬 最终回复:")
    print(result["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

---

十三、总结

LangChain v1 标志着我们从 "玩票性质的 Chain" 走向了 "工程化的 Agent"。

• 如果你需要构建简单的问答机器人，LangChain v1 提供了更统一的接口。
• 如果你需要构建复杂的、多步推理的、具有自我纠错能力的企业级智能体，LangChain v1 (配合 LangGraph) 是目前 Python 生态中最佳的选择。

下一步建议： 安装 langchain-classic 确保旧代码运行，同时在新模块中开始尝试使用 create_agent。 慎重更新老项目。。。。。。崩了。。。别赖我。。