大模型应用开发 / 知识点
LangChain 开发速查手册
手册条目
创建文档检索器将向量存储或其他搜索组件封装为统一检索接口。
创建文档检索器
将向量存储包装成统一检索器后,上层链只需调用 invoke(query),无需关心底层是内存、Chroma、Qdrant 还是其他搜索实现。返回值统一为 Document 列表。
基本语法
对已有向量存储调用 as_retriever():
search_type="similarity":按相似度返回结果,最常用。search_type="mmr":在相关性与结果多样性之间取平衡。search_kwargs:传入k、元数据过滤条件等检索参数;具体支持项由向量存储实现决定。
可运行示例
前置条件是已安装 langchain-core。示例使用确定性假嵌入,仅用于验证检索器接口;生产环境应替换为真实嵌入模型。
from langchain_core.documents import Document
from langchain_core.embeddings import DeterministicFakeEmbedding
from langchain_core.vectorstores import InMemoryVectorStore
documents = [
Document(
page_content="退款到账通常需要 1 到 3 个工作日。",
metadata={"source": "faq"},
),
Document(
page_content="支付回调失败时,先检查签名和 HTTP 状态码。",
metadata={"source": "runbook"},
),
]
embedding = DeterministicFakeEmbedding(size=128)
vector_store = InMemoryVectorStore(embedding=embedding)
vector_store.add_documents(documents=documents)
# 上层只依赖 retriever,不直接绑定具体向量库。
retriever = vector_store.as_retriever(
search_type="similarity",
search_kwargs={"k": 2},
)
results = retriever.invoke("支付问题")
print(f"count={len(results)}")
print(f"sources={sorted(doc.metadata['source'] for doc in results)}")预期输出
count=2
sources=['faq', 'runbook']读取时遍历每个 Document:正文在 page_content,来源、页码、租户等附加信息在 metadata,可选唯一标识在 id。
高频用法
直接接入 RAG 链时传递检索器对象;独立排障时先执行 retriever.invoke("测试问题"),检查返回数量、正文和元数据。需要多样化结果时改用 mmr,并按向量库能力配置 fetch_k 与 lambda_mult。
风险与排障
假嵌入不具备真实语义能力,用于生产会造成召回随机或不稳定;安全替代方案是接入实际嵌入模型,并用固定评测集验证召回。
返回空列表时依次检查:文档是否已写入、查询与入库是否使用同一嵌入模型、元数据过滤是否过严、集合或命名空间是否正确。更换向量库时还要核对其支持的 search_type 和过滤语法,避免把实现特有参数直接复制到另一种后端。
调整检索数量设置召回文档数量并平衡上下文质量与成本。
调整检索数量
通过 search_kwargs={"k": 数量} 控制每次最多召回多少个文档。k 越大,覆盖面通常越高,但会增加检索耗时、后续上下文长度和模型费用。
调整方式
固定数量时,在创建检索器时设置 k。不同接口或租户需要不同数量时,分别创建检索器,或直接调用向量存储的搜索方法并传入本次 k,不要在并发请求中修改共享对象的参数。
可运行示例
示例分别创建 k=1 和 k=3 的检索器,并验证返回数量。假嵌入只用于保证示例无需外部密钥。
from langchain_core.documents import Document
from langchain_core.embeddings import DeterministicFakeEmbedding
from langchain_core.vectorstores import InMemoryVectorStore
documents = [
Document(page_content="银行卡支付失败排查", metadata={"id": "d1"}),
Document(page_content="二维码支付超时处理", metadata={"id": "d2"}),
Document(page_content="退款状态查询方法", metadata={"id": "d3"}),
Document(page_content="回调签名校验步骤", metadata={"id": "d4"}),
]
store = InMemoryVectorStore(
embedding=DeterministicFakeEmbedding(size=128)
)
store.add_documents(documents=documents)
def build_retriever(k: int):
# 在业务入口限制范围,防止异常参数放大成本。
if not 1 <= k <= len(documents):
raise ValueError("k must be between 1 and document count")
return store.as_retriever(
search_type="similarity",
search_kwargs={"k": k},
)
top1 = build_retriever(1).invoke("支付问题")
top3 = build_retriever(3).invoke("支付问题")
print(f"top1_count={len(top1)}")
print(f"top3_count={len(top3)}")预期输出
top1_count=1
top3_count=3k 表示最多返回数量,不保证一定返回这么多。集合中文档不足、过滤条件过严,或使用分数阈值检索时,实际数量可能小于 k。
取值建议
问答型 RAG 可先从 k=3 或 k=4 起步,再根据评测结果调整。答案分散在多段文档时适当增大;文档块较长、模型上下文较小或费用敏感时应减小。使用 MMR 时,k 是最终返回数,fetch_k 是候选池大小,通常应满足 fetch_k >= k。
风险与排障
k 过小会漏掉关键依据,表现为回答不完整;替代方案是提高 k、优化切分或增加查询改写。k 过大会引入弱相关内容,可能导致模型混淆、延迟升高和令牌超限;替代方案是设置上限,并结合重排、元数据过滤或分数阈值缩小上下文。
调参时不要只看返回数量,应记录命中文档、排序、最终上下文令牌数和答案正确率。若修改 k 后数量不变,检查是否复用了旧检索器、是否存在过滤条件,以及后端是否对最大返回数另有限制。
重排检索结果使用重排模型提升高相关文档的最终排序。
重排检索结果
当向量检索能召回相关文档,但前几名排序不稳定时,在基础检索器之后增加交叉编码器重排。推荐先扩大召回数量,再由重排模型选出最终 top_n,不要直接把重排器当作全库检索器。
基本语法
安装 LangChain 组件和本地交叉编码器依赖:
python -m pip install -U langchain-core langchain-classic langchain-community sentence-transformers预期结果:
Successfully installed langchain-core-<VERSION> langchain-classic-<VERSION> langchain-community-<VERSION> sentence-transformers-<VERSION><VERSION> 取决于安装时间。首次运行还会从模型仓库下载权重,生产环境应提前缓存。
高频用法
下面用静态检索器模拟“已召回的候选集”,再用中文重排模型从 3 条候选中保留 2 条。复制为 rerank_demo.py 后运行:
from langchain_core.callbacks import CallbackManagerForRetrieverRun
from langchain_core.documents import Document
from langchain_core.retrievers import BaseRetriever
from langchain_classic.retrievers.contextual_compression import (
ContextualCompressionRetriever,
)
from langchain_classic.retrievers.document_compressors import CrossEncoderReranker
from langchain_community.cross_encoders import HuggingFaceCrossEncoder
class StaticRetriever(BaseRetriever):
documents: list[Document]
def _get_relevant_documents(
self,
query: str,
*,
run_manager: CallbackManagerForRetrieverRun,
) -> list[Document]:
# 生产中替换为向量库或混合检索器,并把召回 k 设得大于最终 top_n。
return self.documents
candidates = [
Document(
page_content="退款到账时间通常为 1 到 3 个工作日,具体以支付渠道为准。",
metadata={"title": "退款到账时间"},
),
Document(
page_content="忘记密码后,可通过邮箱验证码重置登录密码。",
metadata={"title": "密码重置"},
),
Document(
page_content="退款申请成功不等于资金已到账,应继续检查渠道退款状态。",
metadata={"title": "退款状态说明"},
),
]
base_retriever = StaticRetriever(documents=candidates)
model = HuggingFaceCrossEncoder(
model_name="BAAI/bge-reranker-base",
model_kwargs={"device": "cpu"},
)
reranker = CrossEncoderReranker(model=model, top_n=2)
retriever = ContextualCompressionRetriever(
base_retriever=base_retriever,
base_compressor=reranker,
)
for index, document in enumerate(retriever.invoke("退款多久到账"), start=1):
print(f"{index}. {document.metadata['title']}")预期输出:
1. 退款到账时间
2. 退款状态说明模型版本可能造成两条退款文档的先后轻微变化;验收重点是无关的“密码重置”不应进入前两名。
常用参数
top_n 是重排后保留的文档数,通常小于基础检索器的 k。例如先召回 20 条,再保留 3~5 条。model_name 决定语言覆盖、精度、显存和延迟;中文或多语言知识库不要使用仅面向英文训练的模型。model_kwargs.device 可固定为 cpu、cuda 或 mps,避免部署环境自动选错设备。
风险与边界
基础召回没有找到目标文档时,重排无法“创造”缺失结果。触发条件是 k 太小、过滤条件过严或向量召回质量差,后果是高精度地返回错误候选;安全替代是先提高召回率,并用离线评测确定 k 和 top_n。
候选数量过大或文档过长会使交叉编码器逐对推理,导致延迟和内存上升。生产中应限制候选数、预先切分长文档、批量推理并预热模型;超长文本还要检查模型截断长度,避免关键结论位于尾部被截掉。
排障清单
确认基础检索结果中已经存在正确文档;打印重排前后标题,排除元数据映射错误;检查模型是否适配中文;记录候选数、单次耗时和空结果率。升级依赖后若导入失败,优先核对 langchain_classic、langchain_community 和 sentence-transformers 的版本组合,并用本示例做启动烟测。
压缩检索上下文从召回文档中提取与当前问题直接相关的内容。
压缩检索上下文
当召回文档包含大量无关段落、占用上下文窗口或干扰回答时,使用 ContextualCompressionRetriever 在检索后按当前问题提取相关原句。压缩发生在召回之后,输出仍是 Document 列表,可继续传给 RAG 生成链。
基本语法
安装经典检索器和 OpenAI 集成:
python -m pip install -U langchain-core langchain-classic langchain-openai预期结果:
Successfully installed langchain-core-<VERSION> langchain-classic-<VERSION> langchain-openai-<VERSION>运行前设置密钥:
export OPENAI_API_KEY="<YOUR_API_KEY>"预期结果:
命令成功时不输出内容;后续 Python 进程可读取 OPENAI_API_KEY。高频用法
下面的提取提示词要求模型只复制相关原句,避免把“压缩”变成自由摘要。复制为 compress_context.py 后运行:
from langchain_core.callbacks import CallbackManagerForRetrieverRun
from langchain_core.documents import Document
from langchain_core.prompts import PromptTemplate
from langchain_core.retrievers import BaseRetriever
from langchain_classic.retrievers.contextual_compression import (
ContextualCompressionRetriever,
)
from langchain_classic.retrievers.document_compressors import LLMChainExtractor
from langchain_openai import ChatOpenAI
class StaticRetriever(BaseRetriever):
documents: list[Document]
def _get_relevant_documents(
self,
query: str,
*,
run_manager: CallbackManagerForRetrieverRun,
) -> list[Document]:
return self.documents
documents = [
Document(
page_content=(
"退款申请提交后会进入渠道处理。退款到账时间通常为 1 到 3 个工作日。"
"超过 3 个工作日仍未到账,应核对渠道退款状态。"
"登录密码可在安全中心修改。"
),
metadata={"source": "payment-faq", "page": 7},
),
Document(
page_content="新员工入职后应在 24 小时内激活企业邮箱。",
metadata={"source": "account-guide", "page": 2},
),
]
prompt = PromptTemplate.from_template(
"只逐字复制能回答问题的完整原句,不要改写,不要补充。"
"若上下文无关,只输出 NO_OUTPUT。\n"
"问题:{question}\n"
"上下文:{context}\n"
"相关原文:"
)
base_retriever = StaticRetriever(documents=documents)
llm = ChatOpenAI(model="gpt-5-nano", timeout=30, max_retries=2)
extractor = LLMChainExtractor.from_llm(llm, prompt=prompt)
retriever = ContextualCompressionRetriever(
base_retriever=base_retriever,
base_compressor=extractor,
)
results = retriever.invoke("退款超过三天还没到账怎么办?")
for document in results:
print(document.page_content)
print(document.metadata)预期输出:
退款到账时间通常为 1 到 3 个工作日。超过 3 个工作日仍未到账,应核对渠道退款状态。
{'source': 'payment-faq', 'page': 7}模型可能产生标点或空格差异;若要求可审计,验收时应检查输出句子能否在原文中逐字找到。
输出字段说明
page_content 是压缩后保留的相关文本,可能比原文短,也可能为空而被过滤。metadata 应继续保存 source、page、文档 ID 等引用信息;生成答案时同时传递这些字段,避免压缩后失去来源定位。
风险与边界
LLM 提取可能漏掉否定词、限制条件或上下文依赖句。触发条件是提示词过于宽松、原文切分不完整或模型输出改写,后果是答案失真;安全替代是使用“只复制原句”的提示词,对关键业务保留前后句,并做原文可回溯校验。
压缩器通常会对每条候选文档调用模型,候选数过大时会增加费用和延迟。应先用元数据过滤、向量相似度或重排缩小候选集,再执行 LLM 提取;同时设置超时、重试和最大召回数。
若所有文档都被压缩为空,下游链可能得到空上下文。调用方必须显式处理空列表:返回“未找到依据”,或回退到未压缩的最高相关文档,不能让模型在无证据时继续生成确定性结论。
排障清单
先对比压缩前后的文档数量和字符数;确认问题变量传入的是当前查询而不是历史查询;检查 OPENAI_API_KEY、模型权限和请求超时;验证输出文本仍能定位到原始 source 与 page。出现召回正确但压缩为空时,先放宽提示词或扩大切片上下文,不要直接无限增加重试次数。
组合检索器、提示词和模型完成知识库问答。
构建 RAG 问答链
当问题必须基于知识库内容作答时,可以把 Retriever、提示词和聊天模型组合成固定的 2-step RAG:先检索相关 Document,再把检索结果作为上下文交给模型生成答案。这样执行顺序明确,也便于分别验证“检索是否正确”和“生成是否忠于上下文”。
执行流程
核心数据流是“问题 → Retriever → Documents → context + prompt → ChatModel → answer”。向量库负责保存和检索知识,Retriever 只暴露查询接口;生成阶段不应绕过检索结果直接假设知识库内容。

