LangSmith 完整攻略：从新手到高手

是什么 / 适合谁

LangSmith 是 LangChain 官方推出的 LLM 应用观测与调试平台。它的核心定位是帮助开发者追踪、评估和优化基于大语言模型构建的应用，特别是在使用 LangChain 框架时，能实现深度集成。你可以把它理解成 LLM 应用的“监控仪表盘 + 调试工具 + 测试实验室”三合一。

适合谁？

• 正在用 LangChain 构建复杂 LLM 应用（如 RAG、Agent、多步骤链）的开发者
• 需要系统评估 Prompt 效果、模型输出质量、成本与延迟的团队
• 希望从“手动测试”升级到“自动化评估”的 AI 应用工程师
• 研究 Prompt 工程、需要对比不同模型/参数效果的进阶用户

不适合谁？

• 只调用一次 API 做简单问答的轻量用户
• 完全不用 LangChain，且没有评估需求的独立开发者
• 网络环境受限、无法稳定访问海外服务的用户（后面会讲替代方案）

---

阶段学习路径

第1天：跑通基础追踪

目标：让 LangSmith 记录你的第一个 LLM 调用。

1. 注册账号
   访问 LangSmith 官网，用 GitHub 或 Google 账号登录。免费层提供每月 10 万次追踪记录，足够个人学习使用。注意：注册和访问需要正常的海外网络连接，国内直连可能不稳定。

2. 创建项目 + 获取 API Key
   在 Settings 里生成 API Key，复制保存。然后在 LangSmith 控制台新建一个 Project，比如叫“my-first-trace”。

3. 安装 SDK 并配置环境

   pip install langsmith langchain-openai
   

   在代码中设置环境变量：

   import os
   os.environ["LANGCHAIN_TRACING_V2"] = "true"
   os.environ["LANGCHAIN_API_KEY"] = "你的key"
   os.environ["LANGCHAIN_PROJECT"] = "my-first-trace"
   

4. 运行一个简单链并查看追踪

   from langchain_openai import ChatOpenAI
   llm = ChatOpenAI(model="gpt-4o-mini")
   response = llm.invoke("用一句话解释 LangSmith")
   print(response.content)
   

   运行后，回到 LangSmith 控制台，刷新项目页面，就能看到这次调用的完整记录：输入、输出、Token 消耗、延迟时间。

第1周：掌握评估与数据集

目标：学会用 LangSmith 创建测试数据集，并运行自动化评估。

1. 创建数据集
   在 Dataset 页面，手动添加或从 CSV 导入测试用例。每个用例包含输入（如用户问题）和参考输出（期望答案）。例如，为 RAG 应用准备 20 个问答对。

2. 运行评估实验
   在代码中定义评估函数：

   from langsmith import Client
   client = Client()
   
   def exact_match_eval(run, example):
       return {"score": run.outputs["output"] == example.outputs["expected"]}
   
   experiment = client.evaluate(
       llm,  # 你的模型或链
       data="你的数据集名称",
       evaluators=[exact_match_eval]
   )
   

3. 对比实验结果
   实验完成后，LangSmith 会自动生成对比报告。你可以看到不同 Prompt 版本、不同模型在相同测试集上的准确率、延迟、成本差异。这是优化 Prompt 最有力的依据。

进阶：多步链与自定义评估

• 追踪复杂 Agent：LangSmith 能展示 Agent 的每一步思考、工具调用、中间结果。在 Agent 的 callbacks 参数中传入 tracing_v2_enabled 即可自动追踪。
• 自定义评估器：除了内置的精确匹配、语义相似度，你还可以用 LLM-as-Judge 模式：让 GPT-4 评估输出质量，并返回评分和理由。
• 反馈循环：在生产环境中，可以记录用户对输出的点赞/点踩，作为人工反馈，用于后续微调或 Prompt 优化。

---

优势

1. LangChain 原生集成：如果你已经用 LangChain 开发，LangSmith 几乎零配置就能接入。所有链、Agent、Retriever 的调用自动被追踪，无需手动埋点。
2. 评估体系完整：支持数据集管理、批量实验、多维度评分（准确率、延迟、成本、自定义指标），且能一键对比不同版本。
3. 免费层慷慨：每月 10 万次追踪 + 5 万次评估，个人开发者或小团队完全够用。付费版按量计费，没有强制订阅。
4. 可视化友好：追踪记录的树状结构清晰展示每一步的输入输出，调试复杂链时非常直观。

---

短板

1. 国内网络不稳定：这是最大的硬伤。LangSmith 的服务器在海外，国内直连经常超时或掉线。你无法通过修改代码或配置来绕过，必须保证网络能稳定访问海外服务。
2. 与 Langfuse 功能重叠：如果你只想要追踪和评估，Langfuse 是开源的替代品，可以自托管部署，不受网络限制。LangSmith 的优势在于 LangChain 生态的深度绑定。
3. 学习曲线：对于不熟悉 LangChain 的开发者，理解“Run”“Dataset”“Experiment”等概念需要时间。文档偏技术化，缺少面向新手的交互式教程。

---

价格规划

层级	免费层	付费层（按量）
追踪次数	10万次/月	超出后 $0.01/千次
评估次数	5万次/月	超出后 $0.02/千次
数据集存储	100个	无限制
团队协作	1人	支持多成员

建议：个人学习先用免费层。如果项目进入生产且需要团队协作，再考虑付费。注意：付费需要绑定国际信用卡，国内用户可能无法直接支付。

---

不合适怎么办

如果你因为网络限制或预算问题无法使用 LangSmith，推荐以下替代方案：

• Langfuse：开源 LLM 追踪平台，功能最接近 LangSmith。支持自托管部署，可以部署在国内服务器上，网络无压力。同样支持数据集、评估、反馈。缺点是 UI 和 LangSmith 比稍显粗糙，且与 LangChain 的集成需要手动配置回调。
• Phoenix（Arize）：开源的可观测性平台，支持 LLM 追踪和评估。对非 LangChain 框架（如 LlamaIndex、自定义调用）支持更好。部署简单，社区活跃。
• 自建方案：如果只是简单追踪，可以用 loguru 记录日志到本地文件，再用 pandas 分析。但会失去可视化对比和自动化评估能力。

核心建议：如果你能稳定访问海外网络且使用 LangChain，LangSmith 是最省心的选择。否则，优先考虑 Langfuse 自托管。