LangChain 学习笔记（三）：LangSmith 调试与监控

LangChain 学习笔记（三）：LangSmith 调试与监控

---

一、LangSmith 是什么？

LangSmith 是 LangChain 生态系统中专门用于 LLM（大语言模型）应用调试、监控、评估和管理的平台。

四个核心定位：

LangSmith
   ├── 🔍 Tracing   ------ 追踪每一次 LLM 调用的完整链路
   ├── 📊 Monitoring ------ 生产环境的宏观监控看板
   ├── 🐛 Debugging  ------ 排查 Bug 与性能瓶颈
   └── 📈 Evaluation ------ 系统化测试与自动打分

可以把它理解为：

AI 开发版的 SkyWalking / Jaeger / Zipkin。

专门用来回答一个核心问题：

"我的 Agent / RAG 应用，每一步到底发生了什么？"

---

二、LangSmith 核心架构全景

LangSmith 的十二大功能，可以分为三个层次：

第一层：核心应用与开发
   ├── Tracing（追踪）
   ├── Monitoring（监控）
   ├── Datasets & Experiments（数据集与实验）
   ├── Evaluators（评估器）
   └── Annotation Queues（标注队列）

第二层：提示词与调试工具
   ├── Prompts（提示词管理）
   ├── Playground（演练场）
   ├── Studio（工作室）
   └── Context Hub（上下文中心）

第三层：部署与沙盒
   ├── Deployments（部署）
   └── Sandboxes（沙盒）

---

三、账号准备与环境配置

3.1 注册账号

步骤：

访问官网：https://smith.langchain.com/

↓

选择注册或登录方式（Google / GitHub / Email）

↓

登录成功，进入主界面

3.2 获取 API Key

关键操作：

进入 Settings（设置）

↓

点击 "Create API Key"

↓

复制 Key 并妥善保存

↓

⚠️ 重要：Key 只在创建窗口出现一次
   关闭弹窗后，永远无法再次查看
   务必立即保存到安全位置

如果需要删除 Key，可以在设置页面点击删除图标。

3.3 配置环境变量

在项目的 .env 文件中添加四个环境变量：

# 是否启用 LangSmith 监控功能
LANGSMITH_TRACING=true

# LangSmith 监控 WebUI 地址
LANGSMITH_ENDPOINT=https://api.smith.langchain.com

# 你的 API Key
LANGSMITH_API_KEY=lsv2_pt_your_api_key_here

# 自定义项目名称（用于在 WebUI 中分类查看记录）
LANGSMITH_PROJECT="pr-clear-harmony-32"

变量	作用	是否必填
LANGSMITH_TRACING	总开关，true 才会上报数据	必填
LANGSMITH_ENDPOINT	API 地址（SaaS 用户填默认值即可）	必填
LANGSMITH_API_KEY	身份认证凭证	必填
LANGSMITH_PROJECT	项目名称，方便在 UI 中分类查看	可选

✅ 最佳实践：将 .env 文件加入 .gitignore，不要将 API Key 提交到版本库。

❌ 常见错误：忘记设置 LANGSMITH_TRACING=true，导致代码运行了但 LangSmith 上看不到任何记录。

---

四、Tracing（追踪）------ 最重要的功能

4.1 什么是 Tracing？

Tracing 是 LangSmith 最核心的功能。

它会完整记录你的大模型应用的每一次调用链路（Trace）。

当你运行 LangChain 代码时，LangSmith 会自动记录：

一个完整的 Trace
   ├── 输入的 Prompt 是什么
   ├── 模型返回了什么
   ├── 消耗了多少 Token
   ├── 每一个链条节点的耗时
   └── 是否有错误发生

4.2 Tracing 的工作流程

你的 Python 代码
   ↓
load_dotenv() 加载 .env 中的 LangSmith 配置
   ↓
运行 LangChain 程序（model.invoke / chain.invoke）
   ↓
LangSmith 自动拦截调用 → 记录运行指标
   ↓
数据同步至 LangSmith 后台服务
   ↓
浏览器打开 smith.langchain.com → 查看 Tracing 面板

4.3 Tracing 能帮你解决的问题

