langsmith

LangSmith

何时使用此技能

• 用户已经选择了 LangSmith，需要一份精简实用的资料包，用于追踪、评估、审核、提示词管理或追踪传播。
• 请求中提到了 LangChain 追踪、@traceable / traceable、wrap_openai / wrapOpenAI、标注队列、运行树、追踪 ID、数据集或实验对比。
• 团队需要判断某项变更是否需要调试追踪、离线评估关卡、在线审核队列、Prompt Hub / 提示词注册表工作，或多服务谱系追踪。
• 用户已经进行了一些 LangSmith 设置，但仍缺乏信心，需要进行审计 / 差距评估。

遇到以下情况时，不要将此技能作为主要工作流：

• 实际任务是通用仪表板 / 告警 / SLO / 遥测管理 → monitoring-observability
• 实际任务是对现有日志进行根因排查 → log-analysis
• 实际任务是代码级复现 / Bug 隔离 → debugging
• 实际任务是部署 / 发布编排 → deployment-automation
• 实际任务是解读通用导出指标或综合 KPI → data-analysis
• 实际任务是运行时防护 / 审批 / 策略中间件 → 相关的安全或策略技能

核心理念

langsmith 应作为工作流资料包路由器，而不是庞大的 SDK 百科全书。

1. 在提及 API 之前，先对请求分类。
2. 选择一个主要资料包。
3. 选择能回答问题的最小化插桩 / 评估 / 审核范围。
4. 返回精简的操作说明。
5. 尽快将相邻的可观测性、调试、部署和策略工作转交出去。

选择资料包前，请先阅读以下支持文档：

• references/intake-packets-and-route-outs.md
• references/modes-and-routing.md
• references/python-sdk.md
• references/typescript-sdk.md
• references/cli.md

说明

第 1 步：规范化请求

首先将提示词转换为以下接收资料包：

langsmith_packet:
  primary_packet: trace-debug | eval | review | prompt-registry | propagation | audit
  app_shape: chat | rag | tool-calling | agent | batch-job | multi-service | mixed | unknown
  runtime: python | typescript | mixed | cli-only | unknown
  request_type: setup | debug | pre-ship gate | production review | prompt decision | cross-service tracing | audit
  current_evidence: traces | datasets | evaluators | feedback queues | prompt versions | exported runs | none
  confidence_problem: missing traces | noisy traces | no regression gate | weak review rubric | prompt drift | broken lineage | mixed | unknown
  route_after: stay-here | monitoring-observability | log-analysis | debugging | deployment-automation | data-analysis

为本次运行选择一个主要资料包。如果有两个选项看起来都合理，请选择能最快减少不确定性的那个。

第 2 步：选择资料包

资料包	适用情况	主要输出	典型信号
trace-debug	实际问题是“发生了什么？”	追踪调试资料包	可见性不足、包装器 / 装饰器、追踪覆盖范围、元数据规范
eval	变更需要发布前或回归信心	评估资料包	创建数据集、评估器、实验、基线 / 候选版本对比
review	已有追踪，但对生产环境缺乏信任	审核资料包	标注队列、反馈标准、人工评分、内联审核
prompt-registry	提示词 / 版本管理是瓶颈	提示词资料包	Prompt Hub、提示词版本、Git 同步、比较提示词变体
propagation	一个请求跨越多个服务、任务、工具或 Agent	传播资料包	父 / 子追踪 ID、跨服务标头、多跳谱系追踪
audit	已有 LangSmith，但仍未发挥作用	审计资料包	追踪噪声大、缺少 ID、没有评估、提示词管理不明确

资料包选择规则：

• 如果团队无法解释运行树，优先选择 trace-debug。
• 如果下一项风险是在没有回归关卡的情况下发布，优先选择 eval。
• 如果真实用户的输出需要人工或结构化的质量反馈，优先选择 review。
• 只有在提示词 / 版本选择确实是瓶颈时，才优先选择 prompt-registry。
• 如果一个请求超出单个服务边界并传播到其他服务，优先选择 propagation。
• 如果系统已经“接入 LangSmith”，但仍缺乏信心，优先选择 audit。

