LangSmith：LangChain 应用的官方追踪与评估平台

为什么需要 LangSmith：LLM 应用黑盒调试与线上质量失控

传统方式下，调试 LLM 应用靠 print 和日志。但这套做法有三个硬伤：一是链条长，一次回答可能经历检索、多轮模型调用、工具切换，日志散落各处，难以还原完整调用栈；二是非确定性，同一 Prompt 两次输出不同，没有历史快照就无法对比“改之前”和“改之后”；三是成本不可见，每次失败调用都在烧 Token，但没人说得清哪一步最贵、哪一步最慢。线上出问题后排障以小时甚至天计，Prompt 改动靠肉眼抽查，属于典型的“能用但不可控”。

LangSmith 用“追踪（Tracing）”这根主线解决问题：SDK 自动为 LangChain/LangGraph 的每次调用生成一条 Trace，包含每一步的输入输出、模型、Token 数、延迟、异常信息，并串成树状调用链。开发者不需要改造业务代码，只要设置环境变量，所有链路自动上报到云端控制台，可按项目、按请求逐条回放。在追踪之上，平台再叠两层能力：评估（用数据集 + 评估器对改动做回归）和监控（成本、延迟、错误率的聚合看板与告警）。三层能力共享同一份 Trace 数据，形成“开发调试—上线前验证—生产监控”的完整闭环。

与 Langfuse、Phoenix 等同类工具相比，LangSmith 的气质差异在于它是 LangChain 生态的一等公民：所有框架级能力（LangGraph 状态、流式事件、回调）都优先对齐 LangSmith 的 Trace 结构，集成深度和零配置体验明显领先，代价是平台本体闭源，自托管需走企业版。

安装与环境配置：3 步就绪

第一步，注册账号并创建 API Key。在 smith.langchain.com 注册后，进入设置页的 API keys 区域，点击 Create API key，复制以 lsv2_ 开头的密钥。

第二步，安装 SDK 及相关依赖。仅开发环境需要安装，平台本身是托管服务。

第三步，配置环境变量并验证。在终端设置三个变量：LANGCHAIN_TRACING_V2=true 是追踪总开关（新版 langchain 同时推荐设置 LANGCHAIN_TRACING_SDK=langsmith，两者并存兼容旧版）；LANGCHAIN_API_KEY 填上一步的密钥；LANGCHAIN_PROJECT 指定项目名，Trace 会归入该项目。验证方式：先运行一次导入，无报错即安装成功；真正验证需要跑一个最小链并到控制台查看 Trace。

pip install -U langsmith langchain langchain-openai export LANGCHAIN_TRACING_V2=trueexport LANGCHAIN_TRACING_SDK=langsmith   # 新版推荐，与旧变量并存export LANGCHAIN_API_KEY="lsv2_你的密钥"export LANGCHAIN_PROJECT="my-first-project" python -c "from langsmith import Client; c = Client(); print('API OK')"

快速上手：10 分钟跑通“追踪 + 评估”

最小可用流程分两条线：先跑通追踪，再跑通评估。追踪解决“看得到”，评估解决“信得过”。

1. 按上一节完成安装与三件环境变量配置，并确保本机有可用的 OPENAI_API_KEY。

2. 保存并运行下方脚本，调用一次最简单的 Prompt 链。运行结束后提示信息会给出 Trace 链接。

3. 打开控制台左侧 Traces 页面，确认 my-first-project 下出现一条新记录；点击进入可见调用链：模型名、输入输出、Token 数、延迟逐项列出。

4. 进入 Datasets & Testing 页面，点击 Create dataset，选择从 CSV/JSON 导入或手动添加，至少准备 2 组“输入—期望输出”样本。

5. 在该数据集上点击 Run experiment，添加一个评估器（Evaluator），如“精确匹配”或 LLM-as-judge，然后运行实验。

6. 运行完成后查看 Experiments 对比页，系统给出每条样本的通过/失败及打分明细，这就是最基础的回归报告。

进阶技巧：在 Playground 中切换不同 Prompt 版本或模型，平台会保存每次运行结果，方便做横向对比。对已有生产 Trace，可直接勾选"Export dataset"把真实流量沉淀为回归数据集。