当你的 Agent 或 RAG 系统出现以下问题时：

• 运行变慢 ------ 查看每个节点的耗时分布
• 报错 ------ 精确定位是哪一步出错
• 输出质量差 ------ 查看完整 Prompt 和模型返回，分析问题所在
• Token 消耗过高 ------ 监控每次调用的 Token 使用量
• 多步骤 Agent 行为异常 ------ 查看完整的状态流转

Tracing 就是你排查问题的"显微镜"。

4.4 查看 Tracing 记录

在 LangSmith WebUI 中：

登录 smith.langchain.com
   ↓
点击左侧 Tracing 菜单
   ↓
找到以 LANGSMITH_PROJECT 命名的项目
   ↓
点击任意条目进入详情页面
   ↓
查看完整的调用链路和各项指标

---

五、Monitoring（监控看板）

5.1 与 Tracing 的区别

维度	Tracing	Monitoring
视角	微观	宏观
关注	单次调用的细节	一段时间内的整体趋势
用途	调试、排查 Bug	上线后观察稳定性和成本
典型场景	开发阶段定位问题	生产环境监控系统健康度

5.2 Monitoring 提供的指标

监控看板提供生产环境的高级数据可视化：

监控看板
   ├── Token 消耗趋势 ------ 每天 / 每小时消耗了多少 Token
   ├── QPS（每秒请求数） ------ 系统的并发负载
   ├── 错误率 ------ 请求失败的比例
   ├── 平均延迟（Latency） ------ 响应速度变化趋势
   └── 成本预估 ------ 基于 Token 消耗计算的费用

5.3 如何使用

在 LangSmith WebUI 中，点击 Monitoring 标签页即可看到各类指标的报表。

点击报表标签或下滑页面可以切换不同指标的视图。

✅ 最佳实践：应用上线后，每天至少看一眼 Monitoring 看板，关注异常波动。

---

六、config 字典详解

6.1 为什么需要 config？

默认情况下，LangSmith 会给每条记录分配一个自动生成的 run_name。

这样调试时会很难区分不同来源的调用。

config 字典让你可以自主标记每一次调用：

config = {
    "run_name": "joke_generation",    # 在 LangSmith 中展示的运行名称
    "tags": ["my_tag1", "my_tag2"],  # 标签，方便分类和筛选
    "metadata": {                     # 自定义元数据
        "user_id": "shkstart",
        "session_id": "sess_123"
    },
    "configurable": {                 # 可动态配置的模型参数
        "model": "deepseek-v4-pro",
        "model_provider": "openai",
        "temperature": 0.7,
        "max_tokens": 1000
    }
}

6.2 config 字段说明

字段	作用	备注
run_name	给本次运行起一个可读的名字	方便在 Tracing 列表中快速识别
tags	打标签（可多个）	在 UI 中按标签筛选和分类
metadata	键值对形式记录自定义信息	例如 user_id、session_id、env 等
configurable	运行时动态覆盖模型参数	支持 model、temperature、max_tokens 等

6.3 使用方式

response = model.invoke(
    "请讲一个笑话",
    config=config    # 传入 config 字典
)

✅ 最佳实践：为每个用户请求带上 session_id，方便追踪同一个用户的操作链路。

❌ 常见错误：config 写好了但忘记传给 invoke()，导致仍然使用默认 run_name。

---

七、Datasets & Experiments（数据集与实验）

7.1 解决的问题

大模型开发有一个核心难题：

当你修改了 Prompt 或更换了底层模型，

如何量化地证明 "新版本比旧版本好"？

Datasets & Experiments 就是用来解决这个问题的。

7.2 工作流程

第一步：构建数据集
   收集真实用户输入 + 边界情况（Edge Cases）
   保存为一个 Dataset

        ↓

第二步：修改应用
   修改 Prompt / 更换模型 / 调整参数

        ↓

第三步：运行实验
   用同一个 Dataset 分别测试新旧版本
   LangSmith 自动运行对比

        ↓

第四步：查看结果
   直观看到新旧版本在同一批测试集上的表现差异
   → 用数据说话，而不是凭感觉

7.3 适用场景