关键组件
retriever:接收问题并返回相关Document;k控制最多取回多少条候选。ChatPromptTemplate:明确要求模型只依据context回答,并约定上下文不足时的行为。ChatOpenAI:负责生成答案;模型可替换,但输入变量名称必须与链中映射一致。StrOutputParser:把模型消息解析为普通字符串,便于接口直接返回。
主示例
示例用内存向量库构造一个最小知识库,再把 Retriever、Prompt 和模型组合为可直接 invoke 的链。运行前需要配置 OPENAI_API_KEY。
from langchain_core.documents import Document
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
def format_docs(docs: list[Document]) -> str:
# 这里只拼接正文;真实项目通常还会保留来源等元数据。
return "\n\n".join(doc.page_content for doc in docs)
def main() -> None:
documents = [
Document(page_content="LangChain 的 Retriever 接收字符串查询,并返回一组 Document 对象。"),
Document(page_content="VectorStore 可以通过 as_retriever() 暴露统一的检索接口。"),
]
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vector_store = InMemoryVectorStore.from_documents(documents, embedding=embeddings)
retriever = vector_store.as_retriever(search_kwargs={"k": 2})
prompt = ChatPromptTemplate.from_template(
"只根据给定上下文回答问题;若上下文不足,回答“根据给定上下文无法确定”。\n\n"
"上下文:\n{context}\n\n问题:{question}"
)
model = ChatOpenAI(model="gpt-5.4-mini", temperature=0)
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| model
| StrOutputParser()
)
print(rag_chain.invoke("LangChain 的 Retriever 返回什么?"))
if __name__ == "__main__":
main()预期结果:模型措辞可能略有不同,但答案应只表达检索到的事实,例如:
LangChain 的 Retriever 接收字符串查询,并返回一组 Document 对象。风险与排查
RAG 不能自动保证答案正确。若结果不符合预期,先单独调用 retriever.invoke(question) 检查命中文档,再检查提示词是否真正限制模型依据 context 作答;检索错误时优先修正切分、嵌入、过滤条件或 k,不要先靠扩大提示词掩盖问题。
让智能体根据问题自主决定是否调用知识库检索工具。
构建 RAG 智能体
当知识库检索不是每个问题都必需时,可以把检索器包装成工具,让模型根据问题决定直接回答还是调用知识库。这样既保留普通对话的低开销路径,也能在需要领域事实时补充外部上下文。
使用时机
这种方式适合同时处理知识库问答、闲聊和通用问题的智能体。若业务要求每个答案都必须经过内部资料校验,应使用固定检索链路,而不是把是否检索完全交给模型。

