做过 LangGraph Agent 或 RAG 之后,很快就会遇到一个问题:
程序虽然能跑,但内部到底发生了什么?
一次请求经过了哪些节点?Retriever 返回了什么?模型真正收到的 Prompt 是什么?哪一步最慢?Token 消耗多少?某次异常究竟出在哪个 Run?
再往后还会遇到另一个问题:
这个 Agent 或 RAG 到底“好不好”?
靠人工随便问几个问题,只能得到主观感受。真正进入工程阶段之后,我们需要的是可观测、可回归、可量化。
LangSmith 主要解决的就是这两类问题。
本文默认你已经熟悉 LangChain、LangGraph 和 RAG,不再展开解释向量数据库、Embedding 或 Graph 编排,而是直接以一个现成的 RAG Agent 为对象,学习 LangSmith 的几个核心能力:
| 能力 | 解决的问题 |
|---|---|
| Trace | 一次请求内部到底发生了什么 |
| Monitoring | 一段时间内整体运行得怎么样 |
| Dataset | 如何管理标准测试样本 |
| Evaluator | 如何定义评估指标 |
| Experiment | 如何批量跑测试并比较结果 |
最终我们会完成这样一个闭环:
1Agent / RAG 2 ↓ 3Trace 4 ↓ 5Monitoring 6 ↓ 7Dataset 8 ↓ 9Evaluator 10 ↓ 11Experiment 12
一、接入 LangSmith
LangSmith 的接入成本很低。
进入:
1https://smith.langchain.com/ 2
创建 API Key。
然后在现有项目的 .env 中加入:
1LANGCHAIN_API_KEY=你的_LangSmith_API_Key 2 3LANGCHAIN_PROJECT=langsmith-test 4 5LANGCHAIN_TRACING_V2=true 6
这三个变量分别表示:
1LANGCHAIN_API_KEY 2→ LangSmith 身份认证 3 4LANGCHAIN_PROJECT 5→ Trace 归属哪个项目 6 7LANGCHAIN_TRACING_V2 8→ 开启链路追踪 9
如果项目本身还使用模型和向量数据库,那么 .env 可能类似:
1# ===== LangSmith ===== 2 3LANGCHAIN_API_KEY=xxx 4LANGCHAIN_PROJECT=langsmith-test 5LANGCHAIN_TRACING_V2=true 6 7 8# ===== LLM ===== 9 10OPENAI_API_KEY=xxx 11OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 12MODEL_NAME=qwen-plus 13 14 15# ===== Embedding ===== 16 17EMBEDDING_MODEL=text-embedding-v3 18 19 20# ===== Milvus ===== 21 22MILVUS_URI=http://localhost:19530 23MILVUS_COLLECTION=rag_docs 24
这里最重要的是区分:
1LANGCHAIN_API_KEY 2
用于 LangSmith。
而:
1OPENAI_API_KEY 2
用于模型服务。
LangSmith 本身并不负责调用你的业务模型,它负责记录和分析调用过程。
当环境变量配置完成之后,LangChain / LangGraph 运行时就可以自动将 Trace 上报到 LangSmith。
二、Trace:先看清一次 Agent 执行
先看一个最小的 LangGraph:
1import "dotenv/config"; 2 3import { 4 Annotation, 5 START, 6 END, 7 StateGraph 8} from "@langchain/langgraph"; 9 10const StateAnnotation = Annotation.Root({ 11 text: Annotation({ 12 reducer: (_prev, next) => next, 13 default: () => "" 14 }) 15}); 16 17const stepOk = (state) => ({ 18 text: `${state.text}[ok]` 19}); 20 21const stepThrow = () => { 22 throw new Error( 23 "DemoError: 节点内故意抛出异常" 24 ); 25}; 26 27const graph = new StateGraph(StateAnnotation) 28 .addNode("step_ok", stepOk) 29 .addNode("step_throw", stepThrow) 30 .addEdge(START, "step_ok") 31 .addEdge("step_ok", "step_throw") 32 .addEdge("step_throw", END) 33 .compile(); 34 35try { 36 await graph.invoke({ 37 text: "start" 38 }); 39} catch (error) { 40 console.error(error.message); 41} 42
运行之后,进入 LangSmith:
1Tracing 2→ langsmith-test 3
可以看到类似:
1LangGraph 2├── step_ok 3└── step_throw 4
这里要先理解两个概念。
Trace 表示一次完整调用。
Run 表示 Trace 中的某一个具体执行单元。
所以一个复杂 Agent 可能是:
1Trace 2│ 3├── retrieve 4│ └── VectorStoreRetriever 5│ 6├── tool_call 7│ 8└── generate 9 └── ChatOpenAI 10
点开任意 Run,可以看到:
1Input 2Output 3Error 4Attributes 5Latency 6
如果节点报错,还能看到完整异常堆栈。
这和传统日志最大的区别是:
日志通常是一堆按时间输出的字符串,而 Trace 是有父子关系的执行树。
三、在真实 RAG 中看 Trace
假设我们已经有一个 LangGraph RAG:
1START 2 ↓ 3retrieve 4 ↓ 5generate 6 ↓ 7END 8
其中:
1async function retrieve(state) { 2 3 const docs = 4 await retriever.invoke( 5 state.question 6 ); 7 8 return { 9 context: docs 10 }; 11} 12
生成节点:
1async function generate(state) { 2 3 const contextText = 4 state.context 5 .map(doc => doc.pageContent) 6 .join("\n\n"); 7 8 const answer = 9 await chain.invoke({ 10 context: contextText, 11 question: state.question 12 }); 13 14 return { 15 answer 16 }; 17} 18
运行:
1node src/cli.mjs "无理由退货要在几天内?" 2
终端可能只看到:
1无理由退货需在自签收之日起 7 天内申请。 2
但 LangSmith 中可以看到完整调用树:
1LangGraph 2├── retrieve 3│ └── VectorStoreRetriever 4└── generate 5 └── qwen-plus 6
这时候 Trace 就非常有用了。
点击 VectorStoreRetriever,可以看到用户问题以及实际召回的文档。
点击 generate,可以看到它收到的 question 和 context。
继续点击模型 Run,可以看到真正发送给模型的 System Prompt、User Message、模型输出,以及调用耗时等信息。
因此,当 RAG 回答异常时,就可以快速判断:
1是 Retriever 召回错了? 2 3还是 Context 正确,但模型回答错了? 4 5还是 Prompt 拼接出了问题? 6 7还是某一步耗时异常? 8
这也是 LangSmith 在 Agent 调试阶段最直接的价值。
四、Monitoring:从单次请求看向整体
Trace 解决的是:
1这一条请求发生了什么? 2
Monitoring 解决的是:
1这段时间整个 Agent 运行得怎么样? 2
LangSmith Monitoring 中可以观察 Trace Count、成功与失败情况、Latency,以及 LLM Calls、Cost & Tokens、Tools、Run Types 等统计信息。
例如:
1Success 2Error 3
可以用来观察整体成功率。
Latency 则可以帮助判断性能是否发生变化。
因此可以把二者简单区分为:
1Trace 2→ 单次调用诊断 3 4Monitoring 5→ 整体运行趋势 6
调试一个具体问题时看 Trace。
观察线上 Agent 的整体健康状态时看 Monitoring。
五、从“可观测”进入“可评估”
到这里解决的是:
1Agent 是怎么运行的? 2
下一步要解决:
1Agent 运行得好不好? 2
LangSmith 为此提供了 Dataset、Evaluator 和 Experiment。
三者之间的关系非常简单:
1Dataset 2 ↓ 3测试数据 4 5Evaluator 6 ↓ 7评分规则 8 9Experiment 10 ↓ 11让 Agent 批量执行 Dataset 12并使用 Evaluator 打分 13
假设我们的 RAG 提供:
1const { 2 answer, 3 context 4} = await ask(question); 5
那么现在要做的,就是准备一组标准测试样本。
六、Dataset:建立固定测试集
安装:
1pnpm install langsmith 2
创建:
1src/evals/build_dataset.mjs 2
例如:
1import "dotenv/config"; 2 3import { 4 Client 5} from "langsmith"; 6 7const DATASET_NAME = 8 "rag-eval-v1"; 9 10const EXAMPLES = [ 11 12 { 13 inputs: { 14 question: 15 "无理由退货要在几天内申请?" 16 }, 17 18 outputs: { 19 answer: 20 "自签收之日起 7 天内支持无理由退货。" 21 } 22 }, 23 24 { 25 inputs: { 26 question: 27 "满多少元包邮?" 28 }, 29 30 outputs: { 31 answer: 32 "满 99 元包邮,部分大件商品和冷链商品除外。" 33 } 34 }, 35 36 { 37 inputs: { 38 question: 39 "手机保修多久?" 40 }, 41 42 outputs: { 43 answer: 44 "手机、平板和耳机全国联保 1 年。" 45 } 46 } 47 48]; 49
然后创建 Dataset:
1async function main() { 2 3 const client = 4 new Client({ 5 apiKey: 6 process.env.LANGCHAIN_API_KEY 7 }); 8 9 let dataset; 10 11 try { 12 13 dataset = 14 await client.readDataset({ 15 datasetName: 16 DATASET_NAME 17 }); 18 19 } catch { 20 21 dataset = 22 await client.createDataset( 23 DATASET_NAME, 24 { 25 description: 26 "RAG Agent 回归评估集" 27 } 28 ); 29 } 30 31 await client.createExamples( 32 33 EXAMPLES.map(example => ({ 34 35 dataset_id: 36 dataset.id, 37 38 inputs: 39 example.inputs, 40 41 outputs: 42 example.outputs 43 })) 44 ); 45} 46 47main(); 48
运行:
1node src/evals/build_dataset.mjs 2
进入:
1Datasets & Experiments 2
就可以看到:
1Inputs 2Reference Outputs 3
这里的:
1Inputs 2
是给 Agent 的测试输入。
而:
1Reference Outputs 2
是预先准备的参考答案。
Dataset 的价值在于,把原本零散的人工测试问题变成一套固定的回归测试集。
以后修改 Prompt、Retriever、模型或者 RAG 参数,都可以重新跑同一批 Dataset。
七、Evaluator:给 RAG 定义评分维度
本文使用 OpenEvals 内置的三个 RAG 指标:
| 指标 | 关注内容 |
|---|---|
| Groundedness | 答案是否被检索上下文支撑 |
| Helpfulness | 回答是否切题、是否解决用户问题 |
| Retrieval Relevance | 检索内容是否与问题相关 |
安装:
1pnpm install openevals 2
创建:
1src/evals/evaluators.mjs 2
导入:
1import { 2 createLLMAsJudge, 3 RAG_GROUNDEDNESS_PROMPT, 4 RAG_HELPFULNESS_PROMPT, 5 RAG_RETRIEVAL_RELEVANCE_PROMPT 6} from "openevals"; 7 8import { 9 ChatOpenAI 10} from "@langchain/openai"; 11
定义 Judge:
1const judge = 2 new ChatOpenAI({ 3 4 apiKey: 5 process.env.OPENAI_API_KEY, 6 7 configuration: { 8 baseURL: 9 process.env.OPENAI_BASE_URL 10 }, 11 12 model: 13 process.env.MODEL_NAME ?? 14 "qwen-plus", 15 16 temperature: 0 17 }); 18
Groundedness:
1const ragGroundednessJudge = 2 createLLMAsJudge({ 3 4 prompt: 5 RAG_GROUNDEDNESS_PROMPT, 6 7 feedbackKey: 8 "rag_groundedness", 9 10 judge, 11 12 continuous: true 13 }); 14
Helpfulness:
1const ragHelpfulnessJudge = 2 createLLMAsJudge({ 3 4 prompt: 5 RAG_HELPFULNESS_PROMPT, 6 7 feedbackKey: 8 "rag_helpfulness", 9 10 judge, 11 12 continuous: true 13 }); 14
Retrieval Relevance:
1const ragRetrievalRelevanceJudge = 2 createLLMAsJudge({ 3 4 prompt: 5 RAG_RETRIEVAL_RELEVANCE_PROMPT, 6 7 feedbackKey: 8 "rag_retrieval_relevance", 9 10 judge, 11 12 continuous: true 13 }); 14
然后分别封装成 Evaluator:
1export async function 2ragGroundednessEvaluator({ 3 outputs 4}) { 5 6 return ragGroundednessJudge({ 7 8 context: { 9 documents: 10 outputs.context 11 }, 12 13 outputs: { 14 answer: 15 outputs.answer 16 } 17 }); 18} 19
Helpfulness:
1export async function 2ragHelpfulnessEvaluator({ 3 inputs, 4 outputs 5}) { 6 7 return ragHelpfulnessJudge({ 8 9 inputs, 10 11 outputs: { 12 answer: 13 outputs.answer 14 } 15 }); 16} 17
Retrieval Relevance:
1export async function 2ragRetrievalRelevanceEvaluator({ 3 inputs, 4 outputs 5}) { 6 7 return ragRetrievalRelevanceJudge({ 8 9 inputs, 10 11 context: { 12 documents: 13 outputs.context 14 } 15 }); 16} 17
最后统一导出:
1export const ragEvaluators = [ 2 3 ragGroundednessEvaluator, 4 5 ragHelpfulnessEvaluator, 6 7 ragRetrievalRelevanceEvaluator 8]; 9
八、三个 RAG 指标到底在比较什么
这里非常值得单独理解。
Groundedness:
1Answer 2 VS 3Context 4
它关注:
1模型说的内容是否有检索材料支撑? 2有没有脱离上下文胡编? 3
Helpfulness:
1Answer 2 VS 3Question 4
它关注:
1回答有没有真正解决用户的问题? 2是否答非所问? 3
Retrieval Relevance:
1Context 2 VS 3Question 4
它关注:
1Retriever 返回的文档到底相关不相关? 2
于是一个 RAG 问题可以被拆成:
1检索对不对? 2↓ 3Retrieval Relevance 4 5检索正确之后, 6回答有没有依据? 7↓ 8Groundedness 9 10有依据以后, 11回答是否真正有用? 12↓ 13Helpfulness 14
这比单独给 RAG 一个“总分”更容易定位问题。
九、Reference Output 和这三个指标的关系
这里有一个非常容易误解的地方。
Dataset 中虽然保存了:
1Reference Outputs 2
但刚才这三个 Evaluator 并没有直接使用它。
因为它们分别比较的是:
1Groundedness 2Answer vs Context 3 4Helpfulness 5Answer vs Question 6 7Retrieval Relevance 8Context vs Question 9
比如:
1Reference Output: 2 3金卡会员享 95 折, 4同时拥有专属客服和每月优惠券。 5
而 Agent 实际只回答:
1金卡会员享 95 折。 2
某些指标依然可能给高分。
因为这个回答:
1没有脱离 Context 2而且确实回答了 Question 3
如果业务还希望评价:
1Actual Answer 2VS 3Reference Answer 4
那么应该再增加答案 Correctness 一类的 Evaluator。
所以 Dataset 中的 Reference Output 和 Evaluator 是两个独立概念。
Dataset 可以保存标准答案。
但最终哪些字段参与评分,由 Evaluator 决定。
十、Experiment:真正跑一次完整评估
创建:
1src/evals/run_eval.mjs 2
首先把 RAG 包装成一个评测目标:
1async function runRagAgent(inputs) { 2 3 const { 4 answer, 5 context 6 } = 7 await ask( 8 inputs.question 9 ); 10 11 return { 12 13 answer, 14 15 context: 16 context.map( 17 doc => 18 doc.pageContent 19 ) 20 }; 21} 22
然后调用 LangSmith 的:
1evaluate() 2
完整代码:
1import "dotenv/config"; 2 3import { 4 Client 5} from "langsmith"; 6 7import { 8 evaluate 9} from "langsmith/evaluation"; 10 11import { 12 ask 13} from "../rag_agent.mjs"; 14 15import { 16 ragEvaluators 17} from "./evaluators.mjs"; 18 19 20const DATASET_NAME = 21 "rag-eval-v1"; 22 23 24const client = 25 new Client({ 26 apiKey: 27 process.env.LANGCHAIN_API_KEY 28 }); 29 30 31async function runRagAgent(inputs) { 32 33 const { 34 answer, 35 context 36 } = 37 await ask( 38 inputs.question 39 ); 40 41 return { 42 43 answer, 44 45 context: 46 context.map( 47 doc => 48 doc.pageContent 49 ) 50 }; 51} 52 53 54async function main() { 55 56 const result = 57 await evaluate( 58 runRagAgent, 59 { 60 61 data: 62 DATASET_NAME, 63 64 evaluators: 65 ragEvaluators, 66 67 client, 68 69 experimentPrefix: 70 `rag-openevals-${ 71 process.env.MODEL_NAME 72 ?? "qwen" 73 }`, 74 75 maxConcurrency: 2 76 } 77 ); 78 79 80 for await ( 81 const _row of result 82 ) { 83 // 等待所有样例完成 84 } 85 86 87 console.log( 88 "✅ 评测完成" 89 ); 90 91 console.log( 92 "实验名:", 93 result.experimentName 94 ); 95} 96 97 98main(); 99
运行:
1node src/evals/run_eval.mjs 2
LangSmith 会创建一次新的 Experiment。
十一、Experiment 页面怎么看
进入:
1Datasets & Experiments 2→ rag-eval-v1 3→ Experiments 4
可以看到类似:
1Inputs 2Reference Outputs 3Outputs 4rag_groundedness 5rag_helpfulness 6rag_retrieval_relevance 7
其中:
1Inputs 2
是 Dataset 中的问题。
1Reference Outputs 2
是 Dataset 中的参考答案。
1Outputs 2
是 Agent 实际生成的结果。
后面的各个 rag_* 字段就是 Evaluator 给出的评分。
这时评估就不再是:
1“感觉回答还不错” 2
而变成:
1Groundedness = ? 2Helpfulness = ? 3Retrieval Relevance = ? 4
这就是所谓的量化评估。
十二、Experiment 的真正价值在“比较”
只跑一次 Experiment 的意义有限。
更有价值的用法是:
1Experiment A 2→ 原 Prompt 3 4Experiment B 5→ 新 Prompt 6
或者:
1Experiment A 2→ Retriever k = 4 3 4Experiment B 5→ Retriever k = 2 6
或者:
1Experiment A 2→ 模型 A 3 4Experiment B 5→ 模型 B 6
然后在同一套 Dataset 上比较。
因为测试集没有变化,所以你可以观察修改究竟让哪些指标变好了,哪些指标变差了。
这才是 Dataset + Experiment 最核心的工程意义:
1修改前 2↓ 3跑 Experiment 4 5修改后 6↓ 7再跑 Experiment 8 9↓ 10用数据判断修改是否真的有效 11
十三、把 LangSmith 的完整逻辑串起来
最终可以把 LangSmith 理解成两部分。
第一部分是 Observability:
1Agent 2 ↓ 3Trace 4 ↓ 5Run 6 ↓ 7Input / Output 8Error 9Latency 10Token 11Tool Call 12LLM Call 13
再向上汇总:
1Trace 2 ↓ 3Monitoring 4 ↓ 5整体调用量 6错误情况 7耗时趋势 8Token / Cost 9
第二部分是 Evaluation:
1Dataset 2 ↓ 3Agent 4 ↓ 5Outputs 6 ↓ 7Evaluator 8 ↓ 9Scores 10 ↓ 11Experiment 12
所以它不是单纯的 Trace Viewer。
它把:
1调试 2+ 3监控 4+ 5评估 6
串成了一套完整工作流。
十四、总结
如果只记住 LangSmith 的五个核心概念,可以记成这张表:
| 概念 | 一句话理解 |
|---|---|
| Trace | 一次 Agent 调用的完整链路 |
| Monitoring | 多次调用形成的整体运行统计 |
| Dataset | 固定的测试样本集合 |
| Evaluator | 自动评分规则 |
| Experiment | 在 Dataset 上批量运行并评分的一次实验 |
对于已经能够开发 LangGraph Agent 或 RAG 的工程师来说,LangSmith 真正解决的不是:
1“怎么让 Agent 跑起来?” 2
而是:
1“Agent 跑起来以后,我怎么知道它内部发生了什么?” 2 3以及: 4 5“我修改了一版 Agent,怎么证明它真的比上一版更好?” 6
前者由 Trace 和 Monitoring 解决。
后者由 Dataset、Evaluator 和 Experiment 解决。
当 Agent 从 Demo 走向真实项目时,这两种能力往往比继续增加更多节点、更多工具调用更重要:
1可观测 2+ 3可评估 4
这也是 LangSmith 最值得学习的地方。
参考文档
- Primers 编程伙伴/Bash/帮助手册/env
- Primers 编程伙伴/HTML/HTML 元素/map
- Primers 编程伙伴/HTML/HTML 元素/main
- Primers 编程伙伴/HTML/HTML 元素/data
《LangSmith:从链路追踪到 RAG 自动化评估》 是转载文章,点击查看原文。