• Prompt 优化后，验证是否真的有提升
• 更换底层模型（如从 GPT-4 换成 DeepSeek-v4），对比效果
• 回归测试：确保新改动没有导致已修复的问题复现
• A/B 测试不同参数配置

---

八、Evaluators（评估器）

8.1 核心挑战

传统的软件测试中，我们用断言（Assert）来验证输出：

assert result == "expected_value"

但对于大模型，输出往往是自由文本，无法用简单的断言来判定对错。

你需要评估的是：

• 回答是否相关？
• 是否包含幻觉？
• 格式是否正确？
• 语气是否恰当？

这就是 Evaluator 解决的问题。

8.2 三种评估方式

评估方式	原理	适用场景
基于规则（Rule-based）	关键词匹配、正则、JSON 校验	格式检查、结构验证
LLM-as-a-judge	用另一个 LLM 来打分	语义评估、质量判断
人工评估	人类专家评审	最关键的业务场景

8.3 LLM-as-a-judge 的核心思想

被评估的模型的输出
        ↓
发送给另一个"裁判"LLM
        ↓
裁判 LLM 根据评估标准（Rubric）打分
        ↓
返回分数 + 评分理由

评估指标举例：

• Answer Relevance（答案相关性）
• Hallucination Detection（幻觉检测）
• Toxicity Check（有害内容检测）
• Format Compliance（格式合规性）

8.4 自动化评估管线

代码运行
   ↓
Trace 被记录到 LangSmith
   ↓
Evaluator 自动对 Trace 进行打分
   ↓
打分结果写入 Trace 的 Feedback 中
   ↓
在 WebUI 中查看评估结果

✅ 最佳实践：将 Evaluator 集成到 CI/CD 管线中，每次提交代码自动运行评估。

---

九、Annotation Queues（标注队列）

9.1 解决的问题

你可能会遇到这些问题：

• 模型的输出 "感觉不太好"，但很难量化描述
• 需要人类专家来判断回答是否准确
• 需要收集高质量的人工标注数据用于后续微调

Annotation Queues 提供了一套人工反馈与数据清洗的工具。

9.2 工作流程

开发或初上线阶段
   ↓
将部分 Trace 发送到标注队列
   ↓
团队成员 / 业务专家 / 人工客服
   ↓
手动打分、纠正回答、贴标签
   ↓
高质量标注数据
   ↓
可用于后续微调模型 / 扩充测试集

✅ 最佳实践：定期将标注得到的高质量数据导入 Datasets，形成"标注 → 评估 → 优化"的闭环。

---

十、Prompts（提示词管理）

10.1 定位

Prompts 是 "提示词版的 GitHub"。

核心价值：把 Prompt 从代码中解耦出来，统一在云端管理。

10.2 解决的核心痛点

❌ 传统方式：

Prompt 硬编码在 Python 代码中
   ↓
修改 Prompt 需要改代码 → 提交 → 部署
   ↓
每次调整都要走完整发布流程
   ↓
团队之间无法共享 Prompt
   ↓
没有版本追踪，不知道谁改了什么

✅ LangSmith Prompts 的方式：

Prompt 存储在 LangSmith 云端
   ↓
代码通过 API 动态拉取最新 Prompt
   ↓
修改 Prompt 无需重新部署
   ↓
支持版本控制（v1、v2、v3...）
   ↓
团队协作和 Prompt 分享

10.3 核心能力

Prompts 管理
   ├── 版本控制 ------ 每次修改自动生成新版本
   ├── 动态拉取 ------ 代码中通过 API 获取最新 Prompt
   ├── 团队协作 ------ 多人共同维护 Prompt 仓库
   ├── 分享复用 ------ 将一个项目的 Prompt 分享给其他项目
   └── 回滚 ------ 出问题时快速切回旧版本

✅ 最佳实践：上线前在 Playground 中充分测试 Prompt，确认无误后再保存为新版本并发布。

---

十一、Playground（演练场）

11.1 定位

无需写代码，就能快速测试和优化 Prompt。

Playground 是一个网页端的模型交互界面。

11.2 核心功能