from langchain_core.prompts import ChatPromptTemplatefrom langchain_openai import ChatOpenAI llm = ChatOpenAI(model="gpt-4o-mini")          # 需要 OPENAI_API_KEYprompt = ChatPromptTemplate.from_messages([    ("human", "用一句话介绍 {topic}")])chain = prompt | llm print(chain.invoke({"topic": "RAG"}).content)  # 运行后到控制台查看 Trace

核心能力详解：4 大支柱

支柱一·全链路追踪（Tracing）。 这是 LangSmith 的地基。LangChain/LangGraph 应用在设置环境变量后自动上报调用链，每个环节（模型调用、检索器、工具、子链）是一个 span，记录输入输出、Token 使用、延迟、异常与自定义元数据。对于流式应用，2024 年 10 月后的版本支持 Realtime 追踪，可观察逐 Token 产出过程。非 LangChain 代码可用 @traceable 装饰器或 Run Tree API 手动打点。

支柱二·评估与回归（Evaluation）。 平台用“数据集 + 评估器 + 实验”三件套组织测试。数据集存历史问题或构造用例；评估器包括精确匹配、LLM-as-judge（用另一个 LLM 按评分标准打分）、自定义打分函数；一次实验（Experiment）在整份数据集上批量运行并按评估器打分，结果可两两对比，用来回答“这次 Prompt 改动是否变差”。

支柱三·Playground 与 Prompt 管理。 无需写代码即可在浏览器里调试 Prompt：选择模型、填入输入、直接看输出与 Token 明细。Prompt 支持版本化发布，每个版本有独立快照，线上异常时可快速回滚到上一版并对比差异。

支柱四·生产监控（Monitoring）。 项目级看板聚合请求量、成功率、Token 成本、延迟与错误分布；可按模型、版本、标签维度切分；支持设置告警规则，在失败率或成本超过阈值时通知到团队，实现“问题先于用户发现”。

生产部署与监控：从上线到运维

云版生产使用。 线上项目与开发项目分离：每个环境使用独立 LANGCHAIN_PROJECT 和独立 API Key，便于权限隔离与成本核算。Trace 量较大时设置采样率（环境变量 LANGCHAIN_TRACING_SAMPLING_RATE=0.1 表示只上报 10% 请求），保留可统计的核心链路同时控制配额。

企业私有化部署。 2025 年推出的企业版支持 On-Prem 部署，平台镜像可运行在内网 Docker/Kubernetes 环境，数据不出机房，适合金融、医疗等有数据合规要求的场景。与云版功能基本一致，按 License 订阅，需联系销售开通。

可观测性运维。 日常关注三类指标：Trace 量（配额与采样是否合理）、项目成本趋势（Token 花费是否异常上涨）、评估通过率（Prompt 改动后的回归分是否稳定）。平台支持 OpenTelemetry 集成，非 LangChain 生态的组件可通过 OTel 语义约定接入；历史数据保留有期限，重要样本应通过 Export dataset 或 API 定期导出到自有存储。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>忘记设置 LANGCHAIN_TRACING_V2=true（或新版 LANGCHAIN_TRACING_SDK=langsmith）时，SDK 静默不报错也不上报，排障时先确认环境变量是否生效。</li><li>免费版 Trace 配额有限且历史保留有时限，生产环境务必配置采样率并规划数据导出，不要等到月初清零才发现没有留存。</li><li>API Key 只能放后端环境变量或密钥管理服务，切勿写进前端代码或提交到公开仓库；泄露后在控制台立即吊销重建。</li><li>升级 langchain 大版本时必须同步升级 langsmith SDK，旧版 langchain 0.0.x 与新版 SDK 存在兼容差异，版本错配会导致追踪静默失效。</li></ul>

版本迭代

LangSmith 平台本体是持续交付的 SaaS，官方不发布语义化版本号，因此本表按公开里程碑记录；配套 SDK 版本走 0.1.x → 0.2.x → 0.3.x 路线。整体演进主线清晰：先打通框架级自动追踪，再补齐 Prompt 实验与评估回归，随后增强流式与 OpenTelemetry 互操作，2025 年开放企业私有化部署（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题