基本写法
create_agent(model, tools=[search_kb], system_prompt=...) 把检索能力交给智能体。工具名称、工具说明和系统提示词共同决定模型何时调用;检索工具本身只负责返回上下文,不应在内部再次完成最终回答。
| 配置 | 作用 | 关键点 |
|---|---|---|
model |
负责判断与生成 | 必须支持工具调用 |
tools |
暴露可执行能力 | 工具说明要写清适用问题 |
system_prompt |
约束调用边界 | 明确哪些问题应检索、哪些可直接回答 |
主示例
前置条件是已安装 LangChain 的 OpenAI 集成,并在环境变量中配置 OPENAI_API_KEY。下面用同一个智能体分别处理问候和退款规则问题,并检查执行过程中是否真的出现检索工具消息。
from langchain.agents import create_agent
from langchain.messages import ToolMessage
from langchain.tools import tool
from langchain_core.documents import Document
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_openai import OpenAIEmbeddings
documents = [
Document(
page_content="退款申请必须在支付完成后的 7 天内提交。",
metadata={"source": "refund-policy.md"},
)
]
# 用最小知识库构造可检索上下文。
vector_store = InMemoryVectorStore.from_documents(
documents,
OpenAIEmbeddings(model="text-embedding-3-small"),
)
retriever = vector_store.as_retriever(search_kwargs={"k": 1})
@tool
def search_kb(query: str) -> str:
"""检索退款规则。用户询问退款、退费或退款期限时使用。"""
docs = retriever.invoke(query)
return "\n\n".join(doc.page_content for doc in docs)
agent = create_agent(
model="openai:gpt-5.4-mini",
tools=[search_kb],
system_prompt=(
"涉及退款规则时必须先调用 search_kb;"
"问候、闲聊和无需知识库即可回答的问题不要调用该工具。"
),
)
# 用 ToolMessage 判断这一轮是否真的执行过检索。
for question in ("你好", "退款期限是多久?"):
result = agent.invoke(
{"messages": [{"role": "user", "content": question}]}
)
used_retrieval = any(
isinstance(message, ToolMessage) and message.name == "search_kb"
for message in result["messages"]
)
print(f"{question}: used_retrieval={used_retrieval}")预期结果(模型遵循系统指令时):
你好: used_retrieval=False
退款期限是多久?: used_retrieval=True模型最终回答的措辞可能变化,但检索型问题应出现 ToolMessage,无需知识库的问题则应直接回答。这个检查比只观察最终文本更适合验证“是否自主检索”。
风险与恢复
工具说明过于宽泛会导致无意义检索,过于严格又可能漏检。生产环境还要处理空检索结果,并明确要求模型在资料不足时说明无法确认,而不是补写事实。若所有回答都必须可审计,优先把检索设为强制步骤,而不是依赖模型自由选择。
在回答中保留引用文档及其来源元数据。
返回答案来源
要让前端可靠展示“答案来自哪里”,不要只把检索文本拼进提示词后丢弃原始 Document。更稳妥的做法是让工具把文本作为模型上下文,同时把完整文档对象保存在 ToolMessage.artifact,最后由应用代码组装答案和来源。
元数据前提
来源信息应在文档入库时写入 Document.metadata,例如 source、page 或稳定文档 ID。分块后要继续保留这些字段,否则生成阶段无法可靠还原出处,也不应让模型凭文本猜测来源。
基本写法
create_retriever_tool(..., response_format="content_and_artifact") 会把可读文本放进工具消息内容,同时把检索得到的文档列表作为 artifact 留给下游代码。模型负责回答,应用负责读取 artifact、去重并输出可验证的来源字段。
主示例
前置条件是已安装 LangChain 的 OpenAI 集成,并配置 OPENAI_API_KEY。示例只向用户返回白名单中的 source 和 page,避免把文档对象里的其他内部元数据直接暴露出去。
import json
from langchain.agents import create_agent
from langchain.messages import ToolMessage
from langchain_core.documents import Document
from langchain_core.tools import create_retriever_tool
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_openai import OpenAIEmbeddings
documents = [
Document(
page_content="退款申请必须在支付完成后的 7 天内提交。",
metadata={"source": "refund-policy.md", "page": 2},
)
]
vector_store = InMemoryVectorStore.from_documents(
documents,
OpenAIEmbeddings(model="text-embedding-3-small"),
)
retriever = vector_store.as_retriever(search_kwargs={"k": 1})
# content 给模型阅读,artifact 保留原始 Document 供程序提取来源。
search_tool = create_retriever_tool(
retriever,
name="search_kb",
description="查询退款规则;回答退款相关问题前使用。",
response_format="content_and_artifact",
)
agent = create_agent(
model="openai:gpt-5.4-mini",
tools=[search_tool],
system_prompt="退款规则必须先检索知识库,并且只依据检索结果回答。",
)
result = agent.invoke(
{"messages": [{"role": "user", "content": "退款期限是多久?"}]}
)
# 从工具消息的 artifact 读取来源,不从模型生成文本反向解析引用。
sources = []
seen = set()
for message in result["messages"]:
if not isinstance(message, ToolMessage) or message.name != "search_kb":
continue
for doc in message.artifact or []:
key = (doc.metadata.get("source"), doc.metadata.get("page"))
if key not in seen:
seen.add(key)
sources.append({"source": key[0], "page": key[1]})
payload = {
"answer": str(result["messages"][-1].text),
"sources": sources,
}
print(json.dumps(payload, ensure_ascii=False, indent=2))预期结果:
{
"answer": "<VALUE>",
"sources": [
{
"source": "refund-policy.md",
"page": 2
}
]
}<VALUE> 是模型生成的答案文本,实际措辞可能不同;来源字段直接来自检索文档元数据,因此不应由模型自行编造。
风险与恢复
不要把本地绝对路径、鉴权参数、用户隐私或内部对象 ID 无筛选地放入公开来源。若 artifact 为空,先检查工具是否启用了 content_and_artifact;若 source 或 page 缺失,应回到文档加载与分块阶段补齐元数据,而不是在回答阶段猜测。
增量添加、修改或删除知识库中的文档数据。
更新向量索引
当知识库内容发生新增、修改或删除时,不必全量重建索引。关键是给每个分块分配稳定 ID:新增写入新 ID,修改用原 ID 重新写入并重新生成向量,删除则按 ID 移除,最后验证旧内容已经不可检索。
使用时机
适合文档持续更新、知识库按批次同步或需要撤回过期内容的场景。若一次编辑会改变分块边界,不能只更新单个旧分块;应先确定本次产生的新旧 ID 集合,再删除已经不存在的旧分块,避免残留向量继续被召回。
基本调用
以下是 LangChain VectorStore 的核心调用形式。它是片段示例,假设 vector_store 已经完成初始化,documents 是 Document 列表。
vector_store.add_documents(documents=documents, ids=["doc-1", "doc-2"])
vector_store.delete(ids=["doc-2"])add_documents 返回成功写入的 ID 列表;传入已存在的稳定 ID 时,可用新内容覆盖对应文档。delete 按向量记录 ID 删除,不应把文件名、业务主键和分块 ID 混为一谈,除非你的索引设计明确规定它们相同。
增量更新策略
新增文档时生成新的稳定 ID 并写入;修改内容时尽量复用原分块 ID,让旧向量被新向量替换;删除内容时显式删除对应 ID。若重新切分后分块数量发生变化,应把“旧 ID 集合减去新 ID 集合”的差集一并删除。
对于生产向量库,还要确认后端是否提供持久化、批量原子性以及并发写入保障。LangChain 统一了常用接口,但底层事务和一致性语义仍由具体向量数据库决定。
主示例与预期结果
下面用内存向量库和确定性测试 Embedding 演示一次“修改、新增、删除”。测试 Embedding 仅用于本地验证接口,不应替代生产语义向量模型。
from langchain_core.documents import Document
from langchain_core.embeddings import DeterministicFakeEmbedding
from langchain_core.vectorstores import InMemoryVectorStore
vector_store = InMemoryVectorStore(
embedding=DeterministicFakeEmbedding(size=32)
)
vector_store.add_documents(
documents=[
Document(page_content="旧版 LangChain 组合说明。"),
Document(page_content="即将删除的旧知识。"),
],
ids=["doc-1", "doc-2"],
)
# 复用 doc-1 表示修改;写入新 ID 表示新增。
vector_store.add_documents(
documents=[
Document(page_content="LangChain 使用 Runnable 接口组合组件。"),
Document(page_content="LangGraph 用状态图编排工作流。"),
],
ids=["doc-1", "doc-3"],
)
vector_store.delete(ids=["doc-2"])
for doc_id in ["doc-1", "doc-2", "doc-3"]:
docs = vector_store.get_by_ids([doc_id])
print(doc_id, docs[0].page_content if docs else "<missing>")预期输出:
doc-1 LangChain 使用 Runnable 接口组合组件。
doc-2 <missing>
doc-3 LangGraph 用状态图编排工作流。风险与恢复
最大的风险不是写入失败,而是“新内容写进去了,旧分块却没删干净”。更新前应保存来源版本号或本次新旧 ID 清单;更新后按 ID 抽查,并执行一次针对已删除内容的检索验证。若批次结果异常,可按保存的 ID 清单删除本批新记录,再恢复上一版本文档并重新嵌入。
使用 LangGraph 定义带共享状态的工作流。
创建状态图
StateGraph 用一个共享状态描述工作流数据,用节点函数读取状态并返回局部更新,再用边定义执行顺序。创建完成后必须先 compile(),得到可调用的图,再通过 invoke()、流式或异步接口运行。
基本结构
创建状态图通常包含四件事:定义状态模式、注册节点、连接控制流、编译图。节点函数接收当前状态,返回要写回的字段;未返回的字段会保留,多个节点对同一字段的合并方式则取决于该字段是否配置 reducer。
下面是核心调用形式,属于片段示例,假设 State、step_a 和 step_b 已定义。
from langgraph.graph import END, START, StateGraph
builder = StateGraph(State)
builder.add_node("step_a", step_a)
builder.add_node("step_b", step_b)
builder.add_edge(START, "step_a")
builder.add_edge("step_a", "step_b")
builder.add_edge("step_b", END)
graph = builder.compile()状态与控制流
START 表示输入进入图的位置,END 表示显式终点;普通边决定固定执行顺序。共享状态不是节点间直接传对象引用的“消息队列”,而是图运行时维护的数据视图,节点通过返回字典提交状态更新。