Playground
   ├── 选择模型 ------ OpenAI、Anthropic、本地模型等
   ├── 输入 Prompt ------ 自由编写和调整
   ├── 查看输出 ------ 实时看到模型返回
   ├── 快速迭代 ------ 修改 Prompt → 立即看到效果
   └── 一键保存 ------ 将调好的 Prompt 保存到 Prompts 仓库

11.3 典型使用流程

打开 Playground
   ↓
选择要测试的模型（如 GPT-4、DeepSeek-v4）
   ↓
输入初版 Prompt
   ↓
运行 → 查看输出
   ↓
不满意 → 微调 Prompt → 再运行
   ↓
满意 → 一键保存到 Prompts 仓库
   ↓
代码通过 API 拉取使用

---

十二、Studio（工作室）

12.1 定位

与 LangGraph 深度集成的可视化调试工具。

如果你的应用是基于图结构（Graph-based）的复杂 Agent 架构，Studio 是不可或缺的工具。

12.2 核心能力

Studio
   ├── 可视化状态流转 ------ 看到 State 在各个 Node 之间的变化
   ├── 断点调试 ------ 在某个节点"暂停"
   ├── 手动修改数据 ------ 暂停后修改中间状态再继续执行
   └── 逐步执行 ------ 一步一步跟踪 Agent 的决策过程

12.3 何时使用

• 当你的 Agent 有多条分支路径，不确定实际走了哪一条
• 当 Agent 在某个节点卡住，需要定位问题
• 当你想理解 Agent 的决策逻辑，需要逐步观察
• 当你想在中间状态注入测试数据，验证后续逻辑

✅ 建议：简单的 Chain 用 Tracing 就够了。复杂的 LangGraph Agent 才需要 Studio。

---

十三、Context Hub（上下文中心）

13.1 定位

管理全局上下文或通用组件配置。

13.2 解决的问题

多个项目或 Prompt 中经常会用到相同的内容：

• 公司品牌介绍
• 客服话术规范
• 通用的系统预设提示（System Prompt）
• 常见 FAQ 模板

Context Hub 让你把这些公共内容集中管理：

Context Hub
   ├── 公共上下文模板
   ├── 全局变量
   ├── 系统预设提示
   └── 跨项目复用

一处修改，所有引用该 Context 的 Prompt 自动生效。

---

十四、Deployments & Sandboxes（部署与沙盒）

14.1 Deployments（部署）

一键部署
   ↓
将 LangChain 应用 / LangGraph Agent 部署为线上 API
   ↓
依托 LangGraph Cloud
   ↓
自动处理：高并发 + 队列管理 + 状态持久化
   ↓
你只需专注编写业务逻辑

14.2 Sandboxes（沙盒）

沙盒环境
   ↓
轻量级的在线运行和测试环境
   ↓
不污染生产环境
   ↓
安全地试运行新 Agent
   ↓
执行自动化脚本测试

环境	用途	风险
沙盒	开发测试、试运行	无风险
部署	对外提供生产 API 服务	需谨慎

---

十五、学习路线建议

15.1 分阶段学习路径

阶段一（立即上手）
   ├── ★★★★★ Tracing      ------ 会写了代码就能用，最重要
   └── ★★★★★ Playground   ------ 快速调优 Prompt

阶段二（项目复杂度提升后）
   ├── ★★★★  Datasets      ------ 量化评估
   ├── ★★★★  Evaluators    ------ 自动化打分
   └── ★★★★  Studio         ------ 可视化调试复杂 Agent

阶段三（团队协作 & 上线后）
   ├── ★★★   Prompts       ------ 团队共享 Prompt
   ├── ★★★   Monitoring    ------ 生产环境监控
   └── ★★   其余功能       ------ 按需学习

15.2 关键学习原则

不需要一次学完 LangSmith 的所有功能。

• 刚入门：会用 Tracing 就够了
• 引入 RAG 或多 Agent 后：逐步引入 Datasets 做量化评估
• 团队协作时：引入 Prompts 管理
• 上线后：关注 Monitoring 看板

---

十六、完整代码示例

16.1 最简示例（自动上报 Tracing）

import os
from dotenv import load_dotenv
from langchain.chat_models import init_chat_model

