1. 为什么 RAG 系统需要一台“心电监护仪”做过 RAG 应用的人大概都有过这种体验用户反馈“回答不准”你打开日志一看检索回来的文档看起来没问题生成的内容却答非所问或者明明知识库里有的内容模型就是视而不见。更让人头疼的是这类问题往往无法稳定复现——同一个问题问两遍一次答对一次答错你连从哪里下手排查都不知道。这就是 RAG 系统最典型的困境链路太长黑盒太多。一个完整的 RAG 流程至少包含查询改写、向量化、向量检索、重排序、上下文拼接、Prompt 组装、大模型生成这六七个环节任何一个环节出问题最终都会表现为“回答不好”。但“回答不好”这四个字根本无法定位到底是哪一环出了故障。打个比方这就像医生看病。病人说“我不舒服”你不可能直接开药你得先量体温、测血压、做心电图把模糊的主诉转化成一个个可观测的指标才能判断问题出在心脏、肺还是别的地方。RAG 系统也一样它需要的不是“感觉回答不好”这种主观判断而是一套能记录每个环节输入输出、耗时、token 消耗、中间状态的全链路观测能力。LangSmith 就是干这个的。它本质上是一个面向大模型应用的追踪与评估平台能把你 RAG 链路里的每一次调用——不管是检索器的调用、LLM 的调用还是自定义函数的执行——都记录下来形成一棵可视化的调用树。你可以把它理解成给 RAG 系统装了一台心电监护仪每一次心跳调用都被记录波形输入输出都被保存一旦出现异常你能精确回放到出问题的那一次。这篇文章主要面向已经用 LangChain 或类似框架搭过 RAG 应用、但被调试问题折磨过的开发者。如果你还在用 print 大法排查 RAG 问题或者你的日志系统只能告诉你“这次请求失败了”却说不清失败在哪一步那这套观测方案值得你花时间搭起来。我会从整体设计思路讲到具体的接入步骤、参数配置、常见坑尽量让你看完就能在自己的项目里复现。2. 全链路观测的整体设计思路拆解2.1 观测粒度从“请求级”下沉到“节点级”大部分人的第一版 RAG 日志是这样的记录用户问了什么、最终答了什么、耗时多少。这是请求级观测粒度太粗。当回答出错时你只知道“这次请求失败了”但检索到的文档是什么、重排序后的顺序是什么、最终塞进 Prompt 的上下文长什么样全都不知道。LangSmith 的核心价值在于把观测粒度下沉到节点级。它通过 Trace追踪和 Run运行单元两级结构来组织数据一次完整的用户请求对应一个 TraceTrace 内部的每一个环节——检索、重排、生成——都是一个 Run。每个 Run 都记录了输入、输出、开始时间、结束时间、耗时、token 用量、错误信息。这样你排查问题时可以逐层展开看到每个节点的真实数据。我个人的经验是观测粒度至少要下沉到“能独立判断对错”的最小单元。比如检索节点它的输出是一组文档你能判断这组文档是否相关生成节点它的输出是文本你能判断是否答非所问。而像“向量化”这种中间步骤如果它只是把文本转成向量你肉眼也看不出对错那就不必单独建 Run合并到检索节点里即可。粒度太细会让 Trace 树变得臃肿反而影响排查效率。2.2 追踪方式选型自动追踪 vs 手动埋点LangSmith 提供两种追踪方式。自动追踪是指你用了 LangChain 的组件比如RetrievalQA、VectorStoreRetriever只要配置好环境变量框架会自动帮你上报 Trace几乎零代码改动。手动埋点是指你用traceable装饰器或trace上下文管理器手动标记自定义函数的执行。那到底该用哪种我的建议是混合使用。框架内置的组件用自动追踪省事且不会漏你自己写的业务逻辑——比如查询改写、自定义的重排序算法、结果后处理——用手动埋点。因为自动追踪只能覆盖框架认识的组件你写在chain外面的那些函数框架根本不知道它们的存在自然也不会记录。这里有个容易踩的坑很多人以为配了环境变量就万事大吉结果发现自己写的rerank函数在 Trace 里完全看不到排查问题时缺了最关键的一环。所以接入前先梳理一遍你的 RAG 链路把每个环节标注为“框架组件”还是“自定义逻辑”前者自动追踪后者手动埋点一个都别漏。2.3 数据采集的边界记什么不记什么全链路观测不等于“什么都记”。LangSmith 会把每次 Run 的输入输出完整上传如果你的 RAG 系统处理的是用户隐私数据、内部文档、商业机密那这些内容会一并上传到平台。这是接入前必须想清楚的问题。我的处理原则是观测数据只保留排查问题必需的最小集。具体来说检索到的文档内容、最终生成的回答、Prompt 模板这些是排查必需的必须记但用户的原始身份信息、文档里的敏感字段可以在上报前做脱敏处理。LangSmith 支持通过环境变量控制是否记录完整内容也支持在代码里对输入输出做预处理。如果你对数据合规有要求建议在接入前先和团队确认数据边界别等出了问题再补救。另外观测本身是有成本的。每次 Run 上报都会产生网络请求和存储开销如果你的 RAG 系统 QPS 很高全量上报可能会带来可观的费用和延迟。实践中可以采取采样策略正常请求按比例采样比如 10%错误请求和慢请求全量上报。这样既控制了成本又保证了问题样本不丢失。3. 核心细节解析与实操要点3.1 环境准备与关键配置项接入 LangSmith 的第一步是拿到 API Key 并配置环境变量。这一步看起来简单但有几个配置项直接决定了追踪能不能正常工作我逐个说明。export LANGCHAIN_TRACING_V2true export LANGCHAIN_ENDPOINThttps://api.smith.langchain.com export LANGCHAIN_API_KEY你的API Key export LANGCHAIN_PROJECTrag-observability-demoLANGCHAIN_TRACING_V2是总开关必须设为true否则后面配了也白搭。LANGCHAIN_PROJECT是项目名同一个项目下的 Trace 会聚合在一起建议按环境区分比如rag-dev、rag-prod避免测试数据污染生产观测。LANGCHAIN_ENDPOINT一般用默认值即可除非你有自建的服务地址。注意环境变量必须在导入 LangChain 相关模块之前设置好。我见过有人把os.environ的设置写在 import 之后结果追踪死活不生效排查了半天才发现是加载顺序问题。如果你在代码里设置环境变量务必放在所有 LangChain import 的最前面。还有一个容易被忽略的点如果你用的是异步调用ainvoke、astream要确认你的 LangSmith SDK 版本支持异步追踪。早期版本对异步的支持不完善会出现 Trace 丢失或 Run 不完整的情况。建议把langsmith和langchain都升到较新的版本避免这类兼容性问题。3.2 自动追踪的接入与验证自动追踪的接入成本极低配置好环境变量后你原有的 LangChain 代码基本不用改。但“不用改”不代表“不用验证”接入后第一件事是确认 Trace 真的上报成功了。from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate llm ChatOpenAI(modelgpt-4o-mini) prompt ChatPromptTemplate.from_template(用一句话解释{concept}) chain prompt | llm result chain.invoke({concept: 向量检索}) print(result.content)跑完这段代码去 LangSmith 的项目页面看应该能看到一条 Trace展开后有两个 Run一个是 Prompt 的格式化一个是 LLM 的调用。如果只看到一个 Run或者干脆什么都没有那就要检查环境变量和版本了。验证的时候有个小技巧故意制造一个错误比如把 API Key 改错看 Trace 里是否记录了错误信息。一个合格的观测系统不仅要记录成功调用更要记录失败调用因为失败往往才是你排查问题的起点。如果错误没有被捕获那这套观测的价值就打了对折。3.3 手动埋点给自定义逻辑装上探头框架组件之外的逻辑需要手动埋点。LangSmith 提供了两种方式我分别说说适用场景。第一种是traceable装饰器适合装饰独立的函数from langsmith import traceable traceable(namecustom_rerank, run_typetool) def custom_rerank(query: str, docs: list) - list: # 你的重排序逻辑 scored [(doc, compute_score(query, doc)) for doc in docs] scored.sort(keylambda x: x[1], reverseTrue) return [doc for doc, _ in scored]name参数是显示在 Trace 里的节点名建议起得有意义比如custom_rerank比func_1强太多。run_type用来标记节点类型常见的有llm、chain、tool、retriever正确设置类型能让 Trace 的可视化更清晰。第二种是trace上下文管理器适合包裹一段代码块from langsmith import trace def process_query(query: str): with trace(namequery_rewrite, run_typechain) as run: rewritten rewrite_query(query) run.end(outputs{rewritten_query: rewritten}) return rewritten上下文管理器的好处是可以在代码块内部动态设置输入输出适合那些输入输出不是函数参数的场景。比如查询改写输入是原始 query输出是改写后的 query用上下文管理器能精确控制记录的内容。实操心得手动埋点时输入输出要记“有意义的数据”而不是“全部数据”。我见过有人把整个文档列表的 embedding 向量都记进去结果 Trace 页面加载慢得要死排查时也根本看不过来。记住观测数据是给人看的不是给机器看的记那些你能一眼判断对错的信息就够了。3.4 元数据与标签让 Trace 可检索Trace 多了以后怎么快速找到你要排查的那一条靠元数据metadata和标签tags。LangSmith 支持在 Run 上附加任意键值对你可以把用户 ID、会话 ID、模型版本、检索策略等维度都打上去。chain.invoke( {concept: 向量检索}, config{ metadata: {user_id: u_123, strategy: hybrid_search}, tags: [prod, v2] } )这样当你想排查“使用 hybrid_search 策略的所有失败请求”时直接按 metadata 过滤就行不用一条条翻。标签适合做粗粒度的分类比如按环境prod/dev、按版本v1/v2、按优先级high/low打标元数据适合做细粒度的检索比如具体的用户、会话、参数组合。我的习惯是至少打三个维度的标签环境、版本、链路类型。环境区分测试和生产版本区分不同迭代链路类型区分是问答、摘要还是别的场景。这三个维度基本能覆盖 80% 的排查场景剩下的用元数据补充。4. 实操过程与核心环节实现4.1 搭建一个可观测的最小 RAG 链路光讲理论不够我带你搭一个最小可运行的 RAG 链路把观测能力完整接进去。这个链路包含四个节点查询改写、向量检索、重排序、生成。每个节点都做埋点形成一个完整的 Trace 树。先准备基础组件import os os.environ[LANGCHAIN_TRACING_V2] true os.environ[LANGCHAIN_API_KEY] 你的API Key os.environ[LANGCHAIN_PROJECT] rag-observability-demo from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain_core.vectorstores import InMemoryVectorStore from langchain_core.prompts import ChatPromptTemplate from langsmith import traceable llm ChatOpenAI(modelgpt-4o-mini, temperature0) embeddings OpenAIEmbeddings(modeltext-embedding-3-small)这里用内存向量库做演示实际项目里换成你用的向量数据库即可。关键是每个节点都要能被独立观测。4.2 查询改写节点的实现与埋点查询改写是 RAG 里最容易被忽略、但对效果影响很大的环节。用户的问题往往口语化、有指代、信息不全直接拿去检索效果很差。改写节点负责把原始问题转成更适合检索的形式。traceable(namequery_rewrite, run_typechain) def rewrite_query(original_query: str) - str: prompt ChatPromptTemplate.from_template( 把下面的问题改写成适合向量检索的查询保留关键实体去掉口语化表达。 只输出改写后的查询不要解释。\n\n原问题{q} ) chain prompt | llm result chain.invoke({q: original_query}) return result.content.strip()这个节点用traceable装饰后它的输入原始问题和输出改写后的问题都会被记录。排查时你能清楚看到模型到底把问题改成了什么。我遇到过改写节点把“它多少钱”改写成“价格”这种丢失上下文的情况如果没有观测你根本不知道检索失败是因为改写出了问题。注意改写节点本身也是一次 LLM 调用会产生 token 消耗和延迟。如果你的场景对延迟敏感可以考虑用规则改写替代或者只在检测到查询质量低时才触发改写。观测数据能帮你判断改写的收益是否值得这个成本。4.3 检索与重排序节点的埋点检索节点是 RAG 的核心也是最需要观测的环节。我们要记录检索到的原始文档、相似度分数、重排序后的顺序。traceable(namevector_retrieve, run_typeretriever) def vector_retrieve(query: str, k: int 10) - list: docs vectorstore.similarity_search_with_score(query, kk) return [{content: d.page_content, score: s} for d, s in docs] traceable(namecustom_rerank, run_typetool) def custom_rerank(query: str, docs: list, top_n: int 3) - list: # 这里用简单的关键词重叠度做演示实际项目可换成 Cross-Encoder def overlap_score(doc): return len(set(query) set(doc[content])) / max(len(set(query)), 1) ranked sorted(docs, keyoverlap_score, reverseTrue) return ranked[:top_n]检索节点记录的是“召回”重排序节点记录的是“精排”。这两个节点的输出都要完整记录因为排查时你需要对比是召回阶段就没找到相关文档还是召回了但重排序排错了这两种情况的优化方向完全不同——前者要调检索策略后者要调重排序模型。4.4 生成节点与完整链路串联最后是生成节点把重排序后的文档拼进 Prompt交给大模型生成回答。traceable(namegenerate_answer, run_typellm) def generate_answer(query: str, docs: list) - str: context \n\n.join([d[content] for d in docs]) prompt ChatPromptTemplate.from_template( 根据以下资料回答问题资料中没有的信息不要编造。\n\n 资料\n{context}\n\n问题{q}\n\n回答 ) chain prompt | llm return chain.invoke({context: context, q: query}).content traceable(namerag_pipeline, run_typechain) def rag_pipeline(query: str) - str: rewritten rewrite_query(query) docs vector_retrieve(rewritten, k10) reranked custom_rerank(rewritten, docs, top_n3) answer generate_answer(query, reranked) return answer把整个链路包在rag_pipeline这个 Trace 里所有子节点都会挂在它下面形成一棵完整的调用树。跑一次rag_pipeline(你们的退货政策是什么)去 LangSmith 看你会看到类似这样的结构rag_pipeline ├── query_rewrite ├── vector_retrieve ├── custom_rerank └── generate_answer每个节点都能展开看输入输出。这时候如果回答不对你可以逐层往下看改写后的查询对不对检索到的文档相关吗重排序后的前三篇是不是最相关的Prompt 里的上下文完整吗问题定位从“猜”变成了“看”。4.5 参数计算与选择过程观测接入后你会发现很多之前拍脑袋定的参数其实可以用数据来优化。举几个我实际调过的例子。检索的 k 值。一开始我设 k10觉得召回越多越好。但观测数据显示重排序后真正被用到的文档通常只有 2-3 篇k10 意味着有 7 篇是浪费的还增加了重排序的延迟。后来我把 k 降到 6召回质量基本没降延迟降了约 30%。这个结论不是拍脑袋来的是看了几十条 Trace 的检索结果分布后得出的。重排序的 top_n。top_n 决定了塞进 Prompt 的文档数量。设太小可能漏掉关键信息设太大Prompt 变长token 成本上升还可能引入噪声干扰生成。我的做法是看观测数据里“正确答案所在的文档排名分布”如果 90% 的正确答案都在前 3 篇那 top_n3 就够了如果分布很散说明重排序效果不好得先优化重排序。改写是否触发。改写节点有成本不是每次都需要。我通过观测数据统计了“改写前后检索命中率的变化”发现对于短查询少于 5 个字改写收益明显对于长查询收益很小。于是加了个规则只有查询长度小于阈值时才触发改写。这个优化让整体延迟降了不少效果还没受影响。5. 常见问题与排查技巧实录5.1 Trace 不显示或显示不全这是接入初期最常见的问题。按我的排查顺序通常是这几个原因现象可能原因排查方法完全没有 Trace环境变量未生效检查LANGCHAIN_TRACING_V2是否为true且设置在 import 之前只有部分节点自定义函数未埋点检查链路里哪些是自定义逻辑补上traceable异步调用丢失SDK 版本过旧升级langsmith和langchain到较新版本上报延迟网络或采样配置检查网络连通性确认采样率设置我踩过最深的一个坑是环境变量在 Jupyter Notebook 里设置后因为内核已经加载过 LangChain导致设置不生效。解决办法是设置完环境变量后重启内核或者用importlib.reload重新加载模块。这个坑排查了我快一个小时因为代码看起来完全没问题。5.2 观测数据太多找不到重点Trace 多了以后页面会变得很乱。这时候标签和元数据就派上用场了。我的做法是建立一套命名规范项目名按环境分标签按版本和链路类型打元数据里带上关键参数。这样排查时先按标签过滤再按元数据精确定位效率高很多。另外LangSmith 支持对 Trace 做筛选和排序比如“只看耗时超过 5 秒的”“只看报错的”“只看某个用户的”。善用这些筛选条件能帮你快速从海量 Trace 里捞出问题样本。我通常会先按“错误”筛一遍再按“耗时”排个序基本就能找到需要优化的点。5.3 观测带来的性能开销全量上报确实会带来延迟。我实测下来每次 Run 上报大约增加 10-50ms 的网络开销链路节点多的话累积起来不可忽视。如果你的应用对延迟敏感几个优化方向采样上报正常请求按比例采样错误和慢请求全量上报异步上报确认 SDK 用的是异步上报模式不阻塞主流程精简数据只上报排查必需的内容别把大段文档全文都传上去实操心得我一般会在开发环境开全量上报方便调试生产环境开采样上报采样率根据流量调整。这样既保证了排查能力又控制了开销。采样率不是拍脑袋定的而是根据“每天需要排查的问题数量”倒推——如果每天大概有 10 个问题需要排查那采样率保证每天有几百条 Trace 就够了。5.4 排查思路速查表最后整理一个我常用的排查思路表遇到 RAG 回答问题时按这个顺序过一遍排查步骤看什么判断标准1. 看改写改写后的查询是否保留了关键实体是否丢失上下文2. 看召回检索到的文档列表相关文档是否在列表里排名如何3. 看重排重排后的顺序最相关的文档是否排在前列4. 看上下文塞进 Prompt 的内容是否包含回答所需的信息5. 看生成模型输出是否忠实于上下文有无编造这个顺序是从链路前端往后端走因为前端的问题会传导到后端。如果召回阶段就没找到相关文档那后面重排和生成再优化也没用。先定位问题出在哪一环再针对性优化比盲目调参高效得多。这套观测方案搭起来之后我最大的感受是RAG 调优从玄学变成了工程。以前改个参数心里没底现在改完看数据好没好一目了然。当然观测只是手段不是目的最终还是要落到效果提升上。下一篇我会聊聊怎么基于这些观测数据做系统性的评估和优化把“能看见问题”变成“能解决问题”。