---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - langchain
  - langsmith
  - changelog
  - production-readiness
topic: LangSmith 版本漂移、重定向与生产检查清单
sources:
  - https://docs.langchain.com/langsmith/changelog
last_verified: 2026-08-11
---

# 版本漂移、重定向与生产检查清单

> [!summary]
> LangSmith Cloud 按周演进，教程里的默认值和 UI 能力会快速过期。笔记把 2026-08-11 的文档当快照；真正上线要以当前计划、区域、自托管版本、SDK release 和实际 UI/API 为准。

## 一、Changelog 使用方式

Cloud changelog 与 Fleet changelog共用一页，并提供 RSS。自托管有独立 changelog，不能用 Cloud 周报推断自托管已具备某功能。

建议订阅并把变化分为：

- API/SDK deprecation。
- 数据格式与查询后端。
- tracing/retention/billing。
- evaluator/rule 语义。
- model/provider/Gateway。
- 权限、安全与区域。

每次升级只筛选本系统使用的能力，并形成兼容性测试单。

## 二、关键演进时间线

| 时间 | 能力节点 |
|---|---|
| 2025-01 | Trace Waterfall |
| 2025-03 | OpenAI Agents SDK tracing、原生 OTel、UI evaluator |
| 2025-04 | Alerts |
| 2025-05 | 多模态、Agent observability、Prompt webhooks |
| 2025-06/07 | 多模态成本、scheduled export |
| 2025-10 | Insights GA、multi-turn evals；LangGraph Platform/Studio 更名 |
| 2025-12 | 自动成本、LangSmith Fetch、pairwise annotation |
| 2026-02 | 非 LLM run 自定义成本、input/output preview、scheduled Insights |
| 2026-06 | Dashboard builder、OAuth model config、Context Hub webhook、Gateway guard |
| 2026-07 | SmithDB/API 迁移、trace limits、Gateway Credits/政策增强、Remote MCP 修复 |

时间线只说明 Cloud 发布节奏，不代表所有 region/plan/self-host 同时可用。

## 三、近期需要动作的变更

- 一批旧 v1 runs/share/dataset-run/annotation endpoints 已标 deprecated，Sunset 目标为 2027-01-31；按 SmithDB migration 替换。
- <code>POST /feedback/eager</code> 已由 <code>POST /feedback</code> 替代，changelog 给出的移除日为 2026-08-10；当前集成不应再新增 eager 依赖。
- Bulk export Cloud 默认 zstd，自托管可保留 gzip。
- 新 trace 超出 project/user monthly limit 会被拒绝，但已接受 trace 的 patches/feedback 继续流动。
- annotation queue/feedback 是否延长短期 trace retention 的默认行为在近期有调整，调用时显式传意图。
- OTel child-before-parent、oversized multipart、Messages adapters 等行为持续修复，升级后要回归。

## 四、当前文档别名和重复页

本次 140 页对账发现：

| 路径组 | 当前状态 |
|---|---|
| /langsmith 与 /langsmith/observability | 正文相同 |
| get-started-integrations 与 integrations | 正文相同 |
| context-hub 与 prompt-context-hub | 正文相同 |
| llm-gateway-credits 与 llm-gateway-langchain-provider | 正文相同，后者是旧命名入口 |
| chat-observability 与 chat-prompt-engineering | 均重定向到 /langsmith/chat，返回同一 canonical HTML |

对外链接优先 canonical 路径，但来源清单保留所有授权 URL，便于证明逐页核验和识别导航漂移。

## 五、已确认的文档矛盾/缺口

| 主题 | 冲突 | 处理 |
|---|---|---|
| Trace retention | 概念页 180 天，Quickstart 示例 Developer 14 天 | 查当前计划/workspace |
| Remote MCP self-host | 旧页称 0.15+，专页称 0.16+ 且需 JWKS | 以专页和 chart release 为准 |
| Java/Go SDK 聚合页 | 错称 JS/TS 并链接 JS reference | 查语言 package/reference |
| 多 endpoint config | object 示例重复 JSON key | 使用 array |
| Cursor metadata | 字段名与 coding-agent-v1 不一致 | 以权威 contract 为准 |
| Prompt GitHub 示例 | 没完整 HMAC/幂等/并发处理 | 按 webhook 专页补齐 |
| Temporal | endpoint 旧变量、TS client tracing 示例缺口 | 查 Temporal/SDK 当前 reference |
| Gateway Credits | paid plan 资格文案不一致 | 查组织 UI/合同 |
| 手工 Provider tracing | 暗示自动成本，但未总是提交 usage | 以 LLM run 契约验证 |

## 六、版本记录模板

每次实际接入记录：

| 项 | 值 |
|---|---|
| LangSmith Cloud region / self-host version |  |
| Python langsmith |  |
| JS langsmith |  |
| LangChain/LangGraph/Deep Agents |  |
| OTel SDK/Collector |  |
| Provider SDK |  |
| Gateway release stage | beta |
| Prompt/Context commit |  |
| 验证日期 |  |

## 七、生产总检查

### 数据模型

- [ ] 一次业务请求是一条 trace，长期会话用 thread。
- [ ] run type、parent、trace ID、dotted order 和 UUIDv7 正确。
- [ ] root metadata 有环境、release、route、correlation。

### LLM 与成本

- [ ] Messages、tools、usage、provider/model、TTFT 可验证。
- [ ] 自托管/别名模型有价格规则。
- [ ] tool/retrieval 等非模型成本有口径。

### 可靠性

- [ ] serverless、CLI、worker 都会 flush。
- [ ] tracing 失败不阻断业务且有丢弃指标。
- [ ] OTel child-before-parent 与 orphan expiry 已压测。
- [ ] retry/fallback 有 attempt 和幂等 ID。

### 隐私与安全

- [ ] prompt/output/tool/retrieval/metadata/error/attachment 全面分类。
- [ ] SDK/OTel/Gateway 脱敏责任明确。
- [ ] Gateway 未覆盖 response、system、tool arguments 的缺口已补。
- [ ] API key、Provider secret、OAuth secret 最小权限并可轮换。

### 监控与评估

- [ ] Dashboard 有流量、错误、延迟、成本、质量、采样。
- [ ] Alert 有最小样本、恢复、owner 和 runbook。
- [ ] Rules 不依赖跨规则顺序。
- [ ] LLM judge 已用人工样本校准。
- [ ] 多轮 evaluator 的 thread/idle window 正确。

### Prompt 与 Context

- [ ] production 使用固定 commit/受控 tag。
- [ ] commit 写入 trace。
- [ ] cache 一致性和回滚明确。
- [ ] webhook HMAC、幂等、重试和 secret rotation 已演练。

### Gateway

- [ ] beta 接受度、API 翻译和 direct route 已评审。
- [ ] workspace role/key 与 trace 可见性合理。
- [ ] spend/rate/header/fallback 组合经过测试。
- [ ] 区域、计划、Desktop plugin 限制已核实。

## 八、推荐复核节奏

- 每周：RSS/changelog，关注 breaking/deprecation/security。
- 每月：SDK 版本、价格规则、用量、采样、保留和策略。
- 每次发布：Prompt/Context commit、model config、trace schema、dashboard 对比。
- 每季度：权限、secret、webhook、导出下游和恢复演练。