# 加载 .env 中的 LangSmith 配置
load_dotenv(override=True)

# 初始化模型
DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
DEEPSEEK_BASE_URL = os.getenv("DEEPSEEK_BASE_URL")

model = init_chat_model(
    model="deepseek-v4-flash",
    model_provider="deepseek",
    api_key=DEEPSEEK_API_KEY,
    base_url=DEEPSEEK_BASE_URL,
    temperature=0.2,
    max_tokens=500,
)

# 直接调用 ------ LangSmith 会自动记录 Trace
response = model.invoke("你好")
print(response)

16.2 带 config 的完整示例（推荐写法）

import os
from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from rich import print as rprint

# 从 .env 文件中加载环境变量（包括 LangSmith 配置）
load_dotenv(override=True)

DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
DEEPSEEK_BASE_URL = os.getenv("DEEPSEEK_BASE_URL")

# 1. 初始化模型（声明可动态调整的参数）
model = init_chat_model(
    model="deepseek-v4-flash",
    model_provider="deepseek",
    api_key=DEEPSEEK_API_KEY,
    base_url=DEEPSEEK_BASE_URL,
    temperature=0.2,
    max_tokens=500,
    configurable_fields=("model", "model_provider", "temperature", "max_tokens"),
)

# 2. 准备 config 字典
config = {
    "run_name": "math_calculation",             # LangSmith 中显示的名称
    "tags": ["math", "test", "production"],     # 标签分类
    "metadata": {
        "user_id": "shkstart",                   # 用户标识
        "session_id": "sess_001",                # 会话标识
        "env": "development",                    # 环境标识
    },
    "configurable": {
        "model": "deepseek-v4-pro",              # 运行时覆盖模型
        "model_provider": "openai",              # 运行时覆盖 provider
        "temperature": 0.3,                      # 运行时覆盖温度
        "max_tokens": 1000,                      # 运行时覆盖最大 Token
    },
}

# 3. 调用模型并传入 config
response = model.invoke(
    "1 + 1 = ？请给出详细的计算过程。",
    config=config
)

rprint(response)

16.3 .env 文件完整模板

# ==================== LangSmith 配置 ====================
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_pt_your_api_key_here
LANGSMITH_PROJECT="my-first-project"

# ==================== 模型 API 配置 ====================
DEEPSEEK_API_KEY=sk-your-deepseek-api-key
DEEPSEEK_BASE_URL=https://api.deepseek.com

# OpenAI 兼容接口（如国内中转）
CLOSEAI_API_KEY=sk-your-closeai-key
CLOSEAI_BASE_URL=https://api.closeai-asia.com

---

十七、常见问题与排查

17.1 最常见的问题

问题	原因	解决方法
代码运行了但 LangSmith 没有记录	LANGSMITH_TRACING 未设为 true	检查 .env 文件，确认变量名拼写正确
记录存在但找不到	项目名不匹配	检查 LANGSMITH_PROJECT 的值
API Key 报错	Key 丢失或过期	去 LangSmith 设置页面重新创建
.env 变量没生效	load_dotenv() 未调用	确保在代码开头调用 load_dotenv(override=True)

17.2 调试技巧

✅ 在开发环境始终开启 Tracing，每个问题都能追溯到根源。

✅ 给不同的运行场景打不同的 tag，方便在 UI 中按标签筛选。

✅ 在 metadata 中记录关键上下文（如 user_id、session_id），方便快速定位用户反馈的问题。

✅ 使用 run_name 给每次运行起有意义的名字，不要用默认的随机名称。

❌ 不要在生产环境将 Tracing 级别设得过于详细，会消耗额外性能。

---

十八、面试常见问题

Q1：LangSmith 是什么？它的核心功能有哪些？

LangSmith 是 LangChain 生态中的调试、监控和评估平台。

核心功能包括：Tracing（追踪调用链路）、Monitoring（生产监控看板）、Datasets & Experiments（数据集与对比实验）、Evaluators（自动评估打分）、Annotation Queues（人工标注）、Prompts（提示词版本管理）、Playground（在线 Prompt 调试）。

一句话总结：它是 LLM 应用开发全生命周期的可观测性平台。

---

