LangSmith 观测心智模型与追踪数据结构

LangSmith 的核心不是“保存日志”，而是把一次 Agent 交互表达为可查询、可评估、可回放的运行树。生产设计应先稳定 trace、run、thread、project 的身份和边界，再谈图表、告警和评估。

学习导航

• 02-SDK追踪上下文与分布式链路：如何正确创建、嵌套、传播和提交 span。
• 03-LLM成本元数据多模态与检索：LLM、Retriever、消息、用量和附件的数据契约。
• 04-查询过滤采样脱敏导出与用量：观测数据治理与查询面。
• 05-监控仪表盘告警自动化与在线评估：从 trace 走向生产反馈闭环。
• 06-集成矩阵-模型框架与编排：Provider、框架和编排系统的接入选择。
• 07-编码代理语音与专用追踪：编码代理与语音 Agent 的特殊结构。
• 08-OpenTelemetry采集器SDK与参考边界：OTel、Collector 与生成式 SDK 参考。
• 09-Prompt工程版本治理与模型配置：Prompt 生命周期和模型配置。
• 10-Context-Hub-Chat-MCP与Skills：上下文资产与诊断工具。
• 11-LLM-Gateway架构接入与治理：模型流量统一入口。
• 12-版本漂移重定向与生产检查清单：文档漂移和上线检查。

一、四个核心对象

Trace 的结构关系是：

project └─ thread_id（可选） ├─ trace A：root run │ ├─ child LLM run │ └─ child tool run └─ trace B：root run

关键结论：

• run 在文档和 SDK 中也叫 span；不要把一次 trace 误称为一个 span。
• root run 的 ID 同时可成为 <code>trace_id</code>。子 run 通过 <code>parent_run_id</code> 与 <code>dotted_order</code> 定位层级和顺序。
• thread 不是另一棵 run 树，而是对多条 trace 的业务分组。没有稳定 thread ID，线程级成本、反馈和多轮评估都会失真。
• trajectory 是为多轮评估生成的扁平消息轨迹：LangSmith 会展开并去重重复消息；它不是原始 run 树的无损替代品。

二、Run 的最小生产数据契约

每个 run 至少要能回答：

1. 它是什么：稳定的 <code>name</code> 和正确的 <code>run_type</code>。
2. 它何时发生：<code>start_time</code>、<code>end_time</code>，流式 LLM 还应有首 token 时间。
3. 它处理了什么：结构化 <code>inputs</code> 与 <code>outputs</code>。
4. 它属于哪里：<code>trace_id</code>、父 run、project，必要时 <code>thread_id</code>。
5. 它是否成功：状态、错误与异常上下文。
6. 如何切片：tags、metadata、模型和集成元数据。

常用 run type：

• <code>chain</code>：业务编排、Agent、非模型函数。
• <code>llm</code>：真正的模型推理请求；决定消息渲染、token 和成本解析。
• <code>tool</code>：工具执行。
• <code>retriever</code>：检索步骤，输出应保留文档结构。
• <code>prompt</code>、<code>parser</code>：LangChain 等框架可产生的专用步骤。

不要为了“图好看”把所有节点标成 LLM。run type 是后续统计、Messages View、成本和评估的语义输入。

三、身份、顺序与幂等

• 新 run ID 推荐 UUIDv7。它带时间顺序，能降低并发子节点排序歧义。
• 同一事件重试时应复用 run ID，避免重复写；但“重复创建”和“重复更新”仍可能返回 409，调用方必须区分幂等重放与真实冲突。
• 批量/OTel 接入必须正确计算 <code>trace_id</code> 与 <code>dotted_order</code>。仅有 parent ID 不足以覆盖所有异步到达场景。
• 不要依赖 UI 展示顺序恢复业务因果；业务因果应在 run 层级、显式事件 ID 和 metadata 中可验证。

四、UI 的三种读法

Details

用于看输入输出、metadata、tags、错误和父子层级。它最接近原始 run 数据。

Waterfall

用于看并行/串行关系、跨度、瓶颈与首 token 延迟。长 trace 的 turn 标题可固定，但 turn 只是展示辅助，不应反推真实业务状态机。

Messages

用于从 root trace 中重建主对话，合并重复的模型输入输出、工具调用和结果。它是一个适配层：

• 集成必须输出 LangSmith 能识别的消息结构。
• 中间 guardrail、子 Agent 对话可能被排除，以保持“主对话”可读。
• Messages 为空不代表 trace 没数据，可能只是格式适配失败。
• Details 是排查权威视图，Messages 是便于阅读的派生视图。

五、反馈不是日志字段

Feedback 是独立资源，可附着于 run 或 thread，用于人工标注、在线评估和纠错。常见字段包括：

• key：指标名称，必须长期稳定。
• score 或 value：数值或分类结果。
• comment / correction：解释与修正内容。
• source：人工、模型评估器或自动化来源。

生产约束：

• 不要把同一语义拆成频繁变化的 feedback key，否则仪表盘无法形成连续时间序列。
• thread feedback 与 run feedback 的粒度不同；多轮结果不要强行写到任意末次 run。
• 评估器重命名不改变既有 feedback key；重命名前先评估指标连续性。
• reviewer note、feedback 和业务 metadata 作用不同，不能互相替代。

六、组件边界

LangSmith 把能力分为几层：

• Instrumentation：SDK、框架封装、OTel 或 REST 负责产生 runs。
• Storage/query：project、trace、thread、feedback 与用量数据。
• Investigation：Trace UI、筛选、搜索、Chat 和 Insights。
• Monitoring：dashboard、alert、rules 与 online evaluation。
• Prompt/Context：可版本化的非代码行为资产。
• Gateway：统一模型入口和策略控制，但会产生独立 gateway trace。

这几层有关联但不自动等价。例如 Gateway 的模型调用 trace 当前不能自动成为应用 trace 的子节点；模型配置也不等于运行时已经使用该模型。

七、保留期与文档口径

官方页面存在两种口径：

• 概念页写 SaaS trace 保留 180 天。
• 快速开始示例提到 Developer 计划保留 14 天。

应把计划、区域、短期/长期保留层和组织配置视为最终事实来源。上线前在当前 workspace 的 Usage/Retention 设置中核验，不能把教程示例当合同条款。

八、生产建模建议

推荐统一根 run metadata：

推荐 project 命名：<code>系统-能力-环境</code>，例如 <code>horse-ai-chat-prod</code>。project 不应高基数到每用户一个，也不应把生产与测试混在同一 project 后再靠过滤补救。

九、排障顺序

1. 查 root run 是否存在、project 是否正确。
2. 用 Details 看输入输出和错误是否完整。
3. 检查父子 ID、dotted order、时间和 thread ID。
4. 检查 LLM run type、消息格式、model/provider 和 usage metadata。
5. 再看 Messages/Waterfall 是否只是派生展示问题。
6. 最后核对采样、脱敏、组织限额、保留期和异步 flush。