--- type: study created: 2026-08-11 updated: 2026-08-11 sensitivity: standard status: verified tags: - langchain - langsmith - llm-gateway - governance topic: LangSmith LLM Gateway 架构、接入与治理 sources: - https://docs.langchain.com/langsmith/llm-gateway - https://docs.langchain.com/langsmith/llm-gateway-access - https://docs.langchain.com/langsmith/llm-gateway-admin-setup - https://docs.langchain.com/langsmith/llm-gateway-api-formats - https://docs.langchain.com/langsmith/llm-gateway-coding-agents - https://docs.langchain.com/langsmith/llm-gateway-credits - https://docs.langchain.com/langsmith/llm-gateway-custom-providers - https://docs.langchain.com/langsmith/llm-gateway-data-protection - https://docs.langchain.com/langsmith/llm-gateway-direct-model-access - https://docs.langchain.com/langsmith/llm-gateway-fallbacks - https://docs.langchain.com/langsmith/llm-gateway-header-policies - https://docs.langchain.com/langsmith/llm-gateway-langchain-provider - https://docs.langchain.com/langsmith/llm-gateway-monitoring - https://docs.langchain.com/langsmith/llm-gateway-quickstart - https://docs.langchain.com/langsmith/llm-gateway-rate-limit-policies - https://docs.langchain.com/langsmith/llm-gateway-spend-policies last_verified: 2026-08-11 --- # LLM Gateway 架构、接入与治理 > [!warning] > LLM Gateway 当前是 beta。它是模型流量控制面，不是应用 Agent trace 的自动父节点；生产采用前需验证 API 翻译、策略组合、失败语义和区域能力。 ## 一、定位 Gateway 统一： - Provider credentials。 - OpenAI/Anthropic 标准 API。 - Provider-native direct routes。 - model/provider routing。 - spend/rate/header/data policies。 - fallback。 - trace、cost、audit 和 Engine issue。 调用链： application → workspace-scoped LangSmith key → Gateway auth + policy → provider secret / Gateway Credits → upstream model → gateway trace + spend 不要把 Provider key 同时发给开发者；否则调用可绕开 Gateway 策略。 ## 二、认证与权限 调用必须使用 workspace-scoped key；organization-scoped key 不支持 invoke。 权限： - invoke：gateway:invoke + workspaces:read。 - 管策略：organization:manage。 - 看 trace：projects:read + runs:read。 内置 WORKSPACE_USER/VIEWER 没有 invoke 且不可编辑。非管理员需建立 custom role；否则只有 WORKSPACE_ADMIN 默认可调用。 Gateway trace 默认所有具有 runs/projects read 的 workspace 成员可见。敏感组织可： - 分离 workspace。 - Enterprise 使用 project ABAC。 - 关闭 Trace content，只留 metadata。 ## 三、标准 API | 格式 | Base | Endpoint | |---|---|---| | OpenAI Chat Completions | gateway host + /v1 | /chat/completions | | Anthropic Messages | gateway host | /v1/messages | | OpenAI Responses | gateway host + /v1 | /responses | BYOK model ID 使用 provider/model；Gateway Credits 使用 hosted slug。 标准 endpoint 会跨 Provider 翻译请求/响应，适合客户端兼容。Provider 特有能力不能假定完整翻译，应使用 direct route。 Prompt caching： - OpenAI 新模型通常隐式。 - Anthropic 可透传 prompt_cache_options。 - 旧 OpenAI 可透传 prompt_cache_retention。 - 这是临时 provider-specific 机制，不是成熟 Gateway cache policy。 ## 四、Direct model access Direct route 保留 Provider-native API，例如 Gemini 原生 Generate Content，避免标准格式丢能力。路径按 provider/config 区分： - /providers/{config}：调用方仍可指定 model。 - /models/{config}：模型由配置固定。 选择规则： - 最大兼容现有 OpenAI/Anthropic 客户端：标准 endpoint。 - 需要 Provider 独有 API/字段：direct。 - 需要强制固定 model：model config path。 Direct 仍经过 Gateway auth、策略和 trace，但要单独验证哪些 route 支持哪些 policy。 ## 五、Provider secrets、custom provider 与 Credits BYOK： - Admin 在 workspace secrets 配 Provider key。 - caller 只持 LangSmith key。 - provider-prefixed model 决定 secret。 Custom provider： - 可配置 OpenAI-compatible endpoint。 - 需要 URL/SSRF/TLS/egress 校验。 - 验证 streaming、tool、usage、error mapping 和 model list。 Gateway Credits： - 不需要 Provider account/key。 - hosted slug 路由到 LangChain-hosted model。 - 预付 credits，并按 LCU/费用规则扣减。 - llm-gateway-credits 与旧名 llm-gateway-langchain-provider 当前正文完全相同。 计划口径有冲突：正文称所有 paid plans，价格说明又排除 Enterprise。购买资格和合同应以当前组织 UI/销售条款为准。 ## 六、Gateway trace 每次调用写： - 中央 gateway project。 - API-key-specific project。 - model/provider、latency、tokens、cost。 - matched/passed/violated policy IDs/names。 - redaction rule counts。 Gateway trace 与应用 trace 当前相互独立，不能自动用 parent/child 关联。应用应把 request/correlation ID 写入双方 metadata，但不要伪造 run hierarchy。 关闭 Trace content： - 不保存 request/response body。 - 仍写 usage、latency、status、model 等 metadata。 - metadata-only Gateway trace 排除 trace-based billing。 - model usage 仍计入 Gateway spend。 ## 七、Spend policies 可按组织、workspace、user、API key 等主体设小时/日/周/月 cap。所有匹配 policy 一起生效： - 更窄 scope 不能放宽上层 cap。 - 多主体 policy 的额度是选中实体合计，不是每个实体各一份。 - 超限返回 HTTP 402。 - fallback 的每次尝试分别计费。 生产建议： - 组织硬上限 + workspace 预算 + user/key 细分。 - 阈值通知早于硬阻断。 - 重试循环和 fallback 计入预算压力测试。 - 调整 cap 写审计和工单。 ## 八、Rate policies 按 requests 或 tokens，窗口为 minute/hour 等。超限返回 429，并带 Retry-After。 客户端： - 尊重 Retry-After，加 jitter。 - 不并发重试同一 prompt。 - 对 streaming token 计量定义做压测。 - rate 与 spend 同时匹配时，不能假定哪一个先返回。 ## 九、Header policies 与 per-customer quota 可根据自定义 X-Gateway-* header/metadata 细分 quota： - header key 会规范化。 - value 精确且区分大小写。 - 每个 policy 当前只支持一个 header condition。 - header 缺失不匹配。 该 header 是调用方声明，不是身份认证。安全用法： 1. 终端用户先通过应用认证。 2. 后端删除用户传入的同名 header。 3. 后端根据已认证 tenant/customer 重新写。 4. Gateway key 永不下发浏览器。 否则用户可伪造其他 customer 值逃避配额。 ## 十、Fallback 可配置 2–5 个模型，当前专注 OpenAI-compatible endpoint 与 Anthropic 配置。每次 attempt： - 独立 trace。 - 独立计费和 spend。 - 受对应策略约束。 只对明确可恢复错误 fallback。auth、权限、无效参数、内容 policy 不应盲目切模型。还要定义： - tool/schema 兼容。 - 上下文窗口差异。 - streaming 已输出部分内容后的行为。 - 模型质量降级是否可接受。 ## 十一、Data protection 可扫描 PII 与 secrets，在出 Gateway 前替换为 SAFE_TO_USE placeholder，Provider 响应回 caller 时对占位符反替换。 覆盖： - outbound request 的受支持内容。 - Gateway trace 中对应请求内容。 不覆盖： - Provider 新生成的敏感 response，尤其 streaming。 - 直接写 LangSmith Trace API 的数据。 - platform ingestion。 - system/developer prompts。 - tool-call arguments。 scanner 故障 fail close，会阻断请求。近期 Gateway 还支持配置 guard pipeline timeout 是 pass 还是 block；严格合规应 block，并监控不可用率。 Gateway redaction 不能替代 SDK/ingestion 层脱敏。 ## 十二、Spend Monitoring 与 Audit Spend dashboard： - workspace 范围。 - 可按 user、API key、model 切片。 - UTC 时间，小时/日/周 bucket。 - 当前要求 Organization Admin + Plus/Enterprise。 - 当前不支持 EU、APAC、AWS。 Audit logs 记录策略管理和 invoke，当前面向 Enterprise 组织管理员。 UI Top N/Other 是展示压缩；财务对账应使用完整 usage/export，不以图表可见 series 为准。 ## 十三、Coding agents - Claude Code：Messages endpoint；Claude Desktop plugins 会失效，Plus/Max 当前不支持。 - Codex CLI：Responses endpoint + config.toml；Codex Desktop plugins 会因认证改走 Gateway 而失效。 - Gemini CLI：需 native direct route。 - Deep Agents Code：OpenAI-compatible 标准 endpoint。 企业分发应为每用户/团队发独立 workspace key，配套 model allowlist、spend policy 和密钥轮换；不要共享一个全公司 key。 ## 十四、上线门槛 - [ ] beta 风险和回退到 direct provider 方案已评审。 - [ ] workspace key/role 最小权限。 - [ ] 标准翻译与 direct route 能力矩阵通过测试。 - [ ] application/gateway correlation ID 可查。 - [ ] spend、rate、header、fallback 组合测试。 - [ ] redaction 未覆盖面由 SDK/ingestion 补齐。 - [ ] Desktop plugins、区域 dashboard 和计划差异已确认。 - [ ] policy 与 provider secret 变更进入 audit/告警。