Q2：Tracing 和 Monitoring 有什么区别？

Tracing 是微观视角，关注单次调用的完整链路------每一步的 Prompt、输出、耗时、Token 消耗。适合开发阶段排查 Bug。

Monitoring 是宏观视角，关注应用在一段时间内的整体趋势------QPS、错误率、平均延迟、成本。适合上线后观察系统健康度。

类比：Tracing 是给一个病人做 CT 扫描（看细节），Monitoring 是给医院所有病人做统计分析（看趋势）。

---

Q3：什么是 LLM-as-a-judge？为什么需要它？

传统断言（assert result == "expected"）无法评估自由文本的质量。

LLM-as-a-judge 用另一个 LLM 作为裁判，根据评估标准（rubric）对输出进行打分，评估回答的相关性、是否包含幻觉、语气是否恰当等。

这是目前评估 LLM 输出质量最常用的方法之一。

---

Q4：为什么要用 LangSmith 的 Prompts 管理，而不是把 Prompt 写在代码里？

把 Prompt 硬编码在代码里有三个问题：

1. 修改 Prompt 需要重新部署，迭代慢
2. 团队之间无法共享和协作
3. 没有版本追溯，不知道谁改了什么

LangSmith Prompts 把 Prompt 从代码中解耦，支持云端管理、版本控制、动态拉取，改 Prompt 不需要重新部署应用。

---

Q5：config 字典中的 configurable 字段有什么作用？

configurable 允许你在运行时动态覆盖模型的初始化参数。

例如初始化时设 temperature=0.2，但针对某个特定请求你想用 temperature=0.7，只需要在 config 中传入 configurable={"temperature": 0.7}，不需要重新初始化模型。

这让你可以在同一个模型实例上，针对不同请求使用不同的参数配置。

---

Q6：LangSmith 的监控数据是如何自动上报的？

只需要三步：

1. 在 .env 中配置 LangSmith 环境变量
2. 代码中调用 load_dotenv() 加载配置
3. 正常运行 LangChain 代码（invoke / stream 等）

LangSmith 会在底层自动拦截调用，将 Trace 数据上报到后台。不需要写任何额外的上报代码。

---

Q7：LangSmith 和 LangGraph Studio 是什么关系？

Studio 是 LangSmith 平台内的一个功能模块，专门用于可视化调试基于 LangGraph 构建的 Agent。

它让你可以可视化地看到 Agent 的状态机在各个 Node 之间的流转，支持断点暂停、手动修改中间状态、逐步执行。

简单的 Chain 用 Tracing 就够，复杂的 Graph-based Agent 才需要 Studio。

---

本章总结

LangSmith 并不是 LangChain 的可选插件，而是 LLM 应用开发中必不可少的可观测性平台。

功能	定位	推荐度	适用阶段
Tracing	微观调用链路追踪	★★★★★	所有阶段
Monitoring	宏观生产环境监控看板	★★★★	上线后
Datasets	管理测试数据集	★★★★	开发中后期
Evaluators	自动化评估打分（LLM-as-a-judge）	★★★★	开发中后期
Annotation Queue	人工标注与数据清洗	★★★	上线初期
Prompts	提示词版本管理（"Prompt 版 GitHub"）	★★★	团队协作时期
Playground	在线 Prompt 调试，无需写代码	★★★★★	所有阶段
Studio	LangGraph 可视化调试	★★★	复杂 Agent
Context Hub	全局上下文管理	★★	多项目时
Deployments	一键部署为线上 API	★★	生产部署
Sandboxes	安全测试环境	★★	试运行

核心要点：

1. Tracing 是 LangSmith 的基石，会写代码就会用，立刻从中受益
2. Playground 让你无需写代码就能快速迭代 Prompt，开发效率翻倍
3. 当应用走向复杂（RAG、多 Agent 协同），Datasets + Evaluators 帮你用数据说话
4. Prompts 管理让 Prompt 从代码中解耦，支持版本控制和团队协作
5. LangSmith 的自动上报机制让开发者几乎零成本获得全面的可观测性

LangSmith 让你看清 LLM 应用的每一个细节，是构建高质量 AI 应用的必备工具。