Bin✳

学习笔记 · Obsidian

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

LangChainLangSmith
来源更新 2026-08-11下载 Markdown ↓

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-01Trace Waterfall
2025-03OpenAI Agents SDK tracing、原生 OTel、UI evaluator
2025-04Alerts
2025-05多模态、Agent observability、Prompt webhooks
2025-06/07多模态成本、scheduled export
2025-10Insights GA、multi-turn evals；LangGraph Platform/Studio 更名
2025-12自动成本、LangSmith Fetch、pairwise annotation
2026-02非 LLM run 自定义成本、input/output preview、scheduled Insights
2026-06Dashboard builder、OAuth model config、Context Hub webhook、Gateway guard
2026-07SmithDB/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 configobject 示例重复 JSON key使用 array
Cursor metadata字段名与 coding-agent-v1 不一致以权威 contract 为准
Prompt GitHub 示例没完整 HMAC/幂等/并发处理按 webhook 专页补齐
Temporalendpoint 旧变量、TS client tracing 示例缺口查 Temporal/SDK 当前 reference
Gateway Creditspaid 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 stagebeta
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、导出下游和恢复演练。
← 继续探索AI 与智能体回到顶部 ↑