5.1 LangSmith可观测性与调试

5.1 LangSmith 可观测性与调试 — LangChain 框架精通生产部署第一课

本节导读：学完本节，你将能在生产环境中为 LangChain Agent 接入 LangSmith 全链路追踪，通过 Trace 可视化定位工具调用失败、延迟瓶颈和 Prompt 质量问题，并搭建自动化评估流水线。

学习目标

• 理解 LangSmith 可观测性的核心概念：Trace、Span、Run 三级数据模型
• 使用环境变量和 SDK 两种方式为 Agent 接入全链路追踪
• 通过 LangSmith UI 定位生产环境的异常请求和性能瓶颈
• 构建基于 LangSmith 的自动化评估流水线

核心概念

生产环境中的 LLM 应用与传统 Web 应用有一个本质区别：输出不确定。同一组输入，模型可能返回截然不同的结果。这意味着你不能再靠断言固定输出来保证质量——你需要一套能够记录每一次执行全过程的可观测性系统。

LangChain 生态的官方可观测性平台就是 LangSmith。它的核心数据模型是三级结构：

• Trace（追踪）：一次用户请求的完整生命周期，包含所有子步骤
• Span（跨度）：Trace 中的逻辑阶段，如 Agent 决策循环、工具执行、LLM 调用
• Run（运行记录）：Span 内的具体操作记录，包含输入、输出、耗时、Token 用量

这三个层级构成树状结构。当你的 Agent 调用了 3 个工具、模型推理了 5 轮，一次 Trace 里就会有数十个 Run，每个都带有精确时间戳和 Token 计数。这就是你在生产环境排查问题的"黑匣子"——出了问题不用猜，直接看 Trace。

LangSmith 提供的能力不止追踪。它还有三大核心功能：

对于本节，我们聚焦可观测性部分。评估和提示词管理在更高级的场景中使用，理解原理即可。

环境准备 / 前置知识

• 已完成 LangSmith 账号注册（smith.langchain.com，支持 Google/GitHub/邮箱登录，无需信用卡）
• Python 3.10+ 环境
• 已安装 langchain 和 langsmith 包：pip install langchain langsmith
• 一个可用的 LLM API Key（OpenAI / Anthropic / Google 均可）

分步实战

步骤 1：三个环境变量开启自动追踪

LangSmith 与 LangChain 深度集成。如果你用 create_agent 或 LangGraph 构建 Agent，只需要设置三个环境变量，零代码改动即可开启全链路追踪。

import os

# 必填：启用追踪
os.environ["LANGSMITH_TRACING"] = "true"

# 必填：你的 LangSmith API Key
# 在 smith.langchain.com → Settings → API Keys 创建
os.environ["LANGSMITH_API_KEY"] = "lsv2_pt_xxxxxxxxxxxxx"

# 可选但推荐：指定项目名称，方便在控制台区分不同服务
os.environ["LANGSMITH_PROJECT"] = "my-production-agent"
​

这三个环境变量设好后，LangChain 框架内部会自动把每一次 create_agent 调用、每一次工具执行、每一次 LLM 请求都上报到 LangSmith。你不需要写任何额外的追踪代码。

如果你的 LangSmith 账号不在美国区域，还需要设置端点地址：

# 欧盟区域
os.environ["LANGSMITH_ENDPOINT"] = "https://eu.api.smith.langchain.com"
# 亚太区域
os.environ["LANGSMITH_ENDPOINT"] = "https://apac.api.smith.langchain.com"
​

这是一个常见的坑：很多开发者注册了 EU 区域的账号但没设端点，导致认证一直失败，报错信息还不明确。如果你遇到 "Unauthorized" 错误，第一件事就是检查区域端点配置。

步骤 2：用 SDK 为非 LangChain 代码添加追踪

如果你的应用中有一部分逻辑不是用 LangChain 构建的（比如自研的检索模块、第三方的 HTTP 调用），你仍然可以用 LangSmith SDK 的 @traceable 装饰器为它们添加追踪。

from langsmith import traceable

@traceable(run_type="tool", name="knowledge_search")
def search_knowledge_base(query: str, top_k: int = 5) -> list[str]:
    """从向量数据库检索相关文档片段"""
    # 这里是你自己的检索逻辑
    # 可以是 FAISS、Milvus、Elasticsearch 等
    results = vector_store.similarity_search(query, k=top_k)
    return [doc.page_content for doc in results]
​

run_type 参数告诉 LangSmith 这个 Span 的类型，常用的值有：

如果你用的是 OpenAI 官方 SDK 而不是 LangChain 的 ChatOpenAI，LangSmith 还提供了包装器：

from openai import OpenAI
from langsmith.wrappers import wrap_openai

# 用 LangSmith 的包装器替换原始客户端
client = wrap_openai(OpenAI())

# 之后所有通过这个 client 的调用都会自动追踪
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}]
)
​

步骤 3：为 create_agent 接入追踪并观察 Trace 结构