主示例与预期结果
下面的完整示例把输入文本先标准化,再给结果增加状态前缀。两个节点只返回自己需要更新的字段,控制流由边单独定义。
from typing_extensions import TypedDict
from langgraph.graph import END, START, StateGraph
class WorkflowState(TypedDict):
text: str
normalized: str
def normalize(state: WorkflowState) -> dict[str, str]:
# 节点返回局部更新,不需要复制整个状态。
return {"normalized": state["text"].strip().lower()}
def finalize(state: WorkflowState) -> dict[str, str]:
return {"normalized": f"ready:{state['normalized']}"}
builder = StateGraph(WorkflowState)
builder.add_node("normalize", normalize)
builder.add_node("finalize", finalize)
builder.add_edge(START, "normalize")
builder.add_edge("normalize", "finalize")
builder.add_edge("finalize", END)
graph = builder.compile()
result = graph.invoke(
{"text": " Hello LangGraph ", "normalized": ""}
)
print(result)预期输出:
{'text': ' Hello LangGraph ', 'normalized': 'ready:hello langgraph'}风险与恢复
不要在节点里同时隐式修改输入状态又返回另一套值,这会让更新来源难以追踪;优先返回明确的局部更新。并行节点若可能同时写同一字段,应为该字段设计 reducer,否则可能发生更新冲突。拓扑修改后重新构建并编译图,再用固定输入验证终点状态是否符合预期。
定义图节点将模型调用、工具执行或业务逻辑封装为图节点。
定义图节点
图节点用于封装一次可独立执行的模型调用、工具执行或业务处理。节点读取当前共享状态,并返回需要写回的局部状态更新;边负责决定节点何时执行。
节点签名
最常见的同步节点形式是 state -> dict。第一个参数始终是当前状态,返回值必须是状态字段组成的更新字典。
节点还可以按需接收:
config:读取thread_id、标签和追踪配置。runtime:读取运行时上下文、存储或流式写入器。- 异步节点:使用
async def定义,并通过编译图的ainvoke()或astream()执行。
不要直接修改传入的 state。返回局部更新可以让 reducer、检查点和并行合并逻辑保持可预测。
可运行示例
下面把风控判断封装为单个业务节点。节点只负责计算 risk 和 reason,不会重建或覆盖无关字段。
from typing_extensions import TypedDict
from langgraph.graph import END, START, StateGraph
class ReviewState(TypedDict):
amount: int
risk: str
reason: str
def assess_risk(state: ReviewState) -> dict[str, str]:
amount = state["amount"]
# 边界值统一归入人工审核,避免 10000 元订单落入低风险分支。
if amount >= 10_000:
return {"risk": "high", "reason": "manual_review"}
return {"risk": "low", "reason": "auto_pass"}
builder = StateGraph(ReviewState)
builder.add_node("assess_risk", assess_risk)
builder.add_edge(START, "assess_risk")
builder.add_edge("assess_risk", END)
graph = builder.compile()
if __name__ == "__main__":
result = graph.invoke({"amount": 12_000, "risk": "", "reason": ""})
print(result)预期输出
{'amount': 12000, 'risk': 'high', 'reason': 'manual_review'}amount 没有被节点返回,因此保留输入值;risk 和 reason 被节点的局部更新覆盖。节点函数也可以直接单元测试,例如调用 assess_risk({...}) 检查边界值,不必每次启动完整图。
高频用法
模型节点通常读取 messages,调用聊天模型,再返回新增消息;消息列表应配合 MessagesState 或 add_messages reducer,避免每次覆盖全部历史。
工具节点适合执行搜索、数据库查询或外部接口。工具结果应转换成状态字段或消息后返回,异常则交给重试策略或错误处理节点,不要静默吞掉。
业务节点适合校验、格式化、分类和路由前计算。一个节点只承担一个可描述步骤,便于追踪耗时、重试和定位状态异常。
风险与边界
节点返回列表、字符串或 None,而不是状态更新字典时,会触发无效更新错误。安全做法是所有正常分支都显式返回字典;没有字段需要更新时返回空字典。
启用检查点、重试或中断恢复后,节点可能从函数开头重新执行。节点内直接扣款、发消息或插入数据库若没有幂等控制,可能产生重复副作用;应使用业务幂等键、唯一约束、upsert 或执行前状态检查。
同一节点既配置静态 add_edge(),又通过 Command(goto=...) 动态跳转时,两条路径都可能被调度。每个节点应选择一种路由方式,避免重复执行后继节点。
排障清单
- 节点未执行:确认节点已注册,并且从
START或上游节点存在可达边。 - 状态字段被意外清空:检查节点是否返回了空值,或字段是否缺少正确 reducer。
- 异步节点调用报错:使用
await graph.ainvoke(...),不要在同步入口里直接执行未等待的协程。 - 外部操作重复发生:检查重试、恢复和循环路径,并为副作用增加幂等保护。
兼容性
示例面向 LangGraph Python 1.x。add_node(assess_risk) 可使用函数名自动命名节点;生产代码显式指定稳定名称更安全,因为检查点恢复、日志检索和边引用都会依赖节点标识。
连接工作流节点使用边定义节点之间的固定执行顺序。
连接工作流节点
使用 StateGraph.add_edge() 定义不会随状态变化的固定执行顺序。适合线性处理链、固定收尾步骤,以及所有请求都必须经过的校验、转换和持久化节点。
基本语法
add_edge(source, target) 表示 source 完成后调度 target。START 是虚拟入口,END 是虚拟结束节点;节点和边全部注册后必须调用 compile(),再通过 invoke() 执行。
from typing_extensions import TypedDict
from langgraph.graph import END, START, StateGraph
class WorkflowState(TypedDict):
trace: list[str]
def prepare(state: WorkflowState) -> dict:
# 返回局部状态更新,不要直接修改传入的 state。
return {"trace": state["trace"] + ["prepare"]}
def execute(state: WorkflowState) -> dict:
return {"trace": state["trace"] + ["execute"]}
builder = StateGraph(WorkflowState)
builder.add_node("prepare", prepare)
builder.add_node("execute", execute)
# 固定链路:START -> prepare -> execute -> END
builder.add_edge(START, "prepare")
builder.add_edge("prepare", "execute")
builder.add_edge("execute", END)
graph = builder.compile()
result = graph.invoke({"trace": []})
print(result["trace"])预期输出:
['prepare', 'execute']读取方式:列表顺序就是节点实际完成后的状态轨迹,可据此确认固定边是否按预期连接。
高频用法
线性链路直接连续调用 add_edge();统一入口使用 START 指向首节点;统一收尾使用末节点指向 END。一个节点连接多个固定目标时会形成并行分支,只有确实需要同时执行时才这样配置。
风险与边界
同一源节点同时配置普通边和条件边时,两套后继都可能被调度,容易造成重复调用、重复写库或状态覆盖。安全做法是:该节点只保留一种路由机制,固定流转用 add_edge(),动态选择用 add_conditional_edges()。
并行分支同时写入同一个状态字段且没有定义 reducer 时,可能触发并发状态更新错误。可将分支写入不同字段,或为需要聚合的字段配置 reducer。
排障清单
compile()报未知节点:检查边中的节点名是否已通过add_node()注册,大小写必须一致。- 节点未执行:确认存在从
START到该节点的完整可达路径。 - 流程提前结束:检查是否误把中间节点直接连接到
END。 - 节点执行两次:检查同一源节点是否同时存在固定边、条件边或重复注册的出边。
速查:执行顺序固定就用 add_edge();需要根据状态选路时不要继续叠加普通边。
配置条件路由根据工作流状态动态决定下一个执行节点。
配置条件路由
使用 StateGraph.add_conditional_edges() 在节点完成后读取当前状态,并动态选择下一个节点。适合金额分级、审核分流、工具调用判断、重试或提前结束等存在明确分支的流程。
基本语法
add_conditional_edges(source, route_fn, path_map) 接收源节点、路由函数和可选映射。路由函数应返回映射键、目标节点名、END,或用于并行分发的目标列表。
from typing import Literal
from typing_extensions import NotRequired, TypedDict
from langgraph.graph import END, START, StateGraph
class PaymentState(TypedDict):
amount: int
result: NotRequired[str]
def normalize(state: PaymentState) -> dict:
# 真实项目可在此完成格式校验和金额标准化。
return {"amount": max(0, state["amount"])}
def choose_route(state: PaymentState) -> Literal["auto", "manual"]:
return "manual" if state["amount"] >= 1000 else "auto"
def auto_approve(state: PaymentState) -> dict:
return {"result": "auto approved"}
def manual_review(state: PaymentState) -> dict:
return {"result": "manual review"}
builder = StateGraph(PaymentState)
builder.add_node("normalize", normalize)
builder.add_node("auto_approve", auto_approve)
builder.add_node("manual_review", manual_review)
builder.add_edge(START, "normalize")
builder.add_conditional_edges(
"normalize",
choose_route,
{"auto": "auto_approve", "manual": "manual_review"},
)
builder.add_edge("auto_approve", END)
builder.add_edge("manual_review", END)
graph = builder.compile()
for amount in (100, 1500):
result = graph.invoke({"amount": amount})
print(amount, "->", result["result"])预期输出:
100 -> auto approved
1500 -> manual review读取方式:箭头右侧是条件边选择的目标节点执行结果;金额阈值变化会改变后继节点,但不会改变图结构。
常用路由形式
返回映射键时,用 path_map 将业务值映射为节点名,便于重命名节点而不修改业务判断。返回节点名时可以省略映射。需要结束流程时返回 END;返回多个目标会并行调度,必须提前设计状态合并规则。
风险与边界
路由函数返回未注册节点或未出现在映射中的值时,执行会失败。安全做法是使用 Literal 限定返回值,并为未知状态显式返回兜底节点或 END。
不要在路由函数中写库、发消息或调用外部接口。重试、恢复或图重放可能再次执行路由函数,导致副作用重复;应把副作用放进被选中的业务节点。
同一源节点不要再配置普通出边,否则固定目标和条件目标可能同时运行。需要“更新状态并立即跳转”时,可改用返回 Command 的节点,而不是混用两类边。
排障清单
- 总走同一分支:在路由函数入口打印或测试关键状态,确认上游节点已返回对应字段。
- 报目标不存在:核对
path_map的值与add_node()注册名完全一致。 - 分支节点执行后流程悬空:为每个分支补充到后续节点或
END的边。 - 出现重复副作用:检查路由函数是否包含外部调用,以及源节点是否还配置了普通出边。
速查:路由函数只负责“决定去哪”,业务处理放在目标节点中。
使用检查点保存工作流状态和会话执行进度。
配置状态持久化
工作流需要跨进程保留执行状态、支持中断后恢复或查看历史状态时,应在编译图时配置 checkpointer,并在每次调用中传入稳定的 thread_id。检查点按线程保存图状态快照;仅在内存中的 saver 不适合进程重启后的恢复。
基本配置
核心接口是 builder.compile(checkpointer=...),调用时通过 {"configurable": {"thread_id": "..."}} 指定检查点所属线程。同一业务会话复用同一 thread_id,彼此独立的执行应使用不同值。

