LangSmith 全链路 Trace 记录方案

一、LangSmith 全链路 Trace 记录方案LangSmith 可以完整记录 RAG/Agent 应用每一次调用的模型参数、工具执行、检索结果、Token 消耗与完整执行链路形成可追溯的 Trace 树核心分为基础接入和分环节精细化埋点两层。1. 基础追踪接入LangSmith 支持两种接入模式覆盖不同技术栈场景LangChain/LangGraph 生态零代码自动追踪仅通过环境变量配置即可开启全链路自动追踪无需修改业务代码importos os.environ[LANGSMITH_TRACING]true# 新版标准配置向下兼容旧版 LANGCHAIN_TRACING_V2os.environ[LANGSMITH_API_KEY]你的 API 密钥os.environ[LANGSMITH_PROJECT]rag-test-project# 按项目分组管理 Trace配置完成后所有 LangChain 封装的模型、工具、检索器调用会自动生成层级化 Trace完整展示执行顺序与依赖关系。非 LangChain 应用装饰器手动埋点原生 LLM SDK、自定义检索逻辑可通过traceable装饰器标注自主控制追踪粒度fromlangsmithimporttraceable2. 模型调用完整追踪要完整记录模型名称、提供商、调用参数、Token 消耗需满足 4 项配置要求指定run_typellm让 LangSmith 按 LLM 调用格式渲染页面并做成本统计输入输出采用 OpenAI/Anthropic/LangChain 标准消息格式支持 Playground 一键复现调用在metadata中传入ls_provider模型厂商和ls_model_name具体模型名称在输出中返回usage_metadata字段包含input_tokens、output_tokens、total_tokens支持缓存命中、工具调用等细分 Token 统计基于 LangChain 官方封装的模型如 ChatOpenAI、ChatAnthropic会自动完成以上配置自定义模型封装需手动补充上述字段。3. 工具调用追踪工具执行的入参、返回结果、耗时、异常堆栈均可完整记录LangChain 体系内定义的 Tool 会自动被追踪自定义工具函数添加traceable(run_typetool, name工具名称)装饰器即可接入支持捕获工具执行异常与报错信息便于定位工具侧故障与逻辑错误4. 检索环节追踪RAG 的检索链路是核心观测点需单独埋点记录召回全细节将检索函数标记为run_typeretrieverLangSmith 会以专属格式渲染检索结果必须记录的核心字段用户查询 Query、召回文档 ID/内容片段、相似度得分、召回数量、检索耗时多层检索如粗召回精排可嵌套为子 Trace清晰展示每一层的处理结果与过滤逻辑5. Token 与成本自动统计在usage_metadata规范配置的前提下LangSmith 会自动汇总单次调用、整条链路的 Token 消耗并根据对应模型的单价计算预估成本。支持按项目、时间、模型维度聚合统计可用于测试阶段的成本预算与生产环境的成本管控。二、断言与评估体系Trace 是基础数据载体断言与评估是质量判定的核心手段LangSmith 支持「确定性断言 多维度评估器」的组合方案覆盖刚性校验与主观质量评估。1. 确定性断言机制断言是刚性的通过/不通过判定适合结构化、可量化的校验场景通常以代码形式实现实现逻辑在测试数据集的reference_outputs中预定义断言规则字段要求、关键词、正则模式、Schema 结构编写自定义评估器逐条校验返回 1.0通过/ 0.0不通过的二元评分。常见断言场景输出格式断言校验是否为合法 JSON、是否包含指定业务字段业务规则断言校验答案是否命中必填关键词、是否符合业务约束边界链路断言校验是否调用了正确的工具、是否触发了预期的检索逻辑2. 两类核心评估器1代码评估器确定性、零成本通过 Python 代码编写校验逻辑执行速度快、结果可复现适合客观指标校验。典型实现方式为继承RunEvaluator基类实现evaluate_run方法入参为当前运行实例与测试样例返回评分与评语。适用场景包括路由正确性判断、格式校验、检索召回数量校验、敏感词检测等。2LLM-as-Judge 评估器主观质量判定调用大模型作为裁判基于预设评分标准Rubric对输出质量打分适合语义类、主观类的质量评估。支持自定义评分维度与打分规则例如忠实度、相关性、完整性、幻觉检测可配置多维度同时打分一次性输出多个指标结果关键场景需配合人工抽检校准裁判模型降低打分偏差3. 两种评估执行模式离线评估批量回归基于 LangSmith Dataset 测试集批量运行被测应用自动执行所有评估器并生成实验报告。适合版本迭代前的回归测试、多策略 AB 效果对比。在线评估实时监控在生产 Trace 生成后自动触发评估器打分实时监控线上质量。适合核心链路的常态化监控、异常 Case 自动标记与告警。三、LangSmith 辅助 RAG 应用测试的具体方法与步骤RAG 测试核心覆盖「检索质量」和「生成质量」两大维度LangSmith 可实现从用例管理、执行测试、根因定位到回归验证的全流程闭环支撑快速迭代下的质量保障。1. 明确 RAG 测试核心维度测试启动前先定义可量化指标通常分为三层维度核心指标说明检索质量上下文准确率、上下文召回率衡量召回文档是否相关、是否覆盖答案所需的全部信息生成质量忠实度、答案相关性、答案完整性衡量答案是否基于检索内容、是否答非所问、是否完整回应问题全链路效果端到端正确率、幻觉率、平均响应时长、Token 成本衡量最终业务效果与性能成本表现2. 具体测试执行步骤步骤1构建标准化测试数据集测试集是 RAG 测试的基准需覆盖典型业务场景与边界 Case数据来源从真实用户提问、业务高频问题、历史 Bad Case 中采样确保数据贴合实际使用场景标注内容每个样例包含问题、参考答案、参考上下文三类核心字段平台导入在 LangSmith 平台创建 Dataset或通过代码批量上传支持按业务场景分组管理步骤2完成全链路 Trace 埋点按照前文方案对 RAG 完整链路进行埋点遵循一个核心原则测试调用链路必须与生产链路完全一致禁止为测试单独改造逻辑。需确保检索、重排、Prompt 组装、模型生成、后处理每个环节都有对应子 Trace且输入、输出、关键参数完整记录保证后续根因定位可追溯。步骤3配置评估器与评分规则根据测试维度配置对应评估器建议内置评估器与自定义评估器结合使用内置 RAG 评估器直接使用 LangSmith 集成的上下文准确率、上下文召回率、忠实度、答案相关性等标准指标业务自定义评估器针对业务专属规则编写代码评估器例如业务术语正确性、合规性校验LLM 裁判评估器定义业务专属评分 Rubric对答案的业务准确性、逻辑通顺度做综合打分步骤4执行批量测试生成对比实验通过evaluate接口执行全量测试生成独立的实验Experimentfromlangsmith.evaluationimportevaluate resultevaluate(your_rag_chain,# 被测 RAG 完整链路data你的测试集名称,# 对应 LangSmith Datasetevaluators[评估器列表],# 预先配置的所有评估器experiment_prefixrag-v2.0-test,# 实验名称前缀便于版本区分maxConcurrency3# 控制并发量避免压垮底层服务)支持同一测试集下运行多个实验横向对比不同 Prompt、不同检索策略、不同模型版本的效果差异平台自动生成指标对比看板直观展示版本间的指标升降幅度步骤5低分 Case 根因定位这是 LangSmith 测试的核心价值——从宏观指标直接下钻到微观执行链路在实验看板中按指标排序筛选得分低于阈值的 Bad Case点击单条用例查看完整 Trace 树逐层排查问题根因检索得分低排查召回文档是否不相关、TopK 设置是否合理、嵌入模型是否匹配检索正常但忠实度低排查 Prompt 指令是否清晰、模型是否容易产生幻觉格式/规则不符合预期排查后处理逻辑、断言规则是否准确标注问题类型沉淀到问题分类库便于后续统计高频问题步骤6优化验证与持续回归针对定位出的问题进行优化调整 Prompt、优化检索策略、更换模型等在同一测试集上重新运行实验对比优化前后的指标变化验证优化效果将新增的 Bad Case 补充进测试数据集逐步扩大测试覆盖范围将核心测试集纳入 CI/CD 流水线每次版本迭代自动执行回归测试防止质量退化