RAG 与 LangChain on 扎塔-Zata

LangChain 常见报错与排查指南

Tue, 08 Sep 2026 13:30:00 +0800

LangChain 常见报错与排查指南

LangChain 应用报错时，最浪费时间的不是修，而是不知道问题出在哪一层。密钥、模型、提示、解析、编排——每一层的症状可能长得一样（都是「输出不对」），但修法完全不同。

最有效的第一步：先看模型的原始输出。把解析器临时换成 StrOutputParser（或直接 print 响应对象），原始输出正常，问题在解析层；原始输出本身就不对，问题在配置、提示或模型。这一步能省掉大半瞎猜时间。

先定位：问题出在哪一层

层	典型症状	排查手段
配置层	AuthenticationError、模型不存在	检查环境变量；用 curl 直接调平台 API 验证密钥
模型层	输出质量差、不按指令来	换 StrOutputParser 看原始输出；换模型对比
解析层	OutputParserException	确认原始输出没问题后，再调格式指令
编排层	Agent 死循环、链路数据对不上	`verbose=True`、LangSmith 追踪、astream_events

七类高频报错

1. API 密钥错误（AuthenticationError）

症状：提示 API 密钥无效、缺失或未设置。

原因：

环境变量没设置或没导出（OPENAI_API_KEY、DASHSCOPE_API_KEY 等）
密钥过期、被删或无效
账户余额不足（百炼这类预付费平台尤其常见）

解决：

print(os.getenv("OPENAI_API_KEY")) 确认进程内真的读到了
检查密钥有效性，必要时重新生成
确认账户状态和余额

2. 模型未找到（NotFoundError）

症状：提示指定的模型不存在或无法访问。

原因：

模型名拼写错误（比如把 qwen-plus 写成 qwen_plus）
模型对当前 API 密钥或账户不可用（部分模型需要专门开通权限）
API 服务区域问题

解决：

核对模型名拼写；模型名是精确匹配，多一个横线少一个点都不行
查提供商文档，确认模型可用性和访问权限

3. 提示模板错误（TemplateFormatError / MissingInputVariables）

症状：渲染提示时报错，或最终提示里出现了没被替换的 {variable}。

原因：

模板占位符与调用时传入的输入键不匹配
模板语法错误——f-string 风格里想输出字面量 { 却没写成 {{

解决：

确保调用链时提供了模板里所有占位符变量
单独测试渲染：prompt.invoke({...}) 看渲染结果是否符合预期

4. Agent 输出解析错误（OutputParserException）

症状：LLM 输出不符合 Agent 期望的格式（0.x 时代的 ReAct Agent 未能正确输出 “Thought:” / “Action:” 等）。

原因：

模型难以理解提示中的输出格式要求
提示过于复杂，或工具描述含糊导致模型困惑
模型能力不足

解决：

简化输出格式要求；在提示里加几个符合格式的 few-shot 示例
改进工具描述，写清楚功能和预期输入
handle_parsing_errors=True（0.x 的 AgentExecutor 参数）：把解析错误反馈给模型，让它自我纠正
换更强的模型

⚠️ 版本注记：这套症状主要属于 0.x 时代的文本协议 Agent（ReAct）。1.x 的 create_agent 走原生 tool calling，模型输出结构化 JSON，这类格式解析错误已大幅减少。自己写 Pydantic 解析时仍会遇到 OutputParserException，处理思路见本站《langchain_core 组件详解》。

5. 工具执行错误（ToolException）

症状：Agent 正确选中了工具，但工具执行失败。

原因：

传给工具的参数无效
工具依赖的外部服务不可用（限流、网络问题）
工具内部逻辑错误

解决：

工具内部用 try-except 捕获异常，返回有意义的错误信息给 Agent，而不是让它崩掉
在工具入口验证参数；把工具拿出来独立测试
在提示里引导 Agent：工具失败时换一种方法，或如实报告

6. 上下文长度超出（ContextWindowExceeded / InvalidRequestError）

症状：提示 + 对话历史 + 输出预留的总 token 超过模型上限。

原因：

对话历史无限累积
RAG 检索了过多的文档块
提示本身冗长

解决：

⚠️ 0.x 的 ConversationBufferWindowMemory / ConversationTokenBufferMemory / ConversationSummaryBufferMemory 已随 legacy memory 体系移除；现代等价做法是 LangGraph checkpointer + 消息裁剪（trim_messages），或对长输入做分块摘要（本站《订阅摘要 Agent 实战》有完整案例）
控制检索文档的数量和长度
精简提示；或换长上下文模型

7. Agent 死循环（MaxIterationsExceeded）

症状：Agent 反复执行同样的无效操作，直到达到迭代上限。

原因：

提示不清晰，无法引导 Agent 走向正确方向
工具集不完备，缺少解决任务所需的关键能力
LLM 在复杂推理中迷失

解决：

改进提示，给出明确的目标和终止条件
审查工具集是否齐备
谨慎加大迭代上限——0.x 是 AgentExecutor 的 max_iterations，LangGraph 时代对应 config 里的 recursion_limit；但先排查其他原因，调上限只是兜底
引入人工介入：Agent 卡住时让用户兜底

1.x 时代最常见的报错：import 一个已被移除的类

LangChain 1.0（2025 年 10 月发布）移除了全部 legacy 抽象。老教程代码今天最常见的死法不是逻辑错误，而是 import 直接报错：

ImportError: cannot import name 'LLMChain' from 'langchain.chains'

遇到这类报错，对照表查一下，基本都有明确的现代等价物：

被移除的老写法	现代等价物
`LLMChain`	LCEL 管道：`prompt \| llm \| parser`
`RetrievalQA`	LCEL 检索链，或 `create_retrieval_tool`
`ConversationChain`	LangGraph `StateGraph` + checkpointer
`initialize_agent` / `AgentExecutor`	`langchain.agents.create_agent`（1.x）/ `langgraph.prebuilt.create_react_agent`
`create_openai_functions_agent` 等旧 Agent 构造器	同上，统一到 `create_agent`，协议统一走 tool calling
`langchain.memory.*`（ConversationBufferMemory 等）	LangGraph checkpointer + 消息裁剪（`trim_messages`）
`load_summarize_chain`	LangGraph map-reduce，或 LCEL 手写
`langchain.text_splitter`	`langchain_text_splitters` 独立包
`langchain_community` 里的 ChatOllama / HuggingFaceEmbeddings	`langchain-ollama` / `langchain-huggingface` 独立包
`langchain_core.pydantic_v1`	直接用 pydantic v2

需要读存量老代码时，这份表反过来用就是「翻译词典」。

排查顺序清单

报错栈最底层是平台 API 的 4xx？→ 配置层，查密钥、模型名、余额
拿原始输出：StrOutputParser 或 print，判断问题在模型层还是解析层
是解析错？改格式指令 + few-shot + 重试
Agent 行为怪？开 verbose / 用 LangSmith 追踪，看每一步的消息流
还查不出来？把最小可复现片段剥出来单独跑

总结

报错先分层：配置 → 模型 → 解析 → 编排，症状会骗人，层不会
看原始输出是最快的定位手段
1.x 时代大半「奇怪的报错」其实是 import 了已移除的类，对照表一查便知
过程观测交给工具：LangSmith（见本站《LangSmith使用教程》）+ astream_events

LangChain 与 MCP 极简教程：让 Agent 接入外部工具的另一种方式

Tue, 08 Sep 2026 13:00:00 +0800

LangChain 与 MCP 极简教程

给 Agent 接工具，最常见的做法是把所有工具函数都写在应用代码里，再逐个注册给模型。工具少的时候没问题；一旦工具多起来、或者想跨项目复用，这条路就会越来越累——同样的工具，每个应用都要重新写一遍。

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 在 2024 年底推出的开放协议，解决的就是这个问题：把「工具的定义和执行」从应用代码里拆出来，放到独立的服务器上，客户端按需发现和调用。本文用一个最小的双文件例子——FastMCP 起一个数学工具服务，langchain.mcp 把它接进 Agent——把这条链路跑通。

客户端这一侧，2026 年 9 月有个值得注意的变化：MCP 支持已经进到 LangChain 主干里。LangChain v1.4.0 新增了 langchain.mcp 命名空间，基于 FastMCP 实现，把原先独立的 langchain-mcp-adapters 包整个取代了——MultiServerMCPClient 收敛成一个 MCPAdapter。所以现在装依赖是 pip install "langchain[mcp]"，不再是单独装一个适配器包。本文代码全部按新写法给。

MCP 和 Function Call 是什么关系

先说结论：两者不是竞争关系，而是工作在两层的东西。

Function calling 是模型的能力：模型根据工具的名称、描述和参数 schema，决定「该调哪个工具、传什么参数」，并以结构化 JSON 输出。
MCP 是工具的供给协议：约定客户端如何发现服务器上有哪些工具（tool list）、如何调用（tool call）、如何取回结果。

也就是说，MCP 解决的不是「模型会不会调工具」，而是「工具从哪来、谁来维护、能不能复用」。写一次 MCP server，任何支持 MCP 的客户端（Claude Desktop、Cursor、你自己的 Agent）都能连。

最小实战：两个文件跑通

项目就两个文件：

math_server.py：MCP 服务端，提供数学工具
client.py：LangChain 客户端，把 MCP 工具接进 Agent

服务端：FastMCP 起服务

# math_server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
 """Add two numbers"""
 return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
 """Multiply two numbers"""
 return a * b

if __name__ == "__main__":
 mcp.run(transport="stdio")

两个细节值得注意：

工具用 @mcp.tool() 装饰器定义，函数签名和 docstring 就是模型看到的工具说明——和 LangChain @tool 的玩法一致，类型注解必须写清楚。
transport="stdio" 表示通过标准输入/输出通信，客户端会以子进程方式拉起这个脚本，本地工具用它最省事；要跨机器就走 HTTP（streamable HTTP / SSE）。

客户端：把 MCP 工具接进 Agent

# client.py
import asyncio
import os
from pathlib import Path

from langchain.agents import create_agent
from langchain.mcp import MCPAdapter
from langchain_openai import ChatOpenAI

# 模型走阿里云百炼的 OpenAI 兼容模式
model = ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model="qwen-plus",
)

# 目标类型决定传输方式：Path = stdio 子进程，字符串 = 必须是 http(s) URL
adapter = MCPAdapter(Path("math_server.py"))


async def run_agent():
 async with adapter:
 # 把 MCP 工具加载为 LangChain 工具
 tools = await adapter.list_tools()

 # 创建并运行 agent
 agent = create_agent(model, tools)
 return await agent.ainvoke({"messages": "what's (3 + 5) x 12?"})


if __name__ == "__main__":
 print(asyncio.run(run_agent()))

MCPAdapter 最省事的地方是它从你交给它的目标自己推断传输方式，不需要再写 transport 字段：

传给 `MCPAdapter` 的目标	推断出的传输
`"https://example.com/mcp"`	Streamable HTTP
`Path("math_server.py")`	stdio 子进程（每个 adapter 一个）
一个 `FastMCP` 实例	进程内直连，不走子进程也不走 socket，跑测试最合适
`{"mcpServers": {...}}` 配置字典	多服务器，工具名自动加 `{server}_` 前缀
现成的 `fastmcp.Client`	完全自定义（transport、缓存、认证）

有个坑值得单独说：脚本路径必须传 Path 而不是 str。FastMCP 解析字符串时会先当文件路径试，再当 URL 试，所以一个字符串形式的 "math_server.py" 有被当成本地脚本拉起的风险；MCPAdapter 的做法更保守——直接拒绝所有不符合 URL 形状的字符串。想跑本地脚本，明确写 Path(...)。

运行

pip install "langchain[mcp]" langchain-openai mcp

export DASHSCOPE_API_KEY=your_api_key

python client.py

客户端会自己拉起 math_server.py，提出问题 “what’s (3 + 5) x 12?"，并输出计算结果。

运行时发生了什么

MCPAdapter(Path("math_server.py")) 从目标类型推断出 stdio 传输
进入 async with adapter 时以子进程方式启动 math_server.py，完成 MCP 握手
adapter.list_tools() 把服务器上的工具转换成 LangChain 工具列表
create_agent(model, tools) 用这些工具构建 Agent
Agent 收到问题，决定调用哪个工具；实际执行发生在 MCP server 侧，结果经客户端回传给模型

关键点在第 3 步：对 Agent 来说，MCP 工具和本地 @tool 定义的工具没有任何区别，适配器把协议细节全部藏掉了。另外返回的每个工具自己持有连接、每次调用各开一个会话，所以**async with 退出后 agent 依然可用**——不必把整轮推理都关在上下文里。

Function Call vs MCP

维度	Function Calling	MCP
解决的问题	模型如何表达「调这个工具、参数是这些」	工具如何被外部程序发现、提供和复用
所在层	模型 API 的能力	客户端与服务端之间的协议
工具定义位置	应用代码里（`@tool` / JSON Schema）	独立的 MCP server
复用性	换个应用基本要重写	一个 server 服务所有支持 MCP 的客户端
传输方式	随模型 API 请求一起发送	stdio / HTTP，工具在进程外执行

一句话总结：function calling 决定模型「怎么说」，MCP 决定工具「从哪来」；MCP 工具最终还是要靠 function calling 让模型真正用起来。

版本注记：从 langchain-mcp-adapters 迁移过来

这篇教程最早写在 MCP 适配器还是独立包的时期，当时的客户端长这样：

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

client = MultiServerMCPClient({
 "math": {"transport": "stdio", "command": "python", "args": ["math_server.py"]},
})
tools = await client.get_tools()
agent = create_react_agent(model, tools)

LangChain v1.4.0（2026-09-01）之后，这套写法整体退休。对应关系如下：

旧（`langchain-mcp-adapters`）	新（`langchain.mcp`）
`MultiServerMCPClient(...)`	`MCPAdapter(target)`
`await client.get_tools()`	`await adapter.list_tools()`
`load_mcp_tools(session)`	直接用 `adapter.list_tools()`
`convert_mcp_tool_to_langchain_tool`	`as_langchain_tool`（改名，且变成协程）
`tool_name_prefix`	多服务器时自动加 `{server}_` 前缀
`handle_tool_errors` 开关	移除。行为固定：`isError=True` 变成 `ToolMessage(status="error")`，传输故障直接抛异常
`Callbacks(on_elicitation=...)`	取消回调，改为默认开启的 LangGraph `interrupt()`
`tool_interceptors`	用 LangChain `@wrap_tool_call` 中间件（能拦所有工具，不止 MCP 的）
连接上的 `auth` / `headers`	挪到 `fastmcp.Client` 上

三个必须知道的边界：

langchain.mcp 目前是 beta（需要 langchain[mcp]>=1.4.0），import 时会抛一次 LangChainBetaWarning，API 可能变。
elicitation 变成 interrupt：服务端中途要输入时，不再是回调，而是暂停整个 run，用 Command(resume={"responses": {key: 答案}}) 恢复。这是设计变化，不是 bug。
prompts / resources 还没有包装：load_mcp_prompt、load_mcp_resources 这些没有对应实现，需要的话直接用 FastMCP 客户端的 client.get_prompt(...) / client.read_resource(...)。sampling 和 roots 则是因为 MCP 协议本身在无会话时代移除了，会抛 NotImplementedError。

依赖包名也顺便更新一下：现在装的是 langchain[mcp]，不再需要 pip install langchain-mcp-adapters。

收藏的参考资料：

资源
MCP 终极指南（很值得读）
LangChain 官方 MCP 文档
从 langchain-mcp-adapters 迁移
Using LangChain With Model Context Protocol (MCP)
知乎：一文看懂 MCP（大模型上下文协议）
Function Call vs MCP（本文配图出处）

下一步

把数学工具换成你真正需要的东西：查数据库、调内部 API、文件处理，思路完全一样
工具链路稳定之后，如果要做长周期、多步骤的 Agent 工程（文件系统、子智能体、上下文管理），看本站的《DeepAgents完全指南》

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

Tue, 08 Sep 2026 12:30:00 +0800

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

LangChain 进入 1.x 之后，LangGraph 不再是"进阶选读"，而是整个框架的编排核心：官方一行式 create_agent 的底下就是一张 LangGraph 图，Agent 的决策、工具调用、记忆全在图上跑。看懂 LangGraph，基本等于看懂 Agent 本身。

这篇文章解决三件事。一是把 StateGraph、State、条件边这几个地基概念一次讲透；二是不用任何 Agent 封装，手写一遍 tool-call 循环——写完你会发现 Agent 没有魔法，它就是消息列表上转的一圈代码；三是用 LangGraph 把这个循环工程化成完整的 ReAct 天气助手，再补一个 Map-Reduce 长文本摘要图和记忆持久化。

文章由我 2025 年 5～6 月的三篇笔记（《Langchain-Graph实战教程》《LangChain-实战-Tools使用教程》《Langgraph使用教程》）整合而成。合并时修正了原笔记的几处真实 bug——条件边示例的构建顺序与路由映射错误、手动循环里对 tool_call["args"] 多加的一句 json.loads——过时 API 统一在文末版本注记里交代。全文示例模型走阿里云 DashScope 的 qwen 系（qwen-plus / qwen-max）OpenAI 兼容端点，只需要一个 DASHSCOPE_API_KEY 环境变量。

前五节是地基，任何版本都用得上。第六节是 2026 年的新增内容：LangGraph 1.1 / 1.2 给节点加上了超时、错误处理器和优雅停机，还给流式输出换了一套以内容块为中心的 API。这几样是"从能跑到敢上生产"之间的那段距离，值得单独看。

1. 基础三件套：StateGraph、State 与条件边

1.1 StateGraph：把应用建成一张状态机

StateGraph 把应用定义为状态机：节点（node）是执行单元，通常是普通 Python 函数；边（edge）决定流程如何在节点之间转换。构建一张图固定是四步：

定义 State——图运行时传递的数据结构
add_node 添加节点
连边：普通边写死流转，条件边动态路由，入口用 START
compile() 编译成可执行应用，之后用 invoke 跑

依赖安装一次说清：pip install langchain langgraph langchain_openai。

1.2 State 与 Annotated：覆盖还是追加

State 是一个 TypedDict，定义图的模式和状态更新方式。聊天场景下 State 通常只有一个键：messages。关键在 add_messages 这个 reducer 函数——它决定新消息是追加进列表，而不是覆盖列表：

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
 # Messages 的类型是 "list"。`add_messages` 函数
 # 在注解中定义了如何更新这个状态键
 # （在这种情况下，它会将消息追加到列表中，而不是覆盖它们）
 messages: Annotated[list, add_messages]

Annotated 是 Python 类型提示系统的特殊类型，允许为类型附加元数据。在 LangGraph 里它承担两个职责：

类型定义：第一个参数 list 表示 messages 字段是列表
行为定义：第二个参数 add_messages 是 reducer 函数，定义这个键怎么更新——新消息到来时追加进现有列表，而不是整体替换

两种语义的区别直观感受一下：

# 不使用 Annotated（默认行为：覆盖）
state = {"messages": ["消息1"]}
state["messages"] = ["消息2"]
# 结果：["消息2"]

# 使用 Annotated + add_messages
state = {"messages": ["消息1"]}
# 新消息到来时，add_messages 将其追加到列表
# 结果：["消息1", "消息2"]

这种设计在对话场景特别有用：保持对话历史、消息按顺序累积、不会意外覆盖。反过来，没有 reducer 注解的字段就是"最后一次写入覆盖"的语义——第 4 节 Map-Reduce 的流水线正好要靠这个默认行为。

1.3 MessagesState：内置的消息状态

自己写 Annotated[list, add_messages] 是标准做法，LangGraph 也把它做成了内置状态类 MessagesState，位于 langgraph.graph 模块，专为对话场景设计。它内部维护一个 messages 键，等价于：

class MessagesState(TypedDict):
 messages: Annotated[list, add_messages]

它的特点：

与 LangChain 的消息类型（HumanMessage、AIMessage、SystemMessage、ToolMessage）直接兼容
节点返回 {"messages": [...]} 时自动追加进消息列表
可以通过继承扩展自定义字段

一个能跑通的最小示例：

import os
from langgraph.graph import MessagesState, StateGraph, START, END
from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
 model="qwen-plus",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
)

def chatbot_node(state: MessagesState):
 # 取出当前消息，调用 LLM；返回值会自动追加进 messages
 response = llm.invoke(state["messages"])
 return {"messages": [response]}

graph = StateGraph(MessagesState)
graph.add_node("chatbot", chatbot_node)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)
app = graph.compile()

result = app.invoke({"messages": [HumanMessage(content="你好！今天能帮我什么？")]})
for message in result["messages"]:
 print(f"{message.__class__.__name__}: {message.content}")

运行后会打印两条消息：一条 HumanMessage，一条 LLM 追加的 AIMessage。

需要扩展状态时，继承加字段即可：

class CustomMessagesState(MessagesState):
 user_id: str
 session_id: int

graph = StateGraph(CustomMessagesState)

状态将包含 messages 列表以及 user_id 和 session_id，节点可读写这些字段。两个使用注意：消息必须符合 BaseMessage 或兼容格式，塞普通字符串会出问题；长对话历史要么确认模型的上下文窗口装得下，要么自己加截断策略。

1.4 条件边：让图自己决定下一步

普通边是写死的流转，条件边（add_conditional_edges）根据状态动态路由：条件函数的返回值经过映射字典决定下一个节点。这是 LangGraph 表达分支逻辑的方式，也是后面 ReAct 循环里"有 tool_calls 就去执行工具、没有就结束"的实现基础。

下面这个示例修正过原笔记的两处问题：一是 add_edge(START, "router") 写在了 add_node("router", ...) 之前——节点还没注册就连边，LangGraph 校验阶段直接报错；二是路由函数返回 "help_node" / "chatbot_node"，与图中实际节点名 "help" / "chatbot" 错位，而且同一个函数既被当节点又被当条件函数。修正思路：路由函数只作为条件函数，从 START 直接条件路由，返回值与节点名严格对齐。

from typing import Literal
from langgraph.graph import MessagesState, StateGraph, START, END
from langchain_core.messages import HumanMessage, AIMessage

def route_by_intent(state: MessagesState) -> Literal["help", "chatbot"]:
 last_message = state["messages"][-1].content.lower()
 if "帮助" in last_message:
 return "help"
 return "chatbot"

def help_node(state: MessagesState):
 return {"messages": [AIMessage(content="这里是帮助信息！")]}

def chatbot_node(state: MessagesState):
 return {"messages": [AIMessage(content="来聊聊吧！")]}

graph = StateGraph(MessagesState)
graph.add_node("help", help_node)
graph.add_node("chatbot", chatbot_node)

# 条件边：起点是 START，路由函数的返回值映射到目标节点
graph.add_conditional_edges(
 START,
 route_by_intent,
 {"help": "help", "chatbot": "chatbot"},
)
graph.add_edge("help", END)
graph.add_edge("chatbot", END)

app = graph.compile()
result = app.invoke({"messages": [HumanMessage(content="我需要帮助")]})
print(result["messages"][-1].content) # 输出：这里是帮助信息！

add_conditional_edges 收三个参数：起点节点（这里用特殊节点 START）、条件函数、返回值到目标节点的映射字典。条件边也可以从普通节点出发——第 3 节的 should_continue 就是从 agent 节点出发的。

2. 手写 tool-call 循环：Agent 到底在替你做什么

在让 LangGraph 接管之前，值得把这个循环亲手写一遍。create_agent、AgentExecutor、ToolNode 这些封装拆开看没有魔法，核心就是：在消息列表上跑一圈循环。整个流程四步：

把用户消息和工具定义一起发给 LLM
检查响应里有没有 tool_calls
有：执行对应函数，结果包成 ToolMessage 回填进消息列表
带着完整消息再次调用 LLM，它基于工具结果生成最终回复

先定义模型和工具（沿用原笔记的三个 mock 工具）：

import os
from typing import List, Dict, Any, Optional
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, ToolMessage

model = ChatOpenAI(
 model="qwen-plus",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
)

@tool
def get_weather(location: str, unit: str = "celsius") -> str:
 """获取指定位置的当前天气。"""
 return f"{location}当前天气晴朗，温度25{unit}"

@tool
def create_user(name: str, email: str, age: Optional[int] = None) -> Dict[str, Any]:
 """在系统中创建新用户。"""
 user = {"id": hash(email) % 10000, "name": name, "email": email}
 if age:
 user["age"] = age
 return user

@tool
def search_database(query: str) -> List[Dict[str, Any]]:
 """搜索数据库获取信息。"""
 if "产品A" in query:
 return [{"id": 1, "name": "产品A", "price": 99.99}]
 return []

tools = [get_weather, create_user, search_database]

# bind_tools：把工具定义绑定到 LLM，LLM 就"知道"这些工具的存在
llm_with_tools = model.bind_tools(tools)

# 工具名 -> Tool 对象，供手动执行时查找
available_tools = {t.name: t for t in tools}

@tool 装饰器把普通 Python 函数变成 LangChain 工具：函数签名和 docstring 会被转成 LLM 可读的工具描述——LLM 何时调用、怎么调用全靠 docstring。bind_tools(tools) 是关键一步：绑定之后，LLM 在认为合适时就会在响应里返回"工具调用请求"，而不是纯文本。

接下来是循环本身，不用任何 Agent 框架：

# 步骤 1：初始消息列表
messages = [
 HumanMessage(content="创建一个名为李四的用户，邮箱为lisi@example.com，年龄28岁。然后告诉我北京的天气。"),
]

# 步骤 2：第一次调用 LLM（消息 + 工具定义）
first_response = llm_with_tools.invoke(messages)
messages.append(first_response) # AIMessage，可能带 tool_calls

# 步骤 3：检查并处理 tool_calls
if first_response.tool_calls:
 for tool_call in first_response.tool_calls:
 # tool_call 是 {"name": ..., "args": ..., "id": ...}
 # 注意：args 在 LangChain 里已经是解析好的 dict
 function_name = tool_call["name"]
 function_args = tool_call["args"]

 if function_name in available_tools:
 try:
 result = available_tools[function_name].invoke(function_args)
 except Exception as e:
 result = f"Error executing function {function_name}: {e}"
 content = str(result)
 else:
 content = f"Error: Unknown function {function_name}"

 # 结果包成 ToolMessage，tool_call_id 关联原始请求
 messages.append(ToolMessage(
 tool_call_id=tool_call["id"], # 必须提供原始调用的 ID
 content=content,
 name=function_name,
 ))

 # 步骤 4：带着工具结果二次调用 LLM
 final_response = llm_with_tools.invoke(messages)
 print(final_response.content)
else:
 # 第一次响应就没有 tool_calls，说明 LLM 直接回答了
 print(first_response.content)

四个关键点：

first_response.tool_calls 是一个列表。这条消息同时涉及"创建用户"和"查天气"两件事，模型支持并行工具调用时，一次响应里会返回多个 tool_calls，循环逐个执行、逐个回填——并行工具调用的全部真相就这么多
tool_call["args"] 拿到的已经是解析好的 dict。原笔记在这里紧跟过一句 json.loads(...)——dict 传进 loads 会直接 TypeError，这句必须删掉。较老的单函数 function_call 格式里参数才是 JSON 字符串，两种格式混写最容易在这里翻车
ToolMessage 必须带 tool_call_id，LLM 靠它把结果和哪一次请求对应起来
二次调用时，发给 LLM 的是完整三段消息：HumanMessage（原始请求）+ AIMessage（带 tool_calls 的调用决定）+ ToolMessage（执行结果）。LLM 看到这三段，才能生成综合回复

把这段跑通之后再回头看 Agent 封装：create_agent / AgentExecutor / LangGraph 的 ToolNode，做的就是"第 3 步 + 第 4 步包进一个带停止条件的循环"——没有 tool_calls 就退出循环返回文本。手写一遍的意义就在这里：以后封装出问题，你知道往哪一层查。

3. 完整实战：天气助手 ReAct

现在把第 2 节手写的循环交给 LangGraph 工程化：用户用自然语言问某城市天气（示例支持上海和北京），应用自动判断是否调用天气工具，拿到结果后作答，并且记得住对话上下文。

这一节整体迁自我当时的天气助手实战笔记，代码分六段，每段跟着当时的知识点注解。

3.1 环境与依赖

安装（原笔记把 typing、os 也写进了 pip install——它们是标准库，不是 pip 包，这里已删掉）：

pip install langchain langgraph langchain_openai langchain_core

设置环境变量 DASHSCOPE_API_KEY，并做启动检查：

import os
if not os.getenv("DASHSCOPE_API_KEY"):
 raise ValueError("DASHSCOPE_API_KEY environment variable not set. Please set it before running.")

os.getenv 从环境变量读密钥，避免硬编码进代码。

3.2 工具定义：@tool

from langchain_core.tools import tool

@tool
def get_weather_updates(query: str) -> str:
 """
 查询城市当前天气 (Query current weather for a city)
 Use this tool to find out the current weather for a given city.
 """
 print(f"--- Tool 'get_weather_updates' called with query: {query} ---")
 query_lower = query.lower()
 if "上海" in query_lower or 'shanghai' in query_lower:
 return "now is 30 celsius, foggy"
 elif "北京" in query_lower or 'beijing' in query_lower:
 return "now is 20 celsius, sunny"
 else:
 return f"Weather information for {query} not available with this tool. Only Shanghai and Beijing are supported."

tools = [get_weather_updates]

知识点：

@tool 装饰器把普通函数转成 LangChain 工具，query: str 的类型提示和返回值提示都会进入工具描述
docstring 至关重要：LLM 根据工具名和 docstring 判断何时调用（工具能干什么）和怎么调用（query 参数该传什么）。描述含糊，调用就跟着含糊
工具内部目前是 mock 的假数据，实际应用中替换成真实天气 API 调用即可
tools = [get_weather_updates] 收进列表，后续绑定到 LLM

3.3 模型初始化与工具绑定

from langchain_openai import ChatOpenAI

model = ChatOpenAI(
 model="qwen-max",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 temperature=0
)

model_with_tools = model.bind_tools(tools)

知识点：

ChatOpenAI 虽然名字带 OpenAI，但通过 base_url + api_key 可以接任何 OpenAI 兼容服务，这里接 DashScope
temperature=0 让输出更确定，对需要精确调用工具的场景是稳妥选择
bind_tools(tools) 之后，LLM 在认为合适时返回的将不是纯文本，而是携带工具调用指令的 AIMessage

3.4 状态与节点

状态用第 1 节的 MessagesState——本质就是 messages: Annotated[list, add_messages]，每次节点返回 {"messages": [...]} 时自动追加。节点有两个，一个调模型，一个执行工具：

from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode

tool_node = ToolNode(tools) # 预构建的工具执行节点

def call_model(state: MessagesState):
 messages = state["messages"]
 print(f"--- Calling model with {len(messages)} messages. Last message type: {type(messages[-1])} ---")
 response = model_with_tools.invoke(messages)
 return {"messages": [response]}

知识点：

ToolNode(tools) 是 LangGraph 的预构建节点：接收工具调用请求，执行对应工具，把输出包装成 ToolMessage 返回——第 2 节手写的那段 for 循环，它内部替你做了
call_model 是自定义的 Agent 节点：把当前全部消息历史交给绑定了工具的 LLM。LLM 能直接回答时返回普通 AIMessage；需要工具时返回带 tool_calls 属性的 AIMessage，其中包含工具名、参数和唯一的 tool_call_id
返回值封装成 {"messages": [response]}，由 MessagesState 自动追加进消息列表

3.5 条件边与图构建

from typing import Literal
from langgraph.graph import START, END
from langgraph.checkpoint.memory import MemorySaver

def should_continue(state: MessagesState) -> Literal["tools", END]:
 messages = state["messages"]
 last_message = messages[-1]
 # 最后一条消息是否是带工具调用请求的 AIMessage
 if hasattr(last_message, 'tool_calls') and last_message.tool_calls and len(last_message.tool_calls) > 0:
 print(f"--- LLM decided to use tools: {last_message.tool_calls} ---")
 return "tools" # 有工具调用，去 "tools" 节点
 print("--- LLM decided NOT to use tools. Ending. ---")
 return END # 没有，结束流程

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model) # Agent 节点
workflow.add_node("tools", tool_node) # 工具节点
workflow.add_edge(START, "agent") # 入口

# 条件边：从 "agent" 出发，由 should_continue 的返回值决定去向
workflow.add_conditional_edges(
 "agent",
 should_continue,
 {
 "tools": "tools", # 返回 "tools" -> 去 "tools" 节点
 END: END # 返回 END -> 结束
 }
)
workflow.add_edge("tools", "agent") # 工具执行完，回到 "agent"

checkpointer = MemorySaver() # 内存检查点，保存对话状态
app = workflow.compile(checkpointer=checkpointer)

知识点：

tools -> agent 这条回边是整张图的灵魂：工具执行完回到 LLM，让它基于工具结果继续生成——这就是 ReAct（Reasoning and Acting）循环
MemorySaver 把每个线程（对话）的状态存在内存里，让对话有记忆；生产环境要换持久化存储（第 5 节展开）
compile(checkpointer=...) 把图定义转成可执行应用，同时接入状态持久化

3.6 执行：两轮对话

# 用字符串区分不同的对话线程
thread_id = "chat_thread_42"
config = {"configurable": {"thread_id": thread_id}}

print("\nInvoking for Shanghai...")
shanghai_input = {"messages": [HumanMessage(content="what's the weather in Shanghai?")]}
final_state_shanghai = app.invoke(shanghai_input, config=config)

if final_state_shanghai["messages"] and isinstance(final_state_shanghai["messages"][-1], AIMessage):
 print(f"Final response for Shanghai: {final_state_shanghai['messages'][-1].content}")

print("\nInvoking for Beijing (same thread)...")
beijing_input_message = HumanMessage(content="what's the weather in Beijing?")
# 第二次调用：同一个 thread_id，新消息自动追加到已有历史之后
final_state_beijing = app.invoke({"messages": [beijing_input_message]}, config=config)

if final_state_beijing["messages"] and isinstance(final_state_beijing["messages"][-1], AIMessage):
 print(f"Final response for Beijing: {final_state_beijing['messages'][-1].content}")

知识点：

thread_id 区分对话会话。配合 checkpointer，相同 thread_id 的调用共享同一段对话历史
第二次问北京天气时只传新的 HumanMessage——MessagesState 自动把它追加到上海那轮之后，LLM 处理北京问题时看得到之前的完整对话
final_state["messages"][-1].content 取最后一条 AI 消息，即最终回复

3.7 六步执行流程梳理

现在把 “what’s the weather in Shanghai?” 这句话输进去之后，图里到底发生了什么逐步拆开——这段是当初记这篇笔记时最值得留下的部分：

入口（agent 节点）
- call_model 被调用，model_with_tools.invoke 收到 [HumanMessage(content="what's the weather in Shanghai?")]
- LLM（qwen-max）分析输入和 get_weather_updates 的 docstring，判断需要调用这个工具，参数 query 应为 “Shanghai”
- LLM 返回带 tool_calls 的 AIMessage，例如 tool_calls=[ToolCall(name='get_weather_updates', args={'query': 'Shanghai'}, id='call_abc123')]
- call_model 返回 {"messages": [AIMessage_with_tool_call]}
条件路由（should_continue）
- 检查最后一条消息，发现有 tool_calls
- 返回 "tools"
工具执行（tools 节点）
- ToolNode 接收 tool_calls，找到 get_weather_updates，用参数 {'query': 'Shanghai'} 调用
- 工具执行，返回字符串 "now is 30 celsius, foggy"
- ToolNode 把结果包装成 ToolMessage(content="now is 30 celsius, foggy", tool_call_id='call_abc123')
- 返回 {"messages": [ToolMessage_with_result]}
返回 Agent（agent 节点）
- tools -> agent 的回边把流程带回 call_model，此时 state["messages"] 包含：
  1. HumanMessage(content="what's the weather in Shanghai?")
  2. AIMessage(..., tool_calls=[...])
  3. ToolMessage(content="now is 30 celsius, foggy", tool_call_id='call_abc123')
- LLM 看到原始问题、自己调用工具的决定、工具的执行结果，基于这些生成自然回复，例如 AIMessage(content="The current weather in Shanghai is 30 degrees Celsius and foggy.")
- call_model 返回 {"messages": [AIMessage_final_response]}
条件路由（should_continue）
- 检查最后一条消息（最终回复），没有 tool_calls
- 返回 END
结束
- 图执行结束，app.invoke 返回最终状态
- 代码从 final_state["messages"][-1].content 提取并打印最终回复
- MemorySaver 把包含这四条消息的完整状态存到 thread_id="chat_thread_42" 名下

后续问北京天气时，由于 thread_id 相同，call_model 的初始状态里就包含上海那四条消息，再加上新的 HumanMessage(content="what's the weather in Beijing?")——LLM 因此有上下文感知。

回头看这张图，它就是第 2 节手写循环的图化：agent 节点是"调 LLM"，tools 节点是"执行 tool_calls 并回填 ToolMessage"，should_continue 条件边是循环的停止条件。手写过一遍再看这里，每一层都能对上号。

3.8 收尾要点

工具定义（@tool）：docstring 是 LLM 理解工具的唯一入口
模型绑定（bind_tools）：让 LLM 知道有哪些工具可用
MessagesState：消息历史的自动追加
ToolNode：预置的工具执行器
条件边 + END：循环的出口
MemorySaver + thread_id：跨轮次的对话记忆

4. Map-Reduce：超长文本分段摘要

前两节都在聊 Agent 循环，换一个场景：文本长度超过模型单次上下文窗口，怎么做摘要？

经典解法是 Map-Reduce——大数据领域的老朋友，用在长文本摘要上正合适：

切片（Chunking）：把长文本切成模型一次吃得下的小块
映射（Map）：对每个块独立摘要，这一步天然可并行
规约（Reduce）：把所有小摘要合并，让模型做最后一次整合，产出连贯的最终摘要

LangGraph 适合表达这种多步骤工作流：状态在节点间流转，每一步做什么清清楚楚。完整代码：

import os
from typing import TypedDict, List

from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langgraph.graph import StateGraph, START, END

llm = ChatOpenAI(
 model="qwen-plus",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 temperature=0,
)

text_splitter = RecursiveCharacterTextSplitter(chunk_size=2000, chunk_overlap=200)

# 1. 图的状态：整个流程要跟踪的全部数据
class GraphState(TypedDict):
 text: str # 原始长文本
 chunks: List[str] # 切分后的文本块列表
 summaries: List[str] # 每个文本块的摘要列表
 final_summary: str # 最终的摘要

# 2. 节点：切分
def chunk_text_node(state: GraphState):
 print("--- 正在切分文本 ---")
 chunks = text_splitter.split_text(state['text'])
 return {"chunks": chunks}

# 3. 节点：Map，对每个块独立摘要
def summarize_map_node(state: GraphState):
 print("--- 正在对每个块进行摘要 (Map) ---")
 map_prompt = ChatPromptTemplate.from_template(
 "简要总结以下文本内容：\n\n{chunk}"
 )
 summarize_chain = map_prompt | llm

 # batch 并行处理所有块，max_concurrency 控制并发
 summaries = summarize_chain.batch(
 [{"chunk": chunk} for chunk in state['chunks']],
 config={"max_concurrency": 5}
 )
 # batch 返回 AIMessage 列表，提取 .content
 cleaned_summaries = [s.content for s in summaries]
 return {"summaries": cleaned_summaries}

# 4. 节点：Reduce，合并所有小摘要
def summarize_reduce_node(state: GraphState):
 print("--- 正在合并所有摘要 (Reduce) ---")
 summaries_joined = "\n\n".join(state['summaries'])

 reduce_prompt = ChatPromptTemplate.from_template(
 "你收到了关于一个长文档的多个摘要。请将它们整合成一个连贯、流畅、全面的最终摘要。\n\n"
 "以下是各个部分的摘要：\n{summaries_text}"
 )
 reduce_chain = reduce_prompt | llm
 final_summary = reduce_chain.invoke({"summaries_text": summaries_joined})
 return {"final_summary": final_summary.content}

# 5. 连图
workflow = StateGraph(GraphState)
workflow.add_node("chunker", chunk_text_node)
workflow.add_node("mapper", summarize_map_node)
workflow.add_node("reducer", summarize_reduce_node)

workflow.add_edge(START, "chunker") # 入口
workflow.add_edge("chunker", "mapper")
workflow.add_edge("mapper", "reducer")
workflow.add_edge("reducer", END)
app = workflow.compile()

# 6. 跑一个示例：把一段文本重复 10 次模拟长文本
long_text = """
人工智能（AI）正在以前所未有的速度改变世界。从自动驾驶汽车到医疗诊断，AI的应用无处不在。
其核心技术包括机器学习、深度学习和自然语言处理。机器学习使计算机能够从数据中学习规律，而无需进行显式编程。
深度学习是机器学习的一个分支，它利用深度神经网络模型，在图像识别、语音识别等领域取得了巨大成功。
自然语言处理则致力于让计算机能够理解和生成人类语言，Siri和ChatGPT就是最好的例子。
然而，AI的发展也带来了挑战，如数据隐私、算法偏见和就业冲击。解决这些问题需要技术、法律和伦理的共同努力。
""" * 10

final_state = app.invoke({"text": long_text})
print(final_state['final_summary'])

代码要点：

GraphState 是 TypedDict，像一份清单，规定流程要跟踪的全部数据（原文、块、各块摘要、最终摘要）。注意这里的字段没有 add_messages 这类 reducer——默认覆盖语义，每个字段只由一个节点整体写入一次，正好匹配这条线性流水线（对照 1.2 节）
chunk_text_node 是入口节点：接收 text，用 RecursiveCharacterTextSplitter 切分，chunks 写回状态
summarize_map_node 是 Map 步骤：batch() 并行为每个块生成摘要，比手写 for 循环高效；返回的 AIMessage 列表要取 .content
summarize_reduce_node 是 Reduce 步骤：小摘要拼接后交给 LLM 做最后一次、也是最关键的整合
边的连接定义流水线顺序：chunker -> mapper -> reducer -> END
invoke({"text": long_text}) 启动整张图——初始状态只需要 text 一个键，LangGraph 按定义好的流程执行完所有步骤，返回包含全部结果的最终状态

这套结构既绕开了上下文窗口限制，流程又清晰可维护：想加一步"摘要去重"或"质量过滤"，加个节点就行。

5. 记忆与持久化：MemorySaver 与 thread_id

第 3 节的天气助手已经用上了 MemorySaver，这里把机制单独拆开讲，因为它值得。

LangGraph 的记忆靠 checkpointer（检查点）机制：图每执行完一步，就把当前状态存一份快照。编译时传入 checkpointer，运行时指定 thread_id：

from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()
app = graph.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "1"}}
result = app.invoke({"messages": [HumanMessage(content="你好！")]}, config)

# 后续调用恢复状态：只传新消息，历史自动接上
result = app.invoke({"messages": [HumanMessage(content="继续聊")]}, config)

thread_id 是记忆的单位：同一个 thread_id 下的调用共享状态，换一个 thread_id 就是全新对话
MemorySaver 存在内存里，进程结束记忆就没了——适合开发和测试
生产环境要换持久化实现：官方提供了 SQLite、Postgres 等独立安装的 checkpointer 包，也可以自己接 Redis 这类存储

命名注记：这个类现在叫 InMemorySaver，MemorySaver 是保留的旧别名，两个名字指向同一个东西，新代码建议用前者。

6. LangGraph 1.1 / 1.2：从"能跑"到"敢上生产"

前五节的图，跑通没问题，但真接到线上会遇到几类很实际的问题：某个节点卡住了整张图跟着挂、某一步失败之后没有退路只能整个 run 报废、服务收到 SIGTERM 时正在跑的活儿全丢、长对话的 checkpoint 越存越大。1.1 和 1.2 基本就是冲着这些来的。

以下内容默认需要 langgraph>=1.2；6.7 那节是 1.1 引入的。

6.1 节点超时：`TimeoutPolicy`

add_node 现在接受 timeout=，给单次节点尝试封顶：

from datetime import timedelta
from langgraph.types import TimeoutPolicy

# 简单封顶：秒数或 timedelta
builder.add_node("call_model", call_model, timeout=60)
builder.add_node("call_model", call_model, timeout=timedelta(minutes=2))

# 分别限制总时长和空闲时长
builder.add_node(
 "call_model",
 call_model,
 timeout=TimeoutPolicy(run_timeout=120, idle_timeout=30),
)

两种限制的语义不一样，别混用：

run_timeout 是硬性挂钟上限，永不刷新。不管节点多活跃，到点就砍——适合"这个调用最多花两分钟"这种业务约束。
idle_timeout 是随进度重置的上限。只在节点一段时间内没有任何可观测进展时才触发——适合"卡死检测"。还能配 refresh_on="heartbeat" 用心跳当进度信号。

两个值可以同时给。超时后 LangGraph 抛 NodeTimeoutError，清掉这次失败尝试写入的状态，然后交给重试策略决定要不要重试。NodeTimeoutError 默认是可重试的，而且超时时钟每次重试重新计时，所以 timeout 和 retry_policy 放在一起是开箱可用的。

有个容易踩的坑：节点超时只对 async 节点生效。同步节点带 timeout 会在编译期就被拒绝。要包阻塞式 I/O，得在 async 节点里用 asyncio.to_thread。

6.2 节点级错误处理：`error_handler`

重试解决的是"偶发失败"，但有些失败重试三次也还是失败，这时候你需要的是退路而不是重试。add_node 的 error_handler= 就是干这个的：它在节点失败且重试耗尽之后执行，拿到当前状态，可以改状态，也可以用 Command 跳到别的节点。

from langgraph.errors import NodeError
from langgraph.types import Command, RetryPolicy

def charge_payment(state: State) -> State:
 raise RuntimeError("payment gateway timeout")

def payment_error_handler(state: State, error: NodeError) -> Command:
 return Command(
 update={"status": f"compensated: {error.error}"},
 goto="finalize",
 )

graph = (
 StateGraph(State)
 .add_node(
 "charge_payment",
 charge_payment,
 retry_policy=RetryPolicy(max_attempts=3, retry_on=ConnectionError),
 error_handler=payment_error_handler,
 )
 .add_node("finalize", finalize)
 .add_edge(START, "charge_payment")
 .compile()
)

这就是 Saga / 补偿模式的表达方式：失败不是把整张图炸掉，而是走一条补偿路径把状态收拾干净。

几个细节：

执行顺序是固定的——先重试，重试耗尽（或没配重试策略）才轮到错误处理器。两者解耦，可以分别配。
想拿到失败上下文，就把参数标注成 error: NodeError（按类型注解注入，和 runtime: Runtime 一个套路）。NodeError 是 frozen dataclass，只有两个字段：node（失败的节点名）和 error（原始异常）。
不需要上下文的话，签名写成 (state) 或 (state, runtime) 也行。
注入是可选的，但每个节点最多一个 error_handler。

6.3 图级默认值：`set_node_defaults`

如果每个节点都要重复写一遍 retry_policy= / error_handler= / timeout=，代码会很难看。set_node_defaults 把这些提成图级默认：

from langgraph.types import RetryPolicy, TimeoutPolicy

builder = (
 StateGraph(State)
 .set_node_defaults(
 error_handler=default_error_handler,
 timeout=TimeoutPolicy(run_timeout=30),
 )
 .add_node("step_a", step_a) # 用默认处理器
 .add_node("step_b", step_b, error_handler=custom_error_handler) # 用自己的
)

这个能力在"每次图运行都对应一个外部进程"的场景下特别值——比如后台任务表里的一行，任何未处理的节点失败都应该把那行标成 failed，不用在每个 add_node 上重复声明。单节点配置优先于图级默认值。

有个安全设计要注意：错误处理器节点本身不套用 error_handler 默认值——处理器不能接住自己，否则就是无限递归。

6.4 优雅停机：`RunControl` 与 drain

服务要重启、容器要缩容，收到 SIGTERM 时正在跑的图怎么办？1.2 给了一个协作式的停机机制：跑完当前 superstep 再停，并保存一个可恢复的 checkpoint。

import signal
from langgraph.runtime import RunControl
from langgraph.errors import GraphDrained

control = RunControl()
signal.signal(signal.SIGTERM, lambda *_: control.request_drain("sigterm"))

try:
 result = graph.invoke(inputs, config, control=control)
except GraphDrained as e:
 log.info("graph drained: %s", e.reason)
 # 下次启动时用同一个 config 继续

drain 的语义是"协作"，它只在 superstep 之间生效，绝不抢占已经在跑的工作：

场景	行为
节点执行到一半	跑完。drain 在下一个 superstep 生效
节点正在按重试策略重试	重试循环跑到成功或耗尽，之后才生效
图正好在同一次 tick 自然结束	正常返回。用 `control.drain_requested` 区分
后面还有 superstep	抛 `GraphDrained(reason)`，checkpoint 已保存可续跑
子图请求 drain	`GraphDrained` 向上冒泡，让父图在它自己的下一个边界停

节点内也能感知 drain，用来跳过昂贵的工作：

from langgraph.runtime import Runtime

async def my_node(state: State, runtime: Runtime) -> State:
 if runtime.drain_requested:
 return {"status": "skipped", "reason": runtime.drain_reason}
 return {"status": await do_work()}

恢复就是同一 thread_id 下 graph.invoke(None, config)。

别把它当成强制中断：request_drain() 不会取消正在跑的 asyncio task，也不会杀线程。想要硬上限，得把 drain 和一个 grace timeout + 任务取消配合使用。

6.5 DeltaChannel：给长线程的 checkpoint 减重

图跑得越久，checkpoint 越大。原因是消息列表这类 channel 每步都在增长，而过去的做法是每一步都把累积后的全量值重新序列化进 checkpoint——于是存储和读取延迟随对话长度线性上升。

1.2 引入的 DeltaChannel（beta）只存每一步写入的增量，不存全量。对消息列表这种只会越堆越长的 channel，效果最明显。代价是读历史要重放 delta，所以可以配 snapshot_frequency=K，每 K 步写一次全量快照给读取延迟封顶。

如果你在用 DeepAgents，注意它从 0.6.0 起也把消息历史和 agent 文件切到了 DeltaChannel，而且这个变更不可回滚——细节见《DeepAgents完全指南》3.5 节。

6.6 流式输出换代：事件流（v3）

stream_mode="messages" / "updates" 那套是 LangGraph 的原始流式接口，拿到的是 dict，得自己判断这块是什么。1.2 起多了一层更适合应用代码的东西——事件流，传 version="v3" 开启：

stream = graph.stream_events(input_data, version="v3")

for message in stream.messages: # token 级模型输出
 print(str(message.text), end="", flush=True)

final_state = stream.output # 最终状态

它的关键设计是：一次 run 的事件流被归一化成几个带类型的投影，多个消费者可以同时读——读 stream.messages 不会消耗 stream.values 需要的事件。可用的投影有 stream.messages、stream.values、stream.output、stream.subgraphs、stream.interrupts / stream.interrupted，以及给自定义 transformer 用的 stream.extensions。

异步并发读用 asyncio.gather；同步代码想按严格到达顺序混读多个投影，用 stream.interleave("values", "messages", "subgraphs")。

底层 messages 通道是按 content block 建模的，事件序列固定为 message-start → content-block-start → content-block-delta → content-block-finish → message-finish，文本、推理、工具调用、多模态内容都有显式边界，不再依赖各家 provider 的格式。

v1 / v2 保持兼容，没有破坏性变更——老代码不用动，新代码建议直接从 v3 起步。

6.7 类型安全的 invoke / stream（1.1）

1.1 就往这个方向走了一步：invoke() / stream() 传 version="v2" 会拿到带类型的东西。

from langgraph.types import GraphOutput

result: GraphOutput = graph.invoke(input_data, config, version="v2")
print(result.value) # 状态值
print(result.interrupts) # 中断信息

stream(..., version="v2") 则统一输出带 type / ns / data 三个键的 StreamPart，每种 mode 一个 TypedDict，都能从 langgraph.types 导入。另外 version="v2" 下，invoke() 和 values mode 的输出会自动转换成你声明的 Pydantic 模型或 dataclass 类型。

version="v2" 是 opt-in，GraphOutput 也保留了废弃的 dict 风格访问，方便渐进迁移。

7. 版本注记：从 0.x 写法到 LangChain 1.x

这篇整合自 0.x 时代的笔记，几处新旧差异统一交代：

set_entry_point 已统一为 add_edge(START, ...)。原笔记的天气助手和 Map-Reduce 图用的都是 set_entry_point("agent") 这类写法，官方后来统一成 add_edge(START, "agent")（连同 set_finish_point → add_edge(node, END)），本文正文已全部改写。旧写法当前仍可用，但属废弃路径
ChatTongyi 属 legacy。原笔记另一处用 langchain_community.chat_models 的 ChatTongyi 直连通义——这个包里的集成属于 legacy。本文统一走 DashScope 的 OpenAI 兼容端点（ChatOpenAI + base_url），这也是当时验证过可行的路线
模型。原笔记示例里有 gpt-3.5-turbo（已下线）和 gpt-4o-mini，整合时统一替换为 DashScope 的 qwen-plus / qwen-max
一行式封装。现在构建 ReAct Agent 不需要手搓图：langgraph.prebuilt.create_react_agent 一行拉起；LangChain 1.x 的 langchain.agents.create_agent 是官方标准入口，底层就是 LangGraph。但我的判断是：手写一遍第 2 节那个循环，仍然是理解这些封装的最佳方式——封装出问题时，你得知道问题出在哪一层
MemorySaver → InMemorySaver（见第 5 节）。旧名仍是可用别名，但新代码建议用 InMemorySaver
1.1 / 1.2 是增量而非破坏性变更。第 6 节的超时、错误处理器、优雅停机、DeltaChannel、事件流都是 opt-in 的新参数或新 API，老代码不改也能继续跑。注意 timeout / error_handler / 优雅停机需要 langgraph>=1.2

版本基线

组件	本文参考版本	备注
`langgraph`	1.2.11（2026-08-11）	1.2.0 起有超时 / 错误处理 / 优雅停机 / 事件流
`langgraph-checkpoint`	4.2.0	`DeltaChannel` 相关修复在这个线上
`langgraph-sdk`	0.4.4	走 Agent Server 时用
`langchain`	1.4.0	`create_agent` 入口；MCP 已内建为 `langchain.mcp`

更深的 Agent 工程化路线——多智能体、子智能体、规划与上下文管理——同目录的《DeepAgents完全指南》是这篇的自然延伸。

参考：LangGraph 官方文档、容错与优雅停机、事件流

附：题外话——我试过的 LangChain 知识图谱（不是 LangGraph）

如实交代：写《Langchain-Graph实战教程》那篇笔记时，我把两个 “Graph” 搞混了——LangChain 的 Knowledge Graph 功能和 LangGraph 是完全不同的东西。前者（GraphQAChain、NetworkXEntityGraph、LLMGraphTransformer）用图结构表示知识、做图谱问答；后者是工作流编排框架。一个是数据，一个是执行引擎。

不过那次实验的踩坑记录值得留档。当时用 LLMGraphTransformer（langchain_experimental）从文本构建内存知识图谱，写法如下（Tongyi 同样来自 langchain_community，属当时的旧写法）：

from langchain_community.llms import Tongyi
from langchain_community.graphs import NetworkXEntityGraph
from langchain_experimental.graph_transformers.llm import LLMGraphTransformer
from langchain_core.documents import Document

llm_for_graph = Tongyi(model_name="qwen-plus")

document_content = """
张三是北京大学的教授，他研究人工智能领域。
李四是张三的学生，他就读于清华大学，学习计算机科学。
王五是百度的工程师，百度是一家位于北京的科技公司。
"""
docs = [Document(page_content=document_content)]

llm_transformer = LLMGraphTransformer(llm=llm_for_graph)
graph_documents = llm_transformer.convert_to_graph_documents(docs)

final_graph = NetworkXEntityGraph()
final_graph.add_graph_documents(graph_documents)
for triple in final_graph.get_triples():
 print(triple)

两个结论：

GraphQAChain 对 NetworkXEntityGraph 支持不佳。当时直接 graph_qa_chain.run(question) 基本走不通——它内部按生成 Cypher 查询的思路工作，而内存图根本不支持 Cypher，一跑就抛错
手工三元组检索是可用的备选。绕开 Chain，直接从图里捞相关三元组当上下文，交给 LLM 回答：

def get_relevant_triples(graph, entity_name):
 """检索与某个实体相关的三元组"""
 lines = []
 for s, p, o in graph.get_triples():
 if entity_name in str(s) or entity_name in str(o):
 lines.append(f"({s}, {p}, {o})")
 return "\n".join(lines)

context = get_relevant_triples(final_graph, "张三")
# 再把 context 和问题拼进 prompt，交给 LLM 生成答案

另外说明：LLMGraphTransformer 至今还在 langchain_experimental 里，仍属实验性，别在生产上依赖它。我的判断：真要做知识图谱问答，直接上 Neo4j 配 GraphCypherQAChain；或者更轻的做法——三元组检索本质上就是 RAG 的一种上下文来源，没必要被"图谱"这个词吓住。

总结

LangGraph 的地基是三件套：StateGraph（状态机）、State（reducer 决定覆盖还是追加）、条件边（动态路由）。MessagesState 只是 Annotated[list, add_messages] 的官方打包
Agent 没有魔法：tool_calls → 执行 → ToolMessage 回填 → 二次调用，一行式封装做的就是在消息列表上转这一圈
ReAct 循环的图表达就三个部件：agent / tools 节点、should_continue 条件边、tools -> agent 回边
超出上下文窗口的活交给 Map-Reduce，图让流水线每一步可插拔
记忆的单位是 thread_id + checkpointer，内存版叫 InMemorySaver
上线前补齐三件事：timeout= 防卡死（注意只对 async 节点生效）、error_handler= 给失败留退路（Saga 补偿）、RunControl + drain 应对停机。重复的配置用 set_node_defaults 提到图级
长线程的 checkpoint 膨胀用 DeltaChannel 解决；应用层读流式输出优先用 version="v3" 的事件流，投影带类型且可多消费者并发读

先手写一遍循环、看懂消息怎么流，再谈一行式封装——这是全文的路线，也是我判断的入门 LangGraph 最不绕的路。

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

Tue, 08 Sep 2026 12:00:00 +0800

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

本文整合自同一个项目的三篇旧文（2025 年 3 月–4 月），代码、截图、结论都来自当时的真实记录，合并时只做整理和勘误，没有补写任何"当时应该是这样"的情节——包括没起作用的 memory。文中 ConversationSummaryBufferMemory 等 legacy memory API 已在 LangChain 1.0 移除，相应位置有版本注记，核心思路不受版本影响。

2025 年 3 月，我给自己做了一个订阅系统的 agent：定期抓取订阅的网站，对比前后两次抓到的内容，把 diff 交给 LLM，让它总结"这段时间到底更新了什么"，输出一份固定格式的 JSON 摘要（概要、关键点、字数、生成时间）。项目不大，一个月里却把 agent 开发最常见的两类坑各踩了一遍——提示词的坑，和长文本的坑。

先把两个贯穿全文的判断放在前面：

对人类差不多的提示词，对 agent 是天壤之别。 把"仅仅是时间的变化"扩成"时间或者数据的变化"，几个字的改动，让同一批模型、同一类数据上的输出从"全是噪音"变成"基本可用"。
超长文本靠 map-reduce 式分块，不靠记忆机制。 diff 超出 token 上限时，按变更单元切块、逐块抽取、最后汇总——朴素，但真的解决问题。中间版本引入过的"记忆机制"，如后文坦白，在实际代码路径里基本是装饰。

全文按时间线组织：第一节是第一版管线的完整代码；第二节是提示词踩坑与迭代的全过程，含双模型前后对照截图；第三节是超长 diff 的分块处理；第四节把散在代码里的工程取舍集中成一份清单。

一、第一版管线：从 PromptTemplate 到 JSON 解析

输入与输出

业务的输入只有一样东西：contentdiff——前后两次抓取的差异文本，形如：

"Changed: '旧文本' -> '新文本'", "Added: '新增的段落'", "Deleted: '被删掉的段落'"

由于文本长度的限制，历史全文不可能都给模型，只给当前这次更新的差异。输出是固定结构的 JSON，先用一个 dict 把形状定下来：

SUMMARY_TEMPLATE = {
 "summary": {
 "content": "",
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 },
 "status": "success",
 "error_message": None
}

SubscriptionAgent：提示、组链、解析

第一版的完整骨架。LLM 来自项目内部模块 src.agent.llm 的 get_ali_llm——它做的事就是返回一个 LangChain 兼容的模型实例，等价写法附在本节末尾：

from langchain.prompts import PromptTemplate
import json

from src.agent.llm import get_ali_llm


class SubscriptionAgent:
 def __init__(self, llm_model=None):
 self.llm = llm_model if llm_model else get_ali_llm("qwen-7b-chat")
 # 冒烟测试：先 invoke 一句"你好"，确认 LLM 连得上
 print(self.llm.invoke("你好"))

 self.prompt_template = PromptTemplate(
 input_variables=["contentdiff"],
 template="""
 你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 {contentdiff}

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算总字数
 返回结果使用中文

 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": "",
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}
 """
 )

 self.chain = self.prompt_template | self.llm

三个点值得停下来看：

PromptTemplate 用 input_variables 声明动态变量，模板里 {contentdiff} 占位。要留心 JSON 花括号必须写成 {{ }} 转义，否则会被当成变量占位符。
self.prompt_template | self.llm 就是 LCEL 的组链写法：| 两侧只要是 Runnable，拼起来就是一条链。invoke 时 PromptTemplate 先把变量填进模板，产出的字符串直接喂给 LLM，返回一个带 .content 的消息对象。0.1 之前要写 LLMChain(prompt=..., llm=...)，现在一行管道就替代了。
invoke 的输入是字典，key 必须和 input_variables 匹配——传 {"contentdiff": ...}，不是裸字符串。

解析和兜底在 generate_summary 里：

 def generate_summary(self, contentdiff: str) -> dict:
 try:
 result = self.chain.invoke({"contentdiff": contentdiff}).content

 parsed_result = json.loads(result)
 summary_content = parsed_result["summary"]["content"]
 key_points = parsed_result["summary"]["key_points"]
 word_count = parsed_result["summary"]["word_count"]
 generated_at = parsed_result["summary"]["generated_at"]

 response = SUMMARY_TEMPLATE.copy()
 response["summary"]["content"] = summary_content
 response["summary"]["key_points"] = key_points
 response["summary"]["word_count"] = word_count
 response["summary"]["generated_at"] = generated_at
 return response

 except Exception as e:
 error_response = SUMMARY_TEMPLATE.copy()
 error_response["status"] = "error"
 error_response["error_message"] = f"Error on line {e.__traceback__.tb_lineno}: {str(e)}"
 return error_response

流程很直白：跑链、json.loads 直解、把字段填进模板；任何一步炸了就整体降级成 status="error" 的结构返回，不向上抛异常。这里有个隐患：SUMMARY_TEMPLATE.copy() 是浅拷贝，嵌套的 summary 字典是共享的——当时没暴露问题，是因为成功路径每次都把四个字段全覆盖了一遍。复用这段代码的话，用 copy.deepcopy 或者每次构造新 dict 更稳。

用一段玩具 diff（“The quick brown fox jumps over the lazy dog” 那种）喂进去，跑通的输出长这样（原文记录的示例）：

{
 "summary": {
 "content": "内容从'quick'改为'swift'，'jumps'改为'leaps'，新增'quickly'。",
 "key_points": ["quick -> swift", "jumps -> leaps", "新增 quickly"],
 "word_count": 18,
 "generated_at": "2025-03-13T10:00:00"
 },
 "status": "success",
 "error_message": null
}

get_ali_llm 的等价写法——任何 OpenAI 兼容端点都适用（这也是项目后期脚本里的实际写法）：

from langchain_openai import ChatOpenAI
import os

def get_ali_llm(model: str = "qwen-7b-chat"):
 return ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model=model,
 )

当时已知的软肋与对策

第一版最明显的软肋是 LLM 不一定严格按 JSON 格式返回。当时的对策有三条：

解析器上链。 把 SimpleJsonOutputParser 挂在链尾，输出自动解成 dict，不用再手写 json.loads：

from langchain_core.output_parsers.json import SimpleJsonOutputParser

self.chain = self.prompt_template | self.llm | SimpleJsonOutputParser()
result = self.chain.invoke({"contentdiff": contentdiff})

重试。 LCEL 的 Runnable 自带 .with_retry()：

result = self.chain.with_retry(stop_after_attempt=3).invoke({"contentdiff": contentdiff})

后来实际落地时用的是外层循环重试（第三节脚本里的写法），重试间隔和日志更好控制，两种都可行。

异步。 同步 invoke 在高频场景是瓶颈，链本身支持 ainvoke，接口不用改。

管线能跑，只说明"能返回 JSON"；JSON 里装的是不是想要的内容，是另一回事——这就是下一节踩的坑。

二、提示词踩坑：一字之差的质变

我之前一直认为，只要模型好，提示词随便写一写，模型都能返回差不多的内容。实际上，对于人来说是差不多的，因为人的大脑可以进一步理解内容。但是，如果开发 agent 就不一样了！！！

这段话是当时记下的，现在仍然是我对提示词工程最重要的体会。这节把整个过程原样重放一遍。

误判现场

当时我在开发这个订阅系统的 agent，任务是给它一些内容，让它总结这段时间更新了什么。由于文本长度的限制，不可能把历史文本都给它，只给当前更新的差异。

然后遇到了一个问题，对于下面的差异文本：

"[""Changed: '53 分钟' -> '1 小时'"", ""Changed: '1' -> '2'"", ""Changed: '3' -> '4'"", ""Changed: '3' -> '4'"", ""Changed: '4' -> '5'"", ""Changed: '4' -> '5'""]"

人一眼就能看出来，这个内容实际上是没有变化的，因为变化的只不过是网站上内容的间隔时间，但是 agent 却认为有变化。 我的提示词如下写道——这版已经带上了"注意"段，专门提醒模型忽略纯时间变化（第一版连这个都还没有）：

你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 {contentdiff}

 注意，有些内容的更新可能仅仅是由于时间的变化，比如[""Changed: '33' -> '40'"", ""Changed: '58 分钟' -> '1 小时'""]，这样的内容更新是不需要总结的，可以看作没有更新

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算内容的列表长度
 返回结果使用中文,如果内容更新或者没有关键点，请返回空数组。
 请根据以上要求，总结出订阅内容的更新情况，并返回结果。


 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": [],
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}


 """

然后看 qwq-32b 和 grok3 的输出：

可以看到他们都没给我想要的输出——我想要的就是一个空的数组，因为没有更新，但它们给我返回的是……

关键改动

然后我把提示词改成这样：

你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 {contentdiff}

 注意，有些内容的可能仅仅是时间或者数据的变化，这样的内容更新是不需要总结的，可以看作没有更新，返回空数组

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算内容的列表长度
 返回结果使用中文,如果内容更新或者没有关键点，请返回空数组。
 请根据以上要求，总结出订阅内容的更新情况，并返回结果。


 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": [],
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}

就这一点点的改动：

注意，有些内容的可能仅仅是时间或者数据的变化，这样的内容更新是不需要总结的，可以看作没有更新，返回空数组

但是效果：

我感觉没什么问题。

第二轮：真实 diff 再验证

再来试试其他的——这次直接上真实抓取的 diff，数据原样贴出（它也是第三节要处理的"超长输入"的真实模样）：

你是一个订阅号运营专家，可以根据差异内容总结出订阅内容的更新情况，请对以下内容差异进行总结：
 "[""Changed: '2' -> '33'"", ""Changed: 'Fl' -> 'Andr'"", ""Changed: 'we' -> 'id Studio集成Gemini新增多模态功能，开发者可上传图像获取UI代码\n谷歌最新宣布，And'"", ""Changed: ' Labs 颠覆AI' -> 'oid Studio中的Gemini助手已升级支持多模态输入功能，开发者现在可以直接将图像附加到提示中，以获取'"", ""Added: '程序开发过程中的视觉辅助。这项多'"", ""Added: '态功能最初在I/O2024大会上亮相，升级后的Gemini现能够\""理解简单的线框，并将其转换为可用的Jetpack Compose代码\""。在Android Studio Narwal的Canary版本中，Ask Gemini字段新增了\""附加图像文件\""（支持JPEG或PNG格'"", ""Changed: '，2' -> '）选项。谷歌建议用户使用具有\""强烈色彩对比\""的图像并提供\""清晰的提示\""以获得最佳效果。开发者可以上传从简单线框到高保真模型\n58 分钟前\n.\nAIbase\n北京新增'"", ""Changed: '60万美元打造首个全开放混合计算平台\n' -> '4款已完成登记的生成式AI服务，小米AI搜索、Monica在列\n网信北京发布了最新北京市生成式'"", ""Changed: '正在以前所未' -> '服务已登记信息公告，公称，根据《生成式人工智能服务管理暂行办法》及'"", ""Changed: '的速度融入我们的日常' -> '关规定，对于通过API接口或其他方式直接调用已备案大模型能力的生成式人工智能'"", ""Changed: '，而一家名为Flower Labs的初创公司正以革命性的' -> '或功能，采用登记管理'"", ""Changed: '改变AI模型的部署和运行方' -> '，允许上线提供服务。截至3月14日，我市新增34款已完成登记的生成'"", ""Changed: '。这家获得Y C' -> '人工智能服务，累计已完成46款生成式人工智能服务登记。其中，小米AI搜索、小米AI写作、M'"", ""Changed: 'mb' -> 'n'"", ""Deleted: 'nator支持的新锐企业近日推出了Flower Intelligen'"", ""Changed: 'e，一个创新的分布' -> 'a等产品在列。已上线的生成'"", ""Deleted: '云平台，专为在移动设备、个'"", ""Changed: '电脑和网络' -> '工智能'"", ""Added: '或功能，应在显著位置或产品详情页面，公示所取\n1 小时前\n.\nAIbase\n阿里通义实验室语音团队负责人鄢志杰离职\n据tech星球消息，阿里通义实验室语音团队负责人鄢志杰已于 2 月 15 日正式离职，其职级为阿里原P序列体系'"", ""Changed: '提供AI模型服务而设计。Flower Intelligence的核心优势在于其独特的混合计算策略。该平台允许应用程序在本地设备上运行AI模型，既保证了速度，又增强了隐私保护。当需要更强大的计算' -> '的P10 级别。鄢志杰是智'"", ""Changed: '力时，系统会在获得用户同意的情况下，无\n7 分钟前\n.\nAIbase\n调查：5' -> '语音领域专家， '"", ""Changed: '%美国成' -> '003 '"", ""Changed: '人使用过AI聊天机器人\n美国埃隆大学的一项调查显示，52%的美国成年人都曾使用过像ChatGPT、Gemini、Claude这样的AI' -> '进入中科'"", ""Changed: '言模型。这项由北卡罗来纳州埃隆' -> '音实验室攻读博士，师从科'"", ""Changed: '学“想象数字未来中心”在1月份开展的调查，选取了5' -> '讯飞创始人王仁华教授。 2'"", ""Changed: '名受访者。结果' -> '8 年获博士学位后，他在微软亚洲研究院语音组担任主管研究员至 2015 年，主要研究语音识别、语音合成等领域。学术上，他'"", ""Deleted: '现，在使用过AI的人群中，34%的人'"", ""Changed: '示至少每天会使用一次大语言模型。其中，ChatGPT最受欢迎，72%的受访者都用过;谷歌的Gemini位居第二，使用率为50% ' -> '多篇顶级论文，拥有多项专利'"", ""Deleted: '越来越多的人开始和AI聊天机器人建立起特殊的关系。调查显示，38%的用户认为大语言模\n'"", ""Changed: '7 分钟前\n.\nAIbase\n北京将在中小学打造' -> '0'"", ""Changed: '1个人工' -> '5 年加入阿里巴巴后，鄢志杰曾担任IDST'"", ""Changed: '应用场景，启动7个\""京娃\""智能体\n据央视新闻报道，北京市教委宣布，今年将在中小学重点打造首批' -> '语音交互\n'"", ""Changed: '1个人工智能应用场景，并启动培育建设7个\""京娃\""智能体，旨在以人工智能技术赋能五育融合培养体系，助力学生个性化、多样化发展。这些应用场景涵盖了\""AI助教\""的智能备课、智能课堂质量监测、智慧作业/命题;\""AI助学\""的智能错题分析及资源推荐、自主写作批改、外语学习助手;\""AI助育\""的智慧体育、心理健康助手;\""AI助评\""的智慧综合素质评价;\""AI助研\""的智能教师专业发展平台;以及\""AI助管\""的智慧校园。随着场景落地，7个各具\n39 分钟前\n.\nAIbase\n百万成本揭秘LLM训练黄金法则，阶跃星辰推出全领域适用的超参数优化工具\n在人工智能的激烈竞争中，一场耗资百万美元的大规模实验正悄然改变着大语言模型的训练方式。阶跃星辰研究团队日前发布重磅研究成果，他们通过耗费近100万NVIDIA H800GPU' -> ' '"", ""Deleted: '的算力，从零开始训练了3，700个不同规模的模型，累计训练了惊人的100万亿个token，揭示出一条被称为\""Step Law\""的普适性缩放规律，为大语言模型的高效训练提供了全新指南。这项研究不仅仅是对超参数优化的探索，更是第一个全面考察模型最优超参在不同形状、稀疏度和数据分布下稳定性的工作。研究结果表明，无\n55 分钟'"", ""Changed: 'AI“天眼”再进化！YOLOE破壳而出：' -> '论文阅读噩梦'"", ""Deleted: '物体检测“刻板印象”，万物皆可实时识别'"", ""Changed: '\n曾几何时，AI的“眼睛”还带着厚重的“滤镜”，只能识别预设好的“剧本”。 但现在，游戏规则彻底改写! 一种名为YOLOE的全新AI模型破空问世，它像一位打破枷锁的“视觉艺术家”，挥别了传统物体检测的“僵化教条”，宣告了一个“万物皆可实时识别”的全新纪元! 想象一下，AI不再需要“死记硬背”类别标签，而是像人类一样，仅凭文本描述、模糊图像，甚至在毫无线索的情况下，就能“秒懂”眼前的一切。 这种颠覆性的突破，正是YOLOE带来的震撼变革!YOLOE的' -> 'AI神器'"", ""Changed: '，宛' -> '： arXiv论文一键变博客，科研效率火箭式飙升！\n你是否还在论文的海洋里苦苦挣扎?面对学术网站 arXiv 上堆积'"", ""Changed: '给AI装上\n1' -> '山的论文，是不是也感到头皮发麻，无从下手? 那些晦涩难懂的术语，曲折冗长的段落，复杂烧脑的图表，简直像一道道 impenetrable 的高墙，将求知的心牢牢阻隔在外。 对于科研爱好者、莘莘学子，甚至是专业人士来说，啃下一篇论文，往往需要耗费数小时的精力，甚至要查阅海量资料才能勉强摸到门道，这效率，简直让人抓狂!但!是! 所有挣扎，都将成为过去式! 一款横空出世的AI神器—— alphaXiv，要来彻底拯救你于论文苦海!\n3'"", ""Changed: '英国首相计划' -> '一男子因'"", ""Changed: 'AI替代部分公务员工作\n英国' -> ' AI 撰写色情小说被判刑十个月，非法获利超两万元\n近期，湖北省大冶市人民法院对一起'"", ""Changed: '相基尔・斯塔默（Keir Starmer）近日提出了一项新的计划，旨在通过数字化和' -> '例利用'"", ""Deleted: '来提高政府工作的效率。他将在周四的演讲中详细阐述这一构想，表示希望能够在公务员的工作中，尽可能地用数字化和 AI 替代那些可以以相同标准完成的任务。他强调，公务员的时间应该优先用于更需要人类判断和创造力的工作。斯塔默认为，英国政府通过更广泛地采用数字化方法，可以在未来节省超过 450 亿英镑的开支，并计划招募 2000 名新的'"", ""Changed: '学' -> '撰写色情小说并进行牟利的案件作出判决。被告人柯某因制作、贩卖、传播淫秽物品牟利罪，被判处有期'"", ""Changed: '来充实公务员队伍。他表示，这些措\n1 小时前\n.\nAIbase\n英矽智能完成1.1亿美' -> '刑十个月，并处罚金人民币五千'"", ""Changed: 'E轮融资 推动AI平台升级\n今日，英矽智能，一家专注于生成式人工智能技术的生物医药科技公司，正式对外宣布，已成功完成1.1亿美元的E轮融资。本轮融资由惠理集团（HKG:0806）旗下的私募股权基金、浦东创投、浦发集团、锡创投以及宜兴国控联合领投。此外，' -> '，退'"", ""Changed: '有多位专注于行业和科技领域的新晋投资者参与本轮融资，同时' -> '违法所'"", ""Changed: '到了现有投资者的鼎力支持。\n1 小时前\n.\nAIbase\n报道称MiniMax 意向收购AI视频创业公司鹿影科技\n' -> '。'"", ""Changed: '蓝鲸新闻独家消息' -> '公诉机关的'"", ""Changed: '出，人工智能视频初创公司鹿影科技（Avolution.ai）或将被知名人工智能公司MiniMax收购。据多位知情人士透露，双方已就收购达成初步意向，相关流程正在进行中。截至发稿，MiniMax尚未对此消息做出回应。据悉，鹿影科技' -> '控，柯某'"", ""Changed: '4' -> '2'"", ""Deleted: '天使轮融资时的估值约为'"", ""Changed: '亿人民币左右，低于2000万美元。知情人士表示，鹿影科技自去年起寻求第二轮融资并不顺利，而其在AI视频领域的技术积累最终促成了与MiniMax的合作，这被认为是双赢的选择。公开资料显示，鹿影科技成立于' -> '1月至'"", ""Changed: '9' -> '3'"", ""Changed: '\n2' -> '期间，作为一名大专文化的网络文学作者，利用 AI 程序撰写色情小说，并通过在境外黄色网站上发布，同时在其他网站进行销售。在短短五个月的时间内，柯某发布了数十篇色情小说，非法获利超过两万元。检方送检的\n3'"", ""Added: 'AI助力房地产市场'"", ""Changed: '讯' -> '飞，预计2030年规模将达1803.45亿美'"", ""Changed: '宝' -> '\n全球人工智能（AI）在房地产市场的应用正在迅速崛起，预计到2030年将达到1803.45亿美元，年均增长率高达35%。这一市场的快速发展得益于机器学习、预测分析等技术的进步，以及房地产管理对自动化的日益需求。在这一市场中，主要参'"", ""Changed: '腾讯' -> '者包括 Zillow 集团、Compass、Redfin 公司和 Reonomy 等。它们正在利用 AI 驱动的工具，提升客户体验，并优化物业管理流程。图源备注：图片由AI生成，图片授权服务商Midjourney美国市场是该领域的佼佼者，因其 AI 技术的快速采纳和健全的房地产基础设施。近期，\n4 小时前\n.\nAIbase\nOpenAI Chat Playground升级为Prompts Playground 更好测试、迭代提示词\nOpenAI 宣布，其广受欢迎的 Chat Playground 正式升级并更名为 Prompts Playground。这一更新带来了全新的设计和功能，旨在为用户提供更强大的工具，以便更好地测试、比较和迭代提示（prompts）。根据 OpenAI 在 X 平台上的最新介绍，此次重新设计整合了包括 Web 搜索和'"", ""Changed: '档打通' -> '件搜索在内的高级工具，进一步提升了用户体验和创作灵活性。据 OpenAI 开发团队透露，Prompts Playground 的核心目标是让用户能够更高效地探索和优化 AI 模型的交互方式。除了保留原有的对话功能外，新平台还允许用户保存和共享特定\n4 小时前\n.\nAIbase\nSesame发布CSM模型'"", ""Changed: '支持一键上传和导出为腾讯文档' -> '实时情感定制 AI语音合成迈向新高度'"", ""Changed: '腾讯' -> 'Sesame公司推出其最新语音合成模型CSM，引发业界关注。据官方介绍，CSM采用端到端基于Transformer的多模态学习架构，能够理解上下文信息，生成自然且富有情感的语音，声音效果贴近真人，令人惊艳。该模型支持实时语音生成，可处理文本和音频输入，用户还能通过调整参数控制语气、语调、节奏及情感等特性，展现高度灵活性。CSM被认为是AI语音技术的重要突破。其语音自然度极高，甚至“无法分辨是人工合成还是真人”。有用户录制视频展示CSM几近无延迟的表现，称其为“体验\n4 小时前\n.\nAIbase\nAnthropic、IBM 和 Meta 的技术领导者警告称，人工智能将取代软件开发人员的工作\n在最近一次国际会议上，Anthropic 首席执行官达里奥・阿莫迪（Dario Amodei）发表了一个引人注目的预测，他认为人工智能将在未来三到六个月内承担90% 的代码编写工作。阿莫迪表示，如果这一趋势持续下去，到了12个月后，AI 可能将几乎完全取代人类程序员的工作。他指出，尽管程序员仍需为 AI 设定特定的条件和目标，但未来这一过程也可能被技术所取代。阿莫迪认为，尽管人工智能将逐渐取代人类的某些工作，但这也将促使我们重新审视人力资源的有效利用。他指出，当前的思维模式已\n5 小时前\n.\nAIbase\n巨人网络发布行业首个DeepSeek原生游戏玩法 太空杀推出内鬼挑战\n巨人网络'"", ""Changed: '智' -> '社交推理游戏《太空杀》正式接入DeepSeek大模型，并推出基于该技术的原生游戏玩法“内鬼挑战”，目前该玩法已开启灰度测试，后续将面向全量用户开放。这标志着业内首次将DeepSeek大模型'"", ""Changed: '助手腾讯元宝与腾讯文档实现' -> '力'"", ""Changed: '打通，这一升级为' -> '应'"", ""Changed: '户带来了更加便捷高效的办公' -> '于游戏玩法创新，以AI驱动游戏核心玩法，重塑游戏的竞技和交互'"", ""Changed: '，有望改变现有的办公协作模式。在以往的工作场景中，用户需要在文档编辑与智能助手之间频繁进行复制粘贴操作，流程繁琐且易出错。而此次腾讯元宝的升级，成功解决了这一痛点。上传指引:移动端点击右下角“+”后选择腾讯文档;Web端点击“上传文档-上传腾讯文档”;现在，用户不仅可以从元宝一键上传腾讯文档，支持表格、文档、PPT、PDF、思维导图等多种格式，无需\n2 小时前\n.\nAIbase\nLuma开源图像模型预训练技术IMM 采样效率提高10倍\n人工智能初创公司Luma近日在X平台宣布，其开源了一项名为Inductive Moment Matching（IMM）的图像模型预训练技术。这一突破性技术以其高效和稳定的特性引发了广泛关注，被认为是生成式AI领域的一次重要进步。据X用户linqi_zhou透露，IMM是一种全新的生成范式，能够以单模型和单一目标从零开始稳定训练，同时在采样效率和样本质量上超越传统方法。他在帖子中兴奋地表示:“IMM在ImageNet256×256上仅用8步就达到了1.99FID（Fréchet Inception Distance），在CIFAR-10上仅用2步就达到了1.98FID。”这一性能不仅刷' -> '。'""]"

 注意，有些内容的可能仅仅是时间或者数据的变化，这样的内容更新是不需要总结的，可以看作没有更新，返回空数组

 要求：
 1. 提供简洁的内容更新概要
 2. 提取关键点
 3. 计算内容的列表长度
 返回结果使用中文,如果内容更新或者没有关键点，请返回空数组。
 请根据以上要求，总结出订阅内容的更新情况，并返回结果。


 返回格式json（请严格按照以下格式返回）：
 {{
 "summary": {{
 "content": [],
 "key_points": [],
 "word_count": 0,
 "generated_at": ""
 }},
 }}


 """

这个感觉也没什么问题，qwq-32b 的效果更好。

复盘

对照两版提示词，实质是三处改动：

范围从"时间的变化"扩成"时间或者数据的变化"——Changed: '1' -> '2' 这种裸数字变化终于被覆盖；
删掉了举例——现在回看，那两个时间变化的例子反而把模型的理解锚死在字面上的时间字符串，裸数字就漏了出去；
把"返回空数组"这个动作直接缀在"可以看作没有更新"后面——判断和行为写在同一句里，不靠模型自己把两段话联系起来。

验证也是从这次开始分两步走：先用构造的最小样例确认"该空的时候空不空"，再用真实数据回归"该有的时候有没有"。只测前者，会漏掉把真实更新也判成"没有更新"的过头修正。

三、超长文本：按变更单元分块，map-reduce 汇总

进入四月，新的问题来了：真实抓取的 diff 越来越长，一次全塞给模型开始顶不住 token 上限。这一节的完整可执行脚本放在本文同目录：解决上下文过长.py，下面讲思路，代码有删节（去掉了日志行），完整版直接看文件。

模型换成 Dashscope 上的 qwen-plus，走 OpenAI 兼容端点：

pip install langchain-core langchain-openai pydantic openai
export DASHSCOPE_API_KEY="你的密钥"

输出结构：从手写 dict 到 Pydantic

第一版的手写 SUMMARY_TEMPLATE 升级成了 Pydantic 模型，多了 url_list（每个关键点对应的 URL 二维数组）和 raw_response（LLM 原始响应存档）两个字段：

from pydantic import BaseModel, Field
from typing import List, Optional

class SummaryResponse(BaseModel):
 content: List[str] = Field(default_factory=list, description="内容更新摘要")
 key_points: List[str] = Field(default_factory=list, description="关键点列表")
 url_list: List[List[str]] = Field(default_factory=list, description="每个关键点对应的URL列表")
 word_count: int = Field(default=0, description="内容的总字数")
 generated_at: str = Field(default="", description="生成时间戳")
 status: str = Field(default="success", description="处理状态")
 error_message: Optional[str] = Field(default=None, description="错误信息（如有）")
 raw_response: Optional[str] = Field(default=None, description="LLM原始响应")

解析器换成 PydanticOutputParser：结构、类型、默认值都在一处定义，get_format_instructions() 直接生成 JSON 格式说明，用 partial_variables 注进提示词——不用再手抄一遍"请严格按照以下格式返回"的模板：

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from langchain_openai import ChatOpenAI

self.llm = ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model="qwen-plus",
)
self.parser = PydanticOutputParser(pydantic_object=SummaryResponse)
self.prompt_template = PromptTemplate(
 input_variables=["contentdiff"],
 partial_variables={"format_instructions": self.parser.get_format_instructions()},
 template="""
 You are a subscription content expert. Summarize the following content differences:

 {contentdiff}

 ### Notes:
 - Ignore updates that are only time or data changes (return empty arrays).
 - Ensure content and key_points lists have a one-to-one correspondence.
 - url_list is a 2D array, each sublist contains URLs for the corresponding key point.

 ### Requirements:
 1. Provide content update summaries (content) as an array.
 2. Extract key points (key_points) for each content item.
 3. Extract URLs for each key point (url_list); return empty arrays if none.
 4. Calculate word count for content (Chinese/English characters only, no punctuation/spaces).
 5. Return results in Chinese if updates exist; otherwise, return empty arrays.
 6. Follow this JSON format:

 {format_instructions}
 """
)

提示词本身换成了英文，但 Notes 第一条就是第二节踩坑换来的那句——Ignore updates that are only time or data changes。几轮迭代下来的结论，直接固化进了代码。

主流程：token 估算与分块决策

def generate_summary(self, contentdiff: str) -> SummaryResponse:
 avg_token_per_char = 0.5
 estimated_tokens = len(contentdiff) * avg_token_per_char
 if estimated_tokens > self.max_token_limit:
 return self.generate_summary_with_memory(contentdiff) # 超限走分块路径
 # 未超限：直接一条链处理

token 数不引 tokenizer，拿字符数乘 0.5 粗估。这个数不需要准——它只服务"要不要分块"这一个二元决策。宁可把 max_token_limit 设得比模型实际上限低一截，让估算误差只往"多分一块"的方向错，而不是该分没分、请求直接撞上下文上限。

分块策略：优先变更单元，字符数兜底

contentdiff 的结构天然适合按语义边界切：每条变更都是一个 ""Changed: ..."" / ""Added: ..."" / ""Deleted: ..."" 单元。固定字符切分会把一条变更从中间切断，半截单元对模型是纯噪音，还容易诱导出半句幻觉。所以正则优先按变更单元攒包，实在匹配不到单元（比如输入根本不是 diff 格式）才按字符数硬切兜底：

def chunking_content(self, contentdiff: str) -> List[str]:
 avg_token_per_char = 0.5
 if len(contentdiff) * avg_token_per_char <= self.max_token_limit:
 return [contentdiff]

 chunks = []
 change_units = re.findall(r'""(?:Changed|Added|Deleted):.*?"",', contentdiff, re.DOTALL)

 if not change_units:
 # 兜底：没有变更单元，按字符数硬切
 chars_per_chunk = int(self.max_token_limit / avg_token_per_char)
 for i in range(0, len(contentdiff), chars_per_chunk):
 chunks.append(contentdiff[i:i + chars_per_chunk])
 else:
 # 优先：按变更单元攒包
 chars_per_chunk = int(self.max_token_limit / avg_token_per_char)
 current_chunk = ""
 for unit in change_units:
 if len(current_chunk) + len(unit) > chars_per_chunk:
 chunks.append(current_chunk)
 current_chunk = unit
 else:
 if current_chunk:
 current_chunk += "\n"
 current_chunk += unit
 if current_chunk:
 chunks.append(current_chunk)
 return chunks

map：逐块抽取

每个块用一个简单的 chunk_prompt 抽 content / key_points / urls，三个 collected 列表各自累积。单块失败只跳过该块，不炸全局：

for i, chunk in enumerate(content_chunks):
 chunk_prompt = PromptTemplate(
 input_variables=["chunk_content"],
 template="""
 Analyze the following content difference chunk:

 {chunk_content}

 Provide in JSON format:
 1. content: List of content update summaries
 2. key_points: List of corresponding key points
 3. urls: List of URLs (2D array)

 Return only JSON, no extra text.
 """
 )
 chunk_chain = chunk_prompt | self.llm
 try:
 chunk_result = chunk_chain.invoke({"chunk_content": chunk})
 chunk_content = chunk_result.content if hasattr(chunk_result, 'content') else str(chunk_result)
 json_match = re.search(r'\{.*\}', chunk_content, re.DOTALL)
 if json_match:
 chunk_json = json.loads(json_match.group(0))
 if 'content' in chunk_json and isinstance(chunk_json['content'], list):
 collected_content.extend(chunk_json['content'])
 if 'key_points' in chunk_json and isinstance(chunk_json['key_points'], list):
 collected_key_points.extend(chunk_json['key_points'])
 if 'urls' in chunk_json and isinstance(chunk_json['urls'], list):
 collected_urls.extend(chunk_json['urls'])
 memory.save_context(
 {"input": f"Chunk {i+1}:\n{chunk[:200]}..."},
 {"output": f"Analysis:\n{chunk_content[:200]}..."},
 )
 except Exception as e:
 continue # 单块失败只跳过，不炸全局

reduce：汇总成最终结果

所有块处理完，把三个 collected 列表交给 final prompt，让模型合并、去重，生成最终的 SummaryResponse：

final_prompt_template = PromptTemplate(
 input_variables=["collected_content", "collected_key_points", "collected_urls", "format_instructions"],
 template="""
 Generate a final summary from the collected information:

 Content updates: {collected_content}
 Key points: {collected_key_points}
 URLs: {collected_urls}

 Return JSON in this format:

 {format_instructions}

 Notes:
 1. Ensure content and key_points correspond one-to-one.
 2. url_list is a 2D array for each key point's URLs.
 3. Calculate word_count (characters, no punctuation/spaces).
 4. Merge or remove duplicate content.
 5. Return only JSON.
 """
)
final_chain = final_prompt_template | self.llm
raw_response = final_chain.invoke({
 "collected_content": collected_content,
 "collected_key_points": collected_key_points,
 "collected_urls": collected_urls,
 "format_instructions": self.parser.get_format_instructions(),
})

解析成功后还有一层本地兜底——能本地算的字段不依赖模型：

response = self.parser.parse(self.extract_json(raw_content))

if not response.generated_at:
 response.generated_at = datetime.now().isoformat() # 时间戳本地填，不信模型
if response.word_count == 0 and response.content:
 response.word_count = len("".join(response.content).replace(" ", "").replace(",", "").replace(".", ""))
if len(response.url_list) < len(response.key_points):
 for _ in range(len(response.key_points) - len(response.url_list)):
 response.url_list.append([]) # 补齐一一对应
response.raw_response = raw_content # 永远存原文，排查不用重跑

容错与重试

模型偶尔会在 JSON 前后裹话（“以下是总结：…“之类），裸 json.loads 直接炸。extract_json 用一个贪婪的 \{.*\}（DOTALL）把最外层花括号之间的内容抠出来再交给解析器：

def extract_json(self, raw_content: str) -> str:
 json_match = re.search(r'\{.*\}', raw_content, re.DOTALL)
 return json_match.group(0) if json_match else raw_content

重试是外层 while 循环，直接路径和最终汇总两条路径各挂一个，间隔 retry_delay 秒。所有重试耗尽也不抛异常——返回一个 status="error" 的 SummaryResponse，下游拿到的永远是合法结构，错误本身也是数据：

retries = 0
while retries < self.max_retries:
 try:
 raw_response = chain.invoke({"contentdiff": contentdiff})
 response = self.parser.parse(self.extract_json(raw_response.content))
 ...
 return response
 except Exception as e:
 retries += 1
 if retries < self.max_retries:
 time.sleep(self.retry_delay)
# 重试耗尽：返回带错误信息的合法结构
return SummaryResponse(status="error", error_message=f"Failed to parse SummaryResponse: {e}", ...)

演示的时候把 max_token_limit 调到 300 就能强制走分块路径，不用真造一份 3 万 token 的输入。

如实交代：memory 并没有真正生效

原文的标题把这部分叫"记忆机制处理超长文本”，但合并这篇的时候要如实交代两件事：

__init__ 里初始化的 self.memory，在当前实现里从未被 generate_summary 真正使用——真正干活的是 generate_summary_with_memory 里局部新建的另一个实例。
局部 memory 也只做了 save_context——把每块输入/输出的前 200 个字符存进去，理论上为后续块提供上下文。但实际每个块的处理是相对独立的：把结果串起来的是代码里的三个 collected 列表，最终汇总读的也是它们，不是 memory。

所以这套流程的本质就是 map-reduce：map 是逐块抽取，reduce 是最终汇总。要复现的话，把 memory 相关代码整个删掉，主流程不受影响。

⚠️ 版本注记：ConversationSummaryBufferMemory 来自 langchain.memory，属于 legacy memory 体系，LangChain 1.0 已将其整体移除。现在的等价做法是 LangGraph 的 checkpointer（线程级持久化）或对消息列表做裁剪/摘要。这里保留原样，是为了如实记录当时的选择。

四、工程细节清单

把散在代码里的取舍集中列一遍：

细节	做法	取舍
重试	直接路径与汇总路径各挂一个外层 while 循环 + `time.sleep(retry_delay)`	直观、间隔和日志可控；LCEL 的 `.with_retry(stop_after_attempt=3)` 一行可替换，脚本里实际落地的是循环写法
JSON 容错	`extract_json` 正则 `\{.*\}`（DOTALL）先抠 → `PydanticOutputParser.parse` 再校验	模型在 JSON 前后裹话时不至于炸；`raw_response` 永远存原文，排查不用重跑
token 估算	`len(contentdiff) * 0.5`	不引 tokenizer、零依赖；只服务"分不分块"的二元决策，把 `max_token_limit` 设保守点吸收误差
失败语义	重试耗尽不抛异常，返回 `status="error"` 的 `SummaryResponse`	下游拿到的永远是合法结构，错误也是数据

几个不起眼的小处理，一并记在这里：

generated_at 不信模型，本地 datetime.now().isoformat() 填；
word_count 为 0 且有 content 时本地重算（直接路径：拼接后去空格去逗号句号数长度）；
url_list 比 key_points 短就补空列表，保住一一对应；
每块抽取失败 continue 跳过，一块的失败不拖垮整份摘要。

还有一处坑，合并本文时验证过：脚本里 memory 路径的字数兜底写的是 re.sub(r'[\s\p{P}]', '', content_text, flags=re.UNICODE)——\p{P} 是 PCRE / regex 第三方库的语法，标准库 re 不认，这行会直接抛 re.error: bad escape \p（外层 try 会接住，触发无意义的重试）。要按原意去标点，得换 regex 库或手写标点集。直接路径的同名逻辑用的是 replace(" ", "").replace(",", "").replace(".", "")，土，但不会炸。

总结

这个项目从第一版管线到能吃下超长 diff，前后一个月，值得留下的结论就这几条：

提示词是 agent 的行为规格，不是写给人的备忘。 对人类差不多的提示词，对 agent 是天壤之别——“时间或者数据的变化"几个字的改动就是质变。改完之后，最小样例和真实数据各验证一轮，缺一不可。
长文本的正解是 map-reduce 分块。 按语义边界（变更单元）切块优先、字符数兜底，逐块抽取再汇总，朴素但有效；引入的"记忆机制"实际没起作用，如实记录比包装成"记忆驱动"更有参考价值。
结构化输出的可靠性靠工程兜底，不靠模型自觉。 容错解析、重试、永不抛异常的失败语义、raw_response 存档——这一层做好了，模型偶尔不听话只是重试一次的事。
模型选型：这个任务上 qwq-32b 比 grok3 表现更好。 样本很小，是个人判断，但它是双模型、双轮验证之后得出的。

溯源

本文整合自同一个项目的三篇旧文，按时间顺序：

《使用 LangChain 构建订阅内容更新总结智能代理》（2025-03-13）——并入本文第一节：第一版管线、SubscriptionAgent 逐段讲解、LLM 输出不一致的对策。
《提示词使用教程|工程应用实践》（2025-03-14）——并入本文第二节：误判问题、提示词改动前后对照、双模型验证截图与个人结论。
《08-内容分块 (chunking) 和记忆机制 (memory) 处理超出 LLM Token 限制的长文本》（2025-04-12）——并入本文第三节：分块策略、容错重试、可执行脚本解决上下文过长.py。

合并时做的处理，都列在这里：

原文一的 from langchain_core.retry import retry 是不存在的 API（当时的记录里混进了幻觉写法），合并版替换为 .with_retry() 与外层重试循环两种真实写法；get_ali_llm 是项目内模块，补了 ChatOpenAI + base_url 的等价写法。
原文三标题里的"记忆机制"如第三节坦白并未真正生效，合并版按实际代码路径写成 map-reduce 分块，并补了 legacy memory 的版本注记。
原文里被 Markdown 链接污染的 URL（base_url="[https://...](...)" 形式）已还原为纯 URL。
原文二的通用技巧小节（少样本提示等）与烂尾的"PUA大模型"小节没有并入正文；后者保存的 Windsurf（Codeium）系统提示词泄漏截图仍保留在 images/index/windsurf-system-prompt.png。

langchain_core 组件详解：Prompt 模板与 Output Parsers

Tue, 08 Sep 2026 11:30:00 +0800

langchain_core 组件详解：Prompt 模板与 Output Parsers

把一个 LangChain 应用拆到最小，真正绕不开的是一条链：prompt | llm | parser。prompt 决定喂给模型什么，llm 吐出一段自由文本，parser 再把文本变成程序能用的数据。langchain_core 把这条链的两头做成了两个模块——prompts 管输入侧，output_parsers 管输出侧。

这篇是这两个模块笔记的合并整理：输入侧讲 Prompt 模板家族怎么选、FewShot 怎么从固定示例进化到动态选例；输出侧讲五种常用解析器和解析失败后的 async 重试实战；解析报错的排查方法放在末尾。带运行输出和截图的部分来自我的实践记录，代码跑在 LangChain 0.3 时期的 langchain_core 上，个别老 API 的位置会标 ⚠️ 说明。

两个核心判断先放在这里：

输入侧默认 ChatPromptTemplate。 它吃一组消息、吐一组消息，和现代聊天模型的接口天然对齐；字符串版 PromptTemplate 退居二线，主要做内部格式化片段。
要结构化输出，优先 with_structured_output。 LangChain 1.x 时代的主流做法是把 schema 绑在模型上，走 tool calling 或 JSON mode 通道，结构由模型原生保证。PydanticOutputParser 这一族文本解析器是备选：模型不支持原生结构化输出，或需要把格式说明精确嵌进提示词时才用。但 format_instructions、解析、重试这套思路依然值得吃透——排查结构化输出问题时，最终都要回到这条最原始的链上。

一、Prompt 模板（输入侧）

langchain_core.prompts 解决的问题只有一个：把动态变量填进固定结构，生成模型输入。模板类有一族，日常主力只有一个。

ChatPromptTemplate：默认选择

ChatPromptTemplate 生成的不是一段字符串，而是一组结构化消息（List[BaseMessage]），正好对齐聊天模型的输入格式：

from langchain_core.prompts import ChatPromptTemplate

template = [
 ("system", "You are a helpful AI assistant named {name}."),
 ("human", "Tell me a joke about {topic}."),
]
prompt_template = ChatPromptTemplate.from_messages(template)

prompt = prompt_template.invoke({"name": "Grok", "topic": "dogs"})
print(prompt.messages)
# [SystemMessage(content='You are a helpful AI assistant named Grok.'),
# HumanMessage(content='Tell me a joke about dogs.')]

from_messages 接受 ("角色", "模板") 元组，也接受消息模板对象和占位符，可以任意混搭。日常写角色字符串就够了；SystemMessagePromptTemplate、HumanMessagePromptTemplate、AIMessagePromptTemplate 这些细粒度的类，只在需要程序化拼装单条消息时才用得上。

真正解决独立问题的类是 MessagesPlaceholder——往模板中间插一段动态消息列表，最典型的用途是对话历史：

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.messages import HumanMessage, AIMessage

chat_prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a helpful assistant."),
 MessagesPlaceholder(variable_name="history"),
 ("human", "{input}")
])

history = [
 HumanMessage(content="What's the weather like?"),
 AIMessage(content="It's sunny!")
]

prompt = chat_prompt.invoke({"history": history, "input": "What's the forecast tomorrow?"})
print(prompt.messages)
# [SystemMessage(...), HumanMessage(content="What's the weather like?"),
# AIMessage(...), HumanMessage(...)]

注意 variable_name 必须和 invoke 时传入的键一致，写模板时就对清楚。

Prompt 模板家族速查表

完整班底如下，大部分场景只用到前几行：

类	功能	适用场景
`ChatPromptTemplate`	构建对话消息列表，支持多角色	聊天机器人、多轮对话（日常默认）
`MessagesPlaceholder`	插入动态消息列表	对话历史、动态上下文
`PromptTemplate`	格式化字符串提示，支持动态变量	字符串模板、内部格式化片段
`FewShotChatMessagePromptTemplate`	把少样本示例格式化成对话消息	对话任务需要示例引导
`SystemMessagePromptTemplate`	系统消息模板	程序化拼装 system 消息
`HumanMessagePromptTemplate`	用户消息模板	程序化拼装 human 消息
`AIMessagePromptTemplate`	AI 回复模板	少样本对话、预置示例回答
`ChatMessagePromptTemplate`	自定义角色消息模板（如 `"Jedi"`）	非标准角色的创意对话
`FewShotPromptTemplate`	少样本示例，生成字符串	⚠️ 官方已标记 deprecated
`PipelinePromptTemplate`	组合多个子模板	⚠️ 已废弃

两个 deprecated 的类多说两句。FewShotPromptTemplate（字符串版少样本）官方已标记 deprecated，现代做法是 ChatPromptTemplate + FewShotChatMessagePromptTemplate 组合，再配 ExampleSelector 做动态选例（见下节）；PipelinePromptTemplate 原本用来嵌套组合多段子模板，同样废弃了，多段模板的组合用普通变量嵌套或 LCEL 就能解决，不再需要专门的类。

安全上有一条红线：字符串模板默认用 f-string 语法，PromptTemplate 也支持 jinja2，但不要用 jinja2 加载来源不可信的模板——jinja2 模板可以执行代码，是一个真实的注入面。没有特殊语法需求，留在默认的 f-string。

FewShot：从固定示例到动态选例

少样本提示的思路是用示例教模型任务模式。对话版写法是把示例格式化成 human/ai 消息对，作为一个整体嵌进主模板：

from langchain_core.prompts import FewShotChatMessagePromptTemplate, ChatPromptTemplate

examples = [
 {"question": "What is 2+2?", "answer": "4"},
 {"question": "What is 3+3?", "answer": "6"},
]

example_prompt = ChatPromptTemplate.from_messages([
 ("human", "{question}"),
 ("ai", "{answer}")
])

few_shot_prompt = FewShotChatMessagePromptTemplate(
 examples=examples,
 example_prompt=example_prompt
)

final_prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a math expert."),
 few_shot_prompt,
 ("human", "{input}")
])

prompt = final_prompt.invoke({"input": "What is 4+4?"})

固定示例有两个天然限制：示例一多就挤占上下文窗口，示例和当前输入不相关时还会稀释注意力。进阶做法是接一个 ExampleSelector，按语义相似度动态挑出与当前输入最相近的几条示例再拼进提示——等于把 RAG 的检索思路用在了示例库上，官方实现里 SemanticSimilarityExampleSelector 是最常用的一个。

我试过的玩法是把相近对话入库，请求时按相似度取回再传入 FewShot 模板，跑通后的效果：

具体代码：

这套做法的关键在示例库质量和 embedding 的匹配度，示例数量适中即可。再想提升效果，该调的是检索策略，不是往提示里硬塞更多示例。

二、Output Parsers（输出侧）

输出解析器负责把 LLM 的自由文本转换成结构化数据：从自然语言句子、JSON 字符串或列表里提取关键信息，转成 Python 对象、字典或列表这类程序友好的格式。没有它，每个应用都得自己写一遍"从文本里抠 JSON"的脏活，格式约定还会散落在提示词和解析代码两处，很难保持一致。

在链上的位置就是开头那条：

PromptTemplate → LLM → OutputParser

提示模板定义输入和输出格式要求，LLM 生成原始文本，解析器完成最后一步转换。输入侧要求什么格式，输出侧就得配对应的 parser，两头的约定靠 get_format_instructions() 生成的格式说明对齐。

五种常用解析器

解析器	干什么	典型场景
`StrOutputParser`	原样返回字符串	简单问答、文本生成
`JsonOutputParser`	解析为 JSON 字典	API 返回数据、键值对提取
`PydanticOutputParser`	解析为 Pydantic 模型	数据验证、复杂对象处理
`CommaSeparatedListOutputParser`	逗号分隔文本 → 列表	列表提取（选项、标签）
自定义 `BaseOutputParser`	自己实现 `parse`	特殊格式（分号分隔、表格解析）

下面五个示例共用同一个 llm 初始化（OpenAI 兼容接口，配置从 .env 读取），后文不再重复：

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

load_dotenv()
llm = ChatOpenAI(
 model=os.getenv("model"),
 api_key=os.getenv("api_key"),
 base_url=os.getenv("base_url"),
 streaming=True
)

StrOutputParser：什么都不做

最简单的解析器，直接返回字符串，不需要任何格式化指令：

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = PromptTemplate(template="今天是星期几？（假设今天是 2025 年 3 月 16 日）")
parser = StrOutputParser()

chain = prompt | llm | parser
response = chain.invoke({})
print(response)

输出：

今天是星期日。

JsonOutputParser：拿到字典

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import JsonOutputParser

parser = JsonOutputParser()
prompt = PromptTemplate(
 template="以 JSON 格式返回两种水果及其颜色。\n{format_instructions}",
 partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
response = chain.invoke({})
print(response)

输出：

{'apple': 'red', 'banana': 'yellow'}

get_format_instructions() 自动生成"请按 JSON 格式返回"的说明嵌进模板，提示和解析器的约定永远对得上。但硬约束不存在：LLM 输出的不是合法 JSON 时直接抛异常。

PydanticOutputParser：强类型 + 字段校验

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from pydantic import BaseModel, Field

class Book(BaseModel):
 title: str = Field(description="书名")
 author: str = Field(description="作者")
 year: int = Field(description="出版年份")

parser = PydanticOutputParser(pydantic_object=Book)
prompt = PromptTemplate(
 template="推荐一本书，并以指定格式返回。\n{format_instructions}\n推荐什么书？",
 input_variables=["question"],
 partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
response = chain.invoke({"question": "推荐什么书？"})
print(response)

输出：

Book(title='《活着》', author='余华', year=1993)

Pydantic 保证字段类型（year 必须是整数），格式化指令里还会带上每个字段的 description。get_format_instructions() 生成的说明长这样：

Please provide your response in the following JSON format:
{
 "title": "string",
 "author": "string",
 "year": "integer"
}

实例运行截图：

CommaSeparatedListOutputParser：拿到列表

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import CommaSeparatedListOutputParser

parser = CommaSeparatedListOutputParser()
prompt = PromptTemplate(
 template="列出三种编程语言，用逗号分隔。\n{format_instructions}",
 partial_variables={"format_instructions": parser.get_format_instructions()}
)

chain = prompt | llm | parser
response = chain.invoke({})
print(response) # type: list

输出：

['Python', 'Java', 'C++']

实例：

自定义解析器：继承 BaseOutputParser

内置解析器覆盖不到的格式，继承 BaseOutputParser 实现 parse 方法就行，比如解析分号分隔的列表：

from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import BaseOutputParser

class SemicolonListParser(BaseOutputParser):
 def parse(self, text: str) -> list:
 return [item.strip() for item in text.split(";")]

parser = SemicolonListParser()
prompt = PromptTemplate(template="列出三种城市，用分号分隔，例如：北京;上海;广州")

chain = prompt | llm | parser
response = chain.invoke({})
print(response)

输出：

['北京', '上海', '广州']

解析失败重试：async 实战

文本解析器没有硬约束，LLM 输出不稳定或格式要求严格时，解析失败是常态而不是异常，重试应该直接设计进链路。下面是完整跑通的 async 版本：PydanticOutputParser 解析动词提取结果，外层 for 循环控制最多三次尝试，全部失败后再兜底一次。

from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.runnables import RunnableSequence
from pydantic import BaseModel, Field
import os
from dotenv import load_dotenv
import asyncio

# 加载环境变量
load_dotenv()
model = os.getenv("model")
api_key = os.getenv("api_key")
base_url = os.getenv("base_url")

# 初始化 LLM
llm = ChatOpenAI(
 model=model,
 api_key=api_key,
 base_url=base_url,
 streaming=True
)

# 定义输出结构使用 Pydantic
class ParseResult(BaseModel):
 result: str = Field(description="解析出的参数结果")

# 创建输出解析器
output_parser = PydanticOutputParser(pydantic_object=ParseResult)

# 创建提示模板
prompt_template = PromptTemplate.from_template(
 "请解析以下输入并返回结果：{input}\n\n返回格式：\n{format_instructions}",
 partial_variables={"format_instructions": output_parser.get_format_instructions()}
)

# 创建可运行序列
# chain = RunnableSequence(
# prompt_template,
# llm,
# output_parser
# )
chain = prompt_template | llm | output_parser

# 输入数据
user_input = "提取这句话中的动词：'我喜欢跑步和游泳'"

async def run_parsing():
 max_attempts = 3

 for attempt in range(max_attempts):
 try:
 # 使用 invoke 方法运行链
 result = await chain.ainvoke({"input": user_input})

 print(f"第 {attempt + 1} 次尝试成功")
 print(f"解析结果: {result.model_dump()}")
 return result

 except Exception as e:
 print(f"第 {attempt + 1} 次尝试失败，错误: {e}")
 if attempt < max_attempts - 1:
 print("正在重试...")
 else:
 print("已达到最大尝试次数")
 try:
 result = await chain.ainvoke(
 {"input": user_input},
 config={"max_retries": 1}
 )
 print(f"最终修复结果: {result.model_dump()}") # 使用 model_dump() 替代 dict()
 return result
 except Exception as final_error:
 print(f"最终尝试失败，错误: {final_error}")
 return None

# 在已有事件循环中运行
async def main():
 await run_parsing()

# 如果在已有的事件循环中（比如 Jupyter），直接运行
if asyncio.get_event_loop().is_running():
 await main() # 在已有循环中运行
else:
 asyncio.run(main())

输出示例：

解析结果： {'result': '喜欢,跑步,游泳'}

关于这段代码有一点必须澄清（原笔记在这里有误导）：重试全部来自手工调用——外层 for 循环跑满三次，都失败后再兜底调一次。最后那次 ainvoke 传的 config={"max_retries": 1} 并不是解析重试的开关——prompt | llm | parser 这条链上，解析失败抛出的异常只会向上传给调用方，库不会自动重跑；max_retries 至多影响底层 API 请求层面的重试（网络错误、限流），跟解析失败是两回事，真正需要 API 层重试应该设在 ChatOpenAI 的初始化参数里。想让模型重新生成合规输出，只能像上面这样自己捕获异常、重新调用整条链。

重跑整条链之所以有效，是因为 LLM 输出有随机性：同一个输入再来一次，经常就能给出合规格式。捕获异常后重跑，是成本最低的重试方案。

和 with_structured_output 怎么选

回到开头第二个判断。1.x 时代做结构化输出，第一选择是模型侧的 with_structured_output——还是上面那个 Book schema，但玩法完全变了：

structured_llm = llm.with_structured_output(Book)
book = structured_llm.invoke("推荐一本书，返回书名、作者和出版年份")
# 直接拿到 Book 实例

	`with_structured_output`	文本解析器一族
结构由谁保证	schema 绑在模型上，走 tool calling / JSON mode	格式说明嵌进提示词，靠模型遵守约定
提示词	不需要 format_instructions	`get_format_instructions()` 嵌入 partial_variables
解析	库内部完成	链上显式一环，失败自己处理

怎么选：模型支持 tool calling 或 JSON mode（主流模型都支持），直接 with_structured_output，代码更少、格式更有保障；模型不支持原生结构化输出，或需要把格式说明精确控制进提示词（特定提示策略、兼容老链路），用文本解析器。StrOutputParser 不受这场选型影响——拿纯文本时它仍是标准配件，也是后面排查解析问题的关键工具。

三、解析报错排查

Agent 场景：OutputParserException 与 handle_parsing_errors

解析报错最密集的场景是 Agent。ReAct 式 Agent 靠解析模型文本来决定下一步动作（Thought / Action / Final Answer 的固定格式），模型一旦不合规矩就抛 OutputParserException——典型的坏输出比如同一段回复里同时包含 Action 和 Final Answer。

我跑 ReAct Agent 时撞到过这个错，解法是初始化代理时传 handle_parsing_errors=True：

agent = initialize_agent(
 tools=tools,
 llm=llm,
 agent_type="zero-shot-react-description",
 verbose=True,
 handle_parsing_errors=True # 自动处理解析错误
)

response = agent.run("告诉我关于 LangChain 的信息")
print(response)

机制：解析失败时代理不抛异常，而是把错误信息反馈给模型，要求它重新生成符合预期的输出格式——相当于框架替你做了上一节手写的那层重试循环。

⚠️ 此为 0.x 时代写法：initialize_agent / AgentExecutor 属于 legacy API，LangChain 1.x 已将其移出主线。更根本的变化是，现代 tool-calling Agent 让模型直接输出结构化的 tool call，不再靠解析自由文本决定动作，这一类解析报错从源头就少了一大截。这段经验的价值在机制本身：解析失败时把错误反馈给模型让它自我修正，这个思路在哪个版本都适用。

调试心法：先定位问题在模型还是解析器

解析失败时第一个动作不是改提示词，是看原始输出。把链尾换成 StrOutputParser 跑一遍，问题在哪一侧立刻清楚：原始输出本身不符合约定格式，问题在模型侧；原始输出看着合规但 parser 仍报错，问题在解析器侧——多半是格式约定和实际输出没对上。

try:
 response = chain.invoke({})
 print(response)
except Exception as e:
 print(f"解析失败：{e}")
 # 用 StrOutputParser 检查原始输出
 raw_chain = prompt | llm | StrOutputParser()
 raw_output = raw_chain.invoke({})
 print(f"原始输出：{raw_output}")

定位到模型侧之后，两个常用手段：

把格式要求写得更硬。 在提示里重复强调，比如"严格按照 JSON 格式返回，不要添加额外说明"；格式说明用 get_format_instructions() 生成后经 partial_variables 嵌入，不要自己手写一份——手写的和解析器的约定迟早对不上。
降低 temperature。 对格式遵从度差的模型，降低采样温度能减少格式漂移。

总结

输入侧默认 ChatPromptTemplate + MessagesPlaceholder，细粒度消息类按需取用；FewShot 的进阶形态是 ExampleSelector 按相似度动态选例，示例库质量比数量重要。
输出侧要结构化数据，1.x 优先 with_structured_output；文本解析器是备选，五种里 PydanticOutputParser（要校验）和 JsonOutputParser（要字典）最常用，特殊格式继承 BaseOutputParser 自己写 parse。
解析失败按常态路径处理：普通链上自己包一层循环重跑；Agent 场景（0.x）用 handle_parsing_errors=True 让框架把错误喂回模型。
排查顺序固定：先换 StrOutputParser 看原始输出，定位模型侧还是解析器侧，再对应改提示（格式说明、temperature）或改解析约定。
字符串模板留在默认的 f-string，不要用 jinja2 加载来源不可信的模板。

DeepAgents完全指南

Tue, 08 Sep 2026 11:26:34 +0800

DeepAgents 完全指南

本文基于 deepagents==0.7.15（Python，2026-09-16 发布）撰写，涵盖从入门概念到生产部署的全部核心内容。0.x 版本 API 变动较快，如果你的版本低于 0.6，请先升级再对照本文——0.6.0 改了消息历史的持久化格式，升级路径见 3.5 节。

第一章：DeepAgents 是什么

1.1 一句话定义

DeepAgents（包名 deepagents）是 LangChain 团队推出的一个 agent harness（智能体运行框架）—— 一个开箱即用、高度可定制、面向长周期多步任务的智能体运行时。

它不是又一个 LangGraph 图编排工具，也不只是 LangChain 的薄封装，而是一个带有以下"观点"（opinionated）的完整框架：

默认就适合长任务：内置文件系统、上下文压缩、子智能体委派，不用你自己搭。
每个组件都可以替换：模型、文件后端、中间件、子智能体、技能，全部可插拔。
模型无关：只要模型支持 tool calling 就能用——GPT、Claude、Gemini、Qwen、本地 Ollama 都行。
生产就绪：底层是 LangGraph，天然支持流式输出、持久化、checkpoint、断点恢复。

灵感来源是 Claude Code：团队想搞清楚 Claude Code 为什么通用，然后把那些设计提炼成一个可编程的框架。

1.2 在 LangChain 生态中的位置

理解 DeepAgents 的关键，是理解 LangChain 生态的三层结构：

┌─────────────────────────────────┐
│ LangSmith │ ← 可观测性、评测、监控
├─────────────────────────────────┤
│ Deep Agents │ ← 完整 harness（本文主角）
├─────────────────────────────────┤
│ LangChain create_agent │ ← 轻量 agent（无内置文件系统/子agent）
├─────────────────────────────────┤
│ LangGraph │ ← 图运行时（状态、节点、边）
└─────────────────────────────────┘

LangGraph 是底层的图运行时，管状态、节点、边、checkpoint。
LangChain create_agent 是最小的 agent 循环：模型 + 工具 + 消息 → 循环 → 回复。
DeepAgents 在 create_agent 之上叠加了一整套 middleware（文件系统、子智能体、上下文压缩、技能、权限），把"裸 agent"变成一个完整的 agent harness。
任何 LangGraph 编译后的图都可以作为 DeepAgents 的子智能体传入，实现自定义编排与 DeepAgents 默认行为的混合。

什么时候用什么层：

场景	用什么
需要 planning、context 管理、子智能体委派	DeepAgents
只需要一个简单 tool-calling 循环	LangChain `create_agent`
agent 循环不是你想要的形状，需要自定义图	LangGraph
需要监控、评估、trace	LangSmith（可与上面任何层搭配）

1.3 核心能力一览

能力	说明
文件系统	内置 `ls / read_file / write_file / edit_file / delete / glob / grep`，支持多种可插拔后端
子智能体	主 agent 通过 `task` 工具委派任务给拥有独立上下文的子 agent
上下文管理	自动摘要长对话，超大工具输出自动转存到文件系统
Shell 执行	通过 Sandbox 后端提供 `execute` 工具
代码执行	`CodeInterpreterMiddleware`（实验性）在受限 QuickJS 沙箱里跑代码与编程式工具调用
持久记忆	可插拔的状态和存储后端，支持跨会话记忆
Human-in-the-Loop	工具调用或文件操作前暂停，等待人工审批/编辑/拒绝
Skills	可复用的行为模板，按需加载，渐进式披露
结构化输出	主 agent 和子 agent 均支持 Pydantic 模型作为输出 schema
MCP 工具	可接入任意 MCP server 作为工具

1.4 安装

# 推荐
uv add deepagents

# 或者
pip install deepagents

要求 Python >= 3.11, < 4.0。

第二章：架构与中间件协议

DeepAgents 的一切能力都由**中间件栈（middleware stack）**提供。理解这个栈，就理解了 DeepAgents 的全部。

2.1 中间件栈的完整顺序

当你调用 create_deep_agent() 时，框架会按以下顺序组装中间件：

┌─ 基础栈（Base stack）────────────────────────────────┐
│ 1. SkillsMiddleware （仅当传入 skills） │
│ 2. FilesystemMiddleware （始终存在） │
│ 3. SubAgentMiddleware （有子智能体时存在） │
│ 4. SummarizationMiddleware （始终存在） │
│ 5. PatchToolCallsMiddleware （始终存在） │
│ 6. AsyncSubAgentMiddleware （有异步子智能体时存在） │
│ 7. 你的自定义 middleware （插入到这里） │
├─ 尾部栈（Tail stack）────────────────────────────────┤
│ 8. Harness profile 额外中间件 │
│ 9. 工具排除过滤（excluded_tools） │
│ 10. AnthropicPromptCachingMiddleware（非 Anthropic noop）│
│ 11. BedrockPromptCachingMiddleware（未装则跳过） │
│ 12. FireworksPromptCachingMiddleware（未装则跳过） │
│ 13. MemoryMiddleware （仅当传入 memory） │
│ 14. HumanInTheLoopMiddleware （仅当传入 interrupt_on） │
└──────────────────────────────────────────────────────┘

关键点：

你的 middleware 插在位置 7，在核心中间件之后、prompt caching 和 memory 之前。
如果你的 middleware 实例的 .name 与某个内置中间件相同，它会原地替换该内置实例，而不是追加。
某些核心中间件（FilesystemMiddleware、SubAgentMiddleware、PatchToolCallsMiddleware）受框架保护，不能通过 excluded_middleware 移除。
上图是默认组装结果。实验性中间件（如 CodeInterpreterMiddleware）不在其中，只有你显式加进 middleware 才会出现。

2.2 核心中间件详解

FilesystemMiddleware

始终存在。提供以下工具：

工具	功能
`ls(path)`	列出目录内容
`read_file(file_path, offset, limit)`	读取文件，支持分页和多模态（图片/音频/视频）
`write_file(file_path, content)`	写入文件，已存在的文件直接覆盖（0.7.0 起的行为，此前是报错）
`edit_file(file_path, old_string, new_string, replace_all)`	精确字符串替换，`old_string` 为空会被拒绝（0.7.14 起）
`delete(file_path)`	删除文件或递归删除目录（0.7.0 新增）
`glob(pattern, path)`	模式匹配查找文件
`grep(pattern, path, glob)`	文本搜索（优先使用 ripgrep）
`execute(command, timeout)`	执行 shell 命令（仅当后端实现 SandboxBackendProtocol）

0.7.0 开始，这套读写工具明显向「弱模型也能稳定用」的方向调过一遍，几个行为值得记住：

write_file 覆盖而不报错。以前写同名文件会失败，agent 得先 delete 再写；现在直接覆盖。
read_file 分页可续读。返回结果里会报总行数、剩余行数以及下一次该用的 offset，模型不用自己猜还剩多少没读。
grep / glob 返回部分结果而不是卡死。在大目录树上超过上限时，结果里带一个 truncated 标记，grep 另有 1000 条匹配上限，并支持流式输出和可选的上下文行。
edit_file 拒绝空的 old_string。以前传空串会导致不可预期的替换（0.7.14 修的）。

如果你只想暴露其中一部分工具（比如给 agent 一个只读的文件视图），FilesystemMiddleware 接受工具白名单：

from deepagents.middleware.filesystem import FilesystemMiddleware

fs_mw = FilesystemMiddleware(tools=["ls", "read_file", "glob", "grep"])

agent = create_deep_agent(model=model, middleware=[fs_mw])

它还负责大工具结果的自动转存：

默认 20000 token 以上的工具输出会被转存到文件系统（路径如 /large_tool_results/），上下文中只保留摘要和文件路径。
用户消息超过 50000 token 也会被转存。
转存文件按 tool_call_id 命名；对于没有 ID 的调用，0.7.15 起会生成唯一路径，避免多次转存撞到同一个文件名。

SubAgentMiddleware

有子智能体时存在。提供 task 工具，主 agent 用它委派任务给子 agent。子 agent 拥有完全隔离的上下文窗口——主 agent 只看到子 agent 的最终输出。

SummarizationMiddleware

始终存在。当对话 token 数超过阈值时，自动将旧消息压缩为摘要，完整历史转存到文件系统（路径如 /conversation_history/）。阈值的默认值会根据模型的最大输入 token 自动计算，回退方案是固定保留最近 20 条消息。

PatchToolCallsMiddleware

始终存在。修复消息历史中悬空的工具调用（例如 agent 在中断后恢复、或收到格式错误的 tool-call 参数时），确保消息流的一致性。

SkillsMiddleware

仅当传入 skills 参数时存在。将技能目录中的 SKILL.md 元数据（name + description）注入系统提示词，让 agent 知道有哪些技能可用。Agent 判断当前任务匹配某个技能时，会主动读取该技能的完整指令。

MemoryMiddleware

仅当传入 memory 参数时存在。在 agent 启动时加载指定的 AGENTS.md 文件内容，追加到系统提示词中。这是 DeepAgents 的"启动记忆"机制。

CodeInterpreterMiddleware（Interpreter，beta）

0.6.0 引入，不在默认栈里，需要你显式加进 middleware。官方文档里这块叫 Interpreters——给 agent 一个进程内的可编程工作区：agent 写一段 JavaScript，运行时执行后只把结果返回，中间变量不进入模型上下文。

它解决的是一个很具体的问题：正常的工具调用循环里，一次模型 turn 发出的那批 tool call 是固定的——不能循环、不能根据结果分支、不能重试、也不能把上一个调用的输出喂给下一个，除非再来一轮模型推理，而且每个结果都会回到上下文里。让模型去分派几百个条目本身也不可靠，它往往只抽样一部分。Interpreter 把这类编排从"模型逐步决策"挪到"代码里跑"，模型只需要想清楚要做什么。

pip install -U "deepagents[quickjs]"

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
 model=model,
 middleware=[CodeInterpreterMiddleware()],
)

它给 agent 加了一个 eval 工具，agent 写 JS 调它，你不用手动调。几个要点：

默认零外部能力。QuickJS 环境下拿不到宿主机文件系统、网络、shell、包管理器，连时钟都没有，只能计算、保状态、往 console.log/warn/error 写。要放开只有两条明确的口子：PTC（programmatic tool calling，用 ptc=["web_search"] 给一个工具白名单，代码里通过 tools.webSearch(...) 调）和动态子智能体（有子智能体时自动暴露 task() 全局，可以 Promise.all 并行分派）。
状态持久化由 mode 控制："thread"（默认，跨 turn 持久，每轮结束写快照）、"turn"（仅一轮内保持）、"call"（每次 eval 全新 REPL）。快照只保留可序列化的数据——函数和类恢复后会变成不可访问的残留物。
隔离是"能力受限"而不是"内存隔离"。QuickJS 跑在同进程里，官方明确说这是 scoped interpreter runtime，不是生产级 sandbox。不可信代码要另外放到独立进程或容器里跑。
PTC 不经过常规工具调用路径，所以 interrupt_on 的审批对 PTC 里调用的工具不生效。PTC 白名单本身就是权限边界，别把能碰敏感系统、花钱或改数据的工具放进去。

和 SandboxBackend 的 execute 分工很清楚：sandbox 是"对着环境写代码"（shell、装依赖、跑测试、改文件），interpreter 是"在 agent 循环里写代码"（组合工具、保状态、决定什么回给模型）。

HumanInTheLoopMiddleware

仅当传入 interrupt_on 或 permissions 中有 mode="interrupt" 的规则时存在。在指定的工具调用前暂停执行，返回中断信息，等待人工决策（approve / edit / reject / respond）。

2.3 系统提示词的组装

最终发给模型的 system prompt 不是一个字符串拼两个变量那么简单。完整顺序是：

1. 你传入的 system_prompt （可选的用户层）
2. 基础 agent 提示词 （BASE）
3. Memory 提示词 （仅当传了 memory：AGENTS.md + 使用说明）
4. Skills 提示词 （仅当传了 skills：技能位置 + 各技能 frontmatter + 用法）
5. 虚拟文件系统提示词 （含 execute 工具说明，如果用 sandbox 后端）
6. 子智能体提示词 （task 工具的用法）
7. 你自定义中间件附带的提示词 （如果自定义中间件有）
8. Human-in-the-loop 提示词 （仅当设置了 interrupt_on）

HarnessProfile 则控制其中的 BASE 和 SUFFIX 两个变量：

base_system_prompt：整体替换基础提示词。
system_prompt_suffix：在末尾追加指令。

大部分时候你只需要关心 system_prompt 参数。BASE 和 SUFFIX 是框架层面为不同模型提供的默认调优，一般不需要动。

注意 system_prompt 是静态的——每次调用都一样。如果你需要动态提示词（比如按用户权限切换「你有管理员权限」和「你只读」，或者从长期记忆里注入用户偏好），要用 @dynamic_prompt 写中间件，在里读 request.runtime.context 和 request.runtime.store。只在工具内部用到 context 时不必写中间件——工具本身就能拿到 ToolRuntime。

值得一提的是 0.7.0 对这块做过一次大幅瘦身，动机是"别把工具的用法重复写两遍"——工具 schema 本身已经说明了怎么用，再往提示词里塞一遍纯属浪费 token。具体做法是：内置的 BASE 提示词默认改为空，同时删掉与工具 schema 重复的说明性文字。效果是默认 agent 的工具描述 token 从 4005 降到 2302（−43%）；再叠上空 BASE 和按需开启的 todos，单轮输入的 token 从 5395 降到 1895（−65%）。工具的实际行为没有变化。

如果你在自己的 system_prompt 里也习惯把工具用法写得很细，这一点可以直接借鉴：先看 schema 已经说了什么，再决定提示词里还欠什么。

2.4 HarnessProfile

HarnessProfile 是"每个模型的默认调优配置包"。当你传入一个模型时，框架会自动解析对应的 profile，决定：

额外的中间件（如 Anthropic prompt caching、Bedrock prompt caching）
是否禁用某些内置工具（excluded_tools）
是否排除某些中间件（excluded_middleware）
额外的系统提示词内容

大部分使用场景不需要手动创建 profile。框架会根据模型类型自动选择。

内置 profile 的覆盖范围一直在扩。0.7.0 加入了 NVIDIA Nemotron 3 Ultra 的 profile，同时带上了 NIM 的 app-origin 归因；prompt caching 这一侧也补齐了 Bedrock（走 deepagents[aws] extra）和 Fireworks（自动做缓存会话亲和）。0.7.15 顺手修了两个 profile 相关的小问题：model profile 的 key 现在允许出现冒号，Nemotron 的内置 profile 也要求真正的 task transition 才生效。

第三章：`create_deep_agent` 完整签名

这是 DeepAgents 最核心的函数，理解了每个参数，就理解了整个框架的入口。

from deepagents import create_deep_agent

agent = create_deep_agent(
 model=..., # 模型
 tools=..., # 自定义工具
 system_prompt=..., # 系统提示词
 middleware=..., # 额外中间件
 subagents=..., # 子智能体配置
 skills=..., # 技能目录路径
 memory=..., # AGENTS.md 记忆文件路径
 permissions=..., # 文件系统权限规则
 backend=..., # 文件系统后端
 interrupt_on=..., # 人工审批的工具名映射
 response_format=..., # 结构化输出 schema
 state_schema=..., # 自定义图状态 schema
 context_schema=..., # 运行时上下文 schema
 checkpointer=..., # LangGraph checkpointer（持久化）
 store=..., # LangGraph store（跨会话存储）
 debug=..., # 调试模式
 name=..., # 图的名称
 cache=..., # 缓存
)

3.1 `model` 参数

接受三种形式：

# 1. 字符串（推荐——使用 provider:model 格式）
agent = create_deep_agent(model="openai:gpt-5.5")

# 2. 预初始化的 LangChain ChatModel 实例
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-5.5", temperature=0)
agent = create_deep_agent(model=model)

# 3. 传入 None（已弃用，默认是 claude-sonnet-4-6）
# 从 0.5.3 开始弃用，将在 1.0.0 中移除

provider:model 字符串由 LangChain 的 init_chat_model 函数解析。支持的 provider 包括：openai, anthropic, google_genai, aws, azure_openai, ollama, fireworks, together, mistral, groq, xai 等。

重要：OpenAI 模型的 Responses API 默认行为

从 DeepAgents 0.6.x 开始，如果你使用 OpenAI 模型，默认走 Responses API（不是 Chat Completions）。这是因为 Responses API 支持 OpenAI 的内置工具（web search、code interpreter 等）。

如果你想强制走 Chat Completions：

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.5", use_responses_api=False)
agent = create_deep_agent(model=model)

如果你想用 Responses API 但禁用服务端数据保留：

model = init_chat_model(
 "openai:gpt-5.5",
 use_responses_api=True,
 store=False,
 include=["reasoning.encrypted_content"],
)
agent = create_deep_agent(model=model)

接入阿里云百炼（DashScope）

百炼提供 OpenAI 兼容端点，走 Chat Completions 协议：

from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent

model = ChatOpenAI(
 model="qwen-plus", # 或 qwen3-max、qwen-max 等
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

agent = create_deep_agent(model=model, tools=[my_tools])

如果需要百炼的 web_search 等服务端内置工具，有两种策略：

在 tools 中包装：把百炼 Responses API 的 web_search 调用封装为一个普通 function tool，DeepAgents 通过 tool calling 调用它。
直接用 Responses API：绕过 DeepAgents，直接调用百炼的 Responses API（失去 DeepAgents 的 harness 能力）。

3.2 `tools` 参数

传入模型可以调用的自定义工具。这些工具与内置工具合并（additive），不会替换内置工具：

from langchain.tools import tool

@tool
def search_database(query: str) -> str:
 """搜索产品数据库，返回匹配结果"""
 return db.search(query)

@tool
def generate_report(data: dict) -> str:
 """根据数据生成分析报告"""
 return report_gen.run(data)

agent = create_deep_agent(model=model, tools=[search_database, generate_report])

要移除内置工具，需要使用 HarnessProfile 的 excluded_tools 机制，而不是简单地不传。

3.3 `system_prompt` 参数

你自定义的系统提示词。可以是字符串或 SystemMessage：

agent = create_deep_agent(
 model=model,
 system_prompt="你是一个数据分析助手。在给出结论之前，先用 Python 工具验证数据。",
)

如果传入 SystemMessage，会保留其上的 cache_control 标记（用于 Anthropic prompt caching 的显式断点）。

3.4 `response_format` 参数

让 agent 的最终输出符合指定的结构化 schema：

from pydantic import BaseModel, Field

class ResearchReport(BaseModel):
 """研究报告的结构化输出"""
 title: str = Field(description="报告标题")
 summary: str = Field(description="核心发现摘要")
 key_findings: list[str] = Field(description="关键发现列表")
 confidence: float = Field(description="置信度 0-1")
 sources: list[str] = Field(description="参考来源")

agent = create_deep_agent(
 model=model,
 tools=[web_search],
 response_format=ResearchReport,
)

result = agent.invoke({"messages": [{"role": "user", "content": "调研 LangGraph 的最新特性"}]})

# 访问结构化输出
report = result["structured_response"]
print(report.title)
print(report.confidence)

response_format 接受：

Pydantic BaseModel 子类
Python dataclass
TypedDict
JSON Schema 字典
ToolStrategy(schema)：通过 tool calling 提取
ProviderStrategy(schema)：使用 provider 原生结构化输出
AutoStrategy(schema)：自动选择最佳策略

3.5 `checkpointer` 与持久化

DeepAgents 底层是 LangGraph，所以天然支持持久化：

from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
 model=model,
 tools=tools,
 checkpointer=MemorySaver(), # 内存持久化
)

# 使用 thread_id 区分不同会话
config = {"configurable": {"thread_id": "user-123-session-456"}}
result = agent.invoke({"messages": [...]}, config=config)

生产环境使用 PostgreSQL 或 SQLite：

from langgraph.checkpoint.postgres import PostgresSaver

checkpointer = PostgresSaver.from_conn_string("postgresql://...")
agent = create_deep_agent(model=model, checkpointer=checkpointer)

文件系统（StateBackend）的内容也会随 checkpoint 持久化——同一 thread 内跨多轮对话，文件不会丢失。

DeltaChannel：0.6.0 起的持久化格式变更

从 0.6.0 开始，消息历史和 agent 文件改用 DeltaChannel 存储。原来的做法是每一步都把累积后的全量值重新序列化进 checkpoint；DeltaChannel 只存这一步写入的增量。对长线程来说这是数量级的差别——checkpoint 的大小不再随对话变长而线性膨胀。相应地，可以配 snapshot_frequency=K 每 K 步写一次全量快照，用来给读取延迟封顶。

这里有一条必须知道的兼容性红线：一旦 thread 用 0.6.0+ 持久化过，就不支持回滚。

DeltaChannel 写出的 checkpoint 是新格式，0.6.0 之前的版本读不了。降级时这些 channel 会切回非 delta 实现，而已有的 delta checkpoint 就变成不可读了——症状是状态重建不完整或直接出错，而且不一定当场暴露。

真的需要降级，只有两条路：

先用 delta-channel-dump 恢复脚本把受影响的 thread 迁移掉；
或者直接丢弃这些 thread。

推广来说：不要让同一个 channel 在 delta 和非 delta 两种表示之间来回切换。升级前先想清楚要不要留退路，留退路就在升级前把 thread 导出。

第四章：文件系统与后端

DeepAgents 内置的文件系统是一个虚拟文件系统（VFS）。它不是直接操作你的操作系统文件，而是通过**后端协议（backend protocol）**抽象，让文件操作落到不同的存储介质上。

4.1 内置工具

工具名	签名	说明
`ls`	`ls(path: str) -> list[str]`	列出目录内容
`read_file`	`read_file(file_path: str, offset: int = 0, limit: int = 500) -> str`	读取文件内容，支持偏移和限制
`write_file`	`write_file(file_path: str, content: str) -> str`	写入文件，已存在则直接覆盖
`edit_file`	`edit_file(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> str`	精确字符串替换
`delete`	`delete(file_path: str) -> str`	删除文件（需要后端支持删除操作）
`glob`	`glob(pattern: str, path: str = "/") -> list[str]`	模式匹配查找
`grep`	`grep(pattern: str, path: str = "/", glob: str = None) -> list[str]`	内容搜索（优先使用 ripgrep）
`execute`	`execute(command: str, timeout: int = 300) -> str`	执行 shell 命令（仅当后端实现 SandboxBackendProtocol）

读类工具在 0.7.0 之后都改成了「宁可返回部分结果，也不要卡住」的语义，这是专门为开源模型调过的——弱模型容易在大目录树上触发一次巨量 grep，然后整轮就废了：

read_file 会告诉你总共多少行、还剩多少行，以及下一次该传的 offset，模型可以稳定地一页页往下读。
grep / glob 命中过多时返回带 truncated 标记的部分结果；grep 另有 1000 条匹配上限，支持流式输出和可选上下文行。
glob 在路径不合理时会主动提示该往哪个 path 下找（0.7.14 起）。
顺带一提，edit_file 从上到下按 old_string 精确匹配，传空串会被直接拒绝。

4.2 后端协议

DeepAgents 的文件后端遵循 BackendProtocol。核心方法是：

class BackendProtocol(Protocol):
 def ls(self, path: str) -> list[str]: ...
 def read(self, file_path: str, offset: int = None, limit: int = None) -> str: ...
 def write(self, file_path: str, content: str) -> None: ...
 def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> None: ...
 def delete(self, file_path: str) -> None: ...
 def glob(self, pattern: str, path: str = "/") -> list[str]: ...
 def grep(self, pattern: str, path: str = "/", glob: str = None) -> list[str]: ...

如果后端实现了 SandboxBackendProtocol（继承自 BackendProtocol，额外要求 execute 方法），就会额外暴露 execute 工具。

4.3 StateBackend（默认）

StateBackend 是默认后端。文件内容直接存储在 LangGraph 的 state 中：

# 不传 backend 参数，默认使用 StateBackend
agent = create_deep_agent(model=model, tools=tools)

# 文件存在 state["files"] 字典中，key 是路径，value 是内容字符串
result = agent.invoke({"messages": [{"role": "user", "content": "写一个 hello.py"}]})
print(result["files"]) # {"/hello.py": "print('hello world')"}

特点：

文件随 checkpoint 持久化，同一 thread 内跨会话不丢失。
跨 thread 不共享（每个 thread 有独立的 state）。
无需外部依赖。
适合快速原型和不需要真正落盘的场景。

4.4 CompositeBackend

CompositeBackend 允许你把不同路径前缀路由到不同后端，实现"混合存储"：

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend, SandboxBackend

backend = CompositeBackend(
 default=StateBackend(),
 routes={
 "/workspace": StateBackend(),
 "/artifacts": StoreBackend(store=my_store, namespace=("artifacts",)),
 "/memory": StoreBackend(store=my_store, namespace=("agent_memory",)),
 "/sandbox": SandboxBackend(root_dir="/tmp/agent_sandbox", timeout=60),
 "/data": CompositeBackend.FilesystemBackend(root_dir="/path/to/shared_data"),
 },
)

agent = create_deep_agent(model=model, backend=backend)

4.5 SandboxBackend

SandboxBackend 允许 agent 在一个受控的目录中执行 shell 命令：

from deepagents import create_deep_agent
from deepagents.backends import SandboxBackend

backend = SandboxBackend(
 root_dir="/tmp/agent_workspace",
 timeout=120, # 命令超时（秒）
 max_output_size=50000,
)

agent = create_deep_agent(model=model, backend=backend)

# agent 可以调用 execute("pip install requests") 或 execute("python analysis.py")

实现 SandboxBackendProtocol 后，execute 工具会自动暴露给 agent。

4.6 FilesystemBackend（本地真实文件系统）

如果你想让 agent 直接操作本地磁盘（例如代码编辑、数据处理），可以使用 FilesystemBackend：

from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="/Users/zata/code/my-project")

agent = create_deep_agent(model=model, backend=backend)

# agent 可以 read_file / write_file / edit_file / glob / grep 操作真实文件

4.7 StoreBackend（跨会话存储）

StoreBackend 利用 LangGraph 的 Store 接口，将文件内容存储在一个跨 thread 共享的键值存储中：

from langgraph.store.memory import InMemoryStore
from deepagents.backends import StoreBackend

store = InMemoryStore()
backend = StoreBackend(store=store, namespace=("shared_files",))

agent = create_deep_agent(model=model, backend=backend)

# 文件在不同 thread 之间共享（只要使用同一个 store）

生产环境搭配 PostgreSQL Store：

from langgraph.store.postgres import PostgresStore

store = PostgresStore.from_conn_string("postgresql://...")
backend = StoreBackend(store=store, namespace=("knowledge_base",))
agent = create_deep_agent(model=model, backend=backend)

ContextHubBackend：用 LangSmith Hub 当存储（0.6.0 新增）

如果你已经在用 LangSmith，ContextHubBackend 省掉了单独部署一个 LangGraph store 的麻烦——它把 agent 的文件（技能、记忆、其他需要持久化的上下文）直接存成 LangSmith Hub 上的 commit。

from deepagents.backends import ContextHubBackend

backend = ContextHubBackend() # 走 LangSmith 凭据
agent = create_deep_agent(model=model, backend=backend)

它真正的价值在每次写入都带版本历史：skill 和 memory 这类文件最需要的就是「改错了能回退、能看出是谁在什么时候改的」，而这些能力在 Hub 上是现成的。代价是绑定了 LangSmith，纯本地或自托管场景还是用 StoreBackend。

4.8 权限控制

通过 permissions 参数精细控制文件系统访问：

agent = create_deep_agent(
 model=model,
 backend=backend,
 permissions=[
 {"path": "/workspace/*", "operations": ["read", "write", "edit"], "mode": "allow"},
 {"path": "/memory/*", "operations": ["read", "write"], "mode": "allow"},
 {"path": "/system/*", "mode": "deny"},
 {"path": "/*", "operations": ["read"], "mode": "allow"},
 {"path": "/*", "operations": ["write", "edit", "delete"], "mode": "interrupt"},
 ],
)

权限模式：

模式	行为
`allow`	直接放行
`deny`	直接拒绝，返回错误信息给 agent
`interrupt`	暂停执行，等待人工审批

权限规则按顺序匹配，第一条匹配的规则生效。

第五章：子智能体

子智能体是 DeepAgents 最有特色的能力之一。核心思想：主 agent 通过 task 工具把一个任务委派给一个拥有独立上下文窗口的子 agent。主 agent 只看到子 agent 的最终输出，不会看到子 agent 的中间过程。

这解决了长任务中的关键问题：上下文污染。当主 agent 执行搜索、阅读、分析等中间步骤时，会产生大量 token。如果这些 token 都堆在主 agent 的上下文里，很快就会超出限制或降低推理质量。子智能体隔离了这些噪音。

5.1 预配置子智能体

from deepagents import create_deep_agent
from deepagents.subagents import SubAgent

researcher = SubAgent(
 name="research-agent",
 description="负责搜索和整理信息，输出结构化研究报告",
 system_prompt="你是一个信息研究员。用 web_search 和 read_file 工具完成调研任务。",
 model="openai:gpt-5.5", # 子智能体可以用不同模型
 tools=[web_search],
)

analyst = SubAgent(
 name="data-analyst",
 description="负责数据分析和可视化",
 system_prompt="你是一个数据分析师。用 Python 分析数据，生成报告。",
 model="anthropic:claude-sonnet-4-6",
 tools=[execute_python, read_file],
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 subagents=[researcher, analyst],
 system_prompt="你是一个团队负责人。用 task 工具委派任务给子智能体。",
)

当主 agent 判断需要调研时，会调用：

{
 "tool": "task",
 "args": {
 "description": "调研 LangGraph 最新特性并输出报告",
 "subagent_type": "research-agent"
 }
}

5.2 自定义子智能体（传入编译后的 LangGraph）

任何 LangGraph CompiledStateGraph 都可以作为子智能体传入：

from langgraph.graph import StateGraph, MessagesState, END

# 构建一个自定义图
workflow = StateGraph(MessagesState)
workflow.add_node("analyze", analyze_node)
workflow.add_node("report", report_node)
workflow.set_entry_point("analyze")
workflow.add_edge("analyze", "report")
workflow.add_edge("report", END)
custom_graph = workflow.compile()

agent = create_deep_agent(
 model=model,
 subagents=[
 {
 "name": "custom-analyst",
 "description": "自定义分析管道",
 "graph": custom_graph,
 }
 ],
)

5.3 主/子上下文隔离原理

主 Agent 上下文 子 Agent 上下文
┌─────────────────────┐ ┌─────────────────────────────┐
│ system prompt │ │ 子智能体的 system prompt │
│ user message │ │ task description (作为输入) │
│ ... 历史消息 ... │ │ 子智能体的工具和文件系统 │
│ tool: task(...) │──委派──────────→│ │
│ │ │ (子 agent 内部循环) │
│ │←───────────────│ 最终输出（文本摘要） │
│ tool result │ └─────────────────────────────┘
│ ... 继续 ... │
└─────────────────────┘

子 agent 看不到主 agent 的对话历史，只看到任务描述。
主 agent 看不到子 agent 的中间 tool calls、搜索结果、文件内容。
子 agent 的文件系统与主 agent 共享（默认使用同一个 backend）。
如果子 agent 需要向主 agent 传递大文件，通过文件系统写入，主 agent 用 read_file 读取。

5.4 什么时候用子智能体

场景	是否需要子智能体
简单搜索 + 回答	不需要，一个 agent + web_search 就够
多步调研：搜索多个主题、阅读多个来源、综合报告	需要——用 researcher 子智能体隔离搜索噪音
多文件代码修改	需要——用 coder 子智能体隔离文件操作
多源数据采集和分析	需要——不同子智能体处理不同数据源
单一任务，不需要委派	不需要，直接用主 agent

5.5 异步子智能体：并行委派

DeepAgents 同时提供同步和异步两套接口。当需要并行处理多个独立任务时，可以在异步运行环境中用 asyncio.gather 同时发起多个调用，每个子智能体在自己的隔离上下文中工作，主流程只汇总最终结果。

import asyncio

# 同一 agent 的多个独立任务并行执行
results = await asyncio.gather(
 agent.ainvoke({"messages": [("user", "研究主题 A")]}, config),
 agent.ainvoke({"messages": [("user", "研究主题 B")]}, config),
)

如果子智能体内部执行的是 I/O 密集操作（网络搜索、文件读写），并行能显著缩短总耗时。注意每个并行调用会消耗独立的模型调用和 token 配额；asyncio.gather 默认在任一任务异常时取消全部，生产代码建议加 return_exceptions=True 后逐个检查。

5.6 多级子智能体

子智能体的 subagents 字段可以继续传入子智能体配置，形成"主 agent → 一级子 agent → 二级子 agent"的层级结构。每一层都有独立的上下文窗口，适合大型项目中"项目经理 → 领域专家 → 执行者"的分工模式。

deep_researcher = SubAgent(
 name="deep-researcher",
 model="openai:gpt-5.5",
 system_prompt="深入研究并写报告",
 subagents={
 "subagents": [
 SubAgent(
 name="fact-checker",
 model="openai:gpt-5.5",
 system_prompt="验证研究结论中的关键事实",
 ),
 ],
 },
)

层级不宜过深（建议不超过 2-3 层）：每加一层，主 agent 看到的信息就更间接，且 token 消耗按乘数增长。

第六章：上下文管理

DeepAgents 内置了两层上下文管理机制：摘要压缩和大工具输出转存。

6.1 SummarizationMiddleware：对话摘要压缩

当对话的 token 数超过阈值时，SummarizationMiddleware 会：

将旧消息替换为一条摘要消息
将完整的旧消息转存到文件系统（路径如 /conversation_history/{message_id}.json）
保留最近的消息在上下文中

压缩前：
[sys] [msg1] [msg2] [msg3] [msg4] [msg5] ... [msgN]
 ↑ 全部保留在上下文中

压缩后：
[sys] [摘要消息（包含历史概要+文件路径）] [msgN-2] [msgN-1] [msgN]
 ↑ 完整历史在 /conversation_history/

阈值配置：

from deepagents import create_deep_agent
from deepagents.middleware.summarization import SummarizationMiddleware

agent = create_deep_agent(
 model=model,
 tools=tools,
 middleware=[
 SummarizationMiddleware(
 token_threshold=100000, # 超过 100k token 触发压缩
 keep_messages=10, # 保留最近 10 条消息
 )
 ],
)

阈值默认值根据模型的最大输入 token 自动计算（官方口径是达到模型上下文窗口的约 85%）。例如：

GPT-5（128k context）→ 阈值约 100k token
Claude（200k context）→ 阈值约 160k token
回退方案：保留最近 20 条消息

按需压缩：让 agent 自己决定什么时候压

自动摘要只在逼近阈值时才动手，但有些场景你想让它主动在任务边界处压缩——比如一个子任务刚交付完，历史已经没用但离阈值还远。

加一个 compact_conversation 工具就能做到：

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from deepagents.middleware.summarization import create_summarization_tool_middleware

backend = StateBackend # 用默认后端时这样写

agent = create_deep_agent(
 model=model,
 middleware=[create_summarization_tool_middleware(model, backend)],
)

注意这不是替代品：加上它并不会关掉 85% 的自动压缩，两者共用同一个摘要引擎和状态。自定义中间件会被插到 PatchToolCallsMiddleware 之后（也就是 2.1 节栈里的位置 7）。

6.2 大工具输出转存

FilesystemMiddleware 监控所有工具的输出。当输出超过阈值（默认 20000 token）时：

将完整输出写入文件系统（路径如 /large_tool_results/{tool_call_id}.txt）
在上下文中只保留摘要消息：[输出过大，已转存到 /large_tool_results/xxx.txt，请用 read_file 读取]

# 你可以自定义阈值
from deepagents.middleware.filesystem import FilesystemMiddleware

fs_mw = FilesystemMiddleware(
 large_output_threshold=10000, # 10000 token 超限
 large_output_dir="/my_tool_results",
)

agent = create_deep_agent(model=model, middleware=[fs_mw])

6.3 记忆与跨会话

通过 memory 参数加载 AGENTS.md：

agent = create_deep_agent(
 model=model,
 tools=tools,
 memory="/path/to/AGENTS.md", # 启动时注入到系统提示词
)

对于需要动态更新的长期记忆，使用 StoreBackend：

from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
memory_backend = StoreBackend(store=store, namespace=("agent_memory",))

agent = create_deep_agent(
 model=model,
 backend=memory_backend,
 system_prompt="你是一个有记忆的助手。在 /memory 目录中维护长期记忆。",
)

Agent 可以通过文件工具读写 /memory/ 目录，实现跨会话的记忆更新。

第七章：Skills（技能系统）

Skills 是 DeepAgents 的渐进式披露机制——将复杂的指令和工具组合打包成可复用的模块，按需加载。

7.1 基本用法

每个技能是一个目录，包含一个 SKILL.md 文件：

my_skills/
├── code-review/
│ └── SKILL.md
├── data-viz/
│ ├── SKILL.md
│ └── templates/
│ └── chart.py
└── web-research/
 └── SKILL.md

SKILL.md 的格式：

---
name: code-review
description: 对代码库进行系统性审查，检查安全性、性能、可维护性
---

## 步骤

1. 读取目标文件列表（用 glob 工具）
2. 逐一读取关键文件
3. 检查以下方面：
 - 安全性：SQL注入、XSS、不安全的反序列化
 - 性能：N+1 查询、内存泄漏、不必要的全表扫描
 - 可维护性：函数长度、重复代码、缺失的类型注解
4. 用 write_file 工具输出审查报告到 /reports/code-review-{date}.md

## 工具

优先使用 grep 搜索特定模式，用 read_file 读取上下文。

agent = create_deep_agent(
 model=model,
 tools=tools,
 skills="/path/to/my_skills",
)

SkillsMiddleware 会将每个技能的 name 和 description 注入系统提示词。Agent 判断当前任务匹配某个技能时，会主动 read_file 读取该技能的完整指令。

7.2 为什么是"渐进式披露"

如果所有技能的完整内容都塞在系统提示词里，token 浪费严重。渐进式披露的设计是：

系统提示词只包含元数据（name + description），几十个 token 每技能。
完整指令在文件系统中，agent 按需读取。
10 个技能的元数据 ≈ 300 token，比全量内容（可能几千 token）节省 90% 以上。

7.3 带资源的技能

技能目录中可以包含额外文件（模板、脚本、配置等），agent 可以通过文件系统工具访问：

my_skills/
└── report-generator/
 ├── SKILL.md
 ├── templates/
 │ ├── report_template.md
 │ └── chart_template.py
 └── config.yaml

Agent 读取 SKILL.md 后，可以根据指令进一步读取 templates/ 中的文件。

7.4 社区技能示例：研究评估评分标准

官方仓库提供了多个可复用的技能示例。下面是一个"研究评估"技能（rubrics 模式）的典型结构——把评审专家的评分维度固化成可复用的指令文件：

---
name: evaluate-research
description: 用评分标准评估研究报告质量
---

## 评分标准

按以下维度评估研究报告（每项 1-5 分）：

1. **事实准确性**：关键事实是否有可靠来源支撑
2. **逻辑连贯性**：结论是否从证据自然推出
3. **完整性**：是否遗漏了重要角度
4. **可操作性**：读者能否据此做出决策

## 流程

1. 阅读研究报告全文
2. 逐项打分并给出具体依据
3. 汇总总分和改进建议

将此文件放入技能目录后，agent 在收到"评估报告"类任务时会自动加载该技能。你可以基于自己的领域编写类似的评分模板——技能系统的本质就是把"怎么做"的专家知识封装成可复用的指令文件。

第八章：Human-in-the-Loop（人机协作）

DeepAgents 允许在工具调用前暂停，等待人工决策。这在生产环境中至关重要——你不希望 agent 在没有人工审核的情况下执行危险操作（删除文件、发送邮件、执行数据库变更等）。

8.1 `interrupt_on` 参数

agent = create_deep_agent(
 model=model,
 tools=[send_email, delete_record, web_search, write_file],
 interrupt_on={
 "send_email": {"allowed_decisions": ["approve", "edit", "reject"]},
 "delete_record": {"allowed_decisions": ["approve", "reject"]},
 },
)

# 第一次 invoke 会触发中断
result = agent.invoke({"messages": [...]})

# 检查是否中断
if result["__interrupt__"]:
 # 获取中断信息
 interrupt_info = result["__interrupt__"][0]
 print(f"工具: {interrupt_info.value['action_request']['action']}")
 print(f"参数: {interrupt_info.value['action_request']['args']}")

 # 人工决策
 human_decision = interrupt_info.value["resume"]
 # 或者用 resume 重新启动
 resumed = agent.invoke(
 {"__interrupt__": [{"resume": {"type": "accept"}}]},
 config=config,
 )

8.2 通过 permissions 实现文件操作审批

agent = create_deep_agent(
 model=model,
 backend=backend,
 permissions=[
 {"path": "/workspace/*", "mode": "allow"},
 {"path": "/*", "operations": ["write", "edit", "delete"], "mode": "interrupt"},
 ],
)

所有 workspace 外的写操作都会触发人工审批。

8.3 中断恢复协议

DeepAgents 的 HITL 基于 LangGraph 的 interrupt 机制。中断后：

图的状态（包括 messages、files）已通过 checkpointer 保存。
agent.invoke() 返回 __interrupt__ 信息。
人工决策通过 agent.invoke() resume：

config = {"configurable": {"thread_id": "session-1"}}

# 第一次调用，触发中断
result1 = agent.invoke({"messages": [...]}, config=config)

# 检查中断并恢复
if "__interrupt__" in result1:
 decision = input("批准/编辑/拒绝？(approve/edit/reject): ")
 result2 = agent.invoke(
 Command(resume={"type": decision}),
 config=config,
 )

支持的决策类型：

决策	行为
`{"type": "accept"}`	批准，继续执行工具调用
`{"type": "edit", "args": {...}}`	编辑参数后继续执行
`{"type": "reject", "message": "..."}`	拒绝，将拒绝理由传回给 agent
`{"type": "respond", "message": "..."}`	不执行工具，向 agent 提供额外信息

第九章：流式输出与中间过程

DeepAgents 基于 LangGraph，支持多种流式模式：

9.1 流式 token

from langchain_core.messages import AIMessageChunk

config = {"configurable": {"thread_id": "session-1"}}

for event in agent.stream(
 {"messages": [{"role": "user", "content": "分析这份数据"}]},
 config=config,
 stream_mode="messages",
):
 # event 是 (message_chunk, metadata) 元组
 msg_chunk, metadata = event
 if hasattr(msg_chunk, "content") and isinstance(msg_chunk.content, str):
 print(msg_chunk.content, end="", flush=True)

9.2 流式工具调用

for event in agent.stream(
 input_data,
 config=config,
 stream_mode="updates",
):
 # 每个节点的更新
 for node_name, node_update in event.items():
 print(f"节点: {node_name}")
 if "messages" in node_update:
 for msg in node_update["messages"]:
 print(f" {msg.type}: {msg.content[:100] if isinstance(msg.content, str) else msg.content}")

9.3 流式文件操作

通过 stream_mode="updates"，可以看到文件系统的变化：

for event in agent.stream(
 input_data,
 config=config,
 stream_mode="updates",
):
 for node_name, node_update in event.items():
 if "files" in node_update:
 print(f"文件变化: {node_update['files'].keys()}")

9.4 事件流（v3）：`stream_events` 与类型化投影

上面几种 stream_mode 是 LangGraph 的原始流式接口——你拿到的是 dict，要自己判断这一块是什么。LangGraph 1.2.0 / DeepAgents 0.6.0 起多了一套更适合应用层写代码的东西：事件流（event streaming），传 version="v3" 开启。

核心变化是：一次 run 产出的事件流被归一化后，经过一层 transformer 管线，暴露成几个带类型的投影，可以同时被多个消费者读——读 stream.messages 不会消耗 stream.values 需要的事件。

stream = agent.stream_events(
 {"messages": [{"role": "user", "content": "分析这份数据"}]},
 version="v3",
)

# 只看模型输出：token 级
for message in stream.messages:
 print(str(message.text), end="", flush=True)

# 最终状态
final_state = stream.output

可用的投影：

投影	用途
`stream`	遍历所有协议事件（原始层）
`stream.messages`	模型消息与 token 增量，另有 `.reasoning` 和 `.tool_calls`
`stream.values`	每一步之后的状态快照，`stream.output` 拿最终值
`stream.subgraphs`	发现并观察嵌套图/子智能体执行
`stream.interrupts` / `stream.interrupted`	人机协作中断的载荷与判定
`stream.extensions`	自定义 transformer 的投影

对 DeepAgents 来说，stream.subgraphs 特别有用——子智能体的执行会作为嵌套作用域出现在这里，直接看 subgraph.graph_name 和 subgraph.path 就行，不用去解析 namespace 字符串：

stream = agent.stream_events(input_data, config=config, version="v3")

for subgraph in stream.subgraphs:
 print(subgraph.graph_name, subgraph.path)
 for message in subgraph.messages:
 print(message.text)

异步场景下可以并发消费多个投影：

stream = await agent.astream_events(input_data, version="v3")

async def consume_messages():
 async for message in stream.messages:
 print(f"[llm] node={message.node}")

async def consume_subgraphs():
 async for subgraph in stream.subgraphs:
 print(f"[subgraph] path={subgraph.path}")

await asyncio.gather(consume_messages(), consume_subgraphs())

同步代码想在严格的到达顺序里混着读多个投影，用 stream.interleave(...)：

for name, item in stream.interleave("values", "messages", "subgraphs"):
 if name == "values":
 print(f"[state] keys={list(item)}")
 elif name == "messages":
 print(f"[llm] node={item.node}")
 elif name == "subgraphs":
 print(f"[subgraph] path={item.path}")

底层通道（event["method"]）有 values、updates、messages、tools、lifecycle、checkpoints、input、tasks、custom。其中 messages 是按 content block 建模的，事件序列固定为 message-start → content-block-start → content-block-delta → content-block-finish → message-finish，文本、推理、工具调用、多模态内容都有显式边界，不再依赖各家 provider 的格式。

v1 和 v2 的写法保持兼容，没有破坏性变更——现有代码不用动，新代码建议直接从 v3 起步。

第十章：生产部署

10.1 部署选项

方案	适用场景
LangGraph Platform	托管部署，LangSmith 集成，自动扩缩
Docker + 自建	需要完全控制的私有化部署
Serverless（Vercel/Modal/Cloud Run）	事件驱动、低流量场景
LangSmith Deployment	与 LangSmith 评估和监控深度集成

10.2 Docker 部署示例

FROM python:3.12-slim
WORKDIR /app

# 安装依赖
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen

# 复制代码
COPY . .

# 暴露端口
EXPOSE 8000

# 启动（LangGraph serve）
CMD ["uv", "run", "langgraph", "serve", "--host", "0.0.0.0", "--port", "8000"]

10.3 环境变量

# 模型 API Key
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-...

# LangSmith（可选，但强烈推荐）
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=my-agent

# 数据库（生产 checkpointer）
DATABASE_URL=postgresql://user:pass@host:5432/db

10.4 安全模型

DeepAgents 遵循"信任 LLM"模型。Agent 可以做任何工具允许的事情。安全边界必须在你这一侧强制执行：

后端层面：使用 SandboxBackend 或 FilesystemBackend 的 root_dir 限制 agent 能访问的目录。
权限层面：使用 permissions 参数控制读写和删除操作。
工具层面：不要暴露你不想让 agent 执行的工具。
HITL 层面：对危险操作（删除、发送、支付）设置 interrupt_on。
网络层面：如果 agent 有 web 访问能力，确保它不能访问内网端点。

10.5 可观测性

LangSmith 集成：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=your_key
export LANGSMITH_PROJECT=production-agent

设置环境变量后，所有 agent 调用自动产生 trace。无需改代码。

10.6 评测

from langsmith import Client

client = Client()

# 创建评测数据集
dataset = client.create_dataset("deep-agents-eval")
client.create_examples(
 dataset_id=dataset.id,
 inputs=[
 {"messages": [{"role": "user", "content": "调研 X 并写报告"}]},
 {"messages": [{"role": "user", "content": "修复 bug #123"}]},
 ],
)

# 运行评测
client.evaluate(
 agent,
 data=dataset.id,
 evaluators=[
 # 自定义评估器
 lambda outputs, reference: {"accuracy": compute_match(outputs, reference)},
 ],
)

第十一章：实战模式

11.1 研究智能体

from deepagents import create_deep_agent
from deepagents.subagents import SubAgent
from langchain.tools import tool

@tool
def web_search(query: str) -> str:
 """搜索互联网获取信息"""
 # 接入 Tavily / Bocha / 百炼 WebSearch MCP
 ...

@tool
def web_extract(url: str) -> str:
 """抽取网页正文内容"""
 ...

research_subagent = SubAgent(
 name="researcher",
 description="搜索和整理信息",
 system_prompt="你是一个信息研究员。用 web_search 和 web_extract 完成调研。",
 model="openai:gpt-5.5",
 tools=[web_search, web_extract],
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 subagents=[research_subagent],
 system_prompt="""你是一个研究助手。
 收到调研任务后，用 task 工具委派给 researcher 子智能体。
 基于子智能体的输出，综合并生成最终回答。""",
)

11.2 代码智能体

from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="/path/to/repo")

agent = create_deep_agent(
 model="anthropic:claude-sonnet-4-6",
 backend=backend,
 system_prompt="""你是一个代码编辑助手。
 先用 glob 和 grep 了解代码库结构。
 修改代码前先 read_file 阅读上下文。
 修改后用 execute 工具运行测试验证。
 修改必须最小化，不要过度工程化。""",
)

11.3 数据分析智能体

from deepagents.backends import SandboxBackend

backend = SandboxBackend(
 root_dir="/tmp/data_sandbox",
 timeout=300,
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 backend=backend,
 system_prompt="""你是一个数据分析师。
 先用 execute("ls /") 查看数据文件。
 用 execute("python -c \"...\\"") 或 execute("head -n 100 data.csv") 探索数据。
 用 execute("python analysis.py") 执行分析脚本。
 用 write_file 生成分析报告。""",
)

11.4 混合模式：DeepAgents + 百炼 Responses API

当你需要 DeepAgents 的 harness 能力 + 百炼的 web_search：

import os
from openai import OpenAI
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# 百炼 Responses API 客户端（用于 web_search）
bailian = OpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

@tool
def bailian_web_search(query: str) -> str:
 """搜索互联网获取最新信息（使用百炼 web_search）"""
 response = bailian.responses.create(
 model="qwen3-max",
 input=query,
 tools=[{"type": "web_search"}],
 )
 # 提取搜索结果
 results = []
 for item in response.output:
 if getattr(item, "type", None) == "web_search_call":
 results.append(str(item))
 elif getattr(item, "type", None) == "message":
 for content in getattr(item, "content", []):
 if hasattr(content, "text"):
 results.append(content.text)
 return "\n".join(results)

# DeepAgents 走 Chat Completions
model = ChatOpenAI(
 model="qwen-plus",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

agent = create_deep_agent(
 model=model,
 tools=[bailian_web_search],
 system_prompt="你是一个研究助手。用 bailian_web_search 查询最新信息。",
)

第十二章：协议对比总结

12.0 Deep Agents Code（dcode）

除了可编程的 Python/JS 库，LangChain 还提供了 Deep Agents Code（dcode）——一个预构建的终端编码智能体，定位类似 Claude Code 或 Cursor CLI，底层就是 DeepAgents harness。它让你不用写代码就能体验文件系统、子智能体、上下文管理等全部能力。

# 一键安装
curl -LsSf https://langch.in/dcode | bash

# 在项目目录中启动
cd your-project
dcode

dcode 使用任何支持 tool calling 的 LLM 作为后端。对于想先"用"再"编"的用户，建议先试 dcode 感受 harness 行为，再用 create_deep_agent 定制自己的流程。

dcode 迭代很快（几乎每周发版），近期（0.1.67 / 0.1.68）值得关注的更新：

工作区隔离增强：项目策略按 workspace 解析、dotenv 按 workspace 作用域隔离、LangSmith 认证与 tracing 隔离；跨工作区切换时复用 server 并在重启前请求确认。
模型支持：新增 Fireworks GLM-5.3 / GLM-5.3 Flash 的用量计价，推荐模型列表纳入 GLM 5.3 系列。
subagent 行为：general-purpose 子智能体默认以 fork 模式运行（继承完整上下文），并支持 fresh subagent 与按任务选择工具。

官方文档：https://docs.langchain.com/deepagents-code

12.1 DeepAgents 的模型协议

DeepAgents 对模型的唯一要求是 tool calling。它不关心底层是 Chat Completions 还是 Responses API，只要 LangChain ChatModel 能完成以下循环：

发送 [system, user, assistant(tool_calls), tool(results)] → 模型返回 tool_calls 或 text → 循环

Chat Completions 兼容端点（OpenAI、DashScope、Ollama、vLLM）：直接用 ChatOpenAI。
Responses API（OpenAI / 百炼）：通过 init_chat_model("openai:...", use_responses_api=True)。
Anthropic：直接用 ChatAnthropic 或 "anthropic:claude-sonnet-4-6"。
本地模型：ChatOllama 或 ChatVLLM。

12.2 与百炼 Responses API 的关系

维度	DeepAgents + Chat Completions	百炼 Responses API
协议	Chat Completions（`messages`）	Responses（`input`）
工具调用	客户端执行（LangChain tool calling）	服务端内置（web_search 等）
Agent 循环	DeepAgents 框架管	你自己管
搜索	需要自己包装工具	服务端内置
文件系统	内置	无
子智能体	内置	无
上下文管理	内置	无
HITL	内置	无

12.3 选型决策树

需要 DeepAgents 的 harness 能力？
├─ 是 → 需要 web_search？
│ ├─ 是 → 自己包装搜索为 function tool（推荐）
│ │ 或混合模式（DeepAgents + 百炼 Responses API）
│ └─ 否 → 直接用 DeepAgents + Chat Completions
└─ 否 → 需要服务端内置工具（web_search 等）？
 ├─ 是 → 直接用百炼 Responses API
└─ 否 → LangChain create_agent / LangGraph

12.4 RubricMiddleware：自评迭代循环

DeepAgents 内置了 RubricMiddleware，让你用"评分标准"定义什么叫做完成。当 agent 准备结束回复时，中间件会调用一个独立的"评分器"子智能体，根据 rubric 逐条检查 agent 的输出。如果评分器返回 needs_revision，其反馈会作为 HumanMessage 注入上下文，agent 循环继续——直到评分器返回 satisfied、failed 或达到最大迭代次数。

from deepagents import create_deep_agent
from deepagents.middleware import RubricMiddleware

rubric_mw = RubricMiddleware(
 rubric=[
 {"criterion": "所有关键论断都有来源引用", "weight": 3},
 {"criterion": "结论与证据逻辑一致", "weight": 2},
 {"criterion": "无事实错误", "weight": 3},
 ],
 grader_model="openai:gpt-5.5",
 max_iterations=3,
)

agent = create_deep_agent(
 model="openai:gpt-5.5",
 middleware=[rubric_mw],
 system_prompt="你是一个研究助手，写完报告后自我检查再提交。",
)

这个模式非常适合对输出质量有硬性要求的场景（合规文档、技术报告、代码审查），把"人工再审一遍"变成可编程的自动质量门。

12.5 官方示例集导读

GitHub 仓库的 examples/ 目录包含十多个端到端案例，按学习优先级推荐如下：

示例	亮点
`content-builder-agent`	用 Memory + Skills + Subagents 三原语构建内容写作 agent，最适合入门
`deep_research`	完整的深度研究 agent（多轮搜索 + 报告生成），展示实际 token 管理
`text-to-sql-agent`	自然语言 → SQL，展示 planning + filesystem + subagent 组合
`rubric_middleware`	RubricMiddleware + LangSmith trace，展示自评迭代全流程
`async-subagent-server`	异步子智能体 + 服务端部署，生产级 FastAPI 集成
`ralph_mode`	Ralph 自主循环模式（Geoff Huntley），`while :; do agent; done` 的 DeepAgents 实现
`better-harness`	用一个 DeepAgent 优化另一个 agent harness 的元循环（harness engineering）

建议先跑 content-builder-agent 理解三原语（Memory / Skills / Subagents），再按需深入其他案例。

附录

A. 常用环境变量

变量	说明
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`DASHSCOPE_API_KEY`	阿里云百炼 API key
`LANGSMITH_TRACING`	启用 LangSmith trace
`LANGSMITH_API_KEY`	LangSmith API key
`LANGSMITH_PROJECT`	LangSmith 项目名
`LANGCHAIN_TRACING_V2`	启用 LangSmith trace（旧变量名）
`LANGCHAIN_API_KEY`	LangSmith API key（旧变量名）
`LANGCHAIN_PROJECT`	LangSmith 项目名（旧变量名）

B. 版本注意事项

deepagents 0.7.x 是当前最新版本系列（最新 0.7.15，2026-09-16），尚未发布 0.8 或 1.0。
0.5.x → 0.6.x 有重大变化：SubAgent 类型变化、response_format 新增，并且消息历史与 agent 文件切到 DeltaChannel 持久化，此变更不可回滚（见 3.5 节）。
0.6.x → 0.7.x 新增了 skills、memory、permissions、delete 工具、FilesystemMiddleware 工具白名单，同时做了一次提示词瘦身（见 2.3 节）。
0.7.13 → 0.7.14 → 0.7.15 都是修补性质：read_file 输出格式调整、edit_file 拒绝空 old_string、ls/glob 字符计数修正、无 ID 的工具结果转存改用唯一路径、subagent state key 传递修复。
如果从 0.3.x 升级，SubAgent 已从 dict 改为类型化对象，create_deep_agent 的参数名有变化。
0.x 版本 API 变动快，生产环境建议锁定版本（uv add deepagents==0.7.15）。

本文覆盖的版本快照（截至 2026-09-21）

包	本文基准版本	发布日期	备注
`deepagents`（Python）	0.7.15	2026-09-16	核心库，本文主体内容
`deepagents-code`（dcode）	0.1.72	2026-09-21	终端编码智能体，见 12.0 节
`deepagents-talon`	0.0.8	2026-09-11	独立发布，本文未覆盖
`langchain-quickjs`	0.3.7	2026-09-06	JS 运行时，`CodeInterpreterMiddleware` 依赖它，本文未展开
`langchain`	1.4.0	2026-09-01	MCP 支持已内建进 `langchain.mcp`
`langchain-mcp-adapters`	—	—	已被 `langchain.mcp` 取代，不再维护
`deepagents.js`（JS/TS）	—	—	独立仓库，见附录 C

下次更新检查清单

查看 GitHub Releases 确认 deepagents 最新 minor 版本（当前 0.7.x；如果发布 0.8 或 1.0，优先检查 breaking changes）。
对比 CHANGELOG（或 release notes），重点看：
- 新增/移除的中间件（libs/deepagents/deepagents/middleware/ 目录）
- create_deep_agent 签名变化
- 新增的 examples 目录
检查 deepagents-code 是否有新 major 功能（dcode 迭代很快，几乎每周发版）。
确认本文引用的文档链接是否仍然有效（LangChain 文档路径经常重组）。
如果有新的 middleware 或新的 examples，优先补充到第 2 章（中间件详解）和 12.5 节（示例导读）。

C. 生态与跨语言

JavaScript/TypeScript：DeepAgents 提供了 deepagents.js 库（GitHub），适合在 Node.js 环境中构建 agent。
Deep Agents Code：终端编码智能体，安装命令见 12.0 节。

D. 相关资源

本文基于 DeepAgents 0.7.15 版本编写，2026 年 9 月。API 在 1.0 之前可能变化，请以官方文档为准。

LangChain 模型接入指南：OpenAI 兼容协议与多平台调用

Tue, 08 Sep 2026 11:00:00 +0800

LangChain 模型接入指南：OpenAI 兼容协议与多平台调用

langchain_openai 名字里带 openai，能做的事却比名字大得多：任何兼容 OpenAI 接口协议的模型服务，它都能接。而到今天，OpenAI API 格式已经成了事实上的工业标准——阿里百炼、DeepSeek、vLLM、Ollama，无一例外都把"兼容 OpenAI 协议"当成默认姿势。

所以在 LangChain 里接模型这件事，可以收敛成一套打法：用 ChatOpenAI 和 OpenAIEmbeddings，配合目标平台的三要素。我把这套打法叫**“换头”**——换平台时业务代码一行不动，只改三处：base_url、api_key、model。一个原本基于 GPT-4 写的应用，改完这三处就直接跑在通义千问上。

这篇文章做两件事：以阿里百炼为例，把对话、流式、嵌入、工具调用四类调用完整走一遍（嵌入那里有个很容易漏的坑）；然后给一份多平台速查表，覆盖 6 家 ChatModel 和 5 家 Embeddings 的包名与初始化要点，换平台时直接查表。

一、百炼实战：用 ChatOpenAI 跑通四类调用

1.1 准备：包、Key 和 Base URL

pip install langchain-openai langchain-core

去阿里云百炼控制台拿两样东西：

API Key（sk- 开头）
Base URL：百炼的 OpenAI 兼容端点是 https://dashscope.aliyuncs.com/compatible-mode/v1

组件上只需要认识两个类，正好对应 LLM 应用的两块基石：

类	用途	百炼上的对应模型
`ChatOpenAI`	对话、指令跟随、逻辑推理、工具调用（Function Calling）	通义千问系列（`qwen-plus`、`qwen-max`、`qwen-turbo`、`qwen-long`）
`OpenAIEmbeddings`	文本转向量，构建 RAG 的基础	向量模型（`text-embedding-v2`、`text-embedding-v3` 等）

ChatOpenAI 走 Chat Completion 接口：输入是消息列表（SystemMessage、HumanMessage、AIMessage），输出是 AIMessage。千问的具体型号清单见百炼官方的模型列表。

1.2 基础对话

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

# 为清晰起见先写成明文变量；生产环境放环境变量，做法见第三节
ALIBABA_API_KEY = "sk-你的阿里百炼API_KEY"
ALIBABA_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"

chat_model = ChatOpenAI(
 model="qwen-plus", # 指向百炼的模型 ID
 api_key=ALIBABA_API_KEY,
 base_url=ALIBABA_BASE_URL,
 temperature=0.7,
 streaming=True,
)

messages = [
 SystemMessage(content="你是一个专业的Python代码助手。"),
 HumanMessage(content="请用Python写一个冒泡排序，并解释其时间复杂度。"),
]

print(chat_model.invoke(messages).content)

除了 model / api_key / base_url 三处"换头"参数，其余写法与调 GPT-4 完全一致——这正是兼容协议的价值。

1.3 流式输出

把 invoke 换成 stream 就是流式：

for chunk in chat_model.stream(messages):
 print(chunk.content, end="", flush=True)

chunk.content 是每次生成的一小段文本。流式对大模型应用的用户体验提升非常直接，做对话类产品基本是必选项。

1.4 向量嵌入：最不能漏的一行

做 RAG（知识库助手）时用 OpenAIEmbeddings 调百炼的向量模型。这里有个坑，也是全文最值得记住的一行参数：

from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
 model="text-embedding-v2",
 api_key=ALIBABA_API_KEY,
 base_url=ALIBABA_BASE_URL,
 check_embedding_ctx_length=False, # 关键：关掉 OpenAI 特有的长度检查，防止报错
)

vector = embeddings.embed_query("阿里百炼是一个大模型服务平台。")
print(f"生成的向量维度: {len(vector)}")
print(f"向量前 5 位: {vector[:5]}")

OpenAIEmbeddings 默认开着一段 OpenAI 特有的逻辑：发送前先按 OpenAI 的分词器做上下文长度检查，超长文本会在本地被切块再分批发送。接到百炼这种非 OpenAI 端点上，这套本地检查既无必要，又可能在调用时直接报错。显式传 check_embedding_ctx_length=False 把它关掉就正常了。第一次接百炼嵌入如果莫名报错，先看是不是漏了这个参数。

1.5 工具调用：bind_tools

百炼的 Qwen 模型对 Function Calling 的支持很好，且完全走 OpenAI 的格式。用 bind_tools 把工具绑定到模型上，模型决定调用时，请求会出现在返回消息的 tool_calls 属性里，而不是正文里：

from langchain_core.tools import tool

@tool
def get_weather(city: str):
 """查询某个城市的天气信息。"""
 return f"{city} 的天气是晴天，气温 25 度。"

llm_with_tools = chat_model.bind_tools([get_weather])

response = llm_with_tools.invoke("杭州今天天气怎么样？")
print(f"工具调用请求: {response.tool_calls}")

拿到 tool_calls 之后，取出参数、真正执行工具、把结果作为 ToolMessage 回传给模型，就是一个完整的工具调用循环——LangChain 的 Agent 封装和 LangGraph 处理的就是这个循环。

二、为什么推荐用 langchain_openai 接百炼

一个自然的疑问：阿里有官方 SDK，LangChain 里也有 ChatTongyi 这种原生类，为什么绕道 langchain_openai？理由有三。

代码零迁移成本。 项目原本基于 GPT-4 开发的话，不需要改动任何业务逻辑，把环境变量里的 BASE_URL 和 API_KEY 换掉，应用就从 OpenAI 切到了百炼 Qwen。把 langchain_openai 当默认接入层，各平台互为"平替"，切换成本约等于零。
生态支持最完善。 LangChain 社区对 OpenAI 类的支持是优先级最高的；走标准接口，后续接 LangGraph、LangSmith 这些工具也最顺。
工具调用格式统一。 OpenAI 的 Tool Calling 格式是当前的黄金标准。百炼通过兼容接口让 Qwen 像 GPT 一样精准地调用工具，不需要自己处理格式转换。

反过来说，只有当你要用 DashScope 原生协议里、兼容层没覆盖的能力时，才需要回到原生 SDK——这条备选路线放在第五节。

三、环境变量与 Key 管理

3.1 永久环境变量：CMD / GUI / zsh / bash

以百炼的 DASHSCOPE_API_KEY 为例。这个名字不是随便起的：第五节的 ChatTongyi、DashScopeEmbeddings 都默认读它。

# Windows CMD
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"
echo %DASHSCOPE_API_KEY% # 验证

# Windows 图形界面
# 系统属性 → 环境变量，手动添加，不再赘述

# zsh
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
source ~/.zshrc
echo $DASHSCOPE_API_KEY # 验证

# bash
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
source ~/.bashrc
echo $DASHSCOPE_API_KEY # 验证

3.2 .env 模板：多平台共存

写进 shell 配置不适合多项目切换，更常见的做法是每个项目放一个 .env，用 python-dotenv 加载：

# 阿里云百炼
DASHSCOPE_API_KEY=sk-你的key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# OpenAI 官方（或另一个兼容端点）
OPENAI_API_KEY=sk-你的key
# OPENAI_BASE_URL=

from dotenv import load_dotenv
import os

load_dotenv()

llm = ChatOpenAI(
 model="qwen-plus",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url=os.getenv("DASHSCOPE_BASE_URL"),
 streaming=True,
)

再进一步还有个偷懒技巧：openai 官方 SDK 本身就认 OPENAI_API_KEY 和 OPENAI_BASE_URL 两个环境变量。把这两个变量指向百炼，代码里连 api_key、base_url 都不用写，ChatOpenAI(model="qwen-plus") 就能直接跑——切换平台时只动环境变量，一行代码不改。

3.3 百炼计费预警

百炼有个和 OpenAI 不一样的计费方式，要提前知道：它没办法单独充值消费，费用会直接从控制台里扣钱。所以动手跑代码之前，先把控制台的高消费预警设上。

四、多平台速查表

“换头"的前提是各家有自己的接入包。LangChain 0.2 之后，集成被拆成一个个独立的合作包，下面两张表按"提供商 → 安装包 → 初始化要点"整理。表里的型号名只是写作时存在过的示例，各家更新很快，使用前以官方现役型号为准。

4.1 ChatModel（6 家）

提供商	安装包	初始化要点
OpenAI / 任意 OpenAI 兼容端点	`langchain-openai`	`ChatOpenAI(model="gpt-4o-mini")`，默认读 `OPENAI_API_KEY`；接百炼则加 `base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"`，`model` 换成 `qwen-plus` 等
Anthropic	`langchain-anthropic`	`ChatAnthropic(model="claude-sonnet-4-5-20250929")`，默认读 `ANTHROPIC_API_KEY`
Google	`langchain-google-genai` / `langchain-google-vertexai`	Gemini API 走 `ChatGoogleGenerativeAI(model="gemini-2.5-flash")`，读 `GOOGLE_API_KEY`；GCP 走 `ChatVertexAI`，需要 gcloud 登录或 `GOOGLE_APPLICATION_CREDENTIALS`
Hugging Face	`langchain-huggingface`	`HuggingFaceEndpoint(repo_id="google/flan-t5-large", task="text-generation")`，读 `HUGGINGFACEHUB_API_TOKEN`；本地 pipeline 用 `HuggingFacePipeline`
Cohere	`langchain-cohere`	`ChatCohere(model="command-r")`，默认读 `COHERE_API_KEY`
Ollama（本地）	`langchain-ollama`	`ChatOllama(model="llama3.2")`；服务默认在 `http://localhost:11434`，不在默认地址时传 `base_url`

4.2 Embeddings（5 家）

提供商	安装包	初始化要点
OpenAI / 任意 OpenAI 兼容端点	`langchain-openai`	`OpenAIEmbeddings(model="text-embedding-3-small")`；接百炼：`model="text-embedding-v2"` + `base_url` + `check_embedding_ctx_length=False`
Google	`langchain-google-genai` / `langchain-google-vertexai`	`GoogleGenerativeAIEmbeddings(model="models/gemini-embedding-001")`；Vertex 用 `VertexAIEmbeddings(model_name="text-embedding-005")`
Hugging Face（本地）	`langchain-huggingface` + `sentence-transformers`	`HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")`，可用 `model_kwargs={'device': 'cuda'}` 指定设备
Cohere	`langchain-cohere`	`CohereEmbeddings(model="embed-v4.0")`
Ollama（本地）	`langchain-ollama`	`OllamaEmbeddings(model="nomic-embed-text")`

4.3 相对旧版速查的更新

这张表由 2025 年初那版速查表更新而来，几处变化需要说明：

langchain_community.llms.HuggingFaceHub → langchain-huggingface 包的 HuggingFaceEndpoint。Hugging Face 的推理接入这几年变动很大（Inference API 已让位给 Inference Providers），这条路线以官方文档为准。
langchain_community.chat_models.ChatOllama → langchain-ollama 包的 ChatOllama，OllamaEmbeddings 同步从 langchain_community.embeddings 迁到 langchain-ollama。
langchain_community.embeddings.HuggingFaceEmbeddings → langchain-huggingface 的同名类。
旧表里的 gpt-3.5-turbo、claude-3-sonnet-20240229、gemini-pro、llama2 等型号已过时，表中换成了更新的型号；它们同样会过期，以各家官方型号页为准。

4.4 两个容易忽略的差异

embed_query 与 embed_documents 分工不同：前者嵌入单条查询文本（用户搜索的那句话），返回一个向量；后者批量嵌入多个文档，返回向量列表。检索系统的两侧——入库文档和用户查询——必须用同一个嵌入模型，否则维度和语义空间都对不上。
向量维度因模型而异：text-embedding-3-small 是 1536 维，text-embedding-3-large 是 3072 维，常见的 sentence-transformers 模型多为 384 或 768 维。维度决定了向量库的结构和相似度计算，入库后换嵌入模型基本等于重建整个库。

五、备选路线：原生 DashScope 与 init_chat_model

5.1 ChatTongyi / DashScopeEmbeddings（legacy）

LangChain 社区包里保留了走 DashScope 原生 SDK 的两个类。⚠️ 以下是 0.x 时代的社区包写法，能用，但新项目建议优先走 OpenAI 兼容层：

pip install langchain-community dashscope

# ⚠️ 此为 langchain_community 0.x 时代写法
from langchain_community.chat_models.tongyi import ChatTongyi
from langchain_core.messages import HumanMessage

chatLLM = ChatTongyi(
 model="qwen-max",
 streaming=True,
)
res = chatLLM.stream([HumanMessage(content="hi")], streaming=True)
for r in res:
 print("chat resp:", r.content)

嵌入对应 DashScopeEmbeddings：

# ⚠️ 此为 langchain_community 0.x 时代写法
from langchain_community.embeddings import DashScopeEmbeddings

embeddings = DashScopeEmbeddings(model="text-embedding-v2")

query_result = embeddings.embed_query("This is a test document.")
print("文本向量长度：", len(query_result))

doc_results = embeddings.embed_documents(
 ["Hi there!", "Oh, hello!", "What's your name?",
 "My friends call me World", "Hello World!"])
print("文本向量数量：", len(doc_results), "，文本向量长度：", len(doc_results[0]))

两个类都默认读 DASHSCOPE_API_KEY 环境变量。什么时候才需要这条路线：要用 DashScope 原生协议里、兼容层没覆盖的能力时。纯粹跑对话和嵌入，没有理由不用兼容层。

5.2 init_chat_model

LangChain 官方还提供了统一初始化入口 init_chat_model，按模型名和 provider 一步创建实例，不用记各家类名：

from langchain.chat_models import init_chat_model

llm = init_chat_model(
 "qwen-plus",
 model_provider="openai", # 指定走 langchain_openai 的 ChatOpenAI
 api_key="sk-你的key",
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

其余参数原样透传给对应类，细节以官方文档为准。

总结

把这篇文章压成几条可执行的结论：

把 langchain_openai 当默认接入层。OpenAI API 格式已是事实工业标准，ChatOpenAI + OpenAIEmbeddings 能接一切兼容端点。
换平台只改三处：base_url、api_key、model，业务代码不动；配合环境变量或 .env，可以做到一行代码不换平台。
接百炼做嵌入，check_embedding_ctx_length=False 必加，这是最容易漏的一行。
跑代码前先设百炼高消费预警，它的费用直接从控制台账户扣，没有独立余额。
新项目直接装独立集成包（langchain-ollama、langchain-huggingface 等），langchain_community 里的模型类当 legacy 看。

下一步：拿 1.2 的基础对话代码，把三个"换头"参数换成你手上的平台——百炼、DeepSeek 或本地 Ollama——跑通第一条消息。然后做两件事：用 bind_tools 试一次工具调用，用 OpenAIEmbeddings 把一段文本打成向量。这三步走完，LangChain 接模型这件事就算真正上手了。

Graph RAG 开源项目全景：从微软 GraphRAG 到 LightRAG

Fri, 27 Mar 2026 16:00:00 +0800

传统 RAG 的核心思路是"向量检索 + 生成"，但在处理需要多跳推理、全局理解的问题时，效果往往不理想。

Graph RAG（知识图谱 + RAG）通过构建文档间的实体关系网络，让检索不再局限于局部相似度匹配，而是能够进行图遍历、社区发现、路径推理。这让 RAG 系统能回答更复杂的问题。

这篇文章系统梳理 Graph RAG 的主流开源项目，帮你快速了解和选型。

一、为什么需要 Graph RAG

传统 RAG 的局限

问题 1：多跳推理

用户问："A 公司的合作方的竞争对手有哪些？"

传统 RAG：
1. 检索"A 公司的合作方" → 找到 B 公司
2. 检索"B 公司的竞争对手" → 找到 C、D 公司

问题：
- 需要两轮检索，中间结果可能丢失
- 无法自动发现推理路径

Graph RAG：
A 公司 --合作--> B 公司 --竞争--> C、D 公司
一次图遍历即可完成

问题 2：全局理解

用户问："这篇文章的核心观点是什么？"

传统 RAG：
- 检索 Top-K 相关段落
- 但核心观点可能分散在各处
- 无法形成全局视角

Graph RAG：
- 通过社区发现，将文档划分为多个主题
- 每个社区生成摘要
- 整合社区摘要，形成全局理解

Graph RAG 的核心思路

传统 RAG：
文档 → Chunk → 向量化 → 向量检索

Graph RAG：
文档 → 实体抽取 → 关系抽取 → 知识图谱
 ↓
 图检索 + 向量检索
 ↓
 LLM 生成

二、主流框架概览

框架	Stars	作者	核心特点	适用场景
LightRAG	36K+	港大 HKUDS	轻量快速，双层检索	中小规模，实时更新
GraphRAG	33K+	Microsoft	社区摘要，全局理解	大规模文档
HippoRAG	3.5K+	俄亥俄州立	模拟海马体记忆	长期记忆系统
Fast-GraphRAG	3.8K+	Circlemind	自适应，快速	快速部署
Neo4j Graph Builder	4.7K+	Neo4j	企业级图数据库	可视化，企业应用
R2R	7.8K+	SciPhi AI	生产级，完整方案	企业部署

下面逐一详细介绍。

三、Microsoft GraphRAG

基本信息

GitHub: https://github.com/microsoft/graphrag
Stars: 33,800+
论文: GraphRAG: Unlocking LLM Discovery on Narrative Private Data
语言: Python

核心原理

GraphRAG 的核心创新是社区发现 + 社区摘要：

Step 1: 知识图谱构建
文档 → 实体抽取 → 关系抽取 → 图存储

Step 2: 社区发现
用 Leiden 算法将图划分为多个社区
每个社区是一个紧密相关的实体群组

Step 3: 社区摘要
对每个社区，用 LLM 生成摘要
摘要包含社区的核心实体和关系

Step 4: 检索
局部查询：从相关实体出发，图遍历
全局查询：检索社区摘要，整合回答

架构图

┌──────────────────────────────────────────────────────┐
│ Microsoft GraphRAG Pipeline │
└──────────────────────────────────────────────────────┘
 │
 ▼
 ┌──────────────────┐
 │ 文档输入 │
 └────────┬─────────┘
 │
 ┌──────────────┼───────────────┐
 ▼ ▼ ▼
 ┌─────────┐ ┌──────────┐ ┌──────────┐
 │ 文本分块 │ │ 实体抽取 │ │ 关系抽取 │
 └────┬────┘ └────┬─────┘ └────┬─────┘
 │ │ │
 └──────────────┼───────────────┘
 ▼
 ┌──────────────────┐
 │ 知识图谱 │
 │ (NetworkX) │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 社区发现 │
 │ (Leiden) │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 社区摘要 │
 │ (LLM 生成) │
 └────────┬─────────┘
 │
 ┌──────────────┼───────────────┐
 ▼ ▼ ▼
 ┌─────────┐ ┌──────────┐ ┌──────────┐
 │ 局部查询 │ │ 全局查询 │ │ 混合查询 │
 └────┬────┘ └────┬─────┘ └────┬─────┘
 │ │ │
 └──────────────┼───────────────┘
 ▼
 ┌──────────────────┐
 │ LLM 生成答案 │
 └──────────────────┘

快速开始

# 安装
pip install graphrag

# 初始化项目
python -m graphrag.index --init --root ./ragtest

# 配置（settings.yaml）
graphrag:
 llm:
 type: openai_chat
 model: gpt-4o
 embeddings:
 type: openai_embedding
 model: text-embedding-3-small

# 构建索引
python -m graphrag.index --root ./ragtest

# 查询
python -m graphrag.query --root ./ragtest --method local "What is the main topic?"
python -m graphrag.query --root ./ragtest --method global "What are the key themes?"

查询模式

Local Search（局部查询）：
- 从问题中识别实体
- 扩展实体的邻居节点
- 用局部子图生成答案
- 适合：具体事实查询

Global Search（全局查询）：
- 检索相关社区摘要
- 整合多个社区的信息
- 形成全局视角
- 适合："核心观点"、"主要主题"类问题

DRIFT Search（混合查询）：
- 结合局部和全局
- 动态调整检索范围
- 适合：复杂推理问题

优缺点

优点：
✅ 全局理解能力强（社区摘要）
✅ 微软官方维护，质量有保障
✅ 论文驱动，原理清晰
✅ 支持多种查询模式

缺点：
❌ 索引构建慢（需要多次 LLM 调用）
❌ 成本高（实体抽取、关系抽取、社区摘要）
❌ 不适合实时更新（重建索引代价大）
❌ 需要一定学习成本

适用场景

✅ 推荐：
- 大规模文档库（10K+ 文档）
- 需要全局理解（"核心观点"、"主要趋势"）
- 需要多跳推理
- 离线构建，在线查询

❌ 不推荐：
- 小规模知识库
- 需要实时更新
- 成本敏感

四、LightRAG

基本信息

GitHub: https://github.com/HKUDS/LightRAG
Stars: 36,600+
论文: LightRAG: Simple and Fast Retrieval-Augmented Generation (EMNLP 2025)
作者: 香港大学数据科学实验室
语言: Python

核心创新

LightRAG 针对 GraphRAG 的痛点做了优化：

GraphRAG 的问题：
1. 索引构建慢：需要多次 LLM 调用
2. 成本高：实体抽取、关系抽取、社区摘要
3. 不支持实时更新

LightRAG 的解决方案：
1. 双层检索：低层（实体）+ 高层（关键概念）
2. 无需社区发现：用双层图代替
3. 流式插入：支持实时更新
4. 轻量存储：无需图数据库，文件即可

双层检索原理

传统 GraphRAG：
文档 → 实体 → 图 → 社区发现 → 社区摘要 → 检索

LightRAG：
文档 → 实体 + 关键概念 → 双层图 → 直接检索

双层图结构：
┌─────────────────────────────────────┐
│ 高层（关键概念层） │
│ [AI] ── [机器学习] ── [深度学习] │
│ │ │ │ │
├─────────┼───────────┼───────────┼───┤
│ │ │ │ │
│ ▼ ▼ ▼ │
│ 低层（实体层） │
│ [GPT-4] [神经网络] [CNN/RNN] │
└─────────────────────────────────────┘

查询时：
1. 先在高层找到相关概念
2. 再在低层找到具体实体
3. 双层结果融合

快速开始

# 安装
pip install lightrag-hku

# 基础使用
from lightrag import LightRAG
from lightrag.llm import openai_complete_if_cache, openai_embedding

# 初始化
rag = LightRAG(
 working_dir="./rag_storage",
 llm_model_func=openai_complete_if_cache,
 embedding_func=openai_embedding
)

# 插入文档
with open("document.txt", "r") as f:
 rag.insert(f.read())

# 查询
result = rag.query("What is machine learning?", mode="hybrid")

# 查询模式
result = rag.query("...", mode="naive") # 纯向量检索
result = rag.query("...", mode="local") # 局部图检索
result = rag.query("...", mode="global") # 全局图检索
result = rag.query("...", mode="hybrid") # 混合检索

性能对比（官方数据）

索引构建时间：
- GraphRAG: 100 分钟
- LightRAG: 10 分钟
- 提升: 10x

查询时间：
- GraphRAG: 2 秒
- LightRAG: 0.3 秒
- 提升: 6x

成本（Token 消耗）：
- GraphRAG: $10
- LightRAG: $1
- 降低: 90%

准确率：
- GraphRAG: 45%
- LightRAG: 52%
- 提升: 7%

优缺点

优点：
✅ 快：索引和查询都很快
✅ 省：成本降低 50-90%
✅ 灵活：支持实时插入更新
✅ 简单：无需图数据库
✅ 准确：双层检索更精准

缺点：
❌ 全局理解不如 GraphRAG（无社区摘要）
❌ 大规模场景下，图文件可能很大
❌ 功能相对简单

适用场景

✅ 推荐：
- 中小规模知识库（< 10K 文档）
- 需要实时更新
- 成本敏感
- 快速原型

❌ 不推荐：
- 超大规模文档
- 需要深度全局理解

五、HippoRAG

基本信息

GitHub: https://github.com/OSU-NLP-Group/HippoRAG
Stars: 3,500+
论文: HippoRAG: A Neurobiological Framework for Long-Term Memory (NeurIPS 2024)
作者: 俄亥俄州立大学
语言: Python

核心原理：模拟海马体

人类记忆机制：
海马体（Hippocampus）：
- 索引新记忆
- 将记忆整合到大脑皮层

大脑皮层：
- 存储长期记忆
- 知识以网络形式组织

检索时：
- 从海马体获取线索
- 在大脑皮层中激活相关记忆
- 通过联想找到答案

HippoRAG 的实现：
海马体 → 向量索引（快速找到入口）
大脑皮层 → 知识图谱（关联检索）
检索 → Personalized PageRank（模拟联想）

架构图

┌──────────────────────────────────────────────────────┐
│ HippoRAG 架构 │
└──────────────────────────────────────────────────────┘

索引阶段：
文档 → Passage 节点 → 向量化（海马体索引）
 → 实体抽取 → 实体节点
 → 关系抽取 → 边
 → 知识图谱（大脑皮层）

检索阶段：
Query → 向量化 → 找到相关 Passage 节点
 ↓
 Personalized PageRank
 （从入口节点扩散）
 ↓
 激活相关实体和 Passage
 ↓
 LLM 生成答案

Personalized PageRank

传统 PageRank：
- 所有节点平等
- 计算全局重要性

Personalized PageRank：
- 从特定节点出发（Query 相关的 Passage）
- 计算相对这些节点的重要性
- 模拟"联想"过程

示例：
Query: "GPT-4 的训练数据"

Step 1: 向量检索找到入口 Passage
入口节点: [Passage_A, Passage_B]

Step 2: Personalized PageRank
从 Passage_A、Passage_B 出发
计算其他节点的激活程度

Step 3: 激活扩散
Passage_A → 实体"GPT-4" → 实体"训练数据" → Passage_C
Passage_B → 实体"OpenAI" → 实体"GPT-4" → ...

Step 4: 收集高激活度的 Passage
Top-K: [Passage_A, Passage_B, Passage_C, ...]

Step 5: LLM 生成答案

快速开始

# 安装
pip install hipporag

# 使用
from hipporag import HippoRAG

rag = HippoRAG(
 graph_db="neo4j", # 支持 Neo4j 或 NetworkX
 llm_model="gpt-4",
 embedding_model="text-embedding-3-small"
)

# 索引
rag.index("./documents")

# 查询
result = rag.query("What are the key features of GPT-4?")

适用场景

✅ 推荐：
- 长期记忆系统
- 持续学习的知识库
- 需要精准检索
- 个性化 RAG

❌ 不推荐：
- 简单问答场景
- 成本敏感

六、Neo4j + RAG 方案

Neo4j LLM Graph Builder

GitHub: https://github.com/neo4j-labs/llm-graph-builder
Stars: 4,700+
作者: Neo4j 官方
语言: Python

核心特点

Neo4j 的优势：
1. 成熟的图数据库
2. 强大的 Cypher 查询语言
3. 可视化工具（Neo4j Browser）
4. 企业级支持

LLM Graph Builder 的功能：
1. 从非结构化文本构建知识图谱
2. 支持多种 LLM（OpenAI、Azure、Gemini、Ollama）
3. 实体和关系抽取
4. 图谱可视化

工作流程

┌──────────────────────────────────────────────────────┐
│ Neo4j Graph Builder Pipeline │
└──────────────────────────────────────────────────────┘
 │
 ▼
 ┌──────────────────┐
 │ 文档输入 │
 │ (PDF/TXT/URL) │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 文本分块 │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ LLM 实体抽取 │
 │ "苹果公司" → Organization │
 │ "库克" → Person │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ LLM 关系抽取 │
 │ (苹果公司, CEO, 库克) │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 存入 Neo4j │
 │ CREATE (a:Org {name:"苹果"})│
 │ CREATE (b:Person {name:"库克"})│
 │ CREATE (a)-[:CEO]->(b) │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 图检索 + LLM │
 └──────────────────┘

快速开始

# 安装
pip install neo4j-graphrag

from neo4j import GraphDatabase
from neo4j_graphrag.llm import OpenAILLM
from neo4j_graphrag.embeddings import OpenAIEmbeddings
from neo4j_graphrag.generation import GraphRAG

# 连接 Neo4j
driver = GraphDatabase.driver(
 "bolt://localhost:7687",
 auth=("neo4j", "password")
)

# 初始化
llm = OpenAILLM(model_name="gpt-4")
embedder = OpenAIEmbeddings()
rag = GraphRAG(driver, llm, embedder)

# 构建图谱
rag.build_graph("./documents")

# 查询
result = rag.search("Who is the CEO of Apple?")

适用场景

✅ 推荐：
- 企业级应用
- 需要可视化
- 已有 Neo4j 基础设施
- 复杂图查询

❌ 不推荐：
- 小规模、轻量场景
- 不想维护图数据库

七、其他值得关注的项目

1. Fast-GraphRAG

GitHub: https://github.com/circlemind-ai/fast-graphrag
Stars: 3,800+

特点：
- 自适应：根据数据和查询自动调整
- 快速：优化的检索算法
- 简单：开箱即用

适用：快速部署，数据多样

2. R2R (Reason to Retrieve)

GitHub: https://github.com/SciPhi-AI/R2R
Stars: 7,800+

特点：
- 生产级 RAG 系统
- Agentic RAG（Agent + RAG）
- 支持知识图谱
- 完整 RESTful API
- 评估工具

适用：企业级部署

3. graph-rag-agent（拼好RAG）

GitHub: https://github.com/1517005260/graph-rag-agent
Stars: 2,200+

特点：
- 融合 GraphRAG + LightRAG + Neo4j
- DeepSearch 推理能力
- 自制 GraphRAG 评估框架
- 国产项目，中文友好

适用：学习对比，评估测试

4. Medical-Graph-RAG

GitHub: https://github.com/ImprintLab/Medical-Graph-RAG
Stars: 800+
论文: ACL 2025

特点：
- 医疗领域专用
- 循证医学信息检索
- 医学实体识别优化

适用：医疗知识库

5. GraphRAG-Local-UI

GitHub: https://github.com/severian42/GraphRAG-Local-UI
Stars: 2,300+

特点：
- 支持本地 LLM（Ollama）
- 完整 UI 界面
- 索引/调参/查询/可视化
- 无需云端 API

适用：本地部署，隐私敏感

八、框架对比

性能对比

指标	GraphRAG	LightRAG	HippoRAG
索引速度	慢	快 10x	中等
查询速度	中等	快 5x	快
成本	高	低 50-90%	中等
全局理解	强	中等	中等
局部检索	强	强	很强
实时更新	❌	✅	✅

功能对比

功能	GraphRAG	LightRAG	HippoRAG	Neo4j
社区发现	✅	❌	❌	✅
双层检索	❌	✅	❌	❌
PageRank	❌	❌	✅	✅
可视化	❌	❌	❌	✅
本地部署	✅	✅	✅	✅
流式插入	❌	✅	✅	✅

适用场景对比

大规模文档（10K+）：
1. GraphRAG（全局理解）
2. Neo4j + RAG（企业级）

中小规模（< 10K）：
1. LightRAG（快速、低成本）
2. Fast-GraphRAG（简单部署）

长期记忆：
1. HippoRAG（模拟海马体）

医疗/专业领域：
1. Medical-Graph-RAG
2. KG_RAG

本地部署：
1. GraphRAG-Local-UI
2. LightRAG + Ollama

九、选型决策树

开始选型
 │
 ├─ 需要全局理解（"核心观点"、"主要趋势"）？
 │ ├─ 是 → Microsoft GraphRAG
 │ └─ 否 → 继续
 │
 ├─ 需要实时更新？
 │ ├─ 是 → LightRAG
 │ └─ 否 → 继续
 │
 ├─ 需要可视化？
 │ ├─ 是 → Neo4j + RAG
 │ └─ 否 → 继续
 │
 ├─ 长期记忆系统？
 │ ├─ 是 → HippoRAG
 │ └─ 否 → 继续
 │
 ├─ 成本敏感？
 │ ├─ 是 → LightRAG
 │ └─ 否 → 继续
 │
 ├─ 快速原型？
 │ ├─ 是 → LightRAG / Fast-GraphRAG
 │ └─ 否 → 继续
 │
 └─ 企业级部署？
 ├─ 是 → R2R / Neo4j + RAG
 └─ 否 → LightRAG

十、学习资源

必读论文

1. GraphRAG: Unlocking LLM Discovery on Narrative Private Data
 - Microsoft GraphRAG 原始论文
 - 社区发现 + 社区摘要的核心思想

2. LightRAG: Simple and Fast Retrieval-Augmented Generation
 - EMNLP 2025
 - 双层检索的设计

3. HippoRAG: A Neurobiological Framework for Long-Term Memory
 - NeurIPS 2024
 - 模拟海马体的记忆机制

4. From Local to Global: A Graph RAG Approach to Query-Focused Summarization
 - 图检索到全局理解的演进

开源资源

Awesome-GraphRAG:
https://github.com/DEEP-PolyU/Awesome-GraphRAG
- 论文、项目、基准测试汇总

GraphRAG 深度学习:
https://github.com/JayLZhou/GraphRAG
- GraphRAG 源码解读

LightRAG 实验对比:
https://github.com/NanGePlus/LightRAGTest
- LightRAG vs GraphRAG 性能对比

官方文档

Microsoft GraphRAG:
https://microsoft.github.io/graphrag/

LightRAG:
https://github.com/HKUDS/LightRAG/blob/main/README.md

Neo4j GraphRAG:
https://neo4j.com/docs/graphrag-manual/

十一、总结

Graph RAG 是 RAG 技术的重要演进方向，让检索从"局部相似度匹配"升级为"全局图推理"。

核心框架对比：

Microsoft GraphRAG：
- 定位：大规模文档，全局理解
- 优势：社区摘要，全局视角
- 代价：构建慢，成本高

LightRAG：
- 定位：中小规模，快速部署
- 优势：快速、低成本、实时更新
- 代价：全局理解较弱

HippoRAG：
- 定位：长期记忆，精准检索
- 优势：模拟海马体，联想检索
- 代价：相对复杂

Neo4j + RAG：
- 定位：企业级，可视化
- 优势：成熟图数据库，生态完善
- 代价：需要维护数据库

选型建议：

快速上手：LightRAG
全局理解：Microsoft GraphRAG
企业部署：Neo4j + RAG 或 R2R
长期记忆：HippoRAG
本地部署：GraphRAG-Local-UI

没有银弹，关键是根据场景选择合适的工具。

相关文章：

RAG 技术全景：从入门到进阶

Thu, 26 Mar 2026 16:00:00 +0800

前面我们分析了 RAGFlow，它解决了"从文档到答案"的核心问题。但 RAG 领域发展极快，除了文档解析、Chunking、混合检索这些基础能力，还有很多值得关注的技术方向。

这篇文章会系统梳理 RAG 的技术演进路线，帮你建立完整的知识图谱。

一、RAG 的技术演进

RAG 1.0：检索 + 生成
Query → 向量检索 → LLM 生成

RAG 2.0：多路检索 + Rerank + 引用溯源
Query → 多路检索 → 融合 → Rerank → 生成 + 引用

RAG 3.0：Agentic RAG + Graph RAG + 多模态
Query → Agent 规划 → 多轮检索/推理 → 反思修正 → 生成

下面按技术方向逐一展开。

二、Graph RAG：知识图谱 + RAG

本文对 Graph RAG 做概要介绍，详细的开源项目分析和选型指南请参阅 Graph RAG 开源项目全景：从微软 GraphRAG 到 LightRAG。

为什么需要 Graph RAG

传统 RAG 的局限：

问题："A 公司的合作方的竞争对手有哪些？"

传统 RAG：
1. 检索"A 公司的合作方" → 找到 B 公司
2. 检索"B 公司的竞争对手" → 找到 C、D 公司
问题：需要多轮检索，且中间结果可能丢失

Graph RAG：
1. 从知识图谱中找到 A → 合作 → B
2. 从知识图谱中找到 B → 竞争 → C、D
优势：一次图遍历即可完成多跳推理

Graph RAG 的架构

┌──────────────────────────────────────────────────────┐
│ Graph RAG Pipeline │
└──────────────────────────────────────────────────────┘
 │
 ┌───────────────┼───────────────┐
 ▼ ▼ ▼
 ┌─────────┐ ┌──────────┐ ┌──────────┐
 │ 文档输入 │ │ 实体抽取 │ │ 关系抽取 │
 └────┬────┘ └────┬─────┘ └────┬─────┘
 │ │ │
 └──────────────┼───────────────┘
 ▼
 ┌──────────────────┐
 │ 知识图谱构建 │
 │ (Neo4j / NetworkX) │
 └────────┬─────────┘
 │
 ┌──────────────┼───────────────┐
 ▼ ▼ ▼
 ┌─────────┐ ┌──────────┐ ┌──────────┐
 │ 向量检索 │ │ 图检索 │ │ 混合检索 │
 └────┬────┘ └────┬─────┘ └────┬─────┘
 │ │ │
 └──────────────┼───────────────┘
 ▼
 ┌──────────────────┐
 │ LLM 生成答案 │
 └──────────────────┘

核心技术点

1. 实体抽取

输入文档："苹果公司由史蒂夫·乔布斯于 1976 年创立，总部位于加利福尼亚州库比蒂诺。"

实体抽取结果：
- 苹果公司（Organization）
- 史蒂夫·乔布斯（Person）
- 1976 年（Date）
- 加利福尼亚州库比蒂诺（Location）

技术方案：
- NER 模型（spaCy、Stanford NER）
- LLM 抽取（GPT-4、Qwen）
- 开源工具（DeepKE、OpenIE）

2. 关系抽取

关系抽取结果：
- 苹果公司 -- 创立者 --> 史蒂夫·乔布斯
- 苹果公司 -- 创立时间 --> 1976 年
- 苹果公司 -- 总部位置 --> 加利福尼亚州库比蒂诺

3. 图检索策略

策略 1：子图检索
- 找到问题中的实体节点
- 扩展 N 跳邻居
- 将子图转为文本，喂给 LLM

策略 2：路径检索
- 找到起点和终点实体
- 检索两点间的路径
- 路径上的节点/边作为上下文

策略 3：社区检索
- 预先对图谱做社区发现
- 检索相关社区
- 社区摘要作为上下文

代表项目

项目	特点	适用场景
Microsoft GraphRAG	微软官方，社区摘要	大规模文档全局理解
LightRAG	轻量级，无图数据库依赖	快速部署
Neo4j + LangChain	成熟图数据库，生态完善	企业级应用
LlamaIndex GraphRAG	与 LlamaIndex 深度集成	已有 LlamaIndex 项目

适用场景

✅ 推荐使用 Graph RAG：
- 需要多跳推理（"A 的 B 的 C 是什么"）
- 需要全局理解（"这篇文章的核心观点"）
- 实体关系密集（知识库、企业图谱）
- 需要可解释的推理路径

❌ 不推荐：
- 文档间无关联
- 问题简单，单次检索可解
- 实体稀疏，图构建成本高

三、Agentic RAG：Agent + RAG

从被动检索到主动规划

传统 RAG（被动）：
Query → 检索 → 生成
问题：检索策略固定，无法应对复杂问题

Agentic RAG（主动）：
Query → Agent 规划 → 执行 → 反思 → 再规划 → ...

Agentic RAG 的核心能力

1. 查询理解与改写

原始问题："那个产品怎么样"
↓ LLM 分析
问题太模糊，需要澄清

改写策略：
1. 分解问题："那个产品" → 识别具体产品
2. 扩展问题：生成多个相关 Query
3. HyDE：生成假设性答案，用答案检索

示例：
Query: "报销流程"
↓
改写为：
1. "公司报销流程步骤"
2. "报销需要哪些材料"
3. "报销审批流程"

2. 迭代检索

第一轮检索：
Query: "A 公司的融资情况"
结果: A 公司 B 轮融资 5000 万

判断：信息不完整，缺少投资方
↓
第二轮检索：
Query: "A 公司 B 轮投资方"
结果: 红杉资本领投

判断：信息完整
↓
生成答案

3. 工具调用

Agent 可用的工具：
- 向量检索：检索内部知识库
- 关键词检索：BM25 搜索
- 联网搜索：Google/Bing API
- SQL 查询：查询结构化数据
- API 调用：获取实时信息

示例：
Query: "今天北京天气怎么样，适合户外活动吗？"
↓ Agent 规划
1. 调用天气 API 获取北京天气
2. 检索知识库中"户外活动适宜条件"
3. 综合判断并回答

4. 自我反思

生成答案后，Agent 自我评估：

评估维度：
- 答案是否完整？
- 是否需要补充检索？
- 是否有矛盾信息？

示例：
答案："A 公司成立于 2010 年"
反思：检索结果中有两个年份（2010 和 2012），需要验证
↓
再次检索："A 公司成立时间 官方"
↓
修正答案

Agentic RAG 架构

┌──────────────────────────────────────────────────────┐
│ Agentic RAG │
└──────────────────────────────────────────────────────┘
 │
 ▼
 ┌──────────────────┐
 │ Query 分析 │
 │ - 意图识别 │
 │ - 实体抽取 │
 │ - 查询改写 │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 规划器 │
 │ - 分解任务 │
 │ - 选择工具 │
 │ - 生成执行计划 │
 └────────┬─────────┘
 │
 ┌──────────────┼───────────────┐
 ▼ ▼ ▼
 ┌─────────┐ ┌──────────┐ ┌──────────┐
 │ 向量检索 │ │ 联网搜索 │ │ SQL 查询 │
 └────┬────┘ └────┬─────┘ └────┬─────┘
 │ │ │
 └──────────────┼───────────────┘
 ▼
 ┌──────────────────┐
 │ 反思器 │
 │ - 结果评估 │
 │ - 是否继续检索 │
 │ - 是否需要修正 │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ LLM 生成答案 │
 └──────────────────┘

代表框架

框架	特点	适用场景
LangGraph	LangChain 出品，状态机模型	复杂工作流
AutoGPT + RAG	自主 Agent	开放域任务
CrewAI	多 Agent 协作	团队式任务
LlamaIndex Agent	内置 RAG Agent	快速构建

适用场景

✅ 推荐使用 Agentic RAG：
- 问题复杂，需要多步推理
- 需要调用多种工具
- 需要实时信息（联网、API）
- 需要自我纠错

❌ 不推荐：
- 问题简单，单次检索可解
- 对延迟敏感（Agent 会增加延迟）
- 成本敏感（多轮 LLM 调用）

四、多模态 RAG

为什么需要多模态

企业知识库不只是文本：
- 产品手册：文字 + 图片 + 示意图
- 技术文档：文字 + 代码 + 架构图
- 财务报告：文字 + 表格 + 图表
- 培训视频：音频 + 视频 + 字幕

多模态 RAG 架构

┌──────────────────────────────────────────────────────┐
│ 多模态 RAG Pipeline │
└──────────────────────────────────────────────────────┘
 │
 ┌───────────────┼───────────────┐
 ▼ ▼ ▼
 ┌─────────┐ ┌──────────┐ ┌──────────┐
 │ 文本 │ │ 图片 │ │ 表格 │
 │ 处理 │ │ 处理 │ │ 处理 │
 └────┬────┘ └────┬─────┘ └────┬─────┘
 │ │ │
 ▼ ▼ ▼
 ┌─────────┐ ┌──────────┐ ┌──────────┐
 │ 文本 │ │ VLM 描述 │ │ 结构化 │
 │ Embedding│ │ Embedding│ │ 存储 │
 └────┬────┘ └────┬─────┘ └────┬─────┘
 │ │ │
 └──────────────┼───────────────┘
 ▼
 ┌──────────────────┐
 │ 统一向量存储 │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 多模态检索 │
 │ - 文本 Query │
 │ - 图片 Query │
 └────────┬─────────┘
 │
 ▼
 ┌──────────────────┐
 │ 多模态生成 │
 │ (GPT-4V, Qwen-VL)│
 └──────────────────┘

各模态的处理方式

1. 图片

方案 1：VLM 描述
图片 → VLM → 文字描述 → Embedding

方案 2：直接 Embedding
图片 → CLIP/SigLIP → 图片向量

方案 3：混合
图片 → VLM 描述 + CLIP 向量 → 双路检索

2. 表格

方案 1：Markdown 化
表格 → Markdown 格式 → Embedding

方案 2：结构化存储
表格 → DataFrame → SQL 数据库
查询时：自然语言 → SQL → 执行查询

方案 3：行列切分
表格 → 每行一个 Chunk → 保留表头上下文

3. 音频/视频

音频：
音频 → ASR → 文字 → Embedding

视频：
视频 → 关键帧提取 → VLM 描述 → Embedding
 → ASR（音轨） → 文字 → Embedding

代表技术

技术	用途	特点
CLIP / SigLIP	图文联合 Embedding	支持以图搜文、以文搜图
GPT-4V / Qwen-VL	视觉语言模型	理解图片内容，生成描述
ColPali	端到端文档检索	直接用文档图片检索，无需 OCR
Whisper	语音识别	音频转文字

适用场景

✅ 推荐使用多模态 RAG：
- 知识库包含大量图片/图表
- 需要检索产品图片
- 需要理解架构图/流程图
- 视频内容检索

❌ 不推荐：
- 纯文本知识库
- 对成本敏感（VLM 调用昂贵）

五、长上下文 vs RAG

长上下文模型的崛起

2023 年：Claude 2（100K）、GPT-4 Turbo（128K）
2024 年：Claude 3（200K）、Gemini 1.5 Pro（1M）、Kimi（200K）
2025 年：上下文窗口继续扩大...

长上下文能替代 RAG 吗？

长上下文方案：
Query + 全部文档 → LLM → 答案

优势：
- 不需要检索，不会遗漏信息
- 全局理解能力强
- 实现简单

劣势：
- 成本高（每 token 都要计费）
- 延迟高（处理长上下文需要时间）
- 不适合大规模知识库（100 万 token 放不下）

RAG 的优势

RAG 方案：
Query → 检索 Top-K → LLM → 答案

优势：
- 成本可控（只处理相关文档）
- 延迟低
- 可扩展（知识库无限大）
- 可追溯（知道答案来自哪里）

劣势：
- 可能检索不准，遗漏信息
- 缺乏全局理解

结论：互补而非替代

场景分析：

| 场景 | 推荐方案 | 理由 |
|------|----------|------|
| 小规模文档（<100K） | 长上下文 | 简单，不会遗漏 |
| 大规模知识库 | RAG | 成本、延迟可控 |
| 需要全局理解 | 长上下文 | RAG 擅长局部检索 |
| 需要精确引用 | RAG | 可追溯来源 |
| 实时更新知识库 | RAG | 长上下文需要重新处理 |

最佳实践：RAG + 长上下文
- RAG 检索相关文档
- 长上下文模型处理检索结果
- 兼顾成本和效果

六、检索技术进阶

1. Dense Retrieval 的演进

第一代：Single Vector（单向量）
文档 → 一个向量
问题：语义压缩过度，细节丢失

第二代：Multi-Vector（多向量，ColBERT）
文档 → 每个 token 一个向量
问题：存储成本高，但精度提升

第三代：Late Interaction（延迟交互，ColPali）
检索时不压缩，最后才做交互
优势：精度最高，适合文档检索

ColBERT 的核心思想

传统向量检索：
Query: "机器学习" → 向量 Q
Doc: "机器学习是人工智能的分支..." → 向量 D
相似度 = Q · D

ColBERT：
Query: "机器学习" → [q1, q2]（每个 token 一个向量）
Doc: "机器学习是人工智能的分支..." → [d1, d2, d3, d4, ...]
相似度 = Σ max(qi · dj) ← 每个 Query token 找最相似的 Doc token

优势：
- "机器学习"中的"机器"和"学习"分别匹配
- 精度更高

2. Query 理解技术

HyDE（Hypothetical Document Embeddings）

问题：Query 很短，语义信息不足

HyDE 的思路：
1. 让 LLM 生成一个假设性答案
2. 用假设答案的向量检索
3. 假设答案与真实文档更相似

示例：
Query: "Python 如何读取 JSON 文件？"
↓ LLM 生成假设答案
假设答案: "可以使用 json.load() 函数读取 JSON 文件。首先导入 json 模块，然后用 open() 打开文件..."
↓ 用假设答案检索
检索结果: 找到真实的 JSON 读取教程

Multi-Query（多查询）

问题：用户的 Query 可能表述不清

Multi-Query 的思路：
1. 用 LLM 生成多个相关 Query
2. 多路检索
3. 结果融合

示例：
Query: "报销流程"
↓ LLM 生成
Query 1: "公司报销流程步骤"
Query 2: "报销需要哪些材料"
Query 3: "报销审批流程"
↓ 多路检索，融合结果

3. 自适应检索（Self-RAG）

问题：不是所有问题都需要检索

Self-RAG 的思路：
1. LLM 自己判断是否需要检索
2. 如果需要，检索并生成
3. 生成后，LLM 自我评估答案质量
4. 如果不满意，重新检索

示例：
Query: "写一个 Python Hello World"
↓ LLM 判断
不需要检索（LLM 自己会写）
↓ 直接生成

Query: "公司最新的报销政策"
↓ LLM 判断
需要检索（LLM 不知道）
↓ 检索 → 生成

七、生成技术进阶

1. Citation（引用溯源）

RAG 的可信度关键：答案来自哪里？

输出格式：
答案：参数 timeout 的类型是 int，默认值是 30 秒。
引用：
 [1] API 文档.pdf, 第 3 页, 表格 2
 [2] 配置说明.md, 第 15 行

实现方式：
1. 检索时记录每个 Chunk 的来源
2. 生成时让 LLM 标注使用了哪些 Chunk
3. 前端支持点击引用跳转原文

2. Fact Checking（事实核查）

问题：RAG 也可能产生幻觉

方案：生成后验证

流程：
1. LLM 生成答案
2. 提取答案中的事实陈述
3. 再次检索验证每个事实
4. 标注置信度或修正错误

示例：
答案："A 公司成立于 2010 年，创始人张三"
↓ 提取事实
事实 1: A 公司成立于 2010 年
事实 2: 创始人是张三
↓ 验证
事实 1: ✅ 文档确认
事实 2: ❌ 文档说是李四，不是张三
↓ 修正
答案："A 公司成立于 2010 年，创始人李四"

八、工程优化

1. 增量索引

问题：知识库每天都在更新

方案：
- 只索引新增/修改的文档
- 向量数据库支持增量写入
- 版本管理（可回滚）

实现：
1. 记录每个文档的 hash
2. 检测变更
3. 只索引变更部分
4. 定期全量重建（避免碎片化）

2. 多级缓存

缓存层级：

Level 1: Exact Match Cache
完全相同的问题 → 直接返回缓存答案
命中率：10-20%

Level 2: Semantic Cache
语义相似的问题 → 返回缓存答案
示例："报销流程" ≈ "如何报销"
命中率：20-30%

Level 3: Query Cache
缓存检索结果，只重新生成
命中率：30-40%

效果：
- 延迟降低 60-80%
- 成本降低 50-70%

3. RAG 评估

评估维度：

检索质量：
- Recall@K：前 K 个结果中相关文档的比例
- MRR：正确答案的平均排名
- NDCG：考虑排序的检索质量

生成质量：
- Faithfulness：答案是否忠实于检索内容
- Relevance：答案是否回答了问题
- Coherence：答案是否连贯

端到端：
- Correctness：答案是否正确
- Completeness：答案是否完整
- Latency：响应延迟

评估工具：
- RAGAS：自动化 RAG 评估
- TruLens：LLM 应用评估
- DeepEval：开源评估框架

九、技术选型指南

按场景选择

场景 1：企业知识库（文档密集）
推荐：RAGFlow / Dify / FastGPT
理由：开箱即用，文档解析强

场景 2：需要多跳推理
推荐：GraphRAG / LightRAG
理由：知识图谱支持复杂推理

场景 3：需要 Agent 编排
推荐：LangGraph / CrewAI
理由：灵活的工作流控制

场景 4：多模态知识库
推荐：RAGFlow / LlamaIndex + VLM
理由：支持图片、表格、视频

场景 5：快速原型
推荐：Dify / AnythingLLM
理由：低代码，快速落地

场景 6：深度定制
推荐：LangChain / LlamaIndex
理由：底层控制能力强

按技术栈选择

已有 LangChain 项目：
→ 继续用 LangChain + LangGraph

已有 LlamaIndex 项目：
→ 继续用 LlamaIndex + GraphRAG

从零开始：
→ 考虑 RAGFlow（一站式）或 Dify（低代码）

需要图数据库：
→ Neo4j + LangChain/LlamaIndex

需要极致性能：
→ 自建向量库 + 自定义检索逻辑

十、开源项目速览

项目	Stars	特点	适用场景
RAGFlow	82K+	DeepDoc 文档解析	企业知识库
MinerU	67K+	通用文档解析	文档转 Markdown
Dify	50K+	RAG + Agent 平台	低代码构建
FastGPT	20K+	国产 RAG 平台	快速落地
LangGraph	10K+	Agent 编排	复杂工作流
LightRAG	10K+	轻量级 Graph RAG	多跳推理
GraphRAG	10K+	Microsoft 出品	企业级图谱
QAnything	10K+	多模态 RAG	端到端方案
AnythingLLM	20K+	全功能平台	企业部署

十一、学习资源

必读论文：

Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks（RAG 原始论文）
Self-RAG: Learning to Retrieve, Generate, and Critique through Self-Reflection
GraphRAG: Unlocking LLM Discovery on Narrative Private Data
Dense Passage Retrieval for Open-Domain Question Answering

官方文档：

LlamaIndex Documentation
LangChain RAG Tutorial
RAGFlow Documentation

评估框架：

RAGAS: https://github.com/explodinggradients/ragas
TruLens: https://www.trulens.org/
DeepEval: https://github.com/confident-ai/deepeval

十二、总结

RAG 技术正在快速演进，从简单的"检索 + 生成"发展为复杂的多技术融合系统。

技术演进路线：

RAG 1.0 → RAG 2.0 → RAG 3.0
基础检索 → 多路融合 → Agent + Graph + 多模态

核心趋势：
1. 从被动检索到主动规划
2. 从单一模态到多模态融合
3. 从局部检索到全局理解
4. 从固定流程到自适应调整

选择技术方案时，关键是明确需求：

简单场景：用 RAGFlow、Dify 这类一站式方案
复杂推理：引入 Graph RAG
Agent 编排：用 LangGraph
多模态：选择支持 VLM 的方案
深度定制：用 LangChain/LlamaIndex 自建

没有银弹，只有最适合的方案。

相关文章：

RAGFlow 深度解析：为什么它是最值得关注的 RAG 开源项目

Wed, 25 Mar 2026 16:00:00 +0800

过去两年，RAG 领域涌现了无数框架：LangChain、LlamaIndex、Haystack……它们各有侧重，但解决的核心问题相似——如何让 LLM 接地气。

但如果你实际做过企业级 RAG 项目，会发现一个被忽视的问题：文档解析。

大部分框架默认你已经有干净、结构化的文本。现实却是：PDF 扫描件、嵌套表格、数学公式、多栏排版……这些"脏活累活"往往占据项目 60% 以上的时间。

RAGFlow 的定位很明确：从文档到答案的全流程解决方案，而不是又一个"需要你自己处理文档"的检索框架。

这篇文章会深入分析 RAGFlow 的设计思路、核心技术和适用场景。

一、RAGFlow 的差异化定位

现有框架的盲区

LangChain 和 LlamaIndex 的设计假设是：

输入：干净的文本 / 简单的 PDF
处理：Chunk → Embed → Retrieve → Generate
输出：答案

但企业真实场景是：

输入：扫描件 PDF、带表格的年报、技术手册、合同......
预处理：OCR、布局分析、表格识别、公式识别......
处理：Chunk → Embed → Retrieve → Generate
输出：答案 + 引用

预处理阶段的复杂度，往往被框架忽略。

RAGFlow 的思路

RAGFlow 的核心定位：

不只是 RAG 框架，而是"文档理解 + RAG"的一体化方案

它的技术栈覆盖：

阶段	能力	技术方案
文档解析	OCR、布局分析、表格识别	DeepDoc（自研）
文档切分	8 种切分策略	按文档类型选择
检索	向量 + 关键词 + Rerank	混合检索 + RRF 融合
生成	多模型支持	OpenAI、Qwen、Ollama 等
运维	可视化 UI、API、监控	企业级特性

一句话总结：RAGFlow 解决的是"从 PDF 到答案"的完整链路，而不是"从文本到答案"。

二、DeepDoc：RAGFlow 的核心护城河

DeepDoc 是 RAGFlow 自研的文档理解引擎，也是它区别于其他框架的核心竞争力。

为什么需要 DeepDoc

传统 PDF 解析的问题：

问题 1：OCR 质量差

原文：错误码 E0028
OCR 结果：错误码 E002B（8 被识别成 B）

用户问：错误码 E0028 是什么意思
检索：找不到（因为文档里是 E002B）

问题 2：布局信息丢失

原文（两栏排版）：
┌──────────────┬──────────────┐
│ 左栏内容 │ 右栏内容 │
│ 跨多行... │ 跨多行... │
└──────────────┴──────────────┘

普通解析结果：
左栏内容
右栏内容 ← 两栏混在一起，语义被打断

问题 3：表格结构破坏

原文表格：
┌────────┬────────┬────────┐
│ 参数 │ 类型 │ 说明 │
├────────┼────────┼────────┤
│ timeout│ int │ 超时时间│
│ retry │ bool │ 是否重试│
└────────┴────────┴────────┘

普通解析结果：
参数 类型 说明 timeout int 超时时间 retry bool 是否重试
← 变成一行，结构全丢了

DeepDoc 的技术方案

DeepDoc Pipeline：

┌──────────┐ ┌──────────┐ ┌──────────────┐
│ Input │───▶│ Layout │───▶│ OCR Engine │
│ File │ │ Analysis│ │ (PaddleOCR) │
└──────────┘ └──────────┘ └──────┬───────┘
 │
 ┌──────────────────────┘
 ▼
┌──────────────────────────────────────────────┐
│ Structure Recognition │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Table │ │ Figure │ │ Formula │ │
│ │ Parser │ │ Parser │ │ Parser │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└──────────────────────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────┐
│ Semantic Understanding │
│ • 标题识别 │
│ • 章节分割 │
│ • 关系提取 │
└──────────────────────────────────────────────┘
 │
 ▼
┌──────────────────────────────────────────────┐
│ Markdown / Structured Output │
└──────────────────────────────────────────────┘

核心技术点：

模块	技术方案	解决的问题
OCR	PaddleOCR	高精度文字识别
布局分析	YOLO/LayoutLM	检测文本、表格、图片区域
表格识别	Table-Transformer	还原表格结构
公式识别	LaTeX-OCR	数学公式转 LaTeX
图片描述	VLM	生成图片文字描述

表格识别的原理

表格是最难处理的文档元素之一。DeepDoc 的表格识别流程：

Step 1: 表格检测
用目标检测模型定位表格区域

Step 2: 结构识别
Table-Transformer 识别：
- 行边界
- 列边界
- 单元格合并关系

Step 3: 内容识别
对每个单元格做 OCR

Step 4: 结构化输出
┌────────┬────────┐
│ A1 │ A2 │ → [{"row":1,"col":1,"text":"A1"}, ...]
├────────┼────────┤
│ B1 │ B2 │
└────────┴────────┘

为什么这件事重要？

如果表格结构丢了，用户问"参数 timeout 的类型是什么"，系统找不到答案——因为表格已经变成一团乱码。

与其他解析方案的对比

|| 方案 | OCR | 布局分析 | 表格识别 | 公式识别 | 输出格式 | |——|—–|———-|———-|———-|———-| | PyPDF2 | ❌ | ❌ | ❌ | ❌ | 纯文本 | | pdfplumber | ❌ | ⚠️ 基础 | ⚠️ 基础 | ❌ | 纯文本 | | Unstructured | ⚠️ 外部 | ✅ | ⚠️ 基础 | ❌ | 结构化 | | MinerU | ✅ | ✅ | ✅ | ✅ | Markdown/JSON | | DeepDoc | ✅ | ✅ | ✅ | ✅ | 结构化 + 语义信息 |

DeepDoc vs MinerU：不同的设计哲学

MinerU 是 2024 年上海人工智能实验室开源的文档解析工具，同样具备强大的 OCR、表格识别、公式识别能力。但 DeepDoc 和 MinerU 的设计目标有本质区别：

MinerU：通用文档解析工具

定位：将文档转换为 LLM 可用的 Markdown/JSON
输出：标准化的文本格式
目标：服务于各种下游应用（RAG、Agent、知识库等）
集成：支持 LangChain、Dify、FastGPT、RAGFlow 等

DeepDoc：RAG 原生文档理解引擎

定位：RAGFlow 的核心组件，深度集成
输出：保留语义结构的中间表示（标题层级、章节边界、表格结构等）
目标：直接服务于 Chunking 和检索策略
特点：与后续流程紧密耦合，非独立工具

核心差异：输出是否保留结构语义

MinerU 输出（Markdown）：
# 第一章 概述
## 1.1 背景
文本内容...
## 1.2 目标
文本内容...

↓ 丢失了什么？
- 标题的层级深度信息
- 章节边界的精确位置
- 表格的行列结构（变成 Markdown 表格，但丢失原始坐标）

DeepDoc 输出（结构化表示）：
{
 "chunks": [
 {
 "text": "文本内容...",
 "metadata": {
 "hierarchy": ["第一章", "概述", "1.1", "背景"],
 "level": 3,
 "bbox": [x1, y1, x2, y2],
 "type": "paragraph"
 }
 }
 ],
 "tables": [
 {
 "cells": [[...]],
 "headers": ["参数", "类型", "说明"],
 "bbox": [...]
 }
 ]
}

为什么 RAGFlow 不用 MinerU？

时间线：RAGFlow（2023.12）比 MinerU（2024.02）更早，DeepDoc 已经开发成熟
深度集成：DeepDoc 的输出直接适配 8 种 Chunking 策略，需要语义和结构信息
核心护城河：文档理解是 RAGFlow 的差异化竞争力，不依赖外部工具
输出差异：MinerU 输出 Markdown，DeepDoc 输出保留更多结构信息

选择建议

场景	推荐	理由
只需要文档转 Markdown	MinerU	开箱即用，输出标准
构建企业 RAG 系统	RAGFlow + DeepDoc	文档解析与检索一体化
已有 RAG 框架，需补充解析能力	MinerU	作为独立组件集成
需要自定义 Chunking 逻辑	MinerU + 自己实现	更灵活

DeepDoc 是目前开源方案中唯一为 RAG 场景深度优化的文档解析引擎。

三、Chunking 策略：一种文档一种切法

RAGFlow 提供了 8 种 Chunking 策略，针对不同文档类型：

为什么需要多种策略

不同类型文档的结构差异很大：

FAQ 文档：
Q: 问题
A: 答案
─────────
每个 QA 对是独立的语义单元

技术手册：
## 安装
步骤 1...
步骤 2...
## 配置
参数 1...
参数 2...
─────────
按章节切分，保留标题上下文

法律文档：
第一条 ...
第二条 ...
第三条 ...
─────────
按条款切分，每条有独立法律意义

用同一种"固定长度切分"处理所有文档，效果必然不好。

RAGFlow 的 8 种策略

策略	适用文档	切分依据
Naive	简单文本	固定字符数
Q&A	FAQ 文档	问题-答案对
Book	书籍、长文档	章节层级
Manual	技术手册	小节
Law	法律、合同	条款
Paper	学术论文	摘要、章节
Table	表格数据	行/单元格
Picture	图片	VLM 描述

核心思路：保留语义完整性

无论哪种策略，核心原则相同：一个 chunk 应该能独立回答一个问题。

以 Book Chunking 为例：

原始文档：
# 第一章 概述
## 1.1 背景
文本内容...
## 1.2 目标
文本内容...
# 第二章 设计
## 2.1 架构
文本内容...

切分结果：
Chunk 1: 【第一章 概述 > 1.1 背景】文本内容...
Chunk 2: 【第一章 概述 > 1.2 目标】文本内容...
Chunk 3: 【第二章 设计 > 2.1 架构】文本内容...

关键设计：把父级标题拼到 chunk 前面。

这样做的原因我在 RAG 进阶篇详细讲过：Embedding 只能看到 chunk 内部的文字。如果 chunk 里没有"第一章"、“概述”、“背景"这些关键词，用户问"第一章的背景是什么"时就召不回。

Table Chunking 的特殊性

表格数据的切分需要特殊处理：

方案 1：行级切分
每行一个 chunk，保留表头

方案 2：单元格级切分
每个单元格一个 chunk，附带行列信息

RAGFlow 的做法：
- 检测表格结构
- 保留表头作为上下文
- 行级切分
- 每个 chunk 包含：表头 + 该行内容

示例：
原始表格：
| 参数 | 类型 | 说明 |
|------|------|------|
| timeout | int | 超时时间 |

切分后的 chunk：
【表：API 参数配置】
参数: timeout | 类型: int | 说明: 超时时间

这样用户问"timeout 参数的类型是什么”，就能精确召回这一行。

四、检索架构：混合检索 + RRF 融合

RAGFlow 的检索架构是标准的混合检索方案：

整体架构

Query
 │
 ├─── 向量检索（Dense）───┐
 │ │
 ├─── 关键词检索（BM25）──┤──→ RRF 融合 ──→ Rerank ──→ Top-K
 │ │
 └─── Metadata 过滤 ─────┘

RRF 融合算法

RRF（Reciprocal Rank Fusion）的核心思想：不依赖分数，只依赖排名。

RRF 公式：
score(d) = Σ 1 / (k + rank_i(d))

其中：
- d：文档
- rank_i(d)：文档 d 在第 i 路检索中的排名
- k：平滑参数（通常 60）

为什么有效？

问题：向量分数（0.82）和 BM25 分数（5.2）不在同一尺度

传统方案：
- 分数归一化：复杂，不稳定
- 加权融合：权重难调

RRF 的做法：
- 不管分数多少
- 只看排名
- 排名第 1 → 得分 1/61
- 排名第 2 → 得分 1/62
- 两路都召回的文档，得分更高

示例：

Query："错误码 401"

向量检索：
#1 Doc_A
#2 Doc_B
#3 Doc_C

BM25 检索：
#1 Doc_D
#2 Doc_C ← 两路都有
#3 Doc_A ← 两路都有

RRF 融合：
Doc_C: 1/(60+3) + 1/(60+2) = 0.032 ← 最高
Doc_A: 1/(60+1) + 1/(60+3) = 0.032
Doc_B: 1/(60+2) + 0 = 0.016
Doc_D: 0 + 1/(60+1) = 0.016

两路都召回的文档，得分更高，自然排在前面。

Rerank 实现

RAGFlow 内置 Cross-Encoder Rerank：

原理：
Query + Document → Transformer → Relevance Score

为什么比向量检索更准：
- 向量检索：Query 和 Document 各自编码，交互少
- Cross-Encoder：Query 和 Document 拼在一起编码，充分交互

支持的 Rerank 模型：

模型	特点	延迟（100 候选）
bge-reranker-v2-m3	多语言，效果好	~180ms
bge-reranker-large	效果好	~150ms
ms-marco-MiniLM	轻量，快速	~45ms

Rerank 的成本很高，只能对小规模候选做精排。RAGFlow 的默认配置：

召回：top-50（向量 + BM25）
Rerank：top-50 全部重排
输出：top-5

五、与其他框架的对比

功能对比

维度	RAGFlow	LangChain	LlamaIndex
文档解析	⭐⭐⭐⭐⭐ DeepDoc	⭐⭐⭐ 基础	⭐⭐⭐ 基础
Chunking	⭐⭐⭐⭐⭐ 8 种策略	⭐⭐⭐ 需自己实现	⭐⭐⭐⭐ 较丰富
检索	⭐⭐⭐⭐⭐ 混合 + RRF	⭐⭐⭐ 需组合	⭐⭐⭐⭐ 较完整
可视化 UI	⭐⭐⭐⭐⭐ 完整	⭐⭐ LangSmith	⭐⭐⭐ LlamaCloud
开箱即用	⭐⭐⭐⭐⭐ 高	⭐⭐⭐ 需组装	⭐⭐⭐⭐ 较高
自定义扩展	⭐⭐⭐ 中等	⭐⭐⭐⭐⭐ 高	⭐⭐⭐⭐⭐ 高

架构理念对比

RAGFlow：应用导向
"我要做一个企业知识库" → RAGFlow 提供完整方案
特点：一站式，开箱即用

LangChain：组件导向
"我要组装一个 Agent" → LangChain 提供各种组件
特点：灵活，但需要自己组装

LlamaIndex：数据导向
"我要索引和查询数据" → LlamaIndex 提供数据框架
特点：数据处理能力强，适合研究

代码风格对比

# RAGFlow：高层抽象，配置驱动
from ragflow import RAGFlow

app = RAGFlow()
dataset = app.create_dataset(name="knowledge")
dataset.add_documents("./docs")
chat = app.create_chat(dataset=dataset)
response = chat.query("What is RAG?")

# LangChain：Chain 组合式
from langchain.chains import RetrievalQA
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings

vectorstore = Chroma.from_documents(docs, OpenAIEmbeddings())
qa = RetrievalQA.from_chain_type(
 llm=ChatOpenAI(),
 retriever=vectorstore.as_retriever()
)
response = qa.run("What is RAG?")

# LlamaIndex：索引为中心
from llama_index import VectorStoreIndex, SimpleDirectoryReader

documents = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("What is RAG?")

选型建议

场景	推荐	理由
企业知识库	RAGFlow	开箱即用，DeepDoc 解析复杂文档
复杂 Agent 应用	LangChain	灵活的 Chain/Tool 组合
数据分析研究	LlamaIndex	强大的索引策略
快速原型	RAGFlow	最快落地
高度定制化	LangChain/LlamaIndex	更底层的控制

六、生产级特性

API 设计

RAGFlow 提供完整的 REST API：

# 创建数据集
POST /api/dataset
{"name": "my_knowledge"}

# 上传文档
POST /api/document/upload
-F "file=@document.pdf"
-F "dataset_id={id}"

# 对话
POST /api/chat/completion
{
 "question": "什么是 RAG?",
 "dataset_ids": ["{id}"],
 "stream": true
}

部署方案

最小部署（Docker Compose）：
├── ragflow（API 服务）
├── milvus（向量库）
├── mysql（元数据）
└── elasticsearch（可选，全文检索）

生产部署（Kubernetes）：
├── Ingress
├── ragflow deployment（多副本）
├── milvus cluster
├── mysql primary/replica
└── 监控（Prometheus + Grafana）

多租户与权限

租户隔离：
- 每个租户独立的数据集
- 数据集级别的访问控制
- API Key 认证

权限模型：
- 管理员：全部权限
- 编辑者：上传、解析、编辑
- 查看者：仅查询

可观测性

指标监控：
- 文档处理吞吐量
- 检索延迟（P50/P95/P99）
- LLM 调用耗时
- 向量库查询性能

日志追踪：
- 请求级 Trace ID
- 结构化日志
- 全链路追踪

七、RAGFlow 的优势与局限

优势

维度	说明
DeepDoc	业界最强的开源文档解析能力
开箱即用	完整 UI + API，快速落地
企业级	多租户、权限、监控完备
多策略 Chunking	针对不同文档类型优化
混合检索	向量 + BM25 + Rerank 完整支持

局限

维度	说明
灵活性	不如 LangChain/LlamaIndex 灵活
Agent 能力	不适合复杂多 Agent 场景
定制成本	深度定制需要理解源码
学习曲线	概念较多，需要时间熟悉

适用场景

强烈推荐：

企业内部知识库
需要处理复杂文档（PDF、表格）
追求快速落地
需要可视化管理和审计

谨慎选择：

复杂 Agent 编排
需要深度定制检索逻辑
已有 LangChain/LlamaIndex 生态

八、快速入门

# 克隆项目
git clone https://github.com/infiniflow/ragflow.git
cd ragflow

# Docker Compose 启动
docker compose up -d

# 访问 Web UI
open http://localhost:9380

# 创建数据集、上传文档、开始对话

核心概念：

Dataset（数据集）
├── Document（文档）
│ ├── Chunk（切片）
│ └── Embedding（向量）
└── Chat（对话）

流程：
上传文档 → DeepDoc 解析 → 切分 → 向量化 → 存储
 ↓
Query → 检索 → Rerank → LLM 生成 → 答案 + 引用

九、总结

RAGFlow 不是"又一个 RAG 框架"，而是从文档到答案的全流程解决方案。

它的核心价值：

1. DeepDoc：解决被忽视的文档解析问题
2. 多策略 Chunking：不同文档不同切法
3. 混合检索：向量 + BM25 + Rerank
4. 开箱即用：UI + API + 部署方案

如果你在做企业级 RAG 项目，尤其是需要处理复杂文档的场景，RAGFlow 是目前最值得尝试的开源方案。

它不一定是灵活性最高的，但可能是落地最快的。

相关链接：

GitHub: https://github.com/infiniflow/ragflow
文档: https://ragflow.io/docs
Demo: https://ragflow.io

相关文章：

RAG生产实践：常见坑、性能优化与迭代路线图

Wed, 25 Mar 2026 15:55:00 +0800

RAG 的 Demo 很容易做，生产环境却很容易失控。

一开始你可能只要：

一个 embedding 模型
一个向量库
一个聊天模型

但真到线上，问题会迅速变成：

更新怎么做
成本怎么控
延迟怎么降
数据怎么隔离
错误怎么排查
版本怎么回归

所以生产级 RAG 的重点是"工程稳定性"，不只是"回答效果"。

这篇文章会讲：

生产环境最常见的坑
性能优化的思路
一个可执行的迭代路线

一、最常见的 10 个坑

坑 1：把所有文档放进一个大集合

现象：

公司有产品文档、技术规范、内部 wiki、销售话术、HR 制度……全部丢进一个向量库。

问题：

用户问"API 超时怎么配置"，检索结果混入了销售话术（因为提到了"时间"）、HR 制度（因为提到了"加班时间"）。正确答案被噪声淹没。

原理：

向量检索基于语义相似度。“时间"这个概念在很多文档里都出现，如果检索范围太大，语义相似的噪声也会被召回。

解决：

按业务边界拆分 source，检索时指定来源。

知识库结构：
├── product_docs/ # 产品文档
├── api_specs/ # API 规范
├── internal_wiki/ # 内部 wiki
└── hr_policies/ # HR 制度

检索时：
filter = {"source": "api_specs"}

效果：

配置	Recall@5	噪声比例
全量检索	58%	62%
按 source 过滤	84%	18%

坑 2：chunk 没有业务上下文

现象：

按段落切分后，某个 chunk 只剩一句话：“将旋钮调至 3 档，等待指示灯变绿。”

问题：

用户问"ZK-200 怎么校准”，这个 chunk 不会召回。因为产品名、设备类型、操作名称都在标题里——被切掉了。

原理：

Embedding 只能看到 chunk 内部的文字。如果 chunk 里没有"ZK-200"和"校准"这些关键词，向量就不会和这些问题相似。

解决：

把父级标题拼到 chunk 前面：

原始 chunk：
"将旋钮调至 3 档，等待指示灯变绿。"

补充上下文：
"【ZK-200 操作手册 > 2. 使用方法 > 2.3 校准流程】
将旋钮调至 3 档，等待指示灯变绿。"

效果：

配置	Recall@5
原始 chunk	41%
补充上下文后	78%

这是 RAG 里性价比最高的优化之一：成本几乎为零，效果翻倍。

坑 3：只做 dense search

现象：

用户问"错误码 E0028 是什么意思"，向量检索召回的是"常见错误码及解决方案"这种泛泛而谈的文档，而不是精确包含"E0028"的那段。

原理：

向量检索擅长语义相似，不擅长精确匹配。“E0028"作为一个编号，在向量空间里没有特殊意义，它只是一个 token。

解决：

引入 BM25 或 sparse 检索，做混合检索。

混合检索：
向量检索 → 召回语义相似的文档
BM25 检索 → 召回包含精确关键词的文档
RRF 融合 → 合并两路结果

效果：

检索方式	精确匹配查询 Recall@5	语义查询 Recall@5
向量检索	47%	82%
BM25	76%	58%
混合检索	84%	85%

坑 4：假 rerank

现象：

代码里写着"rerank”，但只是把向量分数重新排了一次序。

def rerank(candidates):
 return sorted(candidates, key=lambda x: x['score'], reverse=True)

问题：

这不是真正的 rerank，只是把已有的分数重新排序，效果和没有 rerank 一样。

原理：

真正的 Rerank 需要用 Cross-Encoder：

把 Query 和每个候选 Document 拼在一起
丢进 Transformer，让模型学习两者的交互
输出新的相关性分数

这比双塔结构的向量检索更精确，因为 Query 和 Document 能充分交互。

解决：

使用真正的 Cross-Encoder 模型：

候选文档 → Cross-Encoder → 新分数 → 重新排序

效果：

配置	Recall@5	正确答案平均排名
无 Rerank	72%	4.2
假 Rerank	72%	4.1
真 Rerank	88%	1.8

坑 5：top_k 和阈值写死

现象：

所有场景都用固定的 top_k=5 和 score_threshold=0.3。

问题：

简单问题：只需要 3 个候选就够了，多余的候选增加噪声
复杂问题：需要 10 个候选才能覆盖，5 个不够

原理：

检索参数取决于问题的复杂度、文档的分布、embedding 模型的特性。不同场景的最优参数不同。

解决：

参数可配置，甚至动态调整：

简单事实问题 → top_k=3, threshold=0.5（少而精）
复杂问题 → top_k=15, threshold=0（多召回）
对比类问题 → top_k=20（需要更多信息）

坑 6：没有 context budget 设计

现象：

检索到 15 个 chunk，全部塞进 prompt，总共 12000 tokens。

问题：

成本高：token 消耗大
延迟高：模型处理慢
效果差：内容太长，模型注意力分散（Lost in the Middle 问题）

原理：

LLM 的注意力机制在长文本上会分散。研究表明，当相关信息在 prompt 中间位置时，模型更容易忽略它。

解决：

设计 context budget：

预算：4000 tokens

组装策略：
1. 优先高分 chunk
2. 控制 token 总量
3. 必要时截断过长的 chunk
4. 保持来源多样性（不同 source 的 chunk 都有）

经验值：

场景	推荐 token 预算
简单问答	2000-3000
复杂问答	3000-5000
文档总结	5000-8000

坑 7：文档更新了，索引没同步

现象：

周一用户问"报销流程"，答案正确。周三财务更新了报销规范，周五用户再问，答案还是旧的。

问题：

文档更新后，向量库没有同步，还在用旧版本。

解决：

建立版本管理机制：

方案 1：定时全量同步
- 每天凌晨重建索引
- 简单但成本高

方案 2：增量更新
- 监控文档变更
- 只更新变化的文档
- 复杂但成本低

方案 3：版本标记
- 每个文档有版本号
- 检索时检查版本是否最新
- 过期则重新索引

关键：保留文档的 hash 或时间戳，便于判断是否需要更新。

坑 8：没有证据引用

现象：

模型回答：“报销需要提交发票和审批单。”

用户：“这个答案依据是什么？”

系统无法回答。

问题：

答案和来源脱节，用户无法验证答案的可信度。

解决：

Prompt 中强制要求引用：

要求：
1. 答案必须基于参考资料
2. 回答时标注引用来源，格式：[来源: 文档名 > 章节]
3. 如果不确定，说明不确定

答案示例：

报销需要提交发票和审批单 [来源: 财务规范 > 3.2 报销流程]。

好处：

用户可以验证答案
系统可以追溯错误
增加答案可信度

坑 9：没有离线 benchmark

现象：

开发者说"效果提升了"，产品说"感觉变差了"，谁也说服不了谁。

问题：

没有客观的评价标准，优化靠主观感受。

解决：

建立固定 benchmark：

评测集：
- 50-100 个问题
- 每个问题有期望召回的 chunk
- 每个问题有参考答案

定期评测：
- 每次改动后跑 benchmark
- 对比历史版本
- 设置阈值（如 Recall@5 > 80%）

原则：

评测集要隔离，不参与训练
定期从线上采样真实问题，更新评测集
多指标综合评估

坑 10：没有 inspect 能力

现象：

答案错了，不知道是检索错、排序错、还是模型错。

问题：

无法定位问题，优化靠猜。

解决：

保留每次请求的 Trace：

Trace 包含：
- 用户问题
- 检索候选（top-10）
- Rerank 结果
- 最终 prompt
- 模型答案

有 Inspect 页面，可以查看每一步的中间结果。

好处：

快速定位问题
积累 bad cases
指导优化方向

二、性能优化的思路

延迟分析

一个典型 RAG 请求的延迟分布：

总延迟：400-600ms

├── Query Embedding：30-50ms（5-10%）
├── 向量检索：30-50ms（5-10%）
├── BM25 检索：10-20ms（2-5%）
├── RRF 融合：<5ms（<1%）
├── Rerank：150-200ms（30-50%）← 主要瓶颈
├── Prompt 组装：<10ms（<1%）
└── LLM 生成：150-300ms（30-50%）← 主要瓶颈

两个主要瓶颈：Rerank 和 LLM 生成。

Rerank 优化

思路 1：减少候选数量

Rerank 的计算量与候选数量成正比。

100 个候选 × Cross-Encoder ≈ 200ms
30 个候选 × Cross-Encoder ≈ 70ms

但不能减太少，否则会漏掉正确答案。建议：

召回 50-100 个
Rerank 前 20-30 个
输出 top 5-10 个

思路 2：用更快的模型

模型	延迟（100 候选）	Recall@5
bge-reranker-large	~180ms	88%
bge-reranker-base	~95ms	85%
ms-marco-MiniLM	~45ms	80%

速度和效果的权衡。

思路 3：跳过简单问题

对于简单问题，可能不需要 Rerank：

简单问题（候选集中度高）→ 跳过 Rerank
复杂问题（候选分散）→ 需要 Rerank

判断标准：看 top-5 候选的分数分布。如果第一名分数远高于其他，说明检索已经足够准确。

LLM 优化

思路 1：用更快的模型

GPT-4o-mini 比 GPT-4o 快 3-5 倍，成本是 1/10。

对于大部分 RAG 场景，mini 版足够用。

思路 2：流式输出

不要等完整答案生成，边生成边返回：

传统模式：
用户等待 → 完整答案 → 一次返回（延迟高）

流式模式：
用户等待 → 第一个字 → 第二个字 → ...（感知延迟低）

流式不会减少实际延迟，但能改善用户体验。

思路 3：缓存热门 query

相同问题直接返回缓存：

热门问题 TOP 100：
"报销流程" → 缓存答案
"API 认证" → 缓存答案
...

命中率：10-30%
节省：10-30% 的 LLM 调用

检索优化

思路 1：缓存 query embedding

同一个问题的 embedding 可以缓存：

Query → Embedding（40ms）
Query（重复）→ 缓存（<1ms）

思路 2：预计算

某些场景可以预计算：

FAQ 场景：
- 预计算每个 FAQ 的 embedding
- 预计算每个 FAQ 的最佳答案
- 用户问题直接匹配 FAQ

适合问题集合固定的场景。

思路 3：减少召回数量

如果检索质量已经很高，可以减少召回数量：

top-50 → top-30
节省：向量检索和 Rerank 的时间
风险：可能漏掉正确答案

三、成本优化

Token 消耗分析

单次请求的 token 消耗：

输入 token：
- Query：20-50
- Chunks（5个）：2000-5000
- System prompt：100-200
总输入：2000-6000 tokens

输出 token：
- Answer：100-500

按 GPT-4o-mini 定价：
输入：$0.15/1M tokens
输出：$0.60/1M tokens

单次请求成本：$0.0003-0.001
日均 10000 次 → 月成本：$100-300

成本优化思路

1. 控制上下文长度

上下文太长不仅成本高，效果还差。

经验值：3000-4000 tokens

超过预算时：
- 截断过长的 chunk
- 减少进入 prompt 的 chunk 数量
- 优先保留高分的 chunk

2. 用更便宜的模型

GPT-4o-mini 的成本是 GPT-4o 的 1/10，效果差距不大。

3. 缓存热门问题

10-30% 的请求是重复问题，直接返回缓存。

4. 优化 prompt

去掉冗余的 prompt 内容，精简指令。

差的 prompt（冗长）：
"你是一个非常专业的技术文档助手，你的任务是根据用户提供的参考资料
来回答用户的问题。请注意，你的回答必须严格基于参考资料..."

好的 prompt（精简）：
"根据参考资料回答问题。答案必须基于资料，标注来源[数字]。"

四、迭代路线图

V1：能跑通（1-2 周）

目标：回答对 60% 的核心问题

配置：
- 基础 chunking（按段落）
- 纯向量检索（top_k=5）
- 基础 prompt + 引用要求

验收：
- 能回答常见问题
- 有引用来源
- 能 demo 演示

不要做：

不要全量导入所有文档
不要追求复杂架构
不要过度优化

V2：能诊断（2-3 周）

目标：知道为什么对/错

配置：
- Inspect 页面（看检索候选）
- Metadata 过滤
- 参数可配置
- 离线评测集（50 条）

验收：
- 能看到检索的 top-10
- 能定位问题在哪一层
- 有 Recall@5 指标

V3：能优化（3-4 周）

目标：召回率 80%+

配置：
- Hybrid Retrieval（向量 + BM25）
- 真 Rerank
- Chunking 优化（补充上下文）
- 评测集扩展（100 条）

验收：
- Recall@5 > 80%
- 能回答复杂问题
- Bad cases 持续跟踪

V4：能运营（持续）

目标：持续监控、持续迭代

配置：
- Trace 存储
- 监控大盘
- 告警规则
- 用户反馈收集
- CI/CD 集成

验收：
- 有质量监控
- 能快速定位线上问题
- 每次改动有回归测试

收益递减规律

60% → 80%：基础优化（chunking、混合检索）
80% → 90%：系统优化（Rerank、prompt 调优）
90% → 95%：高级优化（query rewrite、模型微调）
95% → 99%：难度极大，投入产出比低

建议：先做到 85%，再决定是否值得继续投入。

五、团队协作

角色分工

产品/运营：
- 定义知识边界
- 收集 bad cases
- 标注评测集
- 用户反馈归类

算法/NLP：
- Embedding 模型选择
- Rerank 模型调优
- Chunking 方案
- 高级策略

后端工程师：
- Ingestion pipeline
- 向量库维护
- Trace/Inspect 系统
- 性能优化
- 监控告警

协作流程

日常迭代：

1. 产品收集 bad cases
2. 算法分析问题（定位到哪一层）
3. 算法 + 后端共同优化
4. 跑 benchmark 验证
5. 上线 + 监控

问题归属

问题	归属	方向
召不回正确内容	算法	Chunking、检索策略
候选噪声多	算法	Rerank、过滤
答案格式不对	算法	Prompt
延迟高	后端	缓存、异步
系统不稳定	后端	稳定性
模型幻觉	算法	Prompt、模型选择
知识库没更新	产品/运营	文档维护流程

六、判断系统成熟度

如果满足以下条件，说明系统开始成熟：

□ 知道每次回答用了哪些证据
 （有 Inspect，能追溯）

□ 能复现错误回答的完整链路
 （有 Trace 存储）

□ 有固定 benchmark
 （定期跑，有阈值）

□ 能对比不同版本的质量
 （有版本管理，能 A/B）

□ 知道下一步优化哪一层
 （有监控，不是盲调）

如果这 5 条还做不到，最应该投入的不是"换更强模型"，而是把检索、Inspect 和评测体系补完整。

七、系列总结

这四篇文章回答了 RAG 的核心问题：

入门：

RAG 的本质：把知识从参数里剥离出来
Embedding 的原理：对比学习、向量空间
向量检索的局限：对精确匹配不稳定

进阶：

Chunking：按语义切分 + 补充上下文
混合检索：向量 + BM25 + RRF 融合
Rerank：Cross-Encoder 做真正的精排

评测：

分层评测：检索、重排、组装、生成
LLM-as-Judge：让大模型评判答案质量
Inspect：保留完整 Trace，定位单次问题

生产：

常见坑：上下文丢失、假 rerank、无引用
性能优化：缓存、模型选择、候选数量控制
迭代路线：从能跑到能运营

RAG 不是银弹，但它是目前让 LLM 接地气的最实用方案。关键在于：不要追求一步到位，而是建立可迭代的能力。

后续可以深入的方向：

Query Rewrite 和 Query Decomposition
Contextual Retrieval（Anthropic 的方法）
多租户与权限设计
RAG 与 Agent 的结合
多模态 RAG（图片、表格）

RAG评测与 Inspect：如何知道问题出在检索、重排还是生成

Wed, 25 Mar 2026 15:50:00 +0800

很多 RAG 项目最开始都能跑起来，但一到线上就会卡在一个非常现实的问题上：

用户说答案不对，可你根本不知道问题出在：

没召回到正确内容
召回到了，但排序不对
排好了，但没进最终 prompt
进了 prompt，但模型没用
模型用了，但引用展示错了

所以 RAG 一定不能只做"生成结果观测"，还要做"阶段化 inspect"。

这篇文章会讲：

如何分层定位问题
检索层和生成层的评测指标
LLM-as-a-Judge 的原理
Inspect 系统的设计思路

一、为什么评测这么难

RAG 的评测比传统检索或传统 NLP 都复杂，因为它是多阶段的 pipeline。

用户问题 → 检索 → 重排 → 组装 → 生成 → 答案

最终答案错了，可能的原因：

❌ 检索层：正确内容根本没召回
❌ 重排层：正确内容召回但被排到后面
❌ 组装层：正确内容被截断或过滤掉了
❌ 生成层：模型无视证据自由发挥

如果不分阶段评测，你只能知道"答案错了"，但不知道"为什么错"。

一个真实的问题定位案例

用户投诉：“问错误码 401 的意思，答案完全不对。”

定位过程：

第 1 步：检查检索层
- 用户问题："错误码 401 是什么意思"
- 检索候选 top-10：
 1. 常见 HTTP 错误码列表
 2. 认证失败怎么办
 3. 权限问题排查
 ...
 8. 错误码详解：401 Unauthorized ← 正确答案

结论：正确答案在候选里，但排第 8

第 2 步：检查重排层
- Rerank 后：
 1. 错误码详解：401 Unauthorized ← 正确答案排到第 1
 2. 常见 HTTP 错误码列表
 ...

结论：重排正常

第 3 步：检查组装层
- 最终进入 prompt 的 chunk：
 1. 错误码详解：401 Unauthorized ✅
 2. 常见 HTTP 错误码列表 ✅
 3. 认证失败怎么办 ✅

结论：组装正常

第 4 步：检查生成层
- Prompt 包含正确证据
- 模型输出："错误码 401 表示服务器内部错误..."

结论：模型幻觉！401 是认证错误，不是服务器内部错误

最终诊断：
✅ 检索层：正常
✅ 重排层：正常
✅ 组装层：正常
❌ 生成层：模型无视证据，产生幻觉

解决方案：优化 prompt，强化"必须依据证据"的约束

这就是为什么需要分阶段评测——不同阶段的问题，解决方案完全不同。

二、问题分层框架

建议用下面这套分层框架，每层有明确的责任边界和常见问题：

┌─────────────────────────────────────────────────────────────────┐
│ 第 1 层：检索层（Retrieval） │
│ │
│ 职责：从知识库中召回候选内容 │
│ │
│ 常见问题： │
│ ❌ 正确 chunk 不在候选里 → chunking、embedding、检索策略 │
│ ❌ 正确 chunk 排名太低 → 混合检索、Rerank │
│ ❌ 候选噪声太多 → metadata 过滤、召回数量调整 │
│ │
│ 评测指标：Recall@K、MRR │
└────────────────────────┬────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 第 2 层：重排层（Rerank） │
│ │
│ 职责：对候选重新排序，提升相关性 │
│ │
│ 常见问题： │
│ ❌ 正确 chunk 被排到后面 → Rerank 模型问题 │
│ ❌ Rerank 效果不明显 → 模型选择、候选数量 │
│ │
│ 评测指标：排序提升比例、NDCG │
└────────────────────────┬────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 第 3 层：上下文组装层（Context Assembly） │
│ │
│ 职责：控制进入 prompt 的内容和数量 │
│ │
│ 常见问题： │
│ ❌ 正确 chunk 被截断 → 调整 token 预算 │
│ ❌ 正确 chunk 被过滤 → 检查过滤规则 │
│ ❌ 内容太长噪声多 → 优化组装策略 │
│ │
│ 评测指标：正确 chunk 进入 prompt 的比例 │
└────────────────────────┬────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 第 4 层：生成层（Generation） │
│ │
│ 职责：基于证据生成答案 │
│ │
│ 常见问题： │
│ ❌ 模型无视证据 → Prompt 优化 │
│ ❌ 产生幻觉 → 强化约束、Few-shot │
│ ❌ 引用错误 → 后处理校验 │
│ │
│ 评测指标：答案正确率、幻觉率、引用准确率 │
└─────────────────────────────────────────────────────────────────┘

分层的意义

每一层的问题，需要不同的解决方案：

问题层	典型问题	解决方向
检索层	召不回正确内容	Chunking、混合检索
重排层	排序不对	Rerank 模型
组装层	内容被过滤	组装策略、预算调整
生成层	模型幻觉	Prompt 优化、模型选择

不分层的问题：你发现答案错了，只能"盲调"——换模型、调参数，但不知道调的是哪个环节。

分层的好处：知道问题在哪一层，定向优化。

三、检索层评测

检索层的核心问题是：正确的 chunk 召回了吗？排得够靠前吗？

Recall@K

最直观的指标：正确答案是否在前 K 个候选里。

Recall@K = 正确答案在前 K 的请求数 / 总请求数

示例：

评测集 100 个问题
每个问题有 1-3 个正确 chunk

Recall@5 = 82/100 = 82%（82 个问题的正确 chunk 在前 5）
Recall@10 = 91/100 = 91%（91 个问题的正确 chunk 在前 10）

解读：

Recall@5 > 80%：检索质量良好
Recall@5 < 60%：检索需要优化
Recall@5 ≈ Recall@10：排序效果好（正确答案排在前面）
Recall@5 « Recall@10：排序效果差（正确答案在后面）

MRR（Mean Reciprocal Rank）

Recall@K 只看"是否在前 K"，MRR 还看"具体排第几"。

MRR = Σ (1 / 正确答案的排名) / 总请求数

示例：

问题 1：正确答案排第 1 → 1/1 = 1.0
问题 2：正确答案排第 3 → 1/3 = 0.33
问题 3：正确答案排第 5 → 1/5 = 0.20
问题 4：正确答案未召回 → 1/∞ = 0

MRR = (1.0 + 0.33 + 0.20 + 0) / 4 = 0.38

解读：

MRR > 0.6：排序质量好
MRR < 0.4：排序需要优化

NDCG（Normalized Discounted Cumulative Gain）

更精细的指标，考虑多个正确答案的情况。

DCG = Σ (2^rel_i - 1) / log2(i + 1)

其中：
- rel_i：第 i 个位置的相关性（1=相关，0=不相关）
- i：排名位置

NDCG = DCG / IDCG

IDCG 是理想情况下的 DCG（所有相关文档都排在最前面）

直觉：正确答案排得越靠前，分数越高；排在后面会被惩罚（除以 log）。

不同指标的选择

指标	适用场景	优点	缺点
Recall@K	只关心是否召回	直观、易解释	不关心具体排名
MRR	关心正确答案的排名	考虑排名	只考虑第一个正确答案
NDCG	有多个正确答案	全面	计算复杂

建议：日常用 Recall@5 + Recall@10，深入分析用 MRR 和 NDCG。

四、生成层评测

检索层评测相对客观，生成层评测更主观——“答案好不好"没有标准答案。

传统指标

1. BLEU / ROUGE

来自机器翻译和摘要领域，计算模型输出和参考答案的 n-gram 重叠度。

BLEU-1: 单词重叠
BLEU-2: 二元组重叠
...
ROUGE-L: 最长公共子序列

问题：RAG 答案不追求和参考答案"字面相似”，而是追求"语义正确"。

参考答案："使用 Bearer Token 认证"
模型答案："认证方式是 Bearer Token"

BLEU 分数不高，但语义完全正确。

2. BERTScore

用 BERT 编码后计算语义相似度。比 n-gram 更好，但对 RAG 仍不够精确。

LLM-as-a-Judge

让大模型来评判答案质量，是目前最实用的方法。

思路：

输入：
- 用户问题
- 参考答案（可选）
- 模型答案
- 证据内容（检索到的 chunk）

输出：
- 分数（1-5）
- 是否正确
- 是否有幻觉
- 具体问题

Prompt 设计：

你是一个答案质量评判专家。请评判以下答案的质量。

问题：{question}

参考资料：
{context}

参考答案：{expected_answer}

模型答案：{actual_answer}

请评判：
1. 正确性（1-5分）
2. 是否包含幻觉（编造参考资料中没有的信息）
3. 是否遗漏关键信息
4. 引用是否正确

以 JSON 格式输出：
{
 "score": 1-5,
 "is_correct": true/false,
 "has_hallucination": true/false,
 "issues": ["问题1", "问题2"],
 "explanation": "评分理由"
}

为什么有效？

LLM 本身有很强的语义理解能力，能判断"语义相似"而非"字面相似"。而且 LLM 能理解上下文，判断答案是否"基于证据"。

注意事项：

评判模型要强：用 GPT-4 或 Claude，不要用小模型
避免自我评判：生成模型和评判模型要不同
Few-shot 示例：给几个评分示例，提高一致性
多次评判取平均：减少随机性

评测指标的层次

生成层评测应该回答几个不同的问题：

问题	指标	怎么测
答案对吗？	正确率	LLM 评判 + 人工抽查
有幻觉吗？	幻觉率	检查答案是否超出证据范围
引用对吗？	引用准确率	检查引用的 chunk 是否支持答案
用户满意吗？	满意度	用户反馈

幻觉检测是最重要的，因为 RAG 的核心价值是"有据可查"。

幻觉检测的方法

方法 1：LLM 评判

Prompt：
"以下答案是否包含参考资料中没有的信息？"

答案：{answer}
参考资料：{context}

请指出答案中的每一句话，并判断是否有证据支持。

方法 2：NLI（自然语言推理）

用 NLI 模型判断答案和证据之间的关系：

前提（证据）："Token 有效期为 24 小时"
假设（答案）："Token 有效期为 48 小时"

NLI 输出：Contradiction（矛盾）

方法 3：关键词匹配

简单但粗糙：检查答案中的关键信息是否在证据中出现。

答案："API 超时时间是 30 秒"
证据："API 的默认超时时间为 30 秒"

匹配：✅（"超时"、"30"、"秒"都在证据中）

五、离线评测 vs 在线评测

离线评测

目的：在上线前验证系统质量

方法：

准备评测集（50-100 条）
定期跑评测
对比不同版本

评测集构建：

评测集应该包含：
- 核心问题（30%）：业务最常见的问题
- 边界问题（30%）：难度高、容易出错的
- 长尾问题（20%）：覆盖更多场景
- 坏案例（20%）：之前出过问题的

每条评测数据：
{
 "id": "eval_001",
 "question": "API 的认证方式是什么",
 "expected_chunks": ["chunk_012"], // 期望召回的 chunk
 "expected_answer": "Bearer Token", // 参考答案
 "category": "技术问题",
 "difficulty": "easy"
}

评测流程：

1. 运行 RAG 系统，获取结果
2. 计算检索指标（Recall@K、MRR）
3. 计算生成指标（正确率、幻觉率）
4. 汇总报告
5. 对比历史版本

在线评测

目的：在生产环境持续监控

方法：

用户反馈：点赞/点踩、修改问题、人工标注
自动评分：用 LLM 对线上答案打分
行为分析：用户是否追问、是否放弃

采样策略：

不是所有请求都需要详细评测（成本高）。建议：

100% 记录基本信息（延迟、召回数量）
10% 详细评分（LLM 评判）
1% 人工审核

评测陷阱

陷阱 1：评测集泄露

训练 Embedding 模型或 Rerank 模型时，不小心用了评测集里的内容。评测分数虚高，线上效果差。

解决：评测集严格隔离，不参与任何训练。

陷阱 2：评测集不代表真实

评测集都是"理想问题"，线上用户的问题五花八门：口语化、错别字、表达不清。

解决：定期从线上采样真实问题，加入评测集。

陷阱 3：只看单一指标

只看 Recall@5，可能忽略了答案质量。检索到了，但答案仍然不好。

解决：多指标综合评估，建立指标大盘。

六、Inspect 系统：定位单次问题

评测解决"系统整体质量"，Inspect 解决"某次请求为什么出错"。

Inspect 系统的核心能力

能力	回答的问题	需要的数据
检索可视化	召回了什么？排第几？	候选列表、分数
重排对比	Rerank 前后有什么变化？	重排前后列表
Prompt 快照	模型看到了什么？	最终 prompt
引用追溯	答案来自哪？	引用的 chunk

Trace 的数据结构

每次请求都应该保存完整的 Trace：

Trace 结构：

{
 "trace_id": "唯一标识",
 "timestamp": "请求时间",
 "query": "用户问题",

 "retrieval": {
 "dense_results": [
 {"chunk_id": "xxx", "score": 0.82, "rank": 1},
 ...
 ],
 "bm25_results": [
 {"chunk_id": "xxx", "score": 5.2, "rank": 1},
 ...
 ],
 "merged_results": [...], // RRF 融合后
 "reranked_results": [...] // Rerank 后
 },

 "context": {
 "final_chunks": [...], // 最终进入 prompt 的
 "prompt": "...", // 完整 prompt
 "token_count": 3200
 },

 "generation": {
 "answer": "模型回答",
 "citations": [...],
 "model": "gpt-4o-mini"
 },

 "latency": {
 "total_ms": 450,
 "retrieval_ms": 50,
 "rerank_ms": 180,
 "generation_ms": 220
 }
}

Inspect 页面的设计

一个实用的 Inspect 页面应该包含：

1. 概览区

问题：错误码 401 是什么意思
答案：401 表示认证失败...
耗时：450ms
状态：❌ 答案错误（模型幻觉）

2. 检索区

Dense 检索结果：
#1 [0.82] 常见 HTTP 错误码
#2 [0.79] 认证失败怎么办
...
#8 [0.65] 错误码详解：401 ← 正确答案

BM25 检索结果：
#1 [5.2] 错误码详解：401 ← 正确答案
#2 [4.8] 常见 HTTP 错误码
...

Rerank 后：
#1 [0.92] 错误码详解：401 ← 正确答案排到第 1
...

3. Prompt 区

最终进入 Prompt 的 chunk：
[1] 错误码详解：401 Unauthorized
 Token 无效或已过期...
[2] 常见 HTTP 错误码
 ...

完整 Prompt：
[显示完整 prompt 内容]

4. 评分区

检索是否正确：✅
答案是否正确：❌
是否有幻觉：✅（模型说"服务器内部错误"）
备注：________________

Trace 的存储

方案	优点	缺点
SQLite	简单、本地	不适合大规模
PostgreSQL	功能强	需要运维
Elasticsearch	搜索方便	成本高
专用平台（LangSmith、Langfuse）	功能全	可能有成本

建议：小规模用 SQLite/PostgreSQL，大规模用专用平台。

七、排障流程

当你发现某个问题回答不对时，按这个流程排查：

第 1 步：获取 Trace ID
从用户反馈或日志中获取

第 2 步：检查检索层
正确 chunk 是否在候选里？

❌ 不在候选：
 → 检查 chunking（是否被切碎）
 → 检查 embedding（是否理解正确）
 → 检索策略（是否需要混合检索）

✅ 在候选但排名靠后：
 → 继续检查重排层

第 3 步：检查重排层
Rerank 后排名是否提升？

❌ 排名下降或不变：
 → Rerank 模型可能不适合这个场景
 → 考虑换模型或调整权重

✅ 排名提升但仍不在 top-5：
 → 召回数量不够
 → 增加召回数量

第 4 步：检查组装层
正确 chunk 是否进入 prompt？

❌ 未进入：
 → 被截断：调整 token 预算
 → 被过滤：检查过滤规则

✅ 已进入：
 → 继续检查生成层

第 5 步：检查生成层
模型是否正确使用证据？

❌ 模型无视证据：
 → 强化 prompt 约束
 → 添加 Few-shot 示例

❌ 模型幻觉：
 → 明确"不确定时说明不确定"
 → 后处理校验

❌ 引用错误：
 → 优化引用格式要求
 → 后处理修正

八、本文小结

RAG 要做到可迭代，必须建立完整的评测和观测体系：

能力	解决的问题	核心方法
分层评测	定位问题在哪一层	Recall@K、LLM-as-Judge
离线评测	验证系统质量	评测集 + 定期跑分
在线评测	监控生产质量	采样 + 自动评分
Inspect	定位单次问题	Trace + 可视化

核心建议：

先建评测集：没有评测集，优化都是盲人摸象
分层评测：检索和生成分开评，知道优化哪一层
保留 Trace：每次请求都记录中间结果
持续监控：建立指标大盘，设置告警

只有这样，才能从"会用 RAG"走到"会调 RAG"。

下一篇会讲生产环境最常见的坑，以及一条可执行的迭代路线。

RAG进阶：Chunking、召回、Hybrid Search 与 Rerank

Wed, 25 Mar 2026 15:45:00 +0800

很多人第一次做 RAG，默认流程都是：

文档切 chunk
生成 embedding
向量检索 top_k
拼 prompt
让模型回答

这条路径能跑，但往往不稳。真正让 RAG 质量提升一个台阶的，通常是三件事：

chunking 做得更合理 — 切出来的 chunk 能独立成为证据
召回从单路 dense 变成多路召回 — 结合语义和关键词
用真正的 rerank 做精排 — 不是简单重排，而是用 cross-encoder 重新打分

这篇文章会深入讲这三个环节的算法原理。

一、Chunking：为什么"切短一点"不简单

Chunking 的目标不是凑 embedding 输入长度，而是让"一个 chunk 刚好能独立成为证据"。

好的 Chunk 应该满足什么

四个标准：

语义完整 — 一个 chunk 能回答一个独立的问题
粒度适中 — 太大噪声多，太小信息不够
上下文自洽 — 不依赖外部信息也能理解
可追溯 — 知道来自哪个文档、哪个章节

固定长度切分的问题

最简单的做法是按字符数切：

每 500 个字符切一段

问题：

问题 1：语义被切断

原文：
"所有 API 请求必须在 Header 中携带 Bearer Token。Token 有效期为 24 小时，
过期后需重新获取。获取方式：调用 /auth/token 接口，传入 client_id
和 client_secret。"

固定切分后，某个 chunk 可能变成：
"过期后需重新获取。获取方式：调用 /auth/token 接口，传入 client_id"

用户问"Token 有效期多久？"，这个 chunk 不会召回。

问题 2：上下文丢失

原文：
"### 2.3 校准流程
将旋钮调至 3 档，等待指示灯变为绿色后松开。"

按段落切分后：
"将旋钮调至 3 档，等待指示灯变为绿色后松开。"

用户问"ZK-200 怎么校准"，这个 chunk 不会召回。
因为"ZK-200"在标题里，"校准"在章节名里——都被切掉了。

语义切分的思路

更好的方法是按文档的自然结构切分：

1. 按 Markdown 标题切分

Markdown 文档有天然的层级结构：

# 一级标题
## 二级标题
### 三级标题

切分策略：每个标题下的内容作为一个 chunk，并保留标题作为上下文。

Chunk 1:
【API 规范 > 2. 认证 > 2.1 认证方式】
所有 API 请求必须在 Header 中携带 Bearer Token...

Chunk 2:
【API 规范 > 2. 认证 > 2.2 Token 获取】
调用 /auth/token 接口获取 Token...

2. 按段落切分

对于没有明确结构的文档，按段落切分比按字符数好：

段落边界通常是语义边界。
一个段落讲一个观点，不会把一句话切两半。

3. 语义切分（高级）

用 Embedding 模型判断相邻段落的语义相似度：

步骤：
1. 把文档按句子切分
2. 计算相邻句子的 embedding 相似度
3. 相似度低的地方 = 语义边界，切分

直觉：如果两句话语义相似度低，说明在讲不同的话题，应该分开。

代价：计算量大，不一定比结构化切分更好。

Contextual Chunking：最重要的一步

无论用什么切分方法，都建议做一步：把父级标题拼到 chunk 前面。

原始 chunk：
"将旋钮调至 3 档，等待指示灯变为绿色后松开。"

补充上下文后：
"【ZK-200 操作手册 > 2. 使用方法 > 2.3 校准流程】
将旋钮调至 3 档，等待指示灯变为绿色后松开。"

为什么有效？

原理：Embedding 模型会把整个 chunk 编码成一个向量。如果 chunk 里包含"ZK-200"和"校准"，当用户问"ZK-200 怎么校准"时，相似度就会高。

实测效果：

配置	Recall@5	说明
原始 chunk	41%	大量 chunk 缺上下文
补充标题上下文	78%	效果翻倍

成本几乎为零，但效果提升明显。这是 RAG 里性价比最高的优化之一。

Chunk 粒度的权衡

太大 vs 太小：

问题	太大（1000+ 字）	太小（<100 字）
噪声	噪声多，关键信息被埋	信息不够，上下文缺失
检索	容易召回不相关内容	可能召回片段，语义不完整
成本	Token 消耗大	Chunk 数量多，索引大

经验值：300-500 tokens（中文约 200-350 字）

但比长度更重要的是语义完整性。宁可长度不均，也不要语义被切断。

不同文档类型的切分策略

文档类型	推荐策略	原因
FAQ	一条一 chunk	每条 FAQ 天然独立
技术文档	按标题/小节	标题是天然语义边界
产品手册	按操作步骤	一个步骤一个 chunk
合同/法规	按条款	每条条款有独立法律意义
对话记录	按问答对	一问一答是完整语义单元

二、BM25：关键词检索的经典算法

向量检索擅长语义相似，但对精确匹配不稳定。解决方案是引入关键词检索。

最经典的关键词检索算法是 BM25（Best Matching 25）。

BM25 的原理

BM25 是 TF-IDF 的改进版。先理解 TF-IDF：

TF-IDF = TF × IDF

TF（Term Frequency）：词在文档中出现的次数
- 出现越多，越重要？不完全是，需要惩罚高频词
IDF（Inverse Document Frequency）：词的稀有程度
- 在所有文档中很少出现 → 区分度高 → 权重高
- 在所有文档中都出现（如"的"、“是”）→ 区分度低 → 权重低

问题：TF 会过度奖励高频词。一个词出现 10 次不代表比出现 1 次重要 10 倍。

BM25 的改进：对 TF 做饱和处理。

BM25 公式

score(D, Q) = Σ IDF(qi) × (f(qi, D) × (k1 + 1)) / (f(qi, D) + k1 × (1 - b + b × |D|/avgdl))

其中：
- D：文档
- Q：查询（包含多个词 q1, q2, ...）
- qi：查询中的第 i 个词
- f(qi, D)：词 qi 在文档 D 中的词频
- |D|：文档 D 的长度
- avgdl：平均文档长度
- k1：词频饱和参数（通常 1.2-2.0）
- b：长度归一化参数（通常 0.75）

IDF(qi) = log((N - n(qi) + 0.5) / (n(qi) + 0.5) + 1)
- N：总文档数
- n(qi)：包含词 qi 的文档数

直觉理解：

词频饱和：(f × (k1+1)) / (f + k1) 是一个饱和函数。当 f 很大时，增长变慢。一个词出现 10 次，权重不是 10 倍，而是趋于 k1+1。
长度归一化：长文档天然有更高的词频，需要惩罚。|D|/avgdl 是相对长度，通过参数 b 控制惩罚程度。
IDF 奖励稀有词：在少数文档中出现的词，IDF 高，权重高。

BM25 的特点

优点	缺点
对精确匹配敏感	不理解语义
对编号、术语稳定	同义词问题（“电脑"和"计算机"是两个词）
计算快，可解释	需要分词（中文需要额外的分词步骤）
不需要训练	不适合自然语言问题

适用场景：

用户查询包含编号、版本号、专业术语
文档中有大量缩写、代码
需要精确匹配的场景

中文分词

BM25 依赖词的边界。英文天然有空格分隔，中文需要额外的分词步骤。

常用分词工具：

工具	特点
jieba	最流行，词典+HMM
pkuseg	北大出品，准确率高
HanLP	功能全，支持多种任务

分词质量直接影响 BM25 效果。比如：

"用户体验设计"

分词 1：用户 / 体验 / 设计（三个词）
分词 2：用户体验 / 设计（两个词）
分词 3：用户 / 体验设计（两个词）

不同的分词，检索结果不同。

三、Hybrid Retrieval：语义 + 关键词

向量检索和 BM25 各有优劣，互补性很强。

为什么需要混合

向量检索：
- 擅长：语义相似、同义词、自然语言问题
- 弱项：精确匹配、编号、专业术语

BM25：
- 擅长：精确匹配、编号、专业术语
- 弱项：语义理解、同义词、自然语言问题

实测对比：

查询类型	向量检索 Recall@5	BM25 Recall@5
语义查询（“怎么获取令牌”）	82%	58%
精确匹配（“错误码 401”）	47%	76%
编号查询（“版本 v2.3.1”）	38%	69%
混合查询（“API v2 认证方式”）	64%	71%

没有哪种方法在所有场景下都最优。混合检索可以兼顾两者。

混合检索的架构

Query
 │
 ├─── 向量检索 ──→ Dense 候选集（top-50）
 │
 ├─── BM25 检索 ──→ Sparse 候选集（top-50）
 │
 └─── Metadata 过滤 ──→ 过滤后的候选集
 │
 ▼
 结果融合
 │
 ▼
 Rerank（可选）
 │
 ▼
 最终结果（top-5）

结果融合：RRF（Reciprocal Rank Fusion）

两路检索结果怎么合并？简单的方法是按分数加权，但问题：向量分数和 BM25 分数不在同一个尺度，不好比较。

更优雅的方法是 RRF（Reciprocal Rank Fusion）：不依赖分数，只依赖排名。

RRF 公式：

RRF_score(d) = Σ 1 / (k + rank_i(d))

其中：
- d：文档
- rank_i(d)：文档 d 在第 i 路检索中的排名
- k：平滑参数（通常取 60）

直觉：

排名第 1 的文档得分：1/(60+1) ≈ 0.0164
排名第 2 的文档得分：1/(60+2) ≈ 0.0159
排名第 10 的文档得分：1/(60+10) ≈ 0.0143

排名越高，得分越高，但差距被平滑。k 越大，不同排名之间的得分差距越小。

为什么有效？

不依赖分数：避免了分数归一化的问题
鲁棒性强：单路检索的异常高分不会主导结果
简单高效：只需要排名信息，计算量小

示例：

Query："错误码 401"

向量检索结果：
1. Doc_A（向量分数 0.82）
2. Doc_B（向量分数 0.79）
3. Doc_C（向量分数 0.76）

BM25 检索结果：
1. Doc_D（BM25 分数 5.2）
2. Doc_C（BM25 分数 4.8）
3. Doc_A（BM25 分数 4.1）

RRF 融合（k=60）：
Doc_A: 1/(60+1) + 1/(60+3) = 0.0164 + 0.0159 = 0.0323
Doc_B: 1/(60+2) + 0 = 0.0159（BM25 没召回）
Doc_C: 1/(60+3) + 1/(60+2) = 0.0159 + 0.0159 = 0.0318
Doc_D: 0 + 1/(60+1) = 0.0164（向量没召回）

最终排序：Doc_A > Doc_C > Doc_B > Doc_D

Doc_A 在两路都有出现，最终得分最高。这就是 RRF 的魅力：两路都召回的文档，更有可能是相关的。

Metadata 过滤

除了向量检索和 BM25，还可以利用元数据做过滤：

用户问："销售合同模板在哪下载？"

先过滤：source = "sales_docs"
再检索：在销售文档范围内检索

好处：
- 缩小检索范围，减少噪声
- 提高检索精度
- 支持权限隔离（不同用户可见不同来源）

过滤可以在检索前（pre-filtering）或检索后（post-filtering）。主流向量库都支持 pre-filtering，效率更高。

四、Rerank：精排的原理

召回阶段的目标是"别漏掉”，所以召回数量较多，难免混入噪声。Rerank 阶段的目标是"降噪"，从候选中选出最相关的。

为什么需要 Rerank

向量检索和 BM25 都是"双塔"结构：

Query → Encoder → Query Vector ─┐
 ├→ Similarity
Document → Encoder → Doc Vector ─┘

Query 和 Document 各自编码，只在最后计算相似度。

问题：Query 和 Document 之间的交互太少。编码时看不到对方，只能依赖各自的信息。

Rerank 的思路：让 Query 和 Document 充分交互，更精确地判断相关性。

Cross-Encoder 的工作原理

Cross-Encoder 是"单塔"结构：

Query + Document → Transformer → Relevance Score

把 Query 和 Document 拼在一起，丢进 Transformer，让模型自己学习两者的交互。

示意：

输入：[CLS] Query [SEP] Document [SEP]

Transformer 会计算每个 token 和其他所有 token 的注意力，
包括 Query token 和 Document token 之间的交互。

输出：[CLS] 位置的向量 → 全连接层 → 相关性分数

为什么比双塔更准？

双塔：Query 编码时看不到 Document，只能用通用的语义表示。单塔：Query 和 Document 一起编码，模型可以看到两者之间的关系。

比如：

Query："苹果的价格"
Document 1："苹果公司股价下跌"
Document 2："水果店苹果 5 元一斤"

双塔可能把两个 Document 都召回（都包含"苹果"和"价格"相关词）
Cross-Encoder 能判断：Document 2 更相关（语义上"价格"指水果价格，不是股价）

为什么不能替代检索？

Cross-Encoder 需要把 Query 和每个 Document 都拼起来过一遍模型。

计算量 = 候选数量 × Transformer 计算量

如果候选是 100 万，计算量巨大，延迟无法接受。

所以只能用在召回之后，对小规模候选做精排。

Rerank 模型

常用 Rerank 模型：

模型	特点	延迟（100 候选）
bge-reranker-large	开源，效果好	~180ms
bge-reranker-base	开源，更快	~95ms
cohere rerank-3	API，效果好	~120ms
ms-marco-MiniLM	开源，轻量	~45ms
jina-reranker-v2	开源，多语言	~80ms

选择考虑：

追求效果：bge-reranker-large 或 cohere rerank-3
追求速度：ms-marco-MiniLM 或 bge-reranker-base
中文场景：bge-reranker-large 或 jina-reranker-v2
私有化部署：bge 系列

Rerank 的效果

实测对比：

配置	Recall@5	正确答案平均排名
向量检索	72%	4.2
混合检索（无 Rerank）	79%	3.5
混合 + Rerank	88%	1.8

Rerank 后，正确答案的平均排名从 3.5 提升到 1.8——明显更靠前，更容易进入最终的 prompt。

五、完整的检索流程

结合以上内容，一个完整的检索流程如下：

┌─────────────────────────────────────────────────────────────────┐
│ 用户 Query │
│ "错误码 401 是什么意思" │
└────────────────────────┬────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 阶段 1：候选召回（Recall） │
│ │
│ 目标：不漏掉，召回足够多的候选 │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 向量检索 │ │ BM25 检索 │ │
│ │ top-50 │ │ top-50 │ │
│ │ │ │ │ │
│ │ 擅长语义相似 │ │ 擅长精确匹配 │ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
│ └─────────┬──────────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ RRF 融合 │ │
│ │ ~80 候选 │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ Metadata │ │
│ │ 过滤 │ │
│ │ ~60 候选 │ │
│ └──────┬──────┘ │
└─────────────────────┼──────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 阶段 2：精排（Rerank） │
│ │
│ 目标：从候选中选出最相关的 │
│ │
│ 输入：~60 个候选 │
│ 处理：Cross-Encoder 重新打分 │
│ 输出：top-10 │
│ │
│ 耗时：~150ms │
└────────────────────────┬────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 阶段 3：上下文组装 │
│ │
│ 目标：控制进入 prompt 的内容 │
│ │
│ 输入：top-10 候选 │
│ 处理： │
│ 1. 控制总长度（如 4000 tokens） │
│ 2. 保持多样性（不同 source 的 chunk） │
│ 3. 去重 │
│ 输出：5-8 个 chunk │
└────────────────────────┬────────────────────────────────────────┘
 ▼
 构建 Prompt
 调用 LLM
 答案

各阶段的参数建议

阶段	参数	推荐值	说明
向量召回	top_k	50-100	宁多勿少
BM25 召回	top_k	50-100	宁多勿少
RRF	k	60	经验值，一般不用调
Rerank	输入	20-30	不用太大，计算慢
Rerank	输出	10-15	给 prompt 组装留空间
Prompt 组装	最终数量	3-8	不宜过多
Prompt 组装	token 预算	3000-4000	根据模型调整

各阶段的延迟占比

总延迟：~300-500ms

向量检索：30-50ms（10%）
BM25 检索：10-20ms（5%）
RRF 融合：<5ms（<1%）
Rerank：150-200ms（50%）← 主要瓶颈
Prompt 组装：<10ms（<5%）
LLM 调用：100-200ms（35%）← 另一个瓶颈

优化方向：

减少 Rerank 候选数：从 30 减到 20，节省 ~50ms
用更快的 Rerank 模型：bge-reranker-base 比 large 快 ~80ms
缓存热门 query：相同问题直接返回，跳过整个流程

六、Query Rewrite：高级优化

检索质量不仅取决于检索算法，还取决于 Query 本身。

用户的问题往往不够清晰，需要"改写"才能更好地检索。

常见的改写策略

1. 同义词扩展

原始："怎么获取令牌"
改写："怎么获取令牌 OR token OR access_token"

2. 拼写纠正

原始："错误码 4O1"（字母 O）
改写："错误码 401"（数字 0）

3. 核心词提取

原始："我想了解一下关于 API 超时时间的配置方法"
改写："API 超时时间 配置"

去掉无意义的词，保留核心检索词。

4. Query 分解

原始："对比 v2.0 和 v2.1 版本的 API 差异"
分解：
- Query 1："v2.0 版本 API 特性"
- Query 2："v2.1 版本 API 特性"
- Query 3："v2.0 v2.1 版本差异"

复杂问题拆成多个简单问题，分别检索，再合并。

5. 假设文档生成（HyDE）

原始："API 的认证方式是什么"
生成假设文档：
"API 的认证方式使用 Bearer Token。所有请求需要在 Header 中携带
Authorization: Bearer <token>。Token 有效期 24 小时..."

用假设文档去检索，而不是原始 query。

直觉：假设文档和真实文档的相似度，可能比 query 和文档的相似度更高。

Query Rewrite 的权衡

优点	缺点
提高检索质量	增加 LLM 调用成本
处理复杂问题	增加延迟
适应用户表达习惯	可能改写错误

建议：

简单问题不需要改写
复杂问题、长尾问题适合改写
可以用规则+LLM结合，降低成本

七、一个推荐的升级路线

如果你现在还是单路向量检索，建议按这个顺序升级：

第一步：优化 Chunking（成本低，效果好）

从固定长度改为按段落/标题切分
给每个 chunk 补充父级标题上下文

预期效果：Recall@5 从 60% 提升到 75%

第二步：引入 BM25（成本中）

部署 BM25 检索
实现 RRF 融合

预期效果：Recall@5 从 75% 提升到 82%

第三步：接入 Rerank（成本中）

部署 Cross-Encoder 模型
调整召回数量和精排数量

预期效果：Recall@5 从 82% 提升到 88%

第四步：高级优化（成本高）

Query Rewrite
Query Decomposition
HyDE

预期效果：Recall@5 从 88% 提升到 92%+

收益递减规律

从 60% 到 80%：相对容易，基础优化即可从 80% 到 90%：需要系统优化，混合检索+Rerank 从 90% 到 95%：难度大增，需要高级策略和大量调试

建议：先做到 85%，再考虑是否值得继续投入。

八、本文小结

RAG 做得好不好，很多时候不是模型不够强，而是：

Chunk 没切好 — 语义不完整、缺上下文
候选召回太单一 — 只用向量，对精确匹配不稳定
Rerank 没真正落地 — 用"假 rerank"或根本没 rerank

核心要点：

Chunking：按语义结构切分 + 补充上下文
混合检索：向量（语义）+ BM25（精确）+ RRF 融合
Rerank：Cross-Encoder 做真正的精排
Query Rewrite：处理复杂和长尾问题

下一篇会讲：如何做 RAG 的评测和 Inspect，才能知道问题到底出在哪一层。

RAG入门：从问题定义到系统设计

Wed, 25 Mar 2026 15:40:00 +0800

RAG，全称 Retrieval-Augmented Generation，核心思想其实很朴素：不要把所有知识都塞进模型参数里，而是在回答问题前，先从外部知识库里把最相关的信息找出来，再交给模型生成答案。

这套方法之所以重要，是因为纯大模型回答经常会遇到三类问题：

知识过期 — GPT-4 的训练数据截止到 2023 年底，你问它 2024 年 3 月的新闻，它要么说不知道，要么编一个。
专有知识缺失 — 你们公司的内部文档、API 规范、业务规则，模型从来没见过。
幻觉问题 — 模型会"自信地胡说八道"，尤其是当它不确定的时候。

RAG 的目标不是让模型"更聪明"，而是让系统"更可控"。你把知识更新、答案依据、召回范围、调试手段都从模型参数里解耦了出来。

一、RAG 解决的本质问题

先想清楚一个问题：为什么不让模型直接回答，而要先检索？

答案是：模型的参数空间是有限的，但知识是无限的。

GPT-4 有 1.8 万亿参数，看起来很多，但这些参数要编码：语言规律、世界知识、推理能力、常识……真正留给"事实知识"的空间并不多。而且参数一旦训练完成，就固定了。你想让它知道你们公司最新的报销流程？只能重新训练，成本几十万起步。

RAG 的思路是：把"事实知识"从参数里剥离出来，放到外部存储里。

传统模型：
知识 → 训练 → 参数 → 推理 → 答案
（知识固化在参数里，更新成本高）

RAG：
知识 → 索引 → 向量库 → 检索 → 推理 → 答案
（知识和模型解耦，更新成本低）

代价是：每次回答前，需要先检索。检索的质量直接决定了答案的质量。

二、Embedding：把文本变成向量

RAG 的第一步是让机器"理解"文本。方法是 Embedding——把文本映射到一个高维向量空间。

Embedding 的直觉

假设我们有一个 3 维空间，每个词可以表示为一个点：

"猫" → (0.2, 0.8, 0.1)
"狗" → (0.3, 0.7, 0.2) ← 和"猫"很近，都是宠物
"汽车" → (0.9, 0.1, 0.3) ← 和"猫"很远，不同类别

在这个空间里，语义相似的词距离近，语义不同的词距离远。

实际的 Embedding 维度是几百到几千维，但原理一样：让语义相似的文本在向量空间里距离近。

训练 Embedding 模型

Embedding 模型是怎么训练出来的？核心思想是：让相似文本的向量靠近，不相似文本的向量远离。

常用的训练方式有两种：

1. 对比学习（Contrastive Learning）

准备大量"相似对"和"不相似对"：

相似对：
("如何重置密码", "密码重置方法")
("API 超时设置", "配置 API 超时时间")

不相似对：
("如何重置密码", "API 超时设置")
("密码重置方法", "今天天气怎么样")

训练目标：让相似对的向量距离小，不相似对的向量距离大。

损失函数（InfoNCE Loss）：

L = -log( exp(sim(q, p+)/τ) / Σexp(sim(q, pi)/τ) )

其中：
- q 是 query 的向量
- p+ 是正样本的向量
- pi 是所有样本（包括正样本和负样本）
- sim 是相似度函数（如余弦相似度）
- τ 是温度参数

直觉解释：让正样本的相似度占主导，负样本的相似度被压制。

2. 自监督学习

不用人工标注，利用文本本身的结构：

同一个句子/段落的不同部分互为正样本
不同句子/段落互为负样本

代表性方法：SimCSE，把同一个句子丢进模型两次（不同的 dropout mask），得到的两个向量应该相似。

主流 Embedding 模型

模型	维度	特点	适用场景
text-embedding-3-small	1536	OpenAI，多语言	通用场景
text-embedding-3-large	3072	OpenAI，更高精度	高质量要求
bge-large-zh	1024	开源，中文优化	中文场景
bge-m3	1024	开源，多语言	多语言混合
e5-large-v2	1024	开源，需要加前缀	英文场景

选择原则：

中文为主：选 bge-large-zh
多语言混合：选 text-embedding-3-small 或 bge-m3
追求高质量且有预算：选 text-embedding-3-large
私有化部署：选 bge 系列

三、向量检索：在高维空间找邻居

有了向量，接下来是检索：给定一个 query 向量，找到最相似的文档向量。

相似度计算

最常用的是余弦相似度：

cosine(a, b) = (a · b) / (||a|| × ||b||)

其中：
- a · b 是向量点积
- ||a|| 是向量的模长

结果范围：[-1, 1]，越大越相似

为什么用余弦相似度而不是欧氏距离？

因为 Embedding 的方向比长度更重要。两个文本的语义相似，体现在向量方向相近，而不是长度相近。余弦相似度只看方向，不看长度。

暴力检索的问题

最简单的检索方式是暴力计算：把 query 和所有文档向量都算一遍相似度，排序取 top-k。

问题：慢。

假设向量维度 1024，文档数量 100 万：

单次检索计算量：
100万 × 1024 = 10亿次浮点运算

耗时估算：
单核 CPU ≈ 100-500ms
GPU ≈ 10-50ms

100 万文档还算小，到了 1000 万、1 亿，暴力检索就撑不住了。

近似最近邻搜索（ANN）

解决方案：用精度换速度。不要求找到"最近的"，只要找到"足够近的"。

主流算法：

1. HNSW（Hierarchical Navigable Small World）

思路：构建一个多层的图结构，每层是一个小世界网络。

第 0 层：所有节点
第 1 层：部分节点（概率选取）
第 2 层：更少的节点
...

搜索时：
从最高层开始，快速跳到目标区域附近
逐层下降，越来越精确
最后在第 0 层找到最近邻

类比：找北京的某个人。先在世界地图上定位到中国，再在中国地图上定位到北京，再在北京地图上定位到朝阳区……每一步都在缩小范围。

2. IVF（Inverted File Index）

思路：把向量空间划分为多个区域（聚类中心），每个区域维护一个倒排表。

离线阶段：
1. 用 K-means 聚类，找到 K 个中心点
2. 把每个向量分配到最近的中心点
3. 每个中心点维护一个列表（倒排表）

在线检索：
1. 找到离 query 最近的几个中心点
2. 只在这几个中心点的倒排表里搜索
3. 不用遍历所有向量

参数选择：nprobe（探测几个中心点）。nprobe 越大，精度越高，速度越慢。

3. PQ（Product Quantization）

思路：压缩向量，减少内存占用和计算量。

原始向量：1024 维浮点数 = 4096 字节

压缩方法：
1. 把 1024 维分成 8 组，每组 128 维
2. 每组用 K-means 聚类，生成 256 个中心点
3. 每个向量每组只需 1 字节（存储中心点编号）

压缩后：8 字节
压缩比：512 倍

代价：精度损失。但换来的是内存占用大幅降低，可以索引更多文档。

向量库的选择

向量库	算法	特点	适用场景
Chroma	HNSW	轻量，易上手	开发/小规模
Qdrant	HNSW	开源，功能全	中等规模生产
Milvus	多种	分布式，高性能	大规模生产
Pinecone	专有	全托管，免运维	不想运维
Weaviate	HNSW	原生支持多模态	多模态场景

四、为什么单靠向量检索不够

向量检索很强大，但有天生的局限。

局限 1：对精确匹配不敏感

例子：

文档："错误码 401 表示认证失败"
用户问："401 是什么意思"

向量检索可能召回：
"常见错误码及解决方案"（语义相似）
"权限问题排查"（语义相似）

而不是精确包含 "401" 的那段。

原因：Embedding 模型学习的是语义相似性，不是字面匹配。“401” 这个数字在向量空间里没有特殊意义，它只是一个 token。

局限 2：对专业术语不稳定

例子：

文档："JSON Web Token 的有效期默认为 1 小时"
用户问："JWT 的有效期"

向量检索：可能召回，也可能不召回，取决于模型是否学过 JWT = JSON Web Token

如果模型训练数据里没见过这个缩写，就找不到关联。

局限 3：对编号/版本号不稳定

例子：

文档："v2.3.1 版本新增了批量导出功能"
用户问："v2.3.0 有什么新功能"

向量检索：可能召回 v2.3.1 或 v2.3.2 的内容，因为"版本更新"语义相似

版本号之间的微小差异，在向量空间里可能被"版本"这个大概念淹没。

解决方案：混合检索

这就是为什么生产环境几乎都用 Hybrid Retrieval：

候选集 = 向量检索（语义） + 关键词检索（字面） + 元数据过滤（业务规则）

下一篇文章会详细讲混合检索和 Rerank 的算法。

五、RAG 的三阶段架构

理解了 Embedding 和检索，我们来看 RAG 的整体架构。一个成熟的 RAG 系统分为三个阶段：

┌─────────────────────────────────────────────────────────────────┐
│ 阶段 1：索引（Indexing） │
│ │
│ 文档 → 解析 → 切分 → Embedding → 写入向量库 │
│ │
│ 核心问题：怎么切分才能让每个 chunk 成为独立的证据？ │
└────────────────────────┬────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 阶段 2：检索（Retrieval） │
│ │
│ Query → Embedding → 向量检索 → 关键词检索 → 融合 → Rerank │
│ │
│ 核心问题：怎么召回相关内容，同时减少噪声？ │
└────────────────────────┬────────────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 阶段 3：生成（Generation） │
│ │
│ Query + Chunks → Prompt 组装 → LLM → 答案 + 引用 │
│ │
│ 核心问题：怎么让模型严格依据证据回答，不自由发挥？ │
└─────────────────────────────────────────────────────────────────┘

每个阶段都有特定的优化空间，而且问题往往出现在你忽视的地方。

索引阶段的关键决策

1. 切分粒度

太大：噪声多，模型注意力分散太小：信息碎片化，上下文丢失

经验值：300-500 tokens（中文约 200-350 字）

但比长度更重要的是语义完整性。一个 chunk 应该能独立成为一个"证据"。

2. 上下文补充

一个常见的坑：

原始文档：
### 2.3 校准流程
将旋钮调至 3 档，等待指示灯变为绿色。

按段落切分后，chunk 变成：
"将旋钮调至 3 档，等待指示灯变为绿色。"

问题：用户问"ZK-200 怎么校准"，这个 chunk 不会召回，因为：
- 没有"ZK-200"（在文档标题里）
- 没有"校准"（在章节标题里）

解决方案：把父级标题拼到 chunk 前面。

补充上下文后：
"【ZK-200 操作手册 > 2.3 校准流程】
将旋钮调至 3 档，等待指示灯变为绿色。"

这个技巧叫 Contextual Chunking，成本低，效果好。

3. 元数据设计

每个 chunk 至少要存储：

{
 "id": "唯一标识",
 "content": "文本内容",
 "document_id": "所属文档",
 "source": "知识库来源",
 "title": "文档标题",
 "section": "章节路径",
 "chunk_index": "在文档中的位置",
 "created_at": "创建时间"
}

这些元数据在检索时可以做过滤（只搜特定来源）、在回答时可以做引用（答案来自哪个文档）。

检索阶段的关键决策

1. 召回数量

召回太少：容易漏掉正确答案召回太多：噪声多，成本高

经验值：

召回阶段：50-100 个候选
Rerank 后：保留 10-20 个
最终进 prompt：3-8 个

2. 检索策略

简单场景：纯向量检索够用复杂场景：向量 + BM25 混合高精度场景：混合 + Rerank

3. 过滤策略

利用元数据缩小检索范围：

用户问："销售合同模板在哪下载？"

不过滤：
搜索范围 = 所有文档（产品、研发、销售、HR...）
结果可能混入研发部门的合同管理规范

按 department="sales" 过滤：
搜索范围 = 销售部门文档
结果更精准

生成阶段的关键决策

1. Prompt 设计

核心原则：让模型"不得不"依据证据回答。

差的 Prompt：

参考资料：{chunks}
问题：{query}
请回答：

模型可能无视参考资料，自由发挥。

好的 Prompt：

你是一个文档助手。请根据以下参考资料回答问题。

要求：
1. 答案必须基于参考资料，不要编造
2. 如果参考资料中没有答案，请直接说"根据现有资料无法回答"
3. 回答时标注引用来源，格式：[来源: 文档名 > 章节]

参考资料：
{chunks}

问题：{query}

请回答：

2. 上下文预算

模型有上下文长度限制，不能无限塞内容。更重要的是：内容越多，模型注意力越分散。

经验值：检索内容不超过 4000 tokens（约 3000 字中文）

分配建议：

关键证据：2000-3000 tokens
Prompt 模板：200-300 tokens
用户问题和输出：预留 1000+ tokens

3. 引用机制

让模型标注答案的来源：

答案："API 的超时时间默认为 30 秒 [来源: API 规范 > 3.2 超时配置]"

好处：

用户可以验证答案
系统可以追溯错误
增加答案的可信度

六、RAG vs 微调：怎么选

很多人问：应该用 RAG 还是微调？

答案：不冲突，解决的问题不同。

问题类型	解决方案	原因
知识过时	RAG	更新知识库即可
专有知识缺失	RAG	模型没见过这些知识
输出格式不稳定	微调	让模型学会特定格式
输出风格不对	微调	让模型掌握特定风格
工具使用不规范	微调	让模型学会调用模式

RAG 擅长：解决"知道什么" 微调擅长：解决"怎么做"

实际项目中，往往是两者结合：

微调：
- 让模型学会输出 JSON 格式
- 让模型学会引用来源
- 让模型学会说"不知道"

RAG：
- 提供最新的业务知识
- 提供可追溯的证据
- 提供领域专业信息

七、第一版 RAG 应该怎么搭

如果你从零开始，我的建议是：

不要一上来就追求复杂架构。第一版的目标是"可解释"，不是"最优"。

第一版容易犯的错误

错误 1：上来就全量导入

把公司所有文档都丢进去，结果检索噪声巨大，答案质量很差。

正确做法：先导入核心文档（100-200 篇），验证效果，再逐步扩展。

错误 2：忽视元数据

只存内容和向量，其他什么都不留。后面想做过滤、引用、增量更新，发现数据不够。

正确做法：一开始就设计好元数据结构，chunk 要保留来源、章节、时间等信息。

错误 3：不做评测

优化全靠"感觉"，没有客观标准。

正确做法：准备 20-50 个测试问题，固定评测，每次改动都要看指标变化。

错误 4：没有 Inspect 能力

答案错了，不知道是检索错还是生成错。

正确做法：保留每次请求的中间结果（候选列表、分数、prompt），方便排查。

八、如何判断系统准备好了

在上线前，问自己这些问题：

□ 能回答核心问题吗？
 └── 准备 20 个关键问题，正确率 > 70%

□ 能解释答案来源吗？
 └── 每个答案都有引用，用户能追溯

□ 答案错了能定位吗？
 └── 有 Inspect 页面，能看到检索结果

□ 知道下一步优化什么吗？
 └── 有评测指标，知道哪类问题表现差

□ 文档更新后能同步吗？
 └── 有增量更新机制，不是全量重建

如果这些问题都回答不了，说明系统还不成熟，需要继续打磨。

九、下一篇文章讲什么

这篇文章讲了 RAG 的基础：

Embedding 的原理和选择
向量检索的算法和局限
三阶段架构的关键决策

下一篇会深入讲：

Chunking 的策略：怎么切才能保留语义完整性
混合检索：BM25 算法原理、RRF 融合公式
Rerank：Cross-Encoder 的工作原理、为什么比向量检索更准

这些是 RAG 质量提升的关键，也是最容易踩坑的地方。

vector-database

Thu, 20 Nov 2025 16:41:12 +0800

向量数据库的教程

松果

AI 的“海马体”选型指南：2026 年主流向量数据库全景对比

摘要：在构建 RAG（检索增强生成）和 AI Agent 系统时，向量数据库（Vector Database）充当着“长期记忆”的关键角色。面对市场上琳琅满目的选项——Milvus、Qdrant、Weaviate、pgvector……架构师该如何抉择？本文将从架构轻重、运维成本和适用场景三个维度，为您深度解析主流向量数据库的优劣势。

在构建 RAG（检索增强生成）和 AI Agent 系统时，向量数据库（Vector Database）充当着“长期记忆”的关键角色。通过将文本、图片等非结构化数据转化为高维向量（Embeddings），向量数据库允许我们进行语义搜索。当用户问“还是老规矩”时，系统能从数据库中检索出该用户过去的行为偏好，而不是仅仅匹配关键词。但在 2026 年的今天，选型变得异常困难：是追求极致性能？还是追求开发效率？

我们来聊聊主流的向量数据库，它们各有特色，也有不同的适用场景。以下是第一梯队的原生向量数据库：

Milvus 是全球最流行的开源向量数据库之一，由 Zilliz 主导。

核心定位：企业级、云原生、追求极致扩展性。
✅ 核心优势：
十亿级吞吐：分布式架构极其成熟，轻松支撑 Billion-scale（十亿级）向量存储。
生态完善：国内社区最活跃，文档支持最好，索引类型（HNSW, IVF 等）丰富。
❌ 潜在短板：
架构极重：标准版部署依赖 Etcd（元数据）、MinIO（存储）和 Pulsar/Kafka（消息流）。在 docker-compose 中启动它需要拉起 4-5 个容器，运维成本高。
资源门槛：起步资源要求较高，不适合 MVP（最小可行性产品）阶段的小微项目。
适用场景：大型互联网应用、核心推荐系统、海量知识库。

Qdrant 是用 Rust 编写的新一代向量数据库，也是许多 Agent 框架的首选。

核心定位：兼顾高性能与易用性，开发者友好。
✅ 核心优势：
架构轻量：Rust 编写，内存安全且高效。部署只需一个 Docker 容器，无外部依赖。
元数据过滤：它的 Payload Filtering 机制非常强大，支持像 MongoDB 一样灵活地过滤 JSON 字段（例如：“查找昨天情绪为‘开心’的对话记忆”）。
本地模式：支持 Python 本地内存模式，开发阶段甚至无需启动服务。
❌ 潜在短板：
超大规模验证：虽然支持分布式，但在百亿级规模的公开案例略少于 Milvus。
适用场景：AI Agent 记忆系统、中大型 RAG 应用、快速迭代的初创项目。

Weaviate 是一款 AI 原生的向量数据库，具有模块化特性。

核心定位：模块化、对象存储风格。
✅ 核心优势：
内置模块：可直接集成 OpenAI/HuggingFace 模型，自动处理 Embedding，无需应用层操心。
混合搜索：原生支持 BM25（关键词）+ 向量的混合检索，搜索效果通常优于纯向量。
❌ 潜在短板：
学习曲线：使用 GraphQL 接口查询，Schema 定义方式独特，需要一定的上手时间。
适用场景：Notebook 演示、Hackathon、个人知识库。

Chroma 是一款面向 Python 全栈开发者的向量数据库，设计极简。

核心定位：面向 Python 全栈开发者，极简。
✅ 核心优势：
上手最快：pip install chromadb 即可，API 设计极其简单。
❌ 潜在短板：
性能瓶颈：在大规模并发和分布式能力上弱于上述三位“老大哥”。
适用场景：Notebook 演示、Hackathon、个人知识库。

如果你的技术栈已经很成熟，不想引入新的组件，传统数据库的扩展方案可能是更好的选择。

PostgreSQL (pgvector) 是全球最强开源关系型数据库的插件。

定位：全球最强开源关系型数据库的插件。
优点：单一数据源。无需在 SQL 数据库和向量库之间同步数据，完美支持 ACID 事务。如果你的数据量在百万级以内，直接开插件是最省事的选择。
缺点：在高并发 QPS 或超高维向量场景下，索引构建速度和查询延迟不如原生向量库。

Elasticsearch (ES) / OpenSearch 是全文检索的王者。

定位：全文检索的王者。
优点：如果你需要极强的关键词搜索（BM25）能力，向量检索只是辅助，ES 是不二之选。
缺点：Java 编写，资源消耗大（内存吞噬者），纯向量检索性能并非顶尖。

Redis (RediSearch) 是一款基于内存的数据库。

定位：基于内存的极致速度。
优点：亚毫秒级延迟，适合高频读写的短期记忆缓存。
缺点：内存昂贵，存储海量历史数据成本太高。

为了方便大家决策，我整理了这份决策矩阵：

你的需求场景	推荐选型	核心理由
MVP 原型 / 个人开发	Chroma / Qdrant (Local)	代码量最少，环境搭建最快。
中型生产环境 / 追求性价比	Qdrant	Rust 高效、Docker 单容器部署、Filter 语法极佳。 (这也是我们 V1.2 架构的首选)
超大规模 / 十亿级数据	Milvus	经过大规模验证的分布式能力，Zilliz 企业级支持。
已有 Postgres 且数据量不大	pgvector	架构最简单，不用维护新数据库。
强依赖关键词搜索	Elasticsearch	混合检索生态最强。

没有“最好”的数据库，只有“最适合”的架构。

在我们的**“变色龙”进化型对话系统项目中，我们最终选择了 Qdrant。原因很简单：在快速迭代阶段，我们需要一个部署足够轻量**（不拖累 Docker Compose）、查询足够灵活（处理复杂的记忆元数据）且性能足够强的组件。Qdrant 完美击中了这三个甜点。

tutorial

Milvus

Milvus 专为大规模向量数据的存储、索引和搜索而设计，常用于构建 RAG（检索增强生成）、图像检索、推荐系统等应用。

以下教程将涵盖：环境部署、核心概念、以及完整的 Python 代码实战。

1. 什么是 Milvus？

Milvus 是一款云原生的向量数据库。它的核心作用是存储“向量”（Embeddings，即由 AI 模型生成的浮点数数组），并利用算法快速找出与查询向量“最相似”的数据。

非结构化数据处理： 它可以让图片、视频、文本等非结构化数据通过向量化后进行语义搜索。
高性能： 支持十亿级向量规模的毫秒级搜索。

2. 环境部署 (基于 Docker)

使用 Docker 是运行 Milvus 最简单、最标准的方式。

第一步：下载 Docker Compose 文件

在你的终端中执行以下命令，下载官方的单机版配置文件：

curl -L https://github.com/milvus-io/milvus/releases/download/v2.4.0/milvus-standalone-docker-compose.yml -o docker-compose.yml

第二步：启动 Milvus

docker-compose up -d

启动后，Milvus 会暴露以下端口：

19530: gRPC 端口（主要用于代码连接）。
9091: 管理端口。

推荐工具： 建议安装 Attu (Milvus 的官方可视化管理界面)，可以通过 Docker 一并安装，方便查看数据。

docker run -p 8000:3000 -e MILVUS_URL=localhost:19530 zilliz/attu:v2.6

桌面端安装

如果你是使用docker 容器安装在mac或者windows的docker desktop里面，你可以使用host.docker.internal:19530连接

3. Python 代码实战

我们将使用 Python SDK (pymilvus) 来完成从连接、建表、插入数据到相似度搜索的全过程。

0. 安装 SDK

uv add pymilvus

1. 完整代码示例

这个脚本模拟了一个场景：我们有 10,000 条文本数据（已转化为向量），我们要找出与某条查询最相似的 3 条数据。

import random
import time
import numpy as np
from pymilvus import (
 connections,
 utility,
 FieldSchema,
 CollectionSchema,
 DataType,
 Collection,
)

# ==========================================
# 1. 连接 Milvus
# ==========================================
print(">>> 正在连接 Milvus...")
connections.connect("default", host="host.docker.internal", port="19530")
print(">>> 连接成功！")

# ==========================================
# 2. 定义集合 (Schema)
# ==========================================
# 类似于关系型数据库中的“表”
collection_name = "tutorial_demo"
dim = 128 # 向量维度 (根据你的 Embedding 模型决定，如 OpenAI text-embedding-3 是 1536)

# 如果集合已存在，先删除（为了演示方便）
if utility.has_collection(collection_name):
 utility.drop_collection(collection_name)

# 定义字段
fields = [
 # 主键 ID (自动增长)
 FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
 # 向量字段 (FLOAT_VECTOR)，必须指定维度
 FieldSchema(name="embeddings", dtype=DataType.FLOAT_VECTOR, dim=dim),
 # 元数据字段 (例如文章标题、日期等)
 FieldSchema(name="title", dtype=DataType.VARCHAR, max_length=200),
 FieldSchema(name="count", dtype=DataType.INT64),
]

schema = CollectionSchema(fields, description="Milvus 基础教程演示")
collection = Collection(name=collection_name, schema=schema)

print(f">>> 集合 '{collection_name}' 创建成功")

# ==========================================
# 3. 插入数据 (Insert)
# ==========================================
num_entities = 3000 # 插入 3000 条数据

# 生成随机向量数据模拟 Embeddings
rng = np.random.default_rng(seed=19530)
vectors = rng.random((num_entities, dim), dtype=np.float32) # 生成随机浮点数

# 生成一些元数据
titles = [f"Article_{i}" for i in range(num_entities)]
counts = [i for i in range(num_entities)]

# 组织数据 (列表的顺序必须与 Schema 定义的顺序一致，排除 auto_id 的主键)
# 注意：Milvus 插入数据是列式存储格式 [Column1_List, Column2_List, ...]
data = [
 vectors, # 对应 embeddings
 titles, # 对应 title
 counts, # 对应 count
]

insert_result = collection.insert(data)
# 即使插入了，数据还在内存缓冲区，需要 flush 到磁盘才能确保立即可见（生产环境通常不需要手动频繁 flush）
collection.flush()

print(f">>> 已插入 {insert_result.insert_count} 条数据")

# ==========================================
# 4. 创建索引 (Indexing)
# ==========================================
# 向量搜索如果是暴力搜索 (Flat) 会很慢，必须建立索引。
# IVF_FLAT 是一种基于倒排文件的常见索引。
index_params = {
 "metric_type": "L2", # 距离度量：L2 (欧氏距离) 或 IP (内积/余弦相似度)
 "index_type": "IVF_FLAT", # 索引类型
 "params": {"nlist": 128}, # nlist 是聚类中心的数量
}

print(">>> 正在构建索引...")
collection.create_index(field_name="embeddings", index_params=index_params)
print(">>> 索引构建完成")

# ==========================================
# 5. 加载集合 (Load)
# ==========================================
# *关键步骤*：Milvus 必须将集合加载到内存中才能进行搜索
collection.load()

# ==========================================
# 6. 向量搜索 (Search)
# ==========================================
# 模拟一个查询向量
search_vectors = rng.random((1, dim), dtype=np.float32)

# 搜索参数
search_params = {
 "metric_type": "L2",
 "params": {"nprobe": 10}, # nprobe: 在多少个聚类中心里搜索，值越大越准但越慢
}

print(">>> 开始搜索...")
start_time = time.time()

results = collection.search(
 data=search_vectors, # 查询向量
 anns_field="embeddings", # 在哪个字段搜索
 param=search_params, # 搜索参数
 limit=3, # Top K：返回最相似的 3 个
 output_fields=["title", "count"] # 同时返回这些元数据字段
)

end_time = time.time()

# ==========================================
# 7. 解析结果
# ==========================================
print(f">>> 搜索耗时: {end_time - start_time:.4f} 秒")
print("-" * 20)
for hits in results:
 for hit in hits:
 # hit.id 是主键, hit.distance 是距离, hit.entity.get() 获取元数据
 print(f"ID: {hit.id}, Distance: {hit.distance:.4f}, Title: {hit.entity.get('title')}")

# ==========================================
# 8. 清理 (可选)
# ==========================================
# collection.drop()
# connections.disconnect("default")

4. 关键概念详解

为了用好 Milvus，你需要理解以下几个核心参数：

A. Metric Type (距离度量)

这是衡量两个向量“相似度”的标准，必须在建立索引和搜索时保持一致。

L2 (欧氏距离): 也就是几何距离。值越小表示越相似。适用于大多数场景。
IP (内积): 如果向量已归一化，它等同于余弦相似度。值越大表示越相似。适用于文本语义搜索。

B. Index Type (索引类型)

FLAT: 暴力搜索，准确率 100%，但速度最慢。仅适用于少量数据 (<1万)。
IVF_FLAT / IVF_SQ8: 基于倒排聚类。速度快，但在召回率上有一点点损失。最常用。
HNSW: 基于图的索引。性能极高，是目前最流行的索引算法，但内存占用比 IVF 大。

C. Consistency Level (一致性级别)

Milvus 是分布式的，搜索时可以指定一致性：

Strong: 保证刚插入的数据立马能搜到（性能最慢）。
Bounded: 允许几秒钟的延迟（性能最好，默认推荐）。

5. 进阶：结合 RAG 的应用流程

如果你在做 AI 应用，Milvus 的工作流通常是这样的：

Embedding: 用户输入问题 -> 调用 OpenAI/HuggingFace API -> 获得向量 [0.1, 0.5, ...].
Search: 将这个向量传给 Milvus (collection.search)。
Context: Milvus 返回 Top 3 相似的文本片段 (通过 output_fields 返回文本内容)。
Generation: 将 “用户问题 + Milvus 返回的文本片段” 拼成 Prompt，发给 ChatGPT。
Answer: ChatGPT 根据参考资料回答问题。

6. 常见问题 (FAQ)

为什么搜索报错 Collection not loaded？
- Milvus 为了性能，搜索前必须显式调用 collection.load() 将数据加载到内存。
向量维度不匹配？
- 创建集合时的 dim 必须与你的 Embedding 模型输出维度完全一致（例如 BERT 是 768，OpenAI text-embedding-3-small 是 1536）。
如何删除数据？
- 使用 collection.delete("id in [1, 2]")。注意，删除操作是软删除，物理空间不会立即释放。

以下是一个非常实用的企业级开发场景。阿里云百炼 (DashScope) 提供了强大的通义千问 (Qwen) 大模型和文本向量化服务，结合 Milvus 的存储检索能力，可以快速搭建一个私有知识库问答系统。

以下是完整的 Python 代码示例，涵盖了从“文本向量化”到“存入 Milvus”，再到“检索并生成回答”的全流程。

前置准备

获取 API Key：你需要去阿里云百炼控制台开通服务并获取 API Key。
安装依赖库：你需要安装阿里云的官方 SDK dashscope 和 Milvus SDK pymilvus。

pip install dashscope pymilvus

完整代码示例

新建一个 Python 文件（例如 rag_bailian_milvus.py），填入你的 API Key 即可运行。

import dashscope
from dashscope import Generation
from pymilvus import (
 connections,
 utility,
 FieldSchema,
 CollectionSchema,
 DataType,
 Collection,
)
from http import HTTPStatus

# ==========================================
# 0. 配置部分
# ==========================================

# 【重要】请替换为你的阿里云百炼 API Key
dashscope.api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Milvus 配置
MILVUS_HOST = "localhost" # 如果在 Docker 内运行且用 host 模式，或者是本地运行
MILVUS_PORT = "19530"

# 模型配置
EMBEDDING_MODEL = "text-embedding-v2" # 阿里云通用文本向量模型
LLM_MODEL = "qwen-turbo" # 通义千问-Turbo (性价比高)
VECTOR_DIM = 1536 # text-embedding-v2 的维度是 1536

# ==========================================
# 1. 辅助函数：调用百炼 API
# ==========================================

def get_embedding(text: str):
 """调用阿里云百炼 Embedding API 将文本转换为向量"""
 resp = dashscope.TextEmbedding.call(
 model=EMBEDDING_MODEL,
 input=text
 )

 if resp.status_code == HTTPStatus.OK:
 # 获取向量数据
 return resp.output['embeddings'][0]['embedding']
 else:
 print(f"Embedding API 报错: {resp}")
 raise Exception("Failed to generate embedding")

def call_llm(prompt: str):
 """调用通义千问生成回答"""
 messages = [{'role': 'user', 'content': prompt}]
 resp = Generation.call(
 model=LLM_MODEL,
 messages=messages,
 result_format='message', # 设置返回格式为 message
 )

 if resp.status_code == HTTPStatus.OK:
 return resp.output.choices[0]['message']['content']
 else:
 print(f"LLM API 报错: {resp}")
 return "抱歉，生成回答时出错了。"

# ==========================================
# 2. 初始化 Milvus 集合
# ==========================================
print(">>> 连接 Milvus...")
connections.connect("default", host=MILVUS_HOST, port=MILVUS_PORT)

collection_name = "bailian_rag_demo"

# 如果存在旧集合则删除，保证每次运行都是干净的环境
if utility.has_collection(collection_name):
 utility.drop_collection(collection_name)

# 定义 Schema
fields = [
 FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
 FieldSchema(name="vector", dtype=DataType.FLOAT_VECTOR, dim=VECTOR_DIM),
 FieldSchema(name="text", dtype=DataType.VARCHAR, max_length=2048) # 存储原始文本用于构建 Prompt
]
schema = CollectionSchema(fields, description="阿里云百炼 RAG 演示")
collection = Collection(name=collection_name, schema=schema)

# 创建索引 (IVF_FLAT 适合大多数场景)
index_params = {
 "metric_type": "L2", # 欧氏距离 (阿里云 Embedding 推荐用 Cosine，但在归一化后 L2 效果也能接受，这里演示用 L2)
 "index_type": "IVF_FLAT",
 "params": {"nlist": 1024}
}
collection.create_index(field_name="vector", index_params=index_params)
collection.load() # 加载到内存
print(f">>> 集合 {collection_name} 准备就绪")

# ==========================================
# 3. 模拟私有数据并入库 (Ingestion)
# ==========================================
# 假设这是一些只有你知道，ChatGPT 此时此刻可能不知道的“私有知识”
knowledge_base = [
 "TransMaster 项目是一个由 Python 开发的高效翻译管理系统。",
 "Zata 计划在 2025年9月 去温州旅行。",
 "Milvus 是一款高性能的开源向量数据库，支持十亿级数据检索。",
 "在 Python 中使用 Celery 可以轻松处理异步任务队列。",
 "阿里云百炼是阿里巴巴推出的一站式大模型服务平台。"
]

print(">>> 正在向量化并存入数据...")
data_vectors = []
data_texts = []

for text in knowledge_base:
 vec = get_embedding(text)
 data_vectors.append(vec)
 data_texts.append(text)

# 插入 Milvus
collection.insert([data_vectors, data_texts])
collection.flush()
print(f">>> 成功插入 {len(knowledge_base)} 条知识数据")

# ==========================================
# 4. RAG 核心流程：检索 + 生成
# ==========================================

def rag_chat(user_query):
 print(f"\n[用户提问]: {user_query}")

 # A. 检索 (Retrieval)
 # 1. 把用户的问题变成向量
 query_vector = get_embedding(user_query)

 # 2. 在 Milvus 中搜最相似的 2 条
 search_params = {"metric_type": "L2", "params": {"nprobe": 10}}
 results = collection.search(
 data=[query_vector],
 anns_field="vector",
 param=search_params,
 limit=2, # Top 2
 output_fields=["text"] # 记得把原始文本拿回来
 )

 # 3. 提取上下文
 retrieved_texts = []
 for hits in results:
 for hit in hits:
 # print(f" (命中参考资料: {hit.entity.get('text')} - 距离: {hit.distance})")
 retrieved_texts.append(hit.entity.get("text"))

 context_str = "\n".join(retrieved_texts)

 # B. 生成 (Generation)
 # 4. 组装 Prompt
 prompt = f"""
 请根据以下参考资料回答用户的问题。如果参考资料中没有答案，请回答“我不知道”。

 【参考资料】：
 {context_str}

 【用户问题】：
 {user_query}
 """

 # 5. 调用大模型
 print(">>> 正在思考...")
 answer = call_llm(prompt)
 print(f"[AI 回答]: {answer}")

# ==========================================
# 5. 测试运行
# ==========================================

# 测试 1: 问一个库里有的私有知识
rag_chat("Zata 打算什么时候去温州？")

# 测试 2: 问一个库里有的技术知识
rag_chat("TransMaster 是什么项目？")

# 测试 3: 问一个库里没有的无关问题
rag_chat("西红柿炒鸡蛋怎么做？")

代码核心逻辑解析

统一模型：
- 入库时：使用 text-embedding-v2 将知识转为向量。
- 搜索时：使用同一个 text-embedding-v2 将用户问题转为向量。这是向量搜索准确的前提。
Schema 设计：
- 我们在 Milvus 中定义了 text 字段。这是 RAG 的关键技巧：向量数据库不仅存向量，最好也存一份原始文本。这样搜索到向量后，直接就能取出对应的文字喂给大模型，不需要再去查 MySQL。
Prompt 组装：
- 代码中的 prompt 变量展示了经典的 RAG 提示词模板。强制要求 AI 基于【参考资料】回答，可以有效减少大模型的“幻觉”（胡说八道）。

可能遇到的问题

Dimension 错误： 如果你换了模型（比如换成了 text-embedding-v1），请务必确认它的维度。v2 是 1536 维，如果报错 dimension mismatch，请检查 Milvus 建表时的 dim 参数。
DashScope API 报错： 如果提示 InvalidApiKey，请检查环境变量或代码中 Key 是否复制完整。

下一步

现在你已经跑通了最核心的流程。如果你想把这个应用到实际的 TransMaster 项目中，下一步通常是**“文档切分”**：

任务： 把长的 PDF 或 Markdown 文档切成 500 字左右的小块。
工具： 可以使用 LangChain 的 RecursiveCharacterTextSplitter 来做切分，然后再传给这个脚本入库。

演示如何用 Python 切分长文本

在实际的 RAG 应用（比如你的 TransMaster 项目）中，直接把整篇几千字的文章扔给 Embedding 模型是不行的，因为：

模型限制：Embedding 模型通常有 Token 长度限制（比如 8192 token）。
搜索精度：如果一段文本太长，里面包含的信息太杂，搜索匹配的精准度会下降。

因此，我们需要切分 (Chunking)。

业界最常用的是 LangChain 提供的 RecursiveCharacterTextSplitter（递归字符文本分割器）。它很聪明，会优先在段落（\n\n）处切分，如果不行再在换行（\n）切，尽量保证句子的完整性。

1. 安装必要的库

为了轻量化，我们只安装 LangChain 的文本切分组件，不需要安装整个庞大的 LangChain。

uv add langchain-text-splitters

2. 独立演示代码：长文本切分

这个脚本演示了如何把一篇关于“TransMaster 项目开发规范”的长文档，切分成适合入库的小块。

from langchain_text_splitters import RecursiveCharacterTextSplitter

# 1. 模拟一个长文档 (假设这是你项目里的 README 或需求文档)
long_text = """
# TransMaster 项目开发规范 V1.0

## 1. 项目简介
TransMaster 是一个基于 Python 的高效翻译管理系统，旨在解决多语言项目中的协同翻译痛点。
它集成了 Redis 缓存、Celery 异步任务队列以及 Docker 容器化部署方案。
后端主要使用 Flask/FastAPI 框架，数据库采用 PostgreSQL。

## 2. 核心功能
 2.1 自动翻译
系统接入了百度翻译、DeepL 以及 Google Translate API。
当用户上传文档时，后台会通过 Celery Worker 自动将文档解析并进行预翻译。
为了防止 API 超时，所有网络请求都必须设置 timeout 参数，建议值为 10 秒。

 2.2 术语库管理
用户可以上传 TMX 格式的术语库。
在翻译过程中，系统会优先匹配术语库中的词汇，确保专业名词的统一性。
术语库的匹配算法采用了最长字符串匹配策略。

## 3. 部署指南
 3.1 Docker 环境
请确保本地安装了 Docker 和 Docker Compose。
运行 `docker-compose up -d` 即可启动所有服务，包括 Web、Redis 和 Postgres。
数据库的默认端口映射为 5432，Redis 为 6379。

 3.2 数据库迁移
我们使用 Alembic 进行数据库版本管理。
如果修改了 models.py，请务必执行 `alembic revision --autogenerate` 生成迁移脚本，
然后执行 `alembic upgrade head` 应用变更。

## 4. 常见问题
Q: 为什么上传大文件会失败？
A: 请检查 Nginx 配置中的 client_max_body_size 设置，默认限制为 1MB，建议调整为 50MB。
"""

# 2. 初始化切分器
text_splitter = RecursiveCharacterTextSplitter(
 # chunk_size: 每个块的目标大小（字符数）。
 # 设置为 100-500 之间通常比较适合做 Embedding。
 chunk_size=200,

 # chunk_overlap: 重叠部分。
 # 这是一个关键技巧！让两个块之间有重叠，防止切分时把一句话切断，导致上下文丢失。
 chunk_overlap=50,

 # separators: 切分优先级。先试着按双换行切，不行就按单换行，再不行按空格。
 separators=["\n\n", "\n", " ", ""]
)

# 3. 执行切分
chunks = text_splitter.create_documents([long_text])

# 4. 打印结果
print(f">>> 原始文本长度: {len(long_text)}")
print(f">>> 切分后的块数: {len(chunks)}\n")

print("--- 切分详情 ---")
for i, chunk in enumerate(chunks):
 content = chunk.page_content
 print(f"[块 {i+1}] (长度 {len(content)}):")
 print(f"\"{content}\"") # 打印内容
 print("-" * 30)

运行结果分析

你会发现，它不会在“TransMaster”这个词中间切开，而是尽量在段落结束的地方切开。同时，由于设置了 chunk_overlap=50，你可以观察到块1的结尾和块2的开头会有部分重复的内容。

3. 如何集成到刚才的 RAG 代码中？

把你刚才那个 rag_bailian_milvus.py 的 “3. 模拟私有数据并入库” 部分替换为下面的逻辑：

# ... (前面的代码保持不变) ...
from langchain_text_splitters import RecursiveCharacterTextSplitter

# 假设这是从文件读取出来的超长内容
raw_content = "......这里是很长的 TransMaster 项目文档......"

# 1. 切分
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=100)
split_docs = splitter.create_documents([raw_content])

print(f">>> 文档已切分为 {len(split_docs)} 个片段，开始向量化...")

data_vectors = []
data_texts = []

# 2. 遍历切分后的片段进行 Embedding
for doc in split_docs:
 chunk_text = doc.page_content

 # 调用百炼 API 获得向量
 try:
 vec = get_embedding(chunk_text)

 data_vectors.append(vec)
 data_texts.append(chunk_text)
 print(f" - 已处理片段: {chunk_text[:30]}...") # 打印前30个字示意
 except Exception as e:
 print(f" x 跳过出错片段: {e}")

# 3. 批量插入 Milvus
if data_vectors:
 collection.insert([data_vectors, data_texts])
 collection.flush()
 print(f">>> 成功入库 {len(data_vectors)} 个知识片段！")

# ... (后面的搜索代码保持不变) ...

总结：最佳实践参数

对于中文技术文档（如你的 Python 后端开发文档），我推荐以下参数：

Model: 阿里云 text-embedding-v2
Chunk Size: 300 - 500 字符 (中文含金量高，不需要太长)
Overlap: 50 - 100 字符 (保证上下文连续)
Separators: ["\n\n", "\n", "。", "！", "？"] (优先按段落切，其次按句号切)

这样切分后存入 Milvus，当你问“TransMaster 用什么数据库？”时，RAG 就能精准定位到包含“PostgreSQL”的那一小段文字，而不是把整篇文档都拉出来。

LangSmith使用教程

Fri, 30 May 2025 16:15:40 +0800

LangSmith使用教程

LangSmith 是 LangChain 官方的 LLM 应用观测平台：调试、追踪、评估、监控都在上面。LLM 应用最麻烦的一点是行为不透明——同一份提示，换个模型、换个参数、换个措辞，结果就可能完全不同，只靠 print 调试很快就会失控。我的判断是：追踪不是可选项，而是基础设施；在 LangChain 生态里，LangSmith 是接入成本最低的那个。

本文是我 2025 年 5 月的上手记录（截图都是当时的实拍）；2026 年 9 月整合博客时修订了环境变量命名和评估 API，过时的旧写法在文中用注记标出。

核心概念

概念	一句话说明
Tracing（追踪）	记录应用每个组件的输入、输出、耗时、token，还原完整执行路径
Debugging（调试）	基于 trace 定位错误和非预期行为
Evaluation（评估）	用数据集 + 评估器量化应用表现，比较不同版本
Datasets（数据集）	评估用的输入/期望输出样本集合，可从生产 trace 提取
Monitoring（监控）	部署后持续追踪错误率、延迟、token 消耗
Project（项目）	trace 的归属单位，一个应用一个项目

接入设置

账户与 API Key

到 smith.langchain.com 注册，登录后创建组织（Organization）。

在组织的 Settings → API Keys 里创建密钥，妥善保管，不要公开分享。

安装 SDK

pip install langsmith

环境变量

2026-09 修订：官方现在的推荐前缀是 LANGSMITH_。本文写作时用的还是 LANGCHAIN_ 旧前缀（下方注记），两者目前兼容，新项目直接用新写法。

export LANGSMITH_TRACING_ENABLED="true"
export LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
export LANGSMITH_API_KEY="YOUR_LANGSMITH_API_KEY"
export LANGSMITH_PROJECT="YOUR_PROJECT_NAME" # 可选，默认 "default"

LANGSMITH_TRACING_ENABLED：总开关，设为 true 后 LangChain / LangGraph 应用自动上报
LANGSMITH_PROJECT：trace 归属的项目名，可在界面上创建和管理

⚠️ 旧写法：LANGCHAIN_TRACING_V2="true" / LANGCHAIN_ENDPOINT / LANGCHAIN_API_KEY / LANGCHAIN_PROJECT。仍兼容，但已弃用。

追踪 LangChain 应用

环境变量设好之后，LangChain 应用零代码改动自动上报——这是它比手动埋点省事的核心原因。

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
import os

# 模型：阿里云百炼的 OpenAI 兼容模式
# （修订：原文这里误用了未导入的 Tongyi 类，统一改为博客其他文章一致的 ChatOpenAI 写法）
llm = ChatOpenAI(
 model="qwen-plus",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

prompt = ChatPromptTemplate.from_messages([
 ("system", "You are a helpful assistant that translates {input_language} to {output_language}."),
 ("human", "{text}")
])

chain = prompt | llm | StrOutputParser()

result = chain.invoke({
 "input_language": "English",
 "output_language": "Chinese",
 "text": "Hello, how are you?"
})
print(result)

运行后登录 LangSmith，在对应项目下就能看到这次运行的追踪记录：链的每个步骤、输入、输出、耗时、token，以及可能发生的任何错误。

追踪任意函数：@traceable

不在 LangChain 链里的函数，用 @traceable 装饰器也能纳入追踪：

from langsmith import traceable

@traceable(name="My Custom Function") # name 可选，用于在 UI 中显示
def my_data_processing_function(data: str) -> str:
 return data.upper()

@traceable
def my_llm_logic(user_input: str):
 # 里面可以调 LLM、调其他被追踪函数，调用链会串在一条 trace 里
 return my_data_processing_function(user_input)

output = my_llm_logic("This is some input text.")
print(output)

被装饰的函数每次调用都会生成一条 trace，和 LangChain 链的 trace 在同一个视图里查看。

从 Callbacks 到 astream_events：观测方式的变化

本节为 2026-09 整合时补充。

LangChain 0.x 时代，想监听应用内部发生的事，要写 CallbackHandler——继承 BaseCallbackHandler，实现 on_llm_start / on_llm_new_token 等一串回调。能用，但啰嗦，和异步、流式代码搅在一起还容易出错。

1.x 时代的官方答案是 astream_events：一条流式事件管道，把链内部每个组件的开始/结束/token 都作为事件吐出来，不用写 handler 类：

async for event in chain.astream_events(
 {"input_language": "English", "output_language": "Chinese", "text": "Hello, how are you?"},
 version="v2",
):
 if event["event"] == "on_chat_model_stream":
 print(event["data"]["chunk"].content, end="", flush=True)

分工可以这样理解：给用户看中间步骤、做流式 UI，用 astream_events；沉淀全量记录、做评估和监控，交给 LangSmith。两者不冲突。

查看追踪数据

登录平台后：

Projects 视图：所有项目的概览——运行次数、错误率
Traces 视图：项目下每条 trace 对应一次完整执行；点进去能看到 Chain / LLM / Tool / Retriever 的调用层级、输入输出、耗时
出错时，错误信息和堆栈直接展示在 trace 里
可以给 trace 打 metadata 和 tags，方便组织和筛选

Playground

Playground 是交互式的提示试验台：改提示、换模型、调参数（temperature、max_tokens），立即看输出；所有运行自动留 trace。compare 模式可以把两个版本的输出并排对比——调提示词时特别有用。

Prompt Hub

Prompt Hub 用来存放、版本化、复用提示模板。界面上创建模板，{xxx} 占位符会自动识别成 inputs；修改模板会留 commit 记录，可以回溯。（文档地址）

代码里直接拉取调用：

创建模板，右边自动出现 inputs：

修改有 commit 记录：

数据集与评估

评估是 LangSmith 对我来说价值最大的部分：凭感觉调提示，和拿数据说话，是两回事。

创建数据集

三种方式：

UI 里手动创建，添加输入和期望输出（Ground Truth）
从生产 trace 里筛选样本，「Add to Dataset」存进数据集——基于真实用户交互做评估，这是最推荐的路子
SDK 代码创建（见下）

SDK 创建数据集并运行评估

from langsmith import Client, evaluate

client = Client()

dataset_name = "My Translation Evaluations"
try:
 dataset = client.create_dataset(dataset_name, description="Dataset for evaluating translations.")
 client.create_example(
 inputs={"input_language": "English", "output_language": "French", "text": "Hello"},
 outputs={"expected_translation": "Bonjour"},
 dataset_id=dataset.id,
 )
except Exception:
 # 大概率是数据集已存在，取现成的
 dataset = client.list_datasets(dataset_name_contains=dataset_name)[0]

# 被评估的目标：包装成「接收 inputs、返回 dict」的函数（chain 即上文的翻译链）
def predict(inputs: dict) -> dict:
 translation = chain.invoke({
 "input_language": inputs["input_language"],
 "output_language": inputs["output_language"],
 "text": inputs["text"],
 })
 return {"output": translation}

# 自定义评估器：精确匹配
def exact_match(run, example) -> dict:
 expected = example.outputs["expected_translation"]
 score = int(run.outputs["output"].strip() == expected)
 return {"key": "exact_match", "score": score}

results = evaluate(
 predict,
 data=dataset_name,
 evaluators=[exact_match],
 experiment_prefix="translation-eval",
)

修订说明：原文这里原本是两行省略号占位（没有可运行代码），上面是按 langsmith SDK 的 evaluate() 补全的最小示例，具体参数以官方文档为准。

评估器除了自定义函数，常用的几类：

字符串评估器：精确匹配、正则、包含性判断
LLM-as-Judge：用另一个模型按标准打分（相关性、质量、有害性）
轨迹评估器：评 Agent 的完整执行轨迹（工具用得对不对），而不只是最终答案
比较评估器：两个版本在同一输入上并排比

⚠️ 版本注记：旧文档里的 RunCollector / QAEvalChain（langchain.evaluation 体系）已被 LangSmith 平台和 SDK 的 evaluate() 取代，这里留个名字备查。

我的建议

先在 LangSmith UI 里熟悉评估流程，再上 SDK
应用跑起来、有 trace 上报是评估的前提——评估的对象就是这些运行记录
数据集从真实 trace 里攒，比凭空编造更接近真实分布

监控与协作

应用部署后，LangSmith 可以持续监控：仪表盘看延迟、错误率、token 消耗、用户反馈；指标超阈值可设警报；用户点赞/点踩能关联到对应 trace。团队协作方面，组织内共享 trace、数据集和评估结果。

总结

接入成本几乎为零：环境变量一设，LangChain 应用自动上报
调试靠 trace，迭代靠 Playground + Prompt Hub，质量靠数据集 + 评估
观测分工：给用户看的中间过程用 astream_events，记录和分析交给 LangSmith
官方文档：docs.smith.langchain.com

Langchain-RAG实战教程

Tue, 06 May 2025 11:05:13 +0800

LLM 有两个先天限制：知识停在训练截止日期，你的私有文档、内部资料也不在它的训练语料里。直接问，轻则答"不知道"，重则一本正经地编。RAG（Retrieval Augmented Generation）就是针对这两个问题的标准解法：先从你自己的文档集合里检索出与问题最相关的几段文本，连同问题一起交给模型，让它基于给定材料作答。

这篇文章以我实际跑通的一套为例：阿里云百炼提供的 Embedding 模型和 qwen 系模型，LangChain 做编排，Chroma 做向量库。完整代码在同目录 main.py，知识库是 example_doc.txt（一篇约一万字符的 LangChain 教程文本），运行截图见下文。正文以现在还能跑的写法为准；当年 0.1 时代的老 API（RetrievalQA、get_relevant_documents() 等）单独开一节做注记，不占主线。

动手之前先回答选型问题：什么时候用 RAG，什么时候微调。

维度	RAG	微调
知识更新	换文档立即生效	需重新训练
擅长	私有知识问答、事实性回答	固定的风格、格式、领域行为
成本	主要是检索和推理开销	算力 + 数据准备 + 训练周期
可解释性	回答可溯源到具体文档	难以溯源

我的判断：知识层面的问题优先 RAG，微调解决的是"怎么说话"而不是"知道什么"。两者不冲突，可以叠加，但大多数场景先把 RAG 做好就够用了。

RAG 的核心组件：一条数据流

一个 LangChain RAG 应用的组件可以串成一条数据流看：

原始文档
 │ Document Loaders（加载）
 ▼
Document（整篇 page_content + metadata）
 │ Text Splitters（分割）
 ▼
chunks（小块文本，继承 metadata）
 │ Embedding 模型（向量化）
 ▼
向量 → Vector Store（落库）
 │ 用户提问同样转向量，相似度检索 top-k（Retriever）
 ▼
问题 + 相关 chunks（拼进 Prompt）
 │ LLM（生成）
 ▼
基于文档的回答

对应到具体组件：

组件	职责	本文用的实现
Document Loaders	从 txt/PDF/网页等来源读入文档	`TextLoader`
Text Splitters	把长文档切成语义连贯的小块	`RecursiveCharacterTextSplitter`
Embedding 模型	文本转向量	百炼 `text-embedding-v2`
Vector Store	存向量，提供相似度检索	Chroma
Retriever	统一检索接口，取 top-k	`as_retriever()`
LLM	基于上下文生成回答	qwen-plus（OpenAI 兼容模式）
链（编排）	把上面串成完整流程	LCEL

前四类组件是"建索引"阶段，Retriever 和链是"查询"阶段。索引建一次可以服务无数次查询，知识更新只需重建索引——这是 RAG 相对微调灵活的根源。

实战：百炼 + LangChain + Chroma 端到端

阿里云百炼（Model Studio）是阿里云的大模型服务平台，qwen 系模型和 text-embedding 系向量模型都能通过 DashScope API 调用，并且提供 OpenAI 兼容接口——chat 侧可以直接用 langchain-openai 的 ChatOpenAI 接入，不需要专门的 SDK 封装。

源文件与运行结果

说明：同目录的 main.py 是当时跑通的原始代码，里面还保留着 0.1 时代的写法（from langchain.text_splitter import ...、get_relevant_documents()、vectorstore.persist()、RetrievalQA）。本文正文按当前版本的写法整理过，对照源码阅读时注意区分。

源文件	说明
example_doc.txt	知识库文本，一篇约一万字符的 LangChain 教程
main.py	完整可运行代码

准备：依赖与 API Key

pip install langchain langchain-community langchain-openai langchain-text-splitters chromadb dashscope python-dotenv

dashscope 是 DashScopeEmbeddings 的依赖；如果嵌入走 OpenAI 兼容接口（见下文），这个包也可以不装。去百炼平台申请 API Key，写入脚本同目录的 .env：

DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

import os
from dotenv import load_dotenv

load_dotenv()

模型名以百炼的模型列表为准：https://help.aliyun.com/zh/model-studio/getting-started/models

加载与分割

from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

loader = TextLoader("./example_doc.txt", encoding="utf-8")
documents = loader.load()

text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
texts = text_splitter.split_documents(documents)
print(f"文档被分割成 {len(texts)} 个文本块")

两个参数直接决定检索质量：chunk_size 是每块的最大字符数，太大则一块里混进多个主题、检索不精准，太小则上下文碎、嵌入的语义信息不够；chunk_overlap 是相邻块的重叠字符数，用来避免关键句恰好被切断。1000/200 是常见的起步值，值得针对自己的文档实测调整。

读 PDF 把 TextLoader 换成 PyPDFLoader 即可，分割逻辑完全复用。

版本差异：0.1 时代的教程写 from langchain.text_splitter import ...，现在分割器拆到了独立的 langchain_text_splitters 包，老路径已废弃。

嵌入

from langchain_community.embeddings import DashScopeEmbeddings

embeddings_model = DashScopeEmbeddings(model="text-embedding-v2")

# 快速自检：随便嵌一句话，能出向量就说明模型和 Key 都通了
example_embedding = embeddings_model.embed_query("这是一个示例文本，用于测试嵌入模型。")
print(f"向量维度: {len(example_embedding)}")

⚠️ DashScopeEmbeddings 来自 langchain_community（依赖 dashscope SDK），属于 legacy 集成，不保证长期维护。新代码可以直接走百炼的 OpenAI 兼容接口，与本站其他文章的做法一致：

from langchain_openai import OpenAIEmbeddings

embeddings_model = OpenAIEmbeddings(
 model="text-embedding-v2",
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 check_embedding_ctx_length=False, # 关掉 OpenAI 特有的长度检查，否则会报错
)

向量库：Chroma

from langchain_community.vectorstores import Chroma

vectorstore = Chroma.from_documents(
 documents=texts,
 embedding=embeddings_model,
 persist_directory="./chroma_db",
)

指定 persist_directory 之后，数据在写入时自动落盘，下次运行用 Chroma(persist_directory="./chroma_db", embedding_function=embeddings_model) 直接加载，不必重建索引。

几个容易踩坑的点：

0.1 时代教程里常见的 vectorstore.persist() 不要再写了。Chroma 早就自动持久化，这个方法在新版集成里已被移除，留着只会报错。
langchain_community.vectorstores 里的 Chroma 是老路径，官方现在推荐独立包：pip install langchain-chroma，然后 from langchain_chroma import Chroma，参数一致。
FAISS 也是常用选择：FAISS.from_documents(texts, embeddings_model) 一行建库，纯内存、速度极快，适合原型验证；需要持久化时自己调 save_local() / load_local()。

检索器

retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

relevant_docs = retriever.invoke("什么是 Langchain?")
print(f"检索到 {len(relevant_docs)} 个相关文档块")
for i, doc in enumerate(relevant_docs):
 print(f"文档 {i+1}: {doc.page_content[:150]}...")

k=3 即取相似度最高的 3 个块。Retriever 是 LangChain 的统一检索接口，向量库、多路召回、压缩检索都实现同一个接口，后面换策略不用改下游代码。

版本差异：老教程里的 retriever.get_relevant_documents(query) 已废弃，统一用 retriever.invoke(query)。

生成模型：qwen-plus

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
 api_key=os.getenv("DASHSCOPE_API_KEY"),
 base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
 model="qwen-plus", # 模型列表: https://help.aliyun.com/zh/model-studio/getting-started/models
)

这是百炼的 OpenAI 兼容模式：langchain-openai 一个包通吃 qwen 系模型（qwen-plus、qwen-max 等），换模型只改 model 字符串，我的 main.py 走的就是这条路。另一条路是 langchain_community 的 ChatTongyi（或更新包里的 langchain-alibaba），同样属于 legacy 集成，除非依赖 DashScope SDK 的特有能力，否则兼容模式这条最省事。

用 LCEL 拼生成链

基础链：检索结果拼成上下文，连同问题一起过 Prompt、LLM、输出解析。

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

template = """请根据以下上下文信息来回答问题。如果你不知道答案，就说你不知道，不要试图编造答案。
用最多三句话来回答，并保持答案简洁。

上下文:
{context}

问题: {question}

有用的回答:"""
prompt = ChatPromptTemplate.from_template(template)

def format_docs(docs):
 return "\n\n".join(doc.page_content for doc in docs)

rag_chain = (
 {"context": retriever | format_docs, "question": RunnablePassthrough()}
 | prompt
 | llm
 | StrOutputParser()
)

answer = rag_chain.invoke("Langchain 的核心组件有哪些？")
print(answer)

拆开看这条链：输入是问题字符串，RunnablePassthrough() 把它原样传给 question；retriever | format_docs 表示先用检索器取文档、再拼成字符串赋给 context；然后依次过 Prompt、LLM，StrOutputParser() 把模型输出解析成纯字符串。整条链由 | 组合，每一段都是 Runnable，天然支持 .invoke()、流式输出和异步。

想同时拿到源文档做溯源，用 RunnablePassthrough.assign 把中间结果挂在字典里：

from operator import itemgetter

rag_chain_with_source = RunnablePassthrough.assign(
 context=itemgetter("question") | retriever | format_docs
).assign(
 answer=(
 {"context": itemgetter("context"), "question": itemgetter("question")}
 | prompt
 | llm
 | StrOutputParser()
 )
)

result = rag_chain_with_source.invoke({"question": "Langchain 的核心组件有哪些？"})
print(result["answer"]) # 生成的回答
print(result["context"]) # 参与生成的检索原文，可用来核对出处

Prompt 里"不知道就说不知道"这句话值得保留——它是压制幻觉的第一道闸门，尤其在检索没命中、上下文里根本没有答案的时候。

历史写法注记：RetrievalQA

这份教程最初是用 RetrievalQA 写的，0.1 时代的标准做法长这样：

# ⚠️ LangChain 1.0 已移除，仅供对照历史代码
from langchain.chains import RetrievalQA

qa_chain = RetrievalQA.from_chain_type(
 llm=llm,
 chain_type="stuff", # 或 "map_reduce" / "refine" / "map_rerank"
 retriever=retriever,
 return_source_documents=True,
)
result = qa_chain.invoke({"query": "请介绍一下 Langchain 的主要功能。"})
print(result["result"])

它把"检索 + 拼 Prompt + 生成"封成一个现成的链，chain_type 决定文档的塞法：stuff 全部塞进一个 Prompt；map_reduce 分块各自作答再合并；refine 逐块迭代修正；map_rerank 分块作答后按置信度挑。当年确实好用，我的 main.py 里跑通的也是它。

LangChain 1.0 把 langchain.chains 里这批 legacy 链整体移除了，RetrievalQA 已不存在。现代等价物就是上文那几行 LCEL——十行不到，换来的是每一步可插拔可调试；要接 Agent 的话，用 create_retrieval_tool 把检索器包成工具交给模型自主调用。老代码迁移时，遇到 from langchain.chains import RetrievalQA 直接按上文重写即可。

进阶检索策略

基础 RAG 跑通后，瓶颈多半出在检索而不是生成。三个常用升级：

MMR：解决"检索回来的块都长一个样"

普通 top-k 检索常返回几个彼此高度相似的块，占满上下文却没带来新信息。MMR（Maximal Marginal Relevance）在"与查询相似"和"彼此不相似"之间做平衡，迭代选点。启用只需换参数：

retriever = vectorstore.as_retriever(
 search_type="mmr",
 search_kwargs={"k": 4, "fetch_k": 20, "lambda_mult": 0.5},
)

fetch_k 是参与 MMR 挑选的候选数（应大于 k），lambda_mult 越接近 1 越偏多样性、越接近 0 越偏相似度。

MultiQueryRetriever：用 LLM 改写查询

用户的提问措辞常常和文档措辞对不上，一路查询召回有限。MultiQueryRetriever 让 LLM 把一个问题从不同角度改写成多个查询，分别检索后合并去重，提升召回：

retriever_multiquery = MultiQueryRetriever.from_llm(
 retriever=vectorstore.as_retriever(search_kwargs={"k": 1}),
 llm=llm,
)

代价是每次检索多一次 LLM 调用，适合召回率明显不足时再上。

SelfQueryRetriever：语义检索 + 元数据过滤

文档带结构化元数据（来源、类别、日期）时，SelfQueryRetriever 用 LLM 把自然语言拆成"语义查询 + 元数据过滤条件"两部分，向量库里同时做相似度和过滤。“找水果相关的文档，只要 doc3 来源的"这类需求，普通向量检索表达不出来，它能。

用法上需要用 AttributeInfo 把元数据字段的名称、类型、描述告诉 LLM，再 SelfQueryRetriever.from_llm(llm=..., vectorstore=..., metadata_field_info=[...]) 构建，且向量库必须支持元数据过滤（Chroma 支持）。

同一方向上还有几个值得知道的名字：ContextualCompressionRetriever（检索后用 LLM 过滤或抽取相关片段，给上下文瘦身）、EnsembleRetriever（多路召回 + RRF 融合，比如 BM25 和向量各一路）、ParentDocumentRetriever（小块检索保精度、返回父块保上下文完整）。检索质量还有两个进阶手段：混合检索（关键词 + 向量）和对 top-k 结果做 Rerank 重排。不用一次全上，哪个指标差修哪个。

怎么知道 RAG 好不好：评估指标

调优之前先有度量，否则改 chunk_size、换嵌入模型全是凭感觉。RAG 的质量要拆成两层看：检索层（该找到的找到了吗）和生成层（找到的材料用对了吗）。两层修法完全不同——检索差该动分割策略和嵌入模型，生成差该动 Prompt 和模型——混在一起调是常见错误。

层	指标	衡量什么
检索	Hit Rate	top-k 结果里包含正确文档的比例
检索	MRR	正确文档排名倒数的平均（第 1 名得 1，第 3 名得 1/3）
检索	Precision@k / Recall@k	返回的 k 条里有多少相关 / 该找到的找到了多少
检索	nDCG@k	带排名位置权重的列表质量
生成	EM（Exact Match）	答案与标准答案完全一致的比例
生成	F1	答案词级精确率/召回率的调和平均，适合抽取式问答
生成	BLEU / ROUGE / METEOR	生成文本与参考答案的重叠度，适合开放式生成
生成	语义相似度	用嵌入模型算答案与参考答案的向量相似度

评估方式从贵到便宜排：

人工评估：质量的金标准，准但不可规模化。
LLM-as-judge：让一个强模型按准确性、相关性、忠实度等维度给答案打分，便宜可规模化，但有自己的偏差（比如偏好长答案），结论要抽检校准。
框架：Ragas 专做 RAG 评估，把忠实度（faithfulness）、答案相关性、上下文精确率/召回率等指标现成化；LangSmith 提供数据集管理、运行评估和版本对比。

这些指标都依赖一个带标准答案的测试集（问题 + 正确出处 + 参考答案）。没有测试集，任何指标都算不出来——这也是多数团队跳过评估的原因。哪怕手工整理二十个有代表性的问题，也够支撑第一轮迭代。

总结

一条 RAG 主线至此完整：加载 → 分割 → 嵌入 → Chroma 落库 → 检索 → LCEL 生成，百炼的模型用 OpenAI 兼容模式接入，一套 langchain-openai 通吃。下一步可以按顺序做这几件事：

把 main.py 里的老写法按本文修正（langchain_text_splitters 导入、invoke()、去掉 persist()、RetrievalQA 换 LCEL），在当前版本的 LangChain 上重跑一遍。
用同一组问题对比不同 chunk_size / chunk_overlap 下的检索质量，别沿用默认值。
检索结果重复单一时，先把 search_type 换成 "mmr"，这是成本最低的升级。
整理一批带标准答案的测试问题，用 Hit Rate / MRR 或直接上 Ragas 建立基线，之后的每次改动都对着基线说话。
需要更精细的召回再考虑 MultiQuery / SelfQuery，需要接 Agent 用 create_retrieval_tool。

进一步阅读：LangChain 官方文档 https://python.langchain.com/

模块	配置	原因
文档导入	手动，按需导入	先保证质量，再追求自动化
切分策略	按段落，500 字左右	简单可控，效果有保障
Embedding	text-embedding-3-small 或 bge-large-zh	成熟稳定，效果好
检索	纯向量检索，top_k=5	先跑通，再优化
Prompt	明确约束 + 引用要求	确保答案有依据
Inspect	保留每次检索的候选列表	方便定位问题

RAG 与 LangChain on 扎塔-Zata

LangChain 常见报错与排查指南

LangChain 常见报错与排查指南

先定位：问题出在哪一层

七类高频报错

1. API 密钥错误（AuthenticationError）

2. 模型未找到（NotFoundError）

3. 提示模板错误（TemplateFormatError / MissingInputVariables）

4. Agent 输出解析错误（OutputParserException）

5. 工具执行错误（ToolException）

6. 上下文长度超出（ContextWindowExceeded / InvalidRequestError）

7. Agent 死循环（MaxIterationsExceeded）

1.x 时代最常见的报错：import 一个已被移除的类

排查顺序清单

总结

LangChain 与 MCP 极简教程：让 Agent 接入外部工具的另一种方式

LangChain 与 MCP 极简教程

MCP 和 Function Call 是什么关系

最小实战：两个文件跑通

服务端：FastMCP 起服务

客户端：把 MCP 工具接进 Agent

运行

运行时发生了什么

Function Call vs MCP

版本注记：从 langchain-mcp-adapters 迁移过来

下一步

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

LangGraph 实战：StateGraph、手写 ReAct 循环与 Map-Reduce 摘要

1. 基础三件套：StateGraph、State 与条件边

1.1 StateGraph：把应用建成一张状态机

1.2 State 与 Annotated：覆盖还是追加

1.3 MessagesState：内置的消息状态

1.4 条件边：让图自己决定下一步

2. 手写 tool-call 循环：Agent 到底在替你做什么

3. 完整实战：天气助手 ReAct

3.1 环境与依赖

3.2 工具定义：@tool

3.3 模型初始化与工具绑定

3.4 状态与节点

3.5 条件边与图构建

3.6 执行：两轮对话

3.7 六步执行流程梳理

3.8 收尾要点

4. Map-Reduce：超长文本分段摘要

5. 记忆与持久化：MemorySaver 与 thread_id

6. LangGraph 1.1 / 1.2：从"能跑"到"敢上生产"

6.1 节点超时：TimeoutPolicy

6.2 节点级错误处理：error_handler

6.3 图级默认值：set_node_defaults

6.4 优雅停机：RunControl 与 drain

6.5 DeltaChannel：给长线程的 checkpoint 减重

6.6 流式输出换代：事件流（v3）

6.7 类型安全的 invoke / stream（1.1）

7. 版本注记：从 0.x 写法到 LangChain 1.x

版本基线

附：题外话——我试过的 LangChain 知识图谱（不是 LangGraph）

总结

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

一个订阅更新摘要 Agent 的完整实践：从提示词踩坑到长文本分块

一、第一版管线：从 PromptTemplate 到 JSON 解析

输入与输出

SubscriptionAgent：提示、组链、解析

当时已知的软肋与对策

二、提示词踩坑：一字之差的质变

误判现场

关键改动

第二轮：真实 diff 再验证

复盘

三、超长文本：按变更单元分块，map-reduce 汇总

输出结构：从手写 dict 到 Pydantic

主流程：token 估算与分块决策

分块策略：优先变更单元，字符数兜底

map：逐块抽取

reduce：汇总成最终结果

容错与重试

如实交代：memory 并没有真正生效

四、工程细节清单

总结

溯源

langchain_core 组件详解：Prompt 模板与 Output Parsers

6.1 节点超时：`TimeoutPolicy`

6.2 节点级错误处理：`error_handler`

6.3 图级默认值：`set_node_defaults`

6.4 优雅停机：`RunControl` 与 drain

第三章：`create_deep_agent` 完整签名

3.1 `model` 参数

3.2 `tools` 参数

3.3 `system_prompt` 参数

3.4 `response_format` 参数

3.5 `checkpointer` 与持久化