1. 为什么链路追踪和自动化评估值得放在一起聊做过RAG应用的人大概都有过这种体验上线前觉得检索增强生成这套东西逻辑挺清晰无非就是“查资料、拼上下文、调模型”三步走可一旦真实用户开始用问题就全冒出来了。用户问“上季度那个项目的交付节点是什么时候”系统检索回来一堆不相关的会议纪要用户追问“那它的负责人是谁”模型直接开始编。你盯着日志看半天只能看到最终输出不对但到底是检索环节没召回、还是重排环节把正确文档排到了后面、还是提示词把模型带偏了根本无从判断。这就是链路追踪要解决的核心问题——把一次请求从入口到出口的每一个环节都拆开、记录下来让你能像看慢动作回放一样定位到具体是哪一步出了问题。而自动化评估解决的是另一个维度的问题你不可能每次改完提示词或换完嵌入模型都靠人工一条条去测。你需要一套可重复、可量化、可对比的评估流程让每次迭代都有数据支撑而不是凭感觉说“好像好了一点”。LangSmith这个平台恰好把这两件事串在了一起。它提供的不只是“看日志”的能力而是从追踪数据采集、到数据集构建、再到自动化评估跑分的完整闭环。我最初接触它的时候以为就是个可视化调试工具用了一段时间才发现真正有价值的是它把“发现问题”和“验证修复”这两个动作之间的链路缩短了——你在追踪面板里看到一条bad case可以直接把它加到评估数据集里然后跑一轮评估看看改动有没有引入回归。这个工作流一旦跑顺迭代效率的提升是肉眼可见的。这篇文章适合两类人看一类是已经在做RAG应用、但调试基本靠猜的开发者另一类是想建立系统化评估流程、但不知道从哪下手的技术负责人。我会从整体设计思路讲到具体实操把链路追踪的数据结构、评估器的配置方法、以及我在实际使用中踩过的坑都摊开来说。文章里涉及的工具和平台都是通用的技术方案不涉及任何特定机构或项目背景。2. 链路追踪的底层逻辑与数据模型拆解2.1 一次RAG请求到底经历了什么要理解链路追踪的价值得先搞清楚一次RAG请求在系统内部到底走了哪些路。很多人脑子里对RAG的印象就是“检索生成”两个步骤但实际生产环境里的链路远比这个复杂。我画不出图但可以用文字把典型链路拆一遍。用户输入一个问题后系统通常先做查询改写——把口语化的提问转成更适合检索的形式比如把“那个新功能啥时候能上”改写成“新功能发布时间计划”。这一步可能用一个小模型来做也可能用规则模板。改写完之后进入检索阶段检索本身又分好几层向量检索召回一批候选文档关键词检索再召回一批两路结果做融合。融合之后可能还有一个重排模型对候选文档做精细排序取Top-K个最相关的。拿到检索结果后系统要把这些文档片段和原始问题拼成一个完整的提示词。这个拼接过程涉及模板填充、上下文长度截断、可能还有格式转换。最后才是调用大模型生成回答。生成完之后可能还有后处理比如引用标注、敏感词过滤、格式校验。这一整条链路上任何一个环节出问题都会导致最终输出质量下降。但如果你只看最终输出根本不知道问题出在哪。链路追踪要做的就是给每个环节打上标记记录输入输出、耗时、token消耗、以及自定义的元数据。LangSmith的追踪数据结构就是围绕这个需求设计的它把一次请求建模成一棵调用树根节点是整条链路子节点是各个步骤每个节点都有独立的输入输出和运行信息。2.2 追踪数据的核心字段与采集方式LangSmith的追踪数据模型里有几个字段是必须关注的。第一个是run_type它标记了这个节点是什么类型的操作比如llm表示大模型调用、retriever表示检索、chain表示组合链路、tool表示工具调用。这个字段决定了平台怎么解析和展示这个节点的数据。第二个是inputs和outputs分别记录节点的输入和输出。对于检索节点输入是查询语句输出是召回的文档列表对于大模型节点输入是完整的提示词输出是模型返回的文本。这些数据是后续做评估的基础因为评估器需要拿到这些中间结果才能判断每一步的质量。第三个是extra字段可以塞自定义的元数据。我习惯在这里放一些业务相关的标记比如用户ID、会话ID、实验分组。这样后续在平台上筛选和分析的时候可以按这些维度做聚合。比如你想对比A/B两组不同提示词的效果就可以在extra里标记分组然后在平台上按分组过滤追踪记录。采集方式上LangSmith提供了SDK级别的集成。如果你用的是LangChain框架基本上加几行环境变量配置就能自动采集因为LangChain的每个组件都内置了回调机制。如果你没用LangChain也可以手动埋点在关键步骤前后调用SDK的API记录输入输出。手动埋点的好处是灵活可以精确控制记录哪些数据坏处是工作量大容易漏掉环节。我的建议是如果项目已经用了LangChain就直接用自动采集如果是自研框架至少要在检索和生成这两个核心环节做手动埋点。2.3 追踪数据怎么帮你定位问题有了追踪数据之后定位问题的思路就清晰了。假设用户反馈“回答不准确”你可以按以下顺序排查。先看检索节点的输出。如果召回的文档里根本没有包含正确答案的片段那问题出在检索环节。这时候你要进一步看查询改写的结果——是不是改写后的查询偏离了原意还是嵌入模型对这类问题的语义匹配能力不足或者是向量库里的文档本身就没有覆盖这个知识点如果检索结果里有正确文档但最终回答还是错的那就看生成节点。检查提示词里是否正确地把检索到的文档拼进去了有没有因为上下文长度限制被截断。再看模型的输出是不是忽略了文档内容、开始自由发挥。有时候模型会“过度自信”明明文档里写的是A它非要回答B这时候可能需要调整提示词里的约束条件。还有一种情况是检索和生成都没明显问题但整体体验就是不好。这时候要看耗时数据。如果检索花了3秒、生成花了8秒用户等十几秒才看到回答体验肯定差。追踪数据里的耗时字段可以帮你找到性能瓶颈在哪个环节。我在实际使用中养成了一个习惯每次上线新版本之前先跑一批测试问题把追踪记录逐条过一遍。重点看那些“检索到了正确文档但生成错误”的case这类问题往往最隐蔽因为表面上看检索没问题容易忽略生成环节的提示词设计缺陷。3. 自动化评估体系的搭建与核心组件3.1 评估数据集怎么建才靠谱自动化评估的第一步是有一个靠谱的数据集。很多人一开始会想“我随便找几十个问题不就行了”但实际做下来会发现数据集的构建质量直接决定了评估结果的可信度。一个合格的评估数据集每条样本至少包含三个要素输入问题、参考答案、以及可选的上下文文档。输入问题要覆盖真实用户的各种问法不能全是标准句式。参考答案要准确不能有歧义。上下文文档如果标注了可以用来单独评估检索环节的召回质量。构建数据集的方式有几种。最直接的是从生产环境的追踪记录里挑。LangSmith支持把某条追踪记录直接添加到数据集这样你看到一条bad case一键就能把它变成评估样本。这种方式的好处是样本来自真实场景分布和线上一致。另一种方式是人工构造针对业务里的关键知识点设计一批问题。这种方式可以覆盖那些线上还没出现但你认为重要的场景。我自己的做法是两者结合。先从线上追踪里挑一批有代表性的case作为基础数据集然后再人工补充一些边界场景的问题。数据集不用一开始就很大二三十条就能跑出有参考价值的评估结果。关键是每条样本都要经过人工审核确保参考答案是正确的。如果参考答案本身就有问题那评估结果就是垃圾进垃圾出。还有一个细节容易被忽略数据集要版本化。你改了参考答案或者加了新样本应该记录变更。否则过一段时间回头看评估结果你都不知道当时用的是哪个版本的数据集。LangSmith的数据集支持添加示例和版本管理建议每次修改都打个标记。3.2 评估器的类型与选择策略评估器是自动化评估的核心组件它决定了你怎么判断一个回答是好是坏。LangSmith支持几种类型的评估器各有适用场景。第一种是基于规则的评估器。比如精确匹配、包含匹配、正则匹配。这类评估器适合那些有明确正确答案的场景比如分类任务、抽取任务。优点是快、便宜、结果确定缺点是对自然语言生成的回答不友好因为同一个意思可以有多种表达方式。第二种是基于嵌入的评估器。把模型回答和参考答案都转成向量算余弦相似度。这种方式比精确匹配宽松一些能捕捉语义层面的相似性。但它的局限在于语义相似不等于事实正确。两句话可能说的是相反的意思但嵌入向量却很接近。第三种是基于大模型的评估器。这是目前最常用的方式让一个评判模型来判断回答的质量。可以设计不同的评判维度比如准确性、完整性、相关性、流畅度。LangSmith内置了一些常用的评估提示词模板你也可以自定义。这种方式灵活度高能处理复杂的评判逻辑但成本和延迟也更高而且评判模型本身可能有偏见。第四种是自定义评估器。你可以写Python函数实现任意的评估逻辑。比如检查回答里是否包含了引用来源、是否违反了某些业务规则、是否在特定格式要求下正确输出。这种方式最灵活但需要自己处理各种边界情况。选择评估器的时候我的经验是不要只用一种。对于RAG场景至少要用两个维度来评估一个是检索质量看召回的文档是否包含正确答案另一个是生成质量看最终回答是否准确、完整。检索质量可以用基于规则的评估器判断参考答案里的关键信息是否出现在召回文档中。生成质量用大模型评估器从准确性和完整性两个维度打分。3.3 评估流程的自动化编排有了数据集和评估器之后需要把它们串成一个可重复执行的流程。LangSmith的评估流程大致是这样的指定数据集和评估器平台会自动对数据集里的每条样本跑一遍你的应用然后用评估器给每个输出打分最后汇总成统计报告。这个流程可以手动触发也可以通过API集成到CI/CD流水线里。我建议至少做到每次修改提示词或更换模型后自动跑一轮评估。如果评估分数下降超过阈值就阻断发布。这样能有效防止“改了一个地方、坏了一个地方”的情况。评估报告里要关注的指标有几个。一个是平均分反映整体质量水平。另一个是分数分布看有多少条样本得了低分。平均分高但有几条极低分说明存在长尾问题需要针对性排查。还有一个是与上一轮的对比看哪些样本的分数变化了。如果某个样本之前得分高、现在得分低说明你的改动可能引入了回归。我在实际使用中发现评估流程的自动化程度越高迭代速度越快。最开始我手动跑评估一轮下来要半小时后来集成到CI里每次提交代码自动跑几分钟就能看到结果。这个效率差异直接影响了迭代频率。4. 从追踪到评估的完整实操链路4.1 环境配置与SDK接入先把基础环境搭起来。LangSmith的使用需要API Key在平台上注册后可以获取。拿到Key之后设置几个环境变量export LANGCHAIN_TRACING_V2true export LANGCHAIN_API_KEYyour_api_key_here export LANGCHAIN_PROJECTyour_project_name如果你用的是LangChain框架这三行配置加完之后所有LangChain组件的调用都会自动上报追踪数据。LANGCHAIN_PROJECT用来区分不同项目的追踪记录建议按业务模块命名比如rag-qa-prod、rag-qa-staging。如果你没用LangChain需要手动初始化客户端from langsmith import Client client Client(api_keyyour_api_key_here)然后在你自己的代码里用traceable装饰器或者run上下文管理器来记录关键步骤。比如from langsmith import traceable traceable(run_typeretriever) def retrieve_documents(query: str): # 你的检索逻辑 docs vector_store.search(query, top_k5) return docs这个装饰器会自动记录函数的输入输出和耗时。run_type参数告诉平台这个节点是什么类型方便后续在平台上筛选和展示。注意环境变量里的API Key不要硬编码在代码里用密钥管理工具或者环境变量注入。追踪数据里可能包含用户输入和模型输出如果涉及敏感信息要在上报前做脱敏处理。4.2 追踪数据的查看与问题定位实操配置好之后跑几次请求然后到LangSmith的平台上查看追踪记录。平台会按项目分组展示每次请求的调用树。点击某条记录可以看到完整的链路视图。我通常按以下步骤排查一条追踪记录。先看根节点的总耗时和状态如果状态是error直接看错误信息。如果状态正常但耗时很长展开调用树看哪个子节点耗时最长。然后逐个节点检查输入输出。检索节点重点看召回的文档列表判断是否包含正确答案。生成节点重点看提示词和模型输出判断提示词是否合理、输出是否准确。平台上有一个很实用的功能是“添加到数据集”。当你发现一条典型的bad case可以直接把它加到评估数据集里后续跑评估的时候就会覆盖这个场景。这个动作把“发现问题”和“建立回归测试”连在了一起非常高效。还有一个功能是“对比视图”。你可以选两条追踪记录并排对比看它们的链路差异。比如你想对比两个不同提示词的效果就可以各跑一次然后并排看生成节点的输入输出差异。这个功能在调试提示词的时候特别好用。4.3 构建评估数据集的具体步骤从追踪记录构建数据集操作路径是这样的在追踪列表里选中一条或多条记录点击“添加到数据集”选择目标数据集或新建一个。平台会自动把这条记录的输入作为样本的输入输出作为样本的输出。但这时候参考答案还是空的需要你手动填写。我一般会批量挑一批追踪记录先加到数据集里然后逐条审核和填写参考答案。审核的时候重点关注两类样本一类是模型回答错误的这类样本能暴露系统的薄弱环节另一类是模型回答正确但检索过程有问题的这类样本能帮你发现潜在的隐患。除了从追踪记录导入也可以手动创建样本。在数据集页面点击“添加示例”手动填写输入、输出和参考答案。这种方式适合构造那些线上还没出现但你认为重要的测试场景。数据集建好之后建议先跑一轮基线评估。不做任何优化看看当前系统的得分是多少。这个基线分数是后续所有对比的参照点。4.4 配置评估器与跑通第一轮评估配置评估器的过程本质上是在定义“什么叫做好”。对于RAG场景我建议至少配置两个评估器。第一个是检索相关性评估器。用大模型来判断召回的文档是否与问题相关。提示词可以这样设计from langchain.smith import RunEvalConfig from langchain.evaluation import EvaluatorType eval_config RunEvalConfig( evaluators[ RunEvalConfig.LabeledCriteria(relevance), RunEvalConfig.LabeledCriteria(correctness), ], )relevance评估回答是否与问题相关correctness评估回答是否与参考答案一致。这两个维度能覆盖大部分质量问题。第二个是自定义评估器。比如检查回答里是否包含了引用来源。这个可以用规则来实现def check_citation(run, example): output run.outputs.get(output, ) has_citation [ in output and ] in output return {citation_score: 1 if has_citation else 0}把这个函数注册为评估器平台会在每轮评估中自动调用它。配置好评估器之后在平台上选择数据集和评估器点击“运行评估”。平台会自动对数据集里的每条样本跑一遍你的应用然后逐个打分。跑完之后会生成一份报告包含每个评估器的平均分、分数分布、以及每条样本的详细评分。第一轮评估跑完你可能会发现一些意料之外的低分样本。这时候回到追踪记录里找到对应的请求用前面说的排查方法定位问题。修复之后再跑一轮评估看分数有没有提升。这个“评估-定位-修复-再评估”的循环就是自动化评估的核心工作流。5. 常见问题与排查技巧实录5.1 追踪数据不完整或丢失怎么办这是最常见的问题之一。表现是平台上只能看到部分节点的追踪记录或者某些节点的输入输出是空的。原因通常有几个。第一个可能是SDK版本不兼容。LangChain和LangSmith的SDK版本需要匹配如果版本差距太大回调机制可能失效。解决办法是升级到最新稳定版或者查阅官方文档确认版本兼容性。第二个可能是异步调用没有正确等待。如果你的代码里用了异步请求但没有await追踪数据可能在请求完成前就被截断了。检查所有异步调用的地方确保正确等待。第三个可能是环境变量没生效。有时候在本地终端设置了环境变量但IDE或者容器里没有继承。建议在代码启动时打印一下相关环境变量确认配置正确。第四个可能是网络问题导致上报失败。追踪数据是异步上报的如果网络不稳定可能丢数据。LangSmith的SDK有重试机制但如果持续失败需要检查网络连通性。排查技巧在代码里加一行日志打印LangSmith客户端的初始化状态。如果客户端初始化失败后续所有追踪都不会上报。5.2 评估分数波动大怎么处理评估分数波动大通常说明评估流程本身不够稳定。可能的原因有这几个。一是评估器的提示词不够明确。大模型评估器对提示词很敏感如果提示词里没有清晰定义评分标准模型每次打分可能不一致。解决办法是把评分标准写得更具体比如“回答完全正确得5分部分正确得3分错误得1分”并给出每个分数段的示例。二是数据集里的样本质量参差不齐。如果参考答案本身有歧义评估器就很难给出稳定的分数。建议对数据集做一轮清洗把有问题的样本删掉或修正。三是被评估的应用本身有随机性。大模型生成有温度参数同样的输入可能产生不同的输出。如果温度设得比较高输出波动大评估分数自然也会波动。评估的时候可以把温度调低减少随机性。四是样本量太小。如果数据集只有十几条样本一两条样本的分数变化就会显著影响平均分。建议数据集至少三十条起步有条件的话做到上百条。5.3 评估成本太高怎么优化大模型评估器的成本确实不低尤其是数据集大的时候。优化思路有几个。第一分级评估。先用便宜的规则评估器做初筛只有通过初筛的样本才用大模型评估器。比如先用包含匹配检查回答里是否有关键词如果没有直接判低分不用再调大模型。第二采样评估。不需要每次都对全量数据集跑评估可以随机采样一部分。比如数据集有一百条每次随机抽三十条跑评估。这样能在控制成本的同时保持一定的统计显著性。第三缓存评估结果。如果某条样本的输入输出没有变化评估结果可以复用。LangSmith支持缓存机制避免重复评估相同的样本。第四用更小的模型做评估。评估任务通常比生成任务简单不需要用最大的模型。用中等规模的模型做评估成本能降不少效果差距可能不大。5.4 常见问题速查表问题现象可能原因排查方向解决建议追踪记录缺失SDK版本不兼容检查LangChain和LangSmith版本升级到兼容版本追踪记录缺失异步调用未等待检查代码中的async/await确保所有异步调用正确等待追踪记录缺失环境变量未生效打印环境变量确认在代码启动时显式设置评估分数波动大评估器提示词模糊检查评分标准是否明确细化评分标准并给出示例评估分数波动大数据集质量差人工审核参考答案清洗数据集修正错误样本评估分数波动大生成温度过高检查模型温度参数评估时降低温度评估成本高全量评估开销大统计每次评估的token消耗采用分级评估或采样评估评估成本高重复评估相同样本检查是否有缓存机制启用缓存避免重复计算5.5 几个我踩过的坑第一个坑是数据集泄露。有一次我把生产环境的追踪记录直接导入数据集结果里面包含了用户的真实问题。后来意识到这些数据可能涉及隐私赶紧做了脱敏处理。建议在导入追踪记录之前先检查一下是否包含敏感信息。第二个坑是评估器过拟合。我一开始针对某个特定场景调了一版评估提示词在这个场景上评估分数很高但换到其他场景就不准了。后来明白评估器也要有泛化能力不能针对个别样本过度调优。建议评估器的提示词要通用不要针对特定样本做特殊处理。第三个坑是忽略检索环节的评估。最开始我只评估最终回答的质量后来发现有些问题出在检索环节但最终回答碰巧对了掩盖了检索的缺陷。建议单独评估检索质量把检索和生成分开看。第四个坑是评估频率太低。有段时间我一个月才跑一次评估结果中间改了好几个地方出了问题都不知道是哪个改动引入的。后来改成每次提交代码都跑评估问题定位快了很多。6. 把追踪和评估串成日常迭代习惯工具再好如果不成体系地用效果也有限。我现在的做法是每次要改提示词或者换模型之前先跑一轮基线评估记录当前分数。改完之后再跑一轮对比分数变化。如果分数下降就回滚或者继续调。如果分数上升就把这次改动合并到主分支。追踪数据在日常调试中的用法是每次发现bad case先看追踪记录定位问题环节修复之后把这条case加到数据集里。这样数据集会随着时间越来越丰富覆盖的场景越来越全。评估的置信度也会越来越高。还有一个小技巧是给追踪记录打标签。LangSmith支持给追踪记录添加标签我习惯用标签标记问题的类型比如retrieval-failure、hallucination、format-error。这样后续分析的时候可以按标签聚合看哪类问题出现频率最高优先解决。这套流程跑顺之后RAG应用的迭代会变得很有节奏感。不再是“改一改、试一试、感觉好像好了”而是“评估分数从0.72提升到0.81主要提升在准确性维度”。这种数据驱动的迭代方式比凭感觉调参靠谱得多。最后分享一个我在实际使用中的体会链路追踪和自动化评估不是两个独立的功能而是一个闭环的两端。追踪帮你发现问题评估帮你验证修复。把这两端连起来迭代效率会有质的提升。我刚开始用的时候只用了追踪功能觉得已经很有用了。后来把评估也接上才发现真正的价值在于“可重复验证”。每次改动都有数据支撑心里踏实很多。 
长河君 · 2026/10/12 19:22:44 · 阅读 1.2k RAG应用链路追踪与自动化评估：LangSmith实战指南
1. 为什么链路追踪和自动化评估值得放在一起聊做过RAG应用的人大概都有过这种体验上线前觉得检索增强生成这套东西逻辑挺清晰无非就是“查资料、拼上下文、调模型”三步走可一旦真实用户开始用问题就全冒出来了。用户问“上季度那个项目的交付节点是什么时候”系统检索回来一堆不相关的会议纪要用户追问“那它的负责人是谁”模型直接开始编。你盯着日志看半天只能看到最终输出不对但到底是检索环节没召回、还是重排环节把正确文档排到了后面、还是提示词把模型带偏了根本无从判断。这就是链路追踪要解决的核心问题——把一次请求从入口到出口的每一个环节都拆开、记录下来让你能像看慢动作回放一样定位到具体是哪一步出了问题。而自动化评估解决的是另一个维度的问题你不可能每次改完提示词或换完嵌入模型都靠人工一条条去测。你需要一套可重复、可量化、可对比的评估流程让每次迭代都有数据支撑而不是凭感觉说“好像好了一点”。LangSmith这个平台恰好把这两件事串在了一起。它提供的不只是“看日志”的能力而是从追踪数据采集、到数据集构建、再到自动化评估跑分的完整闭环。我最初接触它的时候以为就是个可视化调试工具用了一段时间才发现真正有价值的是它把“发现问题”和“验证修复”这两个动作之间的链路缩短了——你在追踪面板里看到一条bad case可以直接把它加到评估数据集里然后跑一轮评估看看改动有没有引入回归。这个工作流一旦跑顺迭代效率的提升是肉眼可见的。这篇文章适合两类人看一类是已经在做RAG应用、但调试基本靠猜的开发者另一类是想建立系统化评估流程、但不知道从哪下手的技术负责人。我会从整体设计思路讲到具体实操把链路追踪的数据结构、评估器的配置方法、以及我在实际使用中踩过的坑都摊开来说。文章里涉及的工具和平台都是通用的技术方案不涉及任何特定机构或项目背景。2. 链路追踪的底层逻辑与数据模型拆解2.1 一次RAG请求到底经历了什么要理解链路追踪的价值得先搞清楚一次RAG请求在系统内部到底走了哪些路。很多人脑子里对RAG的印象就是“检索生成”两个步骤但实际生产环境里的链路远比这个复杂。我画不出图但可以用文字把典型链路拆一遍。用户输入一个问题后系统通常先做查询改写——把口语化的提问转成更适合检索的形式比如把“那个新功能啥时候能上”改写成“新功能发布时间计划”。这一步可能用一个小模型来做也可能用规则模板。改写完之后进入检索阶段检索本身又分好几层向量检索召回一批候选文档关键词检索再召回一批两路结果做融合。融合之后可能还有一个重排模型对候选文档做精细排序取Top-K个最相关的。拿到检索结果后系统要把这些文档片段和原始问题拼成一个完整的提示词。这个拼接过程涉及模板填充、上下文长度截断、可能还有格式转换。最后才是调用大模型生成回答。生成完之后可能还有后处理比如引用标注、敏感词过滤、格式校验。这一整条链路上任何一个环节出问题都会导致最终输出质量下降。但如果你只看最终输出根本不知道问题出在哪。链路追踪要做的就是给每个环节打上标记记录输入输出、耗时、token消耗、以及自定义的元数据。LangSmith的追踪数据结构就是围绕这个需求设计的它把一次请求建模成一棵调用树根节点是整条链路子节点是各个步骤每个节点都有独立的输入输出和运行信息。2.2 追踪数据的核心字段与采集方式LangSmith的追踪数据模型里有几个字段是必须关注的。第一个是run_type它标记了这个节点是什么类型的操作比如llm表示大模型调用、retriever表示检索、chain表示组合链路、tool表示工具调用。这个字段决定了平台怎么解析和展示这个节点的数据。第二个是inputs和outputs分别记录节点的输入和输出。对于检索节点输入是查询语句输出是召回的文档列表对于大模型节点输入是完整的提示词输出是模型返回的文本。这些数据是后续做评估的基础因为评估器需要拿到这些中间结果才能判断每一步的质量。第三个是extra字段可以塞自定义的元数据。我习惯在这里放一些业务相关的标记比如用户ID、会话ID、实验分组。这样后续在平台上筛选和分析的时候可以按这些维度做聚合。比如你想对比A/B两组不同提示词的效果就可以在extra里标记分组然后在平台上按分组过滤追踪记录。采集方式上LangSmith提供了SDK级别的集成。如果你用的是LangChain框架基本上加几行环境变量配置就能自动采集因为LangChain的每个组件都内置了回调机制。如果你没用LangChain也可以手动埋点在关键步骤前后调用SDK的API记录输入输出。手动埋点的好处是灵活可以精确控制记录哪些数据坏处是工作量大容易漏掉环节。我的建议是如果项目已经用了LangChain就直接用自动采集如果是自研框架至少要在检索和生成这两个核心环节做手动埋点。2.3 追踪数据怎么帮你定位问题有了追踪数据之后定位问题的思路就清晰了。假设用户反馈“回答不准确”你可以按以下顺序排查。先看检索节点的输出。如果召回的文档里根本没有包含正确答案的片段那问题出在检索环节。这时候你要进一步看查询改写的结果——是不是改写后的查询偏离了原意还是嵌入模型对这类问题的语义匹配能力不足或者是向量库里的文档本身就没有覆盖这个知识点如果检索结果里有正确文档但最终回答还是错的那就看生成节点。检查提示词里是否正确地把检索到的文档拼进去了有没有因为上下文长度限制被截断。再看模型的输出是不是忽略了文档内容、开始自由发挥。有时候模型会“过度自信”明明文档里写的是A它非要回答B这时候可能需要调整提示词里的约束条件。还有一种情况是检索和生成都没明显问题但整体体验就是不好。这时候要看耗时数据。如果检索花了3秒、生成花了8秒用户等十几秒才看到回答体验肯定差。追踪数据里的耗时字段可以帮你找到性能瓶颈在哪个环节。我在实际使用中养成了一个习惯每次上线新版本之前先跑一批测试问题把追踪记录逐条过一遍。重点看那些“检索到了正确文档但生成错误”的case这类问题往往最隐蔽因为表面上看检索没问题容易忽略生成环节的提示词设计缺陷。3. 自动化评估体系的搭建与核心组件3.1 评估数据集怎么建才靠谱自动化评估的第一步是有一个靠谱的数据集。很多人一开始会想“我随便找几十个问题不就行了”但实际做下来会发现数据集的构建质量直接决定了评估结果的可信度。一个合格的评估数据集每条样本至少包含三个要素输入问题、参考答案、以及可选的上下文文档。输入问题要覆盖真实用户的各种问法不能全是标准句式。参考答案要准确不能有歧义。上下文文档如果标注了可以用来单独评估检索环节的召回质量。构建数据集的方式有几种。最直接的是从生产环境的追踪记录里挑。LangSmith支持把某条追踪记录直接添加到数据集这样你看到一条bad case一键就能把它变成评估样本。这种方式的好处是样本来自真实场景分布和线上一致。另一种方式是人工构造针对业务里的关键知识点设计一批问题。这种方式可以覆盖那些线上还没出现但你认为重要的场景。我自己的做法是两者结合。先从线上追踪里挑一批有代表性的case作为基础数据集然后再人工补充一些边界场景的问题。数据集不用一开始就很大二三十条就能跑出有参考价值的评估结果。关键是每条样本都要经过人工审核确保参考答案是正确的。如果参考答案本身就有问题那评估结果就是垃圾进垃圾出。还有一个细节容易被忽略数据集要版本化。你改了参考答案或者加了新样本应该记录变更。否则过一段时间回头看评估结果你都不知道当时用的是哪个版本的数据集。LangSmith的数据集支持添加示例和版本管理建议每次修改都打个标记。3.2 评估器的类型与选择策略评估器是自动化评估的核心组件它决定了你怎么判断一个回答是好是坏。LangSmith支持几种类型的评估器各有适用场景。第一种是基于规则的评估器。比如精确匹配、包含匹配、正则匹配。这类评估器适合那些有明确正确答案的场景比如分类任务、抽取任务。优点是快、便宜、结果确定缺点是对自然语言生成的回答不友好因为同一个意思可以有多种表达方式。第二种是基于嵌入的评估器。把模型回答和参考答案都转成向量算余弦相似度。这种方式比精确匹配宽松一些能捕捉语义层面的相似性。但它的局限在于语义相似不等于事实正确。两句话可能说的是相反的意思但嵌入向量却很接近。第三种是基于大模型的评估器。这是目前最常用的方式让一个评判模型来判断回答的质量。可以设计不同的评判维度比如准确性、完整性、相关性、流畅度。LangSmith内置了一些常用的评估提示词模板你也可以自定义。这种方式灵活度高能处理复杂的评判逻辑但成本和延迟也更高而且评判模型本身可能有偏见。第四种是自定义评估器。你可以写Python函数实现任意的评估逻辑。比如检查回答里是否包含了引用来源、是否违反了某些业务规则、是否在特定格式要求下正确输出。这种方式最灵活但需要自己处理各种边界情况。选择评估器的时候我的经验是不要只用一种。对于RAG场景至少要用两个维度来评估一个是检索质量看召回的文档是否包含正确答案另一个是生成质量看最终回答是否准确、完整。检索质量可以用基于规则的评估器判断参考答案里的关键信息是否出现在召回文档中。生成质量用大模型评估器从准确性和完整性两个维度打分。3.3 评估流程的自动化编排有了数据集和评估器之后需要把它们串成一个可重复执行的流程。LangSmith的评估流程大致是这样的指定数据集和评估器平台会自动对数据集里的每条样本跑一遍你的应用然后用评估器给每个输出打分最后汇总成统计报告。这个流程可以手动触发也可以通过API集成到CI/CD流水线里。我建议至少做到每次修改提示词或更换模型后自动跑一轮评估。如果评估分数下降超过阈值就阻断发布。这样能有效防止“改了一个地方、坏了一个地方”的情况。评估报告里要关注的指标有几个。一个是平均分反映整体质量水平。另一个是分数分布看有多少条样本得了低分。平均分高但有几条极低分说明存在长尾问题需要针对性排查。还有一个是与上一轮的对比看哪些样本的分数变化了。如果某个样本之前得分高、现在得分低说明你的改动可能引入了回归。我在实际使用中发现评估流程的自动化程度越高迭代速度越快。最开始我手动跑评估一轮下来要半小时后来集成到CI里每次提交代码自动跑几分钟就能看到结果。这个效率差异直接影响了迭代频率。4. 从追踪到评估的完整实操链路4.1 环境配置与SDK接入先把基础环境搭起来。LangSmith的使用需要API Key在平台上注册后可以获取。拿到Key之后设置几个环境变量export LANGCHAIN_TRACING_V2true export LANGCHAIN_API_KEYyour_api_key_here export LANGCHAIN_PROJECTyour_project_name如果你用的是LangChain框架这三行配置加完之后所有LangChain组件的调用都会自动上报追踪数据。LANGCHAIN_PROJECT用来区分不同项目的追踪记录建议按业务模块命名比如rag-qa-prod、rag-qa-staging。如果你没用LangChain需要手动初始化客户端from langsmith import Client client Client(api_keyyour_api_key_here)然后在你自己的代码里用traceable装饰器或者run上下文管理器来记录关键步骤。比如from langsmith import traceable traceable(run_typeretriever) def retrieve_documents(query: str): # 你的检索逻辑 docs vector_store.search(query, top_k5) return docs这个装饰器会自动记录函数的输入输出和耗时。run_type参数告诉平台这个节点是什么类型方便后续在平台上筛选和展示。注意环境变量里的API Key不要硬编码在代码里用密钥管理工具或者环境变量注入。追踪数据里可能包含用户输入和模型输出如果涉及敏感信息要在上报前做脱敏处理。4.2 追踪数据的查看与问题定位实操配置好之后跑几次请求然后到LangSmith的平台上查看追踪记录。平台会按项目分组展示每次请求的调用树。点击某条记录可以看到完整的链路视图。我通常按以下步骤排查一条追踪记录。先看根节点的总耗时和状态如果状态是error直接看错误信息。如果状态正常但耗时很长展开调用树看哪个子节点耗时最长。然后逐个节点检查输入输出。检索节点重点看召回的文档列表判断是否包含正确答案。生成节点重点看提示词和模型输出判断提示词是否合理、输出是否准确。平台上有一个很实用的功能是“添加到数据集”。当你发现一条典型的bad case可以直接把它加到评估数据集里后续跑评估的时候就会覆盖这个场景。这个动作把“发现问题”和“建立回归测试”连在了一起非常高效。还有一个功能是“对比视图”。你可以选两条追踪记录并排对比看它们的链路差异。比如你想对比两个不同提示词的效果就可以各跑一次然后并排看生成节点的输入输出差异。这个功能在调试提示词的时候特别好用。4.3 构建评估数据集的具体步骤从追踪记录构建数据集操作路径是这样的在追踪列表里选中一条或多条记录点击“添加到数据集”选择目标数据集或新建一个。平台会自动把这条记录的输入作为样本的输入输出作为样本的输出。但这时候参考答案还是空的需要你手动填写。我一般会批量挑一批追踪记录先加到数据集里然后逐条审核和填写参考答案。审核的时候重点关注两类样本一类是模型回答错误的这类样本能暴露系统的薄弱环节另一类是模型回答正确但检索过程有问题的这类样本能帮你发现潜在的隐患。除了从追踪记录导入也可以手动创建样本。在数据集页面点击“添加示例”手动填写输入、输出和参考答案。这种方式适合构造那些线上还没出现但你认为重要的测试场景。数据集建好之后建议先跑一轮基线评估。不做任何优化看看当前系统的得分是多少。这个基线分数是后续所有对比的参照点。4.4 配置评估器与跑通第一轮评估配置评估器的过程本质上是在定义“什么叫做好”。对于RAG场景我建议至少配置两个评估器。第一个是检索相关性评估器。用大模型来判断召回的文档是否与问题相关。提示词可以这样设计from langchain.smith import RunEvalConfig from langchain.evaluation import EvaluatorType eval_config RunEvalConfig( evaluators[ RunEvalConfig.LabeledCriteria(relevance), RunEvalConfig.LabeledCriteria(correctness), ], )relevance评估回答是否与问题相关correctness评估回答是否与参考答案一致。这两个维度能覆盖大部分质量问题。第二个是自定义评估器。比如检查回答里是否包含了引用来源。这个可以用规则来实现def check_citation(run, example): output run.outputs.get(output, ) has_citation [ in output and ] in output return {citation_score: 1 if has_citation else 0}把这个函数注册为评估器平台会在每轮评估中自动调用它。配置好评估器之后在平台上选择数据集和评估器点击“运行评估”。平台会自动对数据集里的每条样本跑一遍你的应用然后逐个打分。跑完之后会生成一份报告包含每个评估器的平均分、分数分布、以及每条样本的详细评分。第一轮评估跑完你可能会发现一些意料之外的低分样本。这时候回到追踪记录里找到对应的请求用前面说的排查方法定位问题。修复之后再跑一轮评估看分数有没有提升。这个“评估-定位-修复-再评估”的循环就是自动化评估的核心工作流。5. 常见问题与排查技巧实录5.1 追踪数据不完整或丢失怎么办这是最常见的问题之一。表现是平台上只能看到部分节点的追踪记录或者某些节点的输入输出是空的。原因通常有几个。第一个可能是SDK版本不兼容。LangChain和LangSmith的SDK版本需要匹配如果版本差距太大回调机制可能失效。解决办法是升级到最新稳定版或者查阅官方文档确认版本兼容性。第二个可能是异步调用没有正确等待。如果你的代码里用了异步请求但没有await追踪数据可能在请求完成前就被截断了。检查所有异步调用的地方确保正确等待。第三个可能是环境变量没生效。有时候在本地终端设置了环境变量但IDE或者容器里没有继承。建议在代码启动时打印一下相关环境变量确认配置正确。第四个可能是网络问题导致上报失败。追踪数据是异步上报的如果网络不稳定可能丢数据。LangSmith的SDK有重试机制但如果持续失败需要检查网络连通性。排查技巧在代码里加一行日志打印LangSmith客户端的初始化状态。如果客户端初始化失败后续所有追踪都不会上报。5.2 评估分数波动大怎么处理评估分数波动大通常说明评估流程本身不够稳定。可能的原因有这几个。一是评估器的提示词不够明确。大模型评估器对提示词很敏感如果提示词里没有清晰定义评分标准模型每次打分可能不一致。解决办法是把评分标准写得更具体比如“回答完全正确得5分部分正确得3分错误得1分”并给出每个分数段的示例。二是数据集里的样本质量参差不齐。如果参考答案本身有歧义评估器就很难给出稳定的分数。建议对数据集做一轮清洗把有问题的样本删掉或修正。三是被评估的应用本身有随机性。大模型生成有温度参数同样的输入可能产生不同的输出。如果温度设得比较高输出波动大评估分数自然也会波动。评估的时候可以把温度调低减少随机性。四是样本量太小。如果数据集只有十几条样本一两条样本的分数变化就会显著影响平均分。建议数据集至少三十条起步有条件的话做到上百条。5.3 评估成本太高怎么优化大模型评估器的成本确实不低尤其是数据集大的时候。优化思路有几个。第一分级评估。先用便宜的规则评估器做初筛只有通过初筛的样本才用大模型评估器。比如先用包含匹配检查回答里是否有关键词如果没有直接判低分不用再调大模型。第二采样评估。不需要每次都对全量数据集跑评估可以随机采样一部分。比如数据集有一百条每次随机抽三十条跑评估。这样能在控制成本的同时保持一定的统计显著性。第三缓存评估结果。如果某条样本的输入输出没有变化评估结果可以复用。LangSmith支持缓存机制避免重复评估相同的样本。第四用更小的模型做评估。评估任务通常比生成任务简单不需要用最大的模型。用中等规模的模型做评估成本能降不少效果差距可能不大。5.4 常见问题速查表问题现象可能原因排查方向解决建议追踪记录缺失SDK版本不兼容检查LangChain和LangSmith版本升级到兼容版本追踪记录缺失异步调用未等待检查代码中的async/await确保所有异步调用正确等待追踪记录缺失环境变量未生效打印环境变量确认在代码启动时显式设置评估分数波动大评估器提示词模糊检查评分标准是否明确细化评分标准并给出示例评估分数波动大数据集质量差人工审核参考答案清洗数据集修正错误样本评估分数波动大生成温度过高检查模型温度参数评估时降低温度评估成本高全量评估开销大统计每次评估的token消耗采用分级评估或采样评估评估成本高重复评估相同样本检查是否有缓存机制启用缓存避免重复计算5.5 几个我踩过的坑第一个坑是数据集泄露。有一次我把生产环境的追踪记录直接导入数据集结果里面包含了用户的真实问题。后来意识到这些数据可能涉及隐私赶紧做了脱敏处理。建议在导入追踪记录之前先检查一下是否包含敏感信息。第二个坑是评估器过拟合。我一开始针对某个特定场景调了一版评估提示词在这个场景上评估分数很高但换到其他场景就不准了。后来明白评估器也要有泛化能力不能针对个别样本过度调优。建议评估器的提示词要通用不要针对特定样本做特殊处理。第三个坑是忽略检索环节的评估。最开始我只评估最终回答的质量后来发现有些问题出在检索环节但最终回答碰巧对了掩盖了检索的缺陷。建议单独评估检索质量把检索和生成分开看。第四个坑是评估频率太低。有段时间我一个月才跑一次评估结果中间改了好几个地方出了问题都不知道是哪个改动引入的。后来改成每次提交代码都跑评估问题定位快了很多。6. 把追踪和评估串成日常迭代习惯工具再好如果不成体系地用效果也有限。我现在的做法是每次要改提示词或者换模型之前先跑一轮基线评估记录当前分数。改完之后再跑一轮对比分数变化。如果分数下降就回滚或者继续调。如果分数上升就把这次改动合并到主分支。追踪数据在日常调试中的用法是每次发现bad case先看追踪记录定位问题环节修复之后把这条case加到数据集里。这样数据集会随着时间越来越丰富覆盖的场景越来越全。评估的置信度也会越来越高。还有一个小技巧是给追踪记录打标签。LangSmith支持给追踪记录添加标签我习惯用标签标记问题的类型比如retrieval-failure、hallucination、format-error。这样后续分析的时候可以按标签聚合看哪类问题出现频率最高优先解决。这套流程跑顺之后RAG应用的迭代会变得很有节奏感。不再是“改一改、试一试、感觉好像好了”而是“评估分数从0.72提升到0.81主要提升在准确性维度”。这种数据驱动的迭代方式比凭感觉调参靠谱得多。最后分享一个我在实际使用中的体会链路追踪和自动化评估不是两个独立的功能而是一个闭环的两端。追踪帮你发现问题评估帮你验证修复。把这两端连起来迭代效率会有质的提升。我刚开始用的时候只用了追踪功能觉得已经很有用了。后来把评估也接上才发现真正的价值在于“可重复验证”。每次改动都有数据支撑心里踏实很多。