主示例
下面用 SQLite 文件演示状态在 checkpointer 对象重新创建后仍可读取。运行前需安装 langgraph 与 langgraph-checkpoint-sqlite。
from typing_extensions import TypedDict
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.graph import END, START, StateGraph
class State(TypedDict):
count: int
def increment(state: State) -> dict[str, int]:
# 节点只返回本步更新,检查点由编译后的图自动写入。
return {"count": state["count"] + 1}
def build_graph(checkpointer):
builder = StateGraph(State)
builder.add_node("increment", increment)
builder.add_edge(START, "increment")
builder.add_edge("increment", END)
return builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "counter-1"}}
with SqliteSaver.from_conn_string("checkpoints.sqlite") as checkpointer:
graph = build_graph(checkpointer)
print(graph.invoke({"count": 0}, config)["count"])
# 重新打开同一文件,模拟应用重建 checkpointer 后读取已有状态。
with SqliteSaver.from_conn_string("checkpoints.sqlite") as checkpointer:
graph = build_graph(checkpointer)
print(graph.get_state(config).values["count"])预期输出:
1
1第二个 1 来自已保存的最新检查点,而不是前一个 Python 对象中的内存状态。
选型与边界
InMemorySaver 适合测试;SqliteSaver 适合本地开发和轻量同步场景;生产环境通常应选择数据库型持久化实现,例如 PostgresSaver。持久化能否恢复取决于 saver 本身是否耐久,以及调用时是否继续使用正确的 thread_id。
从已保存的检查点继续运行未完成的工作流。
恢复中断任务
工作流通过 interrupt() 暂停后,要真正从已保存的执行点继续,必须重新创建同一图、连接可读取原检查点的 checkpointer,并使用原来的 thread_id 调用 Command(resume=...)。仅传普通输入或换一个线程 ID 都不会恢复该中断。
恢复条件
恢复需要同时满足三个条件:检查点仍然存在;图的状态结构与节点语义仍兼容;恢复调用复用暂停时的 thread_id。Command(resume=value) 中的值会作为对应 interrupt() 的返回值交回节点。