将以上能力组合起来，我们用一个完整的 create_agent 示例来展示 Trace 的完整结构：

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "lsv2_pt_xxxxx"
os.environ["LANGSMITH_PROJECT"] = "agent-trace-demo"

from langchain.agents import create_agent
from langsmith import traceable

@traceable(run_type="tool", name="calculate")
def calculate(expression: str) -> str:
    """计算数学表达式，返回结果字符串"""
    try:
        result = eval(expression)
        return str(result)
    except Exception as e:
        return f"计算错误: {e}"

@traceable(run_type="tool", name="get_current_time")
def get_current_time() -> str:
    """获取当前日期和时间"""
    from datetime import datetime
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[calculate, get_current_time],
    system_prompt="你是一个有用的助手，可以帮用户计算数学表达式和查询时间。",
)

# 执行一个会触发多轮工具调用的请求
result = agent.invoke(
    {"messages": [{"role": "user", "content": "现在几点了？另外帮我算一下 (123 + 456) * 2 等于多少"}]}
)

print(result["messages"][-1].content)
​

执行这段代码后，打开 LangSmith 控制台（smith.langchain.com），在 "agent-trace-demo" 项目中你会看到一条完整的 Trace。展开它的树状结构：

每一步都清晰可见：Agent 先调了时间工具，再调了计算工具，最后生成自然语言回答。点击任意节点可以查看该步骤的完整输入输出。

完整示例：带追踪的 RAG Agent

下面是一个更贴近生产环境的示例——带知识库检索的 Agent，同时展示 LangSmith 追踪的三种接入方式：

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "lsv2_pt_xxxxx"
os.environ["LANGSMITH_PROJECT"] = "rag-agent-prod"

from langchain.agents import create_agent
from langsmith import traceable

# ---- 自定义检索函数，用 @traceable 标记 ----
@traceable(run_type="retriever", name="vector_search")
def retrieve_documents(query: str, top_k: int = 3) -> str:
    """从向量数据库检索相关文档（生产环境对接 FAISS/Milvus）"""
    # 此处用模拟数据，生产中替换为真实的向量检索
    mock_docs = [
        "LangChain create_agent 是 v0.3 推荐的 Agent 创建方式",
        "LangSmith 提供追踪、评估和提示词管理三大能力",
        "LangGraph 适合构建多步骤、有状态的工作流应用"
    ]
    return "\n".join(mock_docs[:top_k])

# ---- 工具定义 ----
def search_docs(query: str) -> str:
    """搜索内部技术文档库"""
    return retrieve_documents(query)

# ---- 创建 Agent ----
agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[search_docs],
    system_prompt="""你是一个技术文档助手。
用户提问时，先用 search_docs 工具检索相关文档，然后基于检索结果回答。
如果检索结果不够相关，诚实告知用户，不要编造信息。""",
)

# ---- 批量执行 ----
questions = [
    "LangChain 最新的 Agent API 是什么？",
    "LangSmith 能做什么？",
    "什么时候应该用 LangGraph？"
]

for q in questions:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": q}]}
    )
    print(f"Q: {q}")
    print(f"A: {result['messages'][-1].content}\n")
​

这段代码展示了三种追踪方式协同工作：环境变量自动追踪 create_agent 的内部循环，@traceable 标记自定义检索函数，两者自动关联到同一个 Trace 树中。

通过 LangSmith UI 排查生产问题

接入追踪后，真正的价值在排查问题。以下是三个生产环境中最常见的排查场景。

场景 1：工具调用失败

在 LangSmith UI 中，失败的 Run 会被自动标红。点击展开可以看到：工具名称、传入参数、错误信息和堆栈跟踪。你还能看到 Agent 在工具失败后的决策——是重试、换工具、还是直接告知用户"我做不到"。这在传统日志中几乎不可能复现。

场景 2：延迟瓶颈定位

每次 LLM 调用的耗时都被精确记录。在 LangSmith Dashboard 中创建延迟分布图，你可以快速区分瓶颈来源：

• 模型推理慢（通常 2-15 秒）：考虑换更快的模型（如 gpt-4o-mini 替代 gpt-4o）或使用流式输出
• 工具执行慢（数据库查询、外部 API 调用）：在工具代码中加缓存或异步化
• Prompt 过长：检查输入 Token 数，优化 Prompt 模板或减少上下文注入量

场景 3：Token 成本追踪

每条 Run 都记录输入 Token 数和输出 Token 数。按项目、模型、时间段汇总后，你可能会发现一些意外：

• 某个工具的描述写得太冗长，每次调用白白多消耗 500 个输入 Token
• Agent 循环次数过多（>10 轮），每次循环都在重复传完整的对话历史
• system_prompt 过长，每轮推理都带着 2000 Token 的系统指令

这些都是只有通过 Trace 数据才能发现的问题。

自动化评估流水线

追踪让你"看见"发生了什么，评估让你"判断"做得好不好。LangSmith 内置了评估框架，可以在 Trace 层面自动打分，避免每次迭代都靠人工判断质量。

from langsmith.evaluation import evaluate, LangChainStringEvaluator