步骤 3：选择最小但有用的方案

方案	适用场景	优势	风险
提供方封装（wrap_openai、wrap_anthropic、wrapOpenAI）	需要快速覆盖模型调用	最快获得可见追踪的途径	单独使用时会遗漏更高层的工作流上下文
装饰器 / traceable()	需要在应用函数周围设置带名称的跨度	跨度边界清晰，可重复使用	仍需审慎选择放置位置
手动追踪代码块 / 追踪上下文	需要限定范围或临时查看	适合审计和可疑代码块	容易埋点不足
标注队列 + 反馈标准	需要结构化的人工审核	保留评分标准和审核流程	仍需设计审核责任归属
数据集 + 实验工作流	需要基准测试或回归检查	可在发布前进行比较	如果范围不明确，可能会偏离到泛泛的评估理论
CLI 导出 / 列表 / 获取流程	相比埋点，更需要审计 / 导出操作	适用于脚本和检查	不能替代埋点设计
跨服务传播标头 / 元数据	需要端到端的溯源	保留父级 / 子级上下文	容易在服务边界处遗漏

规则：

• 优先选择能回答当前问题的最小方案。
• 始终注明项目 / 工作区 / 环境分组。
• 如果之后有人或下游工具会审核运行记录，请保留 run_id、trace_id 和元数据。
• 对 CLI、工作进程和短时任务，应包含关闭时的刷新 / 等待行为。

步骤 4：仅在需要时选择评估或审核层

层	适用场景	说明
确定性评估器 / 代码评估器	输出可以通过机械方式检查	对结构 / 事实规则而言，通常是最佳首选
LLM 评判（openevals）	质量评判具有主观性或缺少参考依据	很有用，但不是真值
人工审核	风险高或细微差异至关重要	需要评分标准、审核人员和审核频率
成对比较	正在比较两个提示词 / 模型 / 应用版本	适合用于基线与候选方案的决策
在线评估器	生产流量需要持续评分	应搭配明确的告警 / 审核规则

不要假装一个层可以替代其他层。

步骤 5：返回一份精简的 LangSmith 简报

默认回复格式：

## LangSmith brief
- Packet: trace-debug | eval | review | prompt-registry | propagation | audit
- App shape: ...
- Runtime: ...
- Current evidence: ...

## Chosen surface
- wrappers / decorators / manual trace / dataset+experiment / review queue / prompt registry / propagation headers

## Required config
- `LANGSMITH_API_KEY`
- project/workspace/environment
- endpoint/workspace overrides if self-hosted

## Required IDs / metadata
- `run_id`, `trace_id`, tags, metadata fields, user/session identifiers as needed

## Verification step
- one trace query, one experiment comparison, one queue review check, or one prompt-version sanity check

## Route-out
- next neighboring skill if the bottleneck moves

保持精简。重点是为用户提供一个最小的下一步产物，而不是一大堆 SDK 说明。

步骤 6：针对不同数据包的启发式规则

对于 trace-debug

• 从缺少可见性的环节入手：应用跨度、工具调用、检索、提供方调用或工作进程边界。
• 优先使用封装，再配合少量高价值装饰器，而不是盲目追踪所有内容。
• 在埋点完成后，给出团队应首先运行的追踪查询 / 筛选条件。

对于 eval

• 定义一个能反映高风险变更的最小数据集。
• 将确定性检查与 LLM 评判或人工审核分开。
• 明确基线 / 候选方案比较、实验命名、并发 / 成本限制，以及发布 / 不发布的决策节点。

对于 review

• 定义反馈键、评分尺度含义、审核责任归属和队列频率。
• 保留 run_id / trace_id，以便之后将反馈关联到正确的产物。
• 如果问题超出输出审核范围，应将更广泛的支持运营工作流转交出去。

对于 prompt-registry