主示例
下面先暂停任务并关闭 SQLite 连接,再重新打开同一检查点文件完成恢复,因此可以验证恢复不依赖原进程中的 Python 对象。
from typing_extensions import TypedDict
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt
class State(TypedDict, total=False):
task: str
approved: bool
status: str
def approval(state: State) -> dict:
# 首次执行在这里暂停;恢复时该节点会从头再次执行。
approved = interrupt({"question": f"批准执行“{state['task']}”吗?"})
return {"approved": bool(approved)}
def finish(state: State) -> dict[str, str]:
return {"status": "done" if state["approved"] else "cancelled"}
def build_graph(checkpointer):
builder = StateGraph(State)
builder.add_node("approval", approval)
builder.add_node("finish", finish)
builder.add_edge(START, "approval")
builder.add_edge("approval", "finish")
builder.add_edge("finish", END)
return builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "release-42"}}
with SqliteSaver.from_conn_string("resume.sqlite") as checkpointer:
graph = build_graph(checkpointer)
paused = graph.invoke({"task": "发布版本"}, config)
print(paused["__interrupt__"][0].value)
# 重新打开持久化存储,模拟应用重启后继续同一任务。
with SqliteSaver.from_conn_string("resume.sqlite") as checkpointer:
graph = build_graph(checkpointer)
resumed = graph.invoke(Command(resume=True), config)
print(resumed["status"])预期输出:
{'question': '批准执行“发布版本”吗?'}
done风险与恢复
恢复时 interrupt() 所在节点会从节点开头重新执行,因此不要在 interrupt() 之前放置不可重复的扣款、发信、写外部系统等副作用;必须提前执行时,应使用幂等键或去重机制。部署新版本后若节点或状态模式发生不兼容变更,也应先完成检查点迁移或让旧任务在兼容版本上收尾。
在暂停或恢复期间人工修改指定会话的状态数据。
更新工作流状态
当 LangGraph 工作流因 interrupt() 暂停,或需要从某个检查点恢复前人工修正数据时,可以按 thread_id 找到该会话的状态,并用 update_state() 创建一个带修改的新检查点。原检查点不会被原地覆盖,因此既能修正状态,也保留回退依据。
使用时机
适合人工审核、补录字段、纠正模型生成的中间结果,以及从历史检查点分叉后继续执行。前提是图已配置 checkpointer,并且调用方拿到正确的 thread_id;没有持久化检查点时,无法跨调用定位会话状态。
基本用法
核心调用是 graph.get_state(config) 与 graph.update_state(config, values, as_node=None)。config 的 configurable.thread_id 决定操作哪个会话,values 只提供要更新的状态字段;如果字段配置了 reducer,更新会按 reducer 规则合并,而不一定是简单覆盖。as_node 会影响后续从哪个节点继续,只有需要显式控制路由时再指定。

主示例
下面的示例先让工作流停在人工审核点,再把同一会话中的草稿从 v1 改为 v2,最后恢复执行。InMemorySaver 仅用于本地演示;生产环境应替换为可持久化的 checkpointer。
from typing_extensions import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt
class State(TypedDict):
draft: str
approved: bool
def review(state: State) -> dict:
# interrupt 会保存检查点并暂停,恢复时节点会重新执行到这里。
approved = interrupt({"draft": state["draft"], "approved": state["approved"]})
return {"approved": bool(approved)}
builder = StateGraph(State)
builder.add_node("review", review)
builder.add_edge(START, "review")
builder.add_edge("review", END)
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "order-42"}}
graph.invoke({"draft": "v1", "approved": False}, config)
paused = graph.get_state(config)
print("paused:", paused.values, paused.next)
# 基于暂停检查点创建新检查点;旧检查点仍保留在历史中。
patched_config = graph.update_state(paused.config, {"draft": "v2"})
patched = graph.get_state(patched_config)
print("patched:", patched.values, patched.next)
result = graph.invoke(Command(resume=True), patched_config)
print("result:", result)预期输出:
paused: {'draft': 'v1', 'approved': False} ('review',)
patched: {'draft': 'v2', 'approved': False} ('review',)
result: {'draft': 'v2', 'approved': True}风险与恢复
不要只凭业务名称猜测 thread_id,更新前先读取当前 StateSnapshot,确认 values、next 和目标检查点。对带 reducer 的列表、消息等字段尤其要确认合并语义,否则可能追加而不是替换。并行分支下如果 LangGraph 无法推断更新应视作哪个节点产生,才需要显式设置 as_node。
如果人工修改错误,不要试图“撤销”原检查点;从修改前保存的 snapshot.config 再调用一次 update_state() 创建正确分支,并使用返回的新 config 恢复执行。这样历史仍可审计,也不会破坏原有检查点链。
启用 LangSmith 追踪配置环境变量记录模型、工具和工作流执行轨迹。
启用 LangSmith 追踪
设置 LANGSMITH_TRACING、API Key 和项目名后,LangSmith 可记录一次请求中的工作流、工具和模型调用层级。非美国区域或自托管环境还需设置正确的 LANGSMITH_ENDPOINT,否则常见结果是鉴权失败或轨迹发送到错误区域。:contentReference[oaicite:1]{index=1}
环境变量
| 变量 | 是否必需 | 用途 |
|---|---|---|
LANGSMITH_TRACING=true |
是 | 开启自动追踪 |
LANGSMITH_API_KEY |
是 | 鉴权,必须通过密钥管理系统注入 |
LANGSMITH_PROJECT |
否 | 指定轨迹项目;未设置时进入默认项目 |
LANGSMITH_ENDPOINT |
条件必需 | 非默认区域或自托管服务的 API 地址 |
LANGSMITH_HIDE_INPUTS |
否 | 设为 true 时不上传运行输入 |
LANGSMITH_HIDE_OUTPUTS |
否 | 设为 true 时不上传运行输出 |
先将占位符替换为实际值。MODEL_NAME 使用当前模型供应商账号可调用的模型名。
python -m pip install -U langsmith openai
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"
export LANGSMITH_PROJECT="langchain-dev"
export OPENAI_API_KEY="<OPENAI_API_KEY>"
export MODEL_NAME="<MODEL_NAME>"
python trace_demo.py最小追踪示例
该示例将 trace_demo_workflow 记录为根运行,load_context 记录为工具运行,invoke_model 记录为模型运行。显式调用 flush,避免短命令行进程在后台队列发送完成前退出。
import os
from langsmith import Client, traceable
from openai import OpenAI
langsmith_client = Client()
model_client = OpenAI()
@traceable(
run_type="tool",
name="load_context",
client=langsmith_client,
)
def load_context() -> str:
return "Respond with exactly TRACE_OK."
@traceable(
run_type="llm",
name="invoke_model",
client=langsmith_client,
)
def invoke_model(context: str) -> str:
response = model_client.chat.completions.create(
model=os.environ["MODEL_NAME"],
temperature=0,
messages=[
{"role": "system", "content": context},
{"role": "user", "content": "Run the tracing check."},
],
)
return response.choices[0].message.content or ""
@traceable(name="trace_demo_workflow", client=langsmith_client)
def run_workflow() -> str:
return invoke_model(load_context())
if __name__ == "__main__":
try:
run_workflow()
print("trace request completed")
finally:
# CLI、任务容器和 Serverless 进程退出前应排空追踪队列。
langsmith_client.flush(timeout=10)预期输出
trace request completed控制台输出只说明业务调用成功结束。最终验证应进入 langchain-dev 项目,确认同一根轨迹下出现 load_context 和 invoke_model 子运行,并检查模型运行的耗时、输入、输出或错误信息。
高频配置
开发、测试和生产应使用不同的 LANGSMITH_PROJECT,例如 agent-dev、agent-test、agent-prod,避免不同环境的错误率和延迟数据混在一起。临时停用追踪只需将 LANGSMITH_TRACING=false,无需删除埋点代码。
容器部署时通过 Secret、Kubernetes Secret 或云密钥服务注入 LANGSMITH_API_KEY,不要写进 Dockerfile、镜像层、仓库或启动日志。区域化账号必须使用该区域对应的 endpoint,不能照抄其他环境的地址。
风险与边界
追踪默认可能包含提示词、工具参数、检索内容、模型输出、异常和元数据。输入中出现个人信息、支付数据或访问令牌时,上传后会形成敏感数据暴露风险;安全替代方案是先脱敏,或设置 LANGSMITH_HIDE_INPUTS=true、LANGSMITH_HIDE_OUTPUTS=true,对零留存请求则按条件关闭追踪。:contentReference[oaicite:2]{index=2}
全量生产追踪会增加网络流量、存储量和观测成本。高流量服务应按环境设置采样或只追踪关键请求,并避免把大型文件、完整文档和无界消息历史直接放入运行输入。
排障清单
- 项目中没有轨迹:检查变量是否在应用启动前生效,值是否为字符串
true,并确认进程实际读取到同一套环境变量。 - 返回 401 或 403:检查 API Key、工作区权限和
LANGSMITH_ENDPOINT区域是否匹配。 - 只有根运行没有子运行:确认子函数也使用
@traceable,模型 SDK 使用受支持的包装器,或将模型函数标记为run_type="llm"。 - CLI 偶发缺少最后一条轨迹:进程退出前调用
Client.flush();Serverless 还需保证平台允许发送请求完成。 - 项目名称不对:检查
LANGSMITH_PROJECT是否在导入和初始化客户端前设置。
速查配置:先开 LANGSMITH_TRACING,再核对 Key、Project、Endpoint,最后用一条最小请求确认根运行和子运行都已入库。
通过追踪记录定位耗时、异常和错误输出来源。
查看调用链路
当 LangChain 或 LangGraph 应用出现慢调用、异常节点或错误输出时,应把一次请求拆成父子 run 查看,而不是只盯最终结果。LangSmith trace 会记录链、模型、工具、检索器等 run 的层级、状态、耗时和输入输出摘要,可直接定位问题发生在哪一层。
使用时机
适合排查端到端延迟突然升高、工具调用失败、检索结果异常、模型输出偏离预期,以及确认某个子调用是否被重复执行。下面采用 LangSmith SDK 查询 trace,不依赖网页界面;执行前需要配置可访问目标项目的 LANGSMITH_API_KEY,且项目中已有追踪数据。
关键字段
一次 trace 中,trace_id 把同一调用链的 run 归到一起,parent_run_ids 表示祖先链,可用其长度得到缩进层级。latency_seconds 用于找慢节点,status 与 error_preview 用于定位失败,outputs_preview 适合先快速查看输出摘要;只有确实需要完整内容时再查询完整 OUTPUTS。

