03-langsmith-primer

03. LangSmith 入门

LangSmith 是一个用于构建、调试、评估、部署和监控 LLM / Agent 应用的平台。它不是只服务 LangChain，也可以接入其他框架或自定义应用，但和 LangChain / LangGraph 的集成最自然。

官方入口：LangSmith docs。

LangSmith、LangChain、LangGraph 的关系

可以这样理解：

• LangChain：提供模型、prompt、tool、retriever、agent 等应用构建抽象。
• LangGraph：提供 stateful、durable、long-running workflow runtime。
• LangSmith：提供 tracing、evaluation、datasets、prompts、feedback、monitoring、deployment 等工程化平台能力。

如果用前端类比：

• LangChain 像应用开发 SDK。
• LangGraph 像状态机和任务编排 runtime。
• LangSmith 像 DevTools、Sentry、实验平台、测试平台和发布管理的组合。

核心概念

1. Tracing

Tracing 记录一次 Agent 请求中的关键步骤：

• 输入
• prompt
• model call
• tool call
• retriever call
• intermediate state
• final output
• latency
• token
• cost
• metadata

你可以用 trace 回答：

• Agent 为什么选择这个工具？
• 哪个工具调用失败？
• 检索到了哪些上下文？
• 模型是否忽略了上下文？
• 最终输出是在哪一步偏掉的？

参考：

• LangSmith Observability
• Trace LangChain apps
• Trace LangGraph apps

2. Datasets

Dataset 是可重复评估的样例集合。它通常包含：

• input
• reference output
• expected behavior
• metadata
• historical failure cases

对 Agent 工程来说，dataset 的价值是把线上失败变成可回归测试。

参考：Manage datasets。

3. Evaluations 和 Experiments

Evaluation 是评分方法，Experiment 是一次具体运行。

你可以比较：

• prompt v1 vs prompt v2
• GPT-4.1 vs Claude vs 小模型
• RAG chunking 策略 A vs B
• tool schema 修改前后
• LangGraph workflow 修改前后

评估指标可以包括：

• correctness
• relevance
• groundedness
• tool-call accuracy
• refusal correctness
• latency
• token
• cost

参考：

• LangSmith Evaluation
• Evaluation concepts

4. Prompt 管理

Prompt 不应该散落在代码里并靠手动复制。LangSmith 支持 prompt 管理、版本、tag、environment 等能力。

你需要关注：

• prompt commit
• version comparison
• dev / staging / prod promotion
• prompt rollback
• prompt 与 eval dataset 绑定

参考：Manage prompts。

5. Feedback 和 Annotation

线上用户反馈是改进 Agent 的关键数据源。

常见反馈：

• thumbs up / down
• 用户文字反馈
• 人工标注
• failure category
• expected answer
• corrected tool call

工作流建议：

1. 线上收集 feedback。
2. 将差评 trace 加入 annotation queue。
3. 人工标注失败原因和期望行为。
4. 重要失败样例进入 dataset。
5. 用 experiment 验证修复。

参考：

• Attach user feedback
• Annotation queues SDK

6. Monitoring

Monitoring 关注线上质量，而不是离线实验结果。

常见监控维度：

• request volume
• latency
• error rate
• tool failure rate
• cost
• feedback score
• evaluator score
• hallucination risk
• retrieval hit quality

参考：

• LangSmith Dashboards
• LangSmith Alerts

7. CI/CD

成熟 Agent 团队会把 eval 放进 CI/CD：

• prompt 修改触发 eval
• model 修改触发 eval
• retrieval 策略修改触发 eval
• workflow 修改触发 eval
• 低于阈值阻止上线

参考：CI/CD pipeline example。

LangSmith 入门练习

练习 1：追踪一个简单 Agent

做一个 TS Agent：

• 输入一个用户问题
• 调用一个搜索或内部 API 工具
• 输出结构化结果
• 在 LangSmith 中查看完整 trace

验收：

• 能看到 model call。
• 能看到 tool input / output。
• 能看到 latency 和 metadata。
• 能从 trace 解释一次失败。

练习 2：创建 dataset 和 experiment

准备 20 条问题：

• 10 条正常问题
• 5 条边界问题
• 5 条故意诱导错误的问题

跑两版 prompt，对比结果。

验收：

• 能解释哪版更好。
• 能按失败类型归类。
• 能基于结果提出下一次修改。

练习 3：把用户反馈变成 eval

在 UI 中加入 thumbs up / down。

验收：

• 用户反馈能关联到 trace。
• 差评 trace 能进入复盘列表。
• 至少 5 条失败样例被加入 dataset。

介入 LangSmith 开发时的关注点

如果你的目标是参与 LangSmith 相关开发，重点不是只会点 UI，而是理解它解决的工程问题：

• trace 数据模型如何表达一次 Agent 执行？
• eval 如何保证可重复？
• prompt 版本和生产环境如何关联？
• feedback 如何从线上回流到 dataset？
• dashboard 如何帮助定位质量和成本问题？
• CI eval gate 如何避免 regression？

你需要把 LangSmith 看成 Agent 应用的工程控制面。