# 定义评估指标
evaluators = [
    # 自定义标准评估：回答是否准确且基于上下文
    LangChainStringEvaluator("criteria", config={
        "criteria": {
            "accuracy": "回答是否准确，基于检索到的上下文，不编造信息",
            "relevance": "回答是否直接回应用户的问题，没有答非所问"
        }
    }),
]

# 准备测试数据集
test_cases = [
    {
        "input": {"messages": [{"role": "user", "content": "LangChain 最新 Agent API？"}]},
        "reference": "create_agent"
    },
    {
        "input": {"messages": [{"role": "user", "content": "LangSmith 有哪些功能？"}]},
        "reference": "追踪、评估、提示词管理"
    }
]

# 运行评估实验
results = evaluate(
    lambda inputs: agent.invoke(inputs),
    data=test_cases,
    evaluators=evaluators,
    experiment_prefix="rag-agent-eval"
)
​

评估结果出现在 LangSmith 的 Experiments 页面。你可以对比不同 Prompt 版本、不同模型、不同工具配置下的评分变化，用数据驱动决策而不是凭感觉。

常见问题 FAQ

Q1：LangSmith 追踪会影响 Agent 性能吗？延迟增加多少？

A：LangSmith 追踪是异步上报的，不会阻塞主流程。实测延迟增加通常在 10-50ms 以内（取决于网络到 LangSmith 服务器的延迟）。如果在极端低延迟场景下有顾虑，可以通过采样率控制，例如只追踪 10% 的请求。

Q2：LangSmith 免费版有什么限制？生产环境够用吗？

A：免费版（Developer Plan）Trace 保留 14 天，每月有一定量的免费 Trace 额度。对于中小规模应用（日均千级请求以内）完全够用。大规模生产环境建议升级到 Team 或 Enterprise Plan，支持更长保留期和更高吞吐量。

Q3：如何在 Docker 或 Kubernetes 中配置 LangSmith？

A：通过环境变量注入是最简单可靠的方式。在 Docker Compose 中用 environment 字段，在 Kubernetes 中用 ConfigMap 或 Secret 挂载。关键环境变量只有三个：LANGSMITH_TRACING、LANGSMITH_API_KEY、LANGSMITH_PROJECT。绝不要在代码或镜像中硬编码 API Key。

Q4：LangSmith 和 OpenTelemetry 是什么关系？

A：LangSmith 有自己的 Trace 格式，但也支持导出到 OpenTelemetry 兼容的后端。如果你公司已有基于 Jaeger 或 Zipkin 的可观测性基础设施，可以把 LLM 追踪数据汇入现有系统。反过来，LangSmith 也可以接收 OpenTelemetry 格式的 Span 数据。

Q5：怎么只追踪失败的请求来节省额度？

A：最简单的方式是先用 LangSmith 全量追踪一周收集基线数据，之后通过采样配置降低正常请求的追踪比例。LangSmith 的 Rules 功能支持基于条件（如错误率、延迟阈值）自动标记异常 Trace，让你在不全量追踪的情况下也能捕获问题。

最佳实践与避坑

• 生产环境必须设 LANGSMITH_PROJECT：不设的话所有 Trace 进入默认项目，多服务混在一起无法区分
• API Key 不要硬编码：用环境变量或密钥管理服务（如 Vault、AWS Secrets Manager）注入
• 善用采样率：开发环境全量追踪，生产环境设 10%-50% 采样率控制成本
• 评估数据集要持续维护：随着业务变化，评估用例要同步更新，否则评估分数会失真
• 不要只看平均指标：关注 P95/P99 延迟和长尾错误率，这才是用户体验的关键
• 坑点：区域端点：非美国区域账号必须设 LANGSMITH_ENDPOINT，否则认证失败
• 坑点：异步应用：如果你用 asyncio，确保异步函数也用 @traceable_async 而不是 @traceable，否则 Trace 可能不完整

本节小结

本节系统讲解了 LangSmith 可观测性平台的接入和使用。核心要点：三个环境变量开启自动追踪、@traceable 装饰器为自定义函数添加追踪、通过 UI 排查工具调用失败和延迟瓶颈、使用评估框架自动化质量检测。

可观测性不是"上线后再说"的事情。我建议从第一个原型开始就接入 LangSmith——它让你在开发阶段就能看到 Agent 的完整决策过程，而不是等到生产环境出问题了才去猜。下一节我们将讨论性能优化与成本控制，看看如何在保证质量的前提下把 Token 消耗降下来。

延伸阅读

• LangSmith 官方文档可观测性快速入门（LangSmith Tracing Quickstart）
• LangSmith 官方文档评估指南（LangSmith Evaluation）
• 本教程 4.1 节 Agent 基础与 create_agent
• 本教程 4.2 节 工具调用进阶与中间件

关键词：LangSmith, LangChain 可观测性, LLM 追踪, Trace, Span, Agent 调试, 生产环境监控, 自动化评估, LangChain 框架精通
难度：进阶
预计阅读：15 分钟