LLM Gateway 架构、接入与治理

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：<code>gateway:invoke</code> + <code>workspaces:read</code>。
• 管策略：<code>organization:manage</code>。
• 看 trace：<code>projects:read</code> + <code>runs:read</code>。

内置 WORKSPACE_USER/VIEWER 没有 invoke 且不可编辑。非管理员需建立 custom role；否则只有 WORKSPACE_ADMIN 默认可调用。

Gateway trace 默认所有具有 runs/projects read 的 workspace 成员可见。敏感组织可：

• 分离 workspace。
• Enterprise 使用 project ABAC。
• 关闭 Trace content，只留 metadata。

三、标准 API

BYOK model ID 使用 <code>provider/model</code>；Gateway Credits 使用 hosted slug。

标准 endpoint 会跨 Provider 翻译请求/响应，适合客户端兼容。Provider 特有能力不能假定完整翻译，应使用 direct route。

Prompt caching：

• OpenAI 新模型通常隐式。
• Anthropic 可透传 <code>prompt_cache_options</code>。
• 旧 OpenAI 可透传 <code>prompt_cache_retention</code>。
• 这是临时 provider-specific 机制，不是成熟 Gateway cache policy。

四、Direct model access

Direct route 保留 Provider-native API，例如 Gemini 原生 Generate Content，避免标准格式丢能力。路径按 provider/config 区分：

• <code>/providers/{config}</code>：调用方仍可指定 model。
• <code>/models/{config}</code>：模型由配置固定。

选择规则：

• 最大兼容现有 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/费用规则扣减。
• <code>llm-gateway-credits</code> 与旧名 <code>llm-gateway-langchain-provider</code> 当前正文完全相同。

计划口径有冲突：正文称所有 paid plans，价格说明又排除 Enterprise。购买资格和合同应以当前组织 UI/销售条款为准。

六、Gateway trace

每次调用写：

• 中央 <code>gateway</code> 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

可根据自定义 <code>X-Gateway-*</code> 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 前替换为 <code>SAFE_TO_USE</code> 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/告警。