学习笔记 · Obsidian
LangSmith 平台产品边界与控制/数据平面
一句话定位
LangSmith 本体负责可观测、评估、Prompt/资源治理；LangSmith Deployment 是面向 Agent 工作负载的生产运行时与编排平台。二者可组合，但“在哪里保存追踪数据”和“在哪里执行 Agent”是两个独立选择，不能把购买 LangSmith Cloud 等同于已经托管 Agent。
三层模型
| 层 | 核心职责 | 关键状态 |
|---|---|---|
| LangSmith 平台 | Trace、评估、Prompt、组织与权限、计费 | 项目、数据集、成员、策略、追踪数据 |
| Control Plane | Deployment、Revision、Integration、Listener 的期望状态与构建/部署管理 | 部署声明、版本、环境配置、监听器元数据 |
| Data Plane | Agent Server、队列、PostgreSQL、Redis、Secrets、Autoscaler | Thread、Run、Checkpoint、长期记忆及执行中状态 |
控制平面不会主动连接数据平面。数据平面的 Listener 周期性调用控制平面 API，拉取创建、更新或删除的期望状态并执行 reconcile。网络设计因此应允许 Data Plane 出站访问 Control Plane，而无需为 Control Plane 打开到私网集群的入站通道。
部署拓扑选择
| 拓扑 | Control Plane | Agent/Data Plane | 适用场景 | 主要责任 |
|---|---|---|---|---|
| Cloud | LangChain | LangChain 的 AWS/GCP | 最低运维成本、快速上线 | LangChain 管基础设施、升级、扩缩容 |
当前 /hybrid 工作流 | 无部署控制面；Standalone Agent Server | 客户基础设施 | Agent 自管，Trace 可发 Cloud 或自托管 LangSmith | 客户管理 Agent Server、数据库、发布和网络 |
| 全量 Self-hosted | 客户基础设施 | 客户基础设施 | 数据驻留、合规、隔离要求最高 | 客户负责 Kubernetes、存储、备份、升级与 DR |
| Standalone Agent Server | 无 Control Plane | 客户基础设施 | 已有发布平台、希望最小运行时 | 客户自行完成镜像、CI/CD、扩缩容、数据库 |
这里存在官方页面间的版本冲突：/hybrid 当前正文明确让客户部署 Standalone Agent Server，仅把 Trace 发往 Cloud/自托管 LangSmith；/deploy-to-self-hosted-overview 的 Hybrid 卡片仍写“LangChain 托管 Control Plane + 客户 Data Plane”，与标成 legacy 的 /hybrid-legacy 相同。新设计不能仅凭导航卡片选型，必须让 LangChain 按合同与目标版本书面确认；在确认前，以 /hybrid 的直接工作流为当前实现，不复制 legacy Listener 配置。
Cloud 与自托管差异
- Cloud Deployment 的数据区域由组织区域决定，当前文档列出 US/EU；部署及其数据库不能跨区域迁移。
- Cloud 请求体上限为 25 MB，超过会返回
413。出站 NAT 有区域静态 IP，可用于上游 allowlist。 - Cloud 提供 Serverless 与 Dedicated，均有 Small/Medium/Large。Serverless 可缩到零，适合测试、后台或内部 Agent；客户面向的持续在线工作负载优先 Dedicated。
- 旧定价用户的 Development/Production 类型保留到 2026-10-01；新系统不应继续以旧类型作为长期设计基线。
- Self-hosted 可完全自定义 CPU、内存、副本、存储，并可接自有 PostgreSQL/Redis；多个 Deployment 可共用物理实例，但必须使用隔离的数据库/Redis DB，不能复用同一逻辑库。
数据面可靠性
Agent Server 服务是无状态且可水平扩展的；持久状态在 PostgreSQL，Redis 只承载队列、心跳、Pub/Sub 和短期元数据。优雅停机时实例停止接新请求、给运行中的 Run 一个完成窗口，再把未完成任务放回队列；硬崩溃后 sweeper 会根据心跳超时重新入队。
这意味着：
- API 副本数控制请求并发，Queue Worker 数与每 Worker 的并发控制 Run 吞吐，两者要独立容量规划。
- Redis 短暂不可用可重试，但长时间不可用仍会使运行时不可用；“不持久”不等于“不关键”。
- Cloud Dedicated 才具备文档所述的托管 PostgreSQL 备份与 standby 自动故障转移；不要把该保证外推到 Serverless 或自托管。
组织边界与工作负载隔离
资源层级是 Organization → Workspace → Application → Resource。Workspace 是信任与权限边界，Application 基于资源标签组织同一 Workspace 内的资源。
- 默认推荐“一团队一 Workspace”，团队内用 Application 与
Environment标签组织 dev/staging/prod，便于复用 Prompt、Dataset 和 Deployment。 - 多团队共用 Workspace 需要 ABAC 严格约束标签，协作好但误配会导致跨团队暴露。
- 每项目/每环境独立 Workspace 隔离最强，但资源不能跨 Workspace 共享，发布与复用成本显著上升。
生产上先以数据与人员信任边界决定 Workspace，再用 Application/Tag 组织环境；不要仅因 UI 分类方便而制造过多 Workspace。
共同责任模型
在 SaaS 中，LangChain 负责平台基础设施、应用安全、租户隔离、传输/静态加密与平台 DR；客户仍负责 Agent 代码、输入数据、最小权限、成员离职回收、密钥轮换和源端 PII 过滤。Self-hosted 中，数据库、备份、恢复演练、网络、证书和升级责任全部转移给客户。
上线检查
- 明确 LangSmith 平台和 Agent 执行各自位于 Cloud、VPC 还是自托管集群。
- 记录 Control Plane、Data Plane、追踪 API 的不同域名与认证方式，CI/CD 不可混用端点。
- 为 Thread/Run 数据库、Trace 数据库与长期对象存储分别定义 RPO/RTO。
- 验证区域、25 MB 请求上限、静态 IP、私网连接和模型 API 出站策略。
- 为 Listener 拉取失败、队列积压、PostgreSQL/Redis 失败和 Revision 回滚建立监控。
- 对自托管明确谁维护 Helm、镜像、证书、依赖数据库、升级与恢复演练。