LangSmith 全链路 Trace 记录方案

一、LangSmith 全链路 Trace 记录方案

LangSmith 可以完整记录 RAG/Agent 应用每一次调用的模型参数、工具执行、检索结果、Token 消耗与完整执行链路，形成可追溯的 Trace 树，核心分为基础接入和分环节精细化埋点两层。

1. 基础追踪接入

LangSmith 支持两种接入模式，覆盖不同技术栈场景：

• LangChain/LangGraph 生态：零代码自动追踪
  仅通过环境变量配置即可开启全链路自动追踪，无需修改业务代码：

  import os
  os.environ["LANGSMITH_TRACING"] = "true" # 新版标准配置，向下兼容旧版 LANGCHAIN_TRACING_V2
  os.environ["LANGSMITH_API_KEY"] = "你的 API 密钥"
  os.environ["LANGSMITH_PROJECT"] = "rag-test-project" # 按项目分组管理 Trace

  配置完成后，所有 LangChain 封装的模型、工具、检索器调用会自动生成层级化 Trace，完整展示执行顺序与依赖关系。

• 非 LangChain 应用：装饰器手动埋点
  原生 LLM SDK、自定义检索逻辑可通过 @traceable 装饰器标注，自主控制追踪粒度：

  from langsmith import traceable

2. 模型调用完整追踪

要完整记录模型名称、提供商、调用参数、Token 消耗，需满足 4 项配置要求：

基于 LangChain 官方封装的模型（如 ChatOpenAI、ChatAnthropic）会自动完成以上配置；自定义模型封装需手动补充上述字段。

3. 工具调用追踪

工具执行的入参、返回结果、耗时、异常堆栈均可完整记录：

• LangChain 体系内定义的 Tool 会自动被追踪
• 自定义工具函数添加 @traceable(run_type="tool", name="工具名称") 装饰器即可接入
• 支持捕获工具执行异常与报错信息，便于定位工具侧故障与逻辑错误

4. 检索环节追踪

RAG 的检索链路是核心观测点，需单独埋点记录召回全细节：

• 将检索函数标记为 run_type="retriever"，LangSmith 会以专属格式渲染检索结果
• 必须记录的核心字段：用户查询 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 方法，入参为当前运行实例与测试样例，返回评分与评语。适用场景包括路由正确性判断、格式校验、检索召回数量校验、敏感词检测等。

（2）LLM-as-Judge 评估器（主观质量判定）

调用大模型作为裁判，基于预设评分标准（Rubric）对输出质量打分，适合语义类、主观类的质量评估。

• 支持自定义评分维度与打分规则，例如忠实度、相关性、完整性、幻觉检测
• 可配置多维度同时打分，一次性输出多个指标结果
• 关键场景需配合人工抽检校准裁判模型，降低打分偏差

3. 两种评估执行模式

• 离线评估（批量回归）：基于 LangSmith Dataset 测试集批量运行被测应用，自动执行所有评估器并生成实验报告。适合版本迭代前的回归测试、多策略 AB 效果对比。
• 在线评估（实时监控）：在生产 Trace 生成后自动触发评估器打分，实时监控线上质量。适合核心链路的常态化监控、异常 Case 自动标记与告警。

三、LangSmith 辅助 RAG 应用测试的具体方法与步骤

RAG 测试核心覆盖「检索质量」和「生成质量」两大维度，LangSmith 可实现从用例管理、执行测试、根因定位到回归验证的全流程闭环，支撑快速迭代下的质量保障。

1. 明确 RAG 测试核心维度

测试启动前先定义可量化指标，通常分为三层：

2. 具体测试执行步骤

步骤1：构建标准化测试数据集

测试集是 RAG 测试的基准，需覆盖典型业务场景与边界 Case：

步骤2：完成全链路 Trace 埋点

按照前文方案对 RAG 完整链路进行埋点，遵循一个核心原则：测试调用链路必须与生产链路完全一致，禁止为测试单独改造逻辑。
需确保检索、重排、Prompt 组装、模型生成、后处理每个环节都有对应子 Trace，且输入、输出、关键参数完整记录，保证后续根因定位可追溯。

步骤3：配置评估器与评分规则

根据测试维度配置对应评估器，建议内置评估器与自定义评估器结合使用：

步骤4：执行批量测试，生成对比实验

通过 evaluate 接口执行全量测试，生成独立的实验（Experiment）：

from langsmith.evaluation import evaluate

result = evaluate(
your_rag_chain, # 被测 RAG 完整链路
data="你的测试集名称", # 对应 LangSmith Dataset
evaluators=[评估器列表], # 预先配置的所有评估器
experiment_prefix="rag-v2.0-test", # 实验名称前缀，便于版本区分
maxConcurrency=3 # 控制并发量，避免压垮底层服务
)

• 支持同一测试集下运行多个实验，横向对比不同 Prompt、不同检索策略、不同模型版本的效果差异
• 平台自动生成指标对比看板，直观展示版本间的指标升降幅度

步骤5：低分 Case 根因定位

这是 LangSmith 测试的核心价值——从宏观指标直接下钻到微观执行链路：

步骤6：优化验证与持续回归