主示例
下面脚本先找到指定项目最近七天的一条根 run,再按 trace_id 取回整条调用链,并按 dotted_order 排序。新版查询接口默认只返回 ID,因此示例显式声明需要的字段。
import asyncio
import os
from datetime import datetime, timedelta, timezone
from langsmith import Client
async def main() -> None:
client = Client()
project_name = os.environ.get("LANGSMITH_PROJECT", "default")
project = await client.aread_project(project_name=project_name)
since = datetime.now(timezone.utc) - timedelta(days=7)
# 先锁定一个最近的根 run,避免把不同 trace 混在一起。
root = None
async for run in client.runs.query(
project_ids=[str(project.id)],
min_start_time=since,
is_root=True,
selects=["ID", "TRACE_ID", "NAME", "START_TIME"],
page_size=20,
):
root = run
break
if root is None:
raise SystemExit(f"No traces found in project {project_name!r} in the last 7 days")
# 再用 trace_id 拉取整条调用链,并只选择诊断所需字段。
runs = []
async for run in client.runs.query(
project_ids=[str(project.id)],
trace_id=str(root.trace_id),
min_start_time=since,
selects=[
"ID", "NAME", "RUN_TYPE", "STATUS", "DOTTED_ORDER",
"LATENCY_SECONDS", "ERROR_PREVIEW", "OUTPUTS_PREVIEW",
"PARENT_RUN_IDS",
],
):
runs.append(run)
for run in sorted(runs, key=lambda item: item.dotted_order or ""):
# 祖先数量就是树深度,可直接生成终端缩进。
depth = len(run.parent_run_ids or [])
latency = (
f"{run.latency_seconds:.3f}s"
if run.latency_seconds is not None
else "<pending>"
)
prefix = " " * depth
print(f"{prefix}{run.name} [{run.run_type}] {run.status} {latency}")
if run.error_preview:
print(f"{prefix} error={run.error_preview}")
elif run.outputs_preview:
print(f"{prefix} output={run.outputs_preview}")
asyncio.run(main())预期输出(名称、耗时和摘要随实际 trace 变化):
agent [CHAIN] SUCCESS <VALUE>s
retrieve [RETRIEVER] SUCCESS <VALUE>s
output=<VALUE>
model [LLM] SUCCESS <VALUE>s
output=<VALUE>定位顺序
先看根 run 的总耗时,再沿缩进层级找 latency_seconds 明显偏高的子 run;若状态为 ERROR,优先读取 error_preview 并回到对应节点的输入条件。最终结果错误但没有异常时,再对照 outputs_preview,从最早出现偏差的子节点向上追,而不是只检查最后一个模型调用。
风险与边界
追踪数据可能包含用户输入、模型输出、工具参数或业务标识,不要在生产环境无差别记录敏感信息。查询脚本也不应默认拉取完整 INPUTS、OUTPUTS;先用 preview 字段定位,再按最小范围取证。若项目追踪量很大,应限制时间窗口和筛选条件,避免一次性扫描大量历史 run。
使用测试数据集和评估器衡量回答与智能体质量。
评估应用效果
要判断提示词、模型或工具调整后是否真的变好,应先固定测试数据,再让目标应用批量运行,用评估器给结果打分,最后比较实验差异。核心不是“跑几条看看”,而是建立可重复、可回归、能定位失败样本的评测闭环。