• 明确决定由 Prompt Hub / LangSmith 管理提示词，还是继续以 Git / 应用配置为准。
• 将提示词版本与评估或实验关联起来；不要把注册表当作独立孤岛。
• 如果公共 Hub 浏览仅供参考，而非团队的事实来源，应明确说明。

对于 propagation

• 明确父级 / 子级标头、元数据交接规则，以及哪些服务必须保留追踪上下文。
• 在适当情况下，将分布式系统可靠性和告警问题转交给通用可观测性方案处理。

对于 audit

• 按严重程度排列问题：缺少覆盖、元数据不当、缺少评测、评审流程薄弱、提示词／版本不明确、刷新或血缘关系中断。
• 推荐第一个改进步骤，而不是庞大的重新安装计划。

步骤 7：积极引导至其他方向

一旦 LangSmith 不再是主要瓶颈，就立即切换：

• 通用遥测／仪表板／告警／SLO → monitoring-observability
• 基于现有日志进行根因排查 → log-analysis
• 复现问题并隔离 Bug → debugging
• 推出／部署／环境晋级 → deployment-automation
• 解读导出的指标、实验或 KPI → data-analysis
• 策略／审批／运行时防护措施 → 相关的安全或策略技能

示例

示例 1：追踪调试方案

提示词：

将 LangSmith 添加到这个 FastAPI RAG 服务中，以便我们排查检索器变更后答案质量下降的原因。

良好回答应包含：

• 选择 trace-debug
• 建议使用包装器，并在需要查看检索和工具时添加有针对性的高层级 Span
• 定义项目／标签／元数据，并为短生命周期运行添加刷新步骤
• 将通用服务健康可观测性引导至其他方向

示例 2：评测方案

提示词：

发布这个提示词改写之前，构建一个 LangSmith 评测工作流，其中包含一个基线、一个候选版本，以及一个用于评判主观质量的评审器。

良好回答应包含：

• 选择 eval
• 定义数据集、评估器组合、实验命名和验证步骤
• 区分确定性检查、LLM-as-judge 和人工评审
• 将发布编排排除在范围之外

示例 3：评审方案

提示词：

我们已经有 LangSmith 追踪，但支持团队负责人仍不信任 AI 助手。请设置一个包含人工评分的评审工作流。

良好回答应包含：

• 选择 review
• 定义反馈键、评分标准、队列负责人和运行 ID 保留方式
• 围绕评审工作流作答，而不是泛泛讨论提示词管理

示例 4：提示词注册方案

提示词：

这些提示词应该放在 LangSmith Prompt Hub 中，还是继续保留在 Git 中？

良好回答应包含：

• 选择 prompt-registry
• 比较由平台管理与由 Git 管理的提示词事实来源
• 将选择与实验和发布信心关联起来
• 如 Prompt Hub 并非必需，应如实说明

示例 5：传播方案

提示词：

一个聊天请求会分发到多个工作进程和工具。我们如何在 LangSmith 中保持单条追踪？

良好回答应包含：

• 选择 propagation
• 定义父／子 ID、元数据传播和服务边界
• 有需要时，将通用分布式系统可观测性引导至其他方向

最佳实践

1. 从方案入手，而不是 SDK 调用。
2. 将 LangSmith 视为追踪／评测／评审基础设施，而不是整个生产控制平面。
3. 有意识地保留 run_id、trace_id、标签和元数据。
4. 优先选择能够回答当前问题的最小实用范围。
5. 将确定性检查、LLM 评审器和人工评审明确区分开。
6. 明确说明 Prompt Hub 是否为可选项或仅供参考。
7. 为脚本、工作进程和类 Cron 任务添加刷新／等待行为。
8. 以一个验证步骤和一个引导至其他方向的建议收尾。

参考资料

• references/intake-packets-and-route-outs.md
• references/modes-and-routing.md
• references/python-sdk.md
• references/typescript-sdk.md
• references/cli.md
• 官方文档：https://docs.langchain.com/langsmith
• SDK 仓库：https://github.com/langchain-ai/langsmith-sdk
• OpenEvals：https://github.com/langchain-ai/openevals