基本流程
- 准备覆盖正常、边界和已知失败场景的数据集;需要客观答案时保存参考输出。
- 把待测链、Agent 或应用封装成输入字典到输出字典的目标函数。
- 为关键质量维度定义评估器,例如精确匹配、结构校验、事实一致性或任务是否完成。
- 每次改动都在同一基准集上运行,并记录模型、提示词、工具版本和实验结果,比较总体分数与失败样本。
评什么
回答型应用至少关注“答案是否正确”和“是否满足格式或引用约束”;智能体还要检查工具选择、参数、轨迹和最终任务是否完成。延迟、令牌消耗和失败率属于运行约束,不能用高质量分数掩盖超时或成本失控。
评估器应尽量贴近真实失败模式。能用确定性规则判断的内容优先用代码评估器;只有语义质量难以规则化时再引入模型评审,并保留代表性样本做人工抽检。
主示例
下面用 langsmith 创建一个临时数据集,对确定性目标函数执行精确匹配评估。运行前需要安装 langsmith,并配置可用的 LANGSMITH_API_KEY。
from uuid import uuid4
from langsmith import Client
client = Client()
dataset = client.create_dataset(
dataset_name=f"eval-demo-{uuid4().hex[:8]}"
)
client.create_examples(
dataset_id=dataset.id,
examples=[
{
"inputs": {"question": "2+2=?"},
"outputs": {"answer": "4"},
},
{
"inputs": {"question": "3*3=?"},
"outputs": {"answer": "9"},
},
],
)
def target(inputs: dict) -> dict:
answers = {"2+2=?": "4", "3*3=?": "9"}
return {"answer": answers.get(inputs["question"], "unknown")}
def exact_match(
inputs: dict,
outputs: dict,
reference_outputs: dict,
) -> bool:
# 规则评估器只比较本条目关心的答案字段。
return outputs["answer"] == reference_outputs["answer"]
client.evaluate(
target,
data=dataset.name,
evaluators=[exact_match],
experiment_prefix="exact-match-demo",
max_concurrency=0,
)
print("evaluation finished")预期输出:脚本自身最后会打印以下一行;SDK 还可能显示实验进度或链接。
evaluation finished验证时,两条样本都应通过该布尔评估器。如果修改 target 让其中一个答案错误,应能在实验结果中定位到对应失败样本,而不是只看到一个平均分。
风险与边界
不要把测试集做成只覆盖“容易成功”的演示问题,也不要频繁改动基准集却继续比较历史分数。对有随机性的模型或智能体,应在关键版本上重复运行并查看分布,而不是把单次得分当成稳定结论。
控制令牌与成本限制上下文规模并记录模型请求的令牌消耗。
控制令牌与成本
在调用模型前裁剪历史消息,在调用后读取 usage_metadata,即可同时控制上下文规模、输出长度和单次请求成本。令牌价格不要写死在业务代码中,应通过配置注入当前模型的输入、输出单价。
基本语法
trim_messages 负责保留最近消息并限制输入令牌;模型参数 max_tokens 限制本次输出长度;返回的 AIMessage.usage_metadata 通常包含 input_tokens、output_tokens 和 total_tokens。
高频用法
下面示例保留系统指令和最近对话,调用模型后按外部配置的每百万令牌价格估算成本。运行前配置 OPENAI_API_KEY,并安装 langchain 与 langchain-openai。
import os
from decimal import Decimal
from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, trim_messages
from langchain_openai import ChatOpenAI
# 价格随模型和服务商变化,使用部署配置而不是硬编码。
input_rate = Decimal(os.getenv("INPUT_USD_PER_1M", "0"))
output_rate = Decimal(os.getenv("OUTPUT_USD_PER_1M", "0"))
model = ChatOpenAI(
model=os.getenv("OPENAI_MODEL", "gpt-4.1-mini"),
temperature=0,
max_tokens=200, # 只限制输出,输入历史仍需单独裁剪
)
history = [
SystemMessage(content="你是简洁的生产排障助手。"),
HumanMessage(content="数据库连接偶发重置,先检查什么?"),
AIMessage(content="先检查连接池超时、数据库超时和网络日志。"),
HumanMessage(content="连接池使用 HikariCP。"),
AIMessage(content="继续核对 maxLifetime、keepaliveTime 与数据库 wait_timeout。"),
HumanMessage(content="请给出三项最优先检查项。"),
]
# 保留系统指令和最近的完整消息,避免截断出无效对话结构。
trimmed = trim_messages(
history,
max_tokens=300,
token_counter=model,
strategy="last",
include_system=True,
start_on="human",
allow_partial=False,
)
response = model.invoke(trimmed)
# 部分服务商不返回用量元数据,缺失时先记录为未知或零值。
usage = response.usage_metadata or {}
input_tokens = int(usage.get("input_tokens", 0))
output_tokens = int(usage.get("output_tokens", 0))
total_tokens = int(usage.get("total_tokens", input_tokens + output_tokens))
estimated_cost = (
Decimal(input_tokens) * input_rate
+ Decimal(output_tokens) * output_rate
) / Decimal(1_000_000)
print(f"kept_messages={len(trimmed)}")
print(f"input_tokens={input_tokens}")
print(f"output_tokens={output_tokens}")
print(f"total_tokens={total_tokens}")
print(f"estimated_cost_usd={estimated_cost:.6f}")预期输出
kept_messages=<N>
input_tokens=<N>
output_tokens=<N>
total_tokens=<N>
estimated_cost_usd=<USD><N> 与 <USD> 取决于模型、提示词和当前价格配置。若单价环境变量未配置,成本会显示 0.000000,但令牌统计仍可用于预算告警。
输出字段说明
input_tokens:发送给模型的输入令牌,包含保留下来的消息及模型接收的其他上下文。output_tokens:模型生成的令牌;降低max_tokens可限制最坏输出成本。total_tokens:通常为输入与输出之和,适合记录到日志、指标或账单明细。estimated_cost_usd:按当前配置估算,不应替代服务商最终账单。
风险与边界
裁剪阈值过低会丢失关键约束,可能导致回答偏离或工具调用缺少上下文。安全做法是始终保留系统消息,按完整消息裁剪,并在长会话中先摘要再删除旧消息。
usage_metadata 依赖服务商是否返回用量;流式调用还可能需要开启集成对应的流式用量选项。统计为空时不要把零令牌写入成本报表,应标记为“用量未知”并补充服务商侧账单校验。
排障清单
- 仍然超出上下文:检查工具定义、检索文档和附件是否在消息历史之外额外占用令牌,并为输出预留空间。
- 成本异常升高:分别记录输入和输出令牌,确认是否出现重复历史、过大的检索片段或失控的代理循环。
- 裁剪后消息报错:确保会话从系统消息或用户消息开始,且工具结果仍与对应工具调用成对出现。
处理模型限流通过退避重试和并发控制应对服务商频率限制。
处理模型限流
遇到服务商 429、瞬时网络错误或 5xx 时,应同时使用请求速率限制、指数退避重试和批处理并发上限。三者分别控制发送频率、短暂失败恢复和瞬时并发,不能互相替代。
推荐组合
模型初始化时配置 rate_limiter、max_retries 和 timeout;批量调用时再通过 max_concurrency 限制并发。重试次数要有限,超过上限后应返回可识别失败,而不是无限阻塞请求线程。
高频用法
下面示例把单进程发送速率限制为每秒 2 次、突发桶容量设为 2,并将批量并发限制为 2。运行前配置 OPENAI_API_KEY,并安装 langchain 与 langchain-openai。
import os
from langchain.rate_limiters import InMemoryRateLimiter
from langchain_openai import ChatOpenAI
# 该限流器仅协调当前 Python 进程内的请求。
rate_limiter = InMemoryRateLimiter(
requests_per_second=2,
check_every_n_seconds=0.1,
max_bucket_size=2, # 允许短时突发,但不会无限积累额度
)
model = ChatOpenAI(
model=os.getenv("OPENAI_MODEL", "gpt-4.1-mini"),
temperature=0,
timeout=30,
max_retries=5, # 对可重试的限流、网络和服务端错误做退避重试
rate_limiter=rate_limiter,
)
prompts = [
"只回复 A",
"只回复 B",
"只回复 C",
]
# 限制瞬时并发,并保留每个任务的独立失败结果。
results = model.batch(
prompts,
config={"max_concurrency": 2},
return_exceptions=True,
)
for index, result in enumerate(results):
if isinstance(result, Exception):
print(f"{index}: failed {type(result).__name__}")
else:
print(f"{index}: ok")预期输出
0: ok
1: ok
2: ok当重试耗尽、密钥无效或配额不可用时,对应行会变为 failed <异常类型>。生产代码应继续记录请求 ID、HTTP 状态、重试次数和服务商返回的限流头,避免只保存异常文本。
常用参数
requests_per_second:单进程平均放行速率,应低于服务商配额并预留其他实例的流量。max_bucket_size:允许的瞬时突发量;设得过大可能在空闲后集中发送请求。max_retries:最大重试次数。增加它会提高成功率,也会拉长尾延迟并放大积压。max_concurrency:同时执行的任务数,主要限制瞬时并发,不保证每分钟请求数或令牌数。timeout:单次尝试的等待上限,应小于上游接口或任务的总超时。
风险与边界
InMemoryRateLimiter 只在当前进程内共享,也只按请求次数限速。多实例部署若各自按完整配额放行,会共同冲破服务商限制;安全替代方案是使用 Redis、网关或统一任务队列实现分布式配额。
对所有异常无差别重试会放大故障。认证失败、参数错误和确定性业务错误通常不应重试;对于 429 应优先遵守服务商的等待提示,并给退避加入随机抖动,避免多个实例同时再次冲击。
排障清单
- 重试后仍持续
429:降低发送速率和并发,核对限制是请求数、令牌数还是模型级配额。 - 延迟突然升高:检查是否大量请求正在限速器中等待,或每次调用都执行了多轮重试。
- 单机正常、多实例失败:确认限流器是否为分布式实现,并按所有实例合计流量配置额度。
- 批任务部分失败:保留
return_exceptions=True的逐项结果,只重放可重试项,避免整批重复计费。