LLM 工程化与网关

LLM Gateway 不是把不同供应商伪装成完全相同的 API。它统一业务 contract、身份、预算、观测和发布控制，同时保留每个 provider 的能力、参数、错误和数据处理差异。

系统位置

Product / Agent
      ↓ business request + identity + task type
LLM Gateway
  ├─ auth / tenant / purpose
  ├─ request + schema validation
  ├─ policy routing + provider allowlist
  ├─ budget / quota / timeout
  ├─ provider adapters
  ├─ response validation
  └─ trace / audit / kill switch
      ↓
Approved model endpoint

1. Gateway Contract

type GatewayRequest = {
	taskType: 'draft_note' | 'policy_answer' | 'tool_decision';
	tenantId: string;
	actorId: string;
	dataClass: 'public' | 'internal' | 'sensitive';
	input: unknown;
	schemaVersion?: string;
	traceId: string;
	idempotencyKey?: string;
};

客户端提交业务任务，不直接选择任意 provider/model，也不能传入 provider key。

2. Model Registry

3. Policy Routing

Routing 顺序应先检查硬约束，再比较质量、成本和延迟：

permission → data classification → region/provider allowlist
→ required capability → task quality baseline
→ budget/latency → selected model

Fallback 不是“主模型报错就换一家”。跨 provider 可能改变数据区域、retention、工具 contract 和模型行为。只有 routing policy 预先允许、请求可安全重试且目标模型通过相同 contract tests 时才能 fallback。

4. Provider Adapter

Adapter 负责把统一业务请求转换为该 provider 的真实契约，并把结果归一到可观测字段。它不能假装所有模型都支持相同的 temperature、top_p、reasoning、tool call、stream event 或 prompt cache。

5. Reliability Boundary

有副作用的 tool action 需要 idempotency key、approval 和结果确认；Gateway 的模型重试不能导致工具重复执行。

6. Observability

记录：trace ID、task type、tenant（可脱敏）、selected provider/model、routing reason、schema version、latency、usage/cache usage、retry、fallback、validation 和 final status。

默认不记录：API key、完整敏感 Prompt、未脱敏 tool output 或 PII。日志的访问、保留和删除也受 governance 控制。

7. Rollout Controls

• canary：只允许指定 task/tenant/case；
• shadow：在获授权且成本允许时并行比较，不影响用户结果；
• regression gate：新模型必须通过既有 dataset；
• kill switch：按 model/provider/task 禁用；
• rollback：恢复已验证 route/config，不回滚已发生的外部动作；
• model retirement：迁移、回归、下线与审计记录。

8. 安全配置示例

routes:
    policy_answer:
        required_capabilities: [structured_output]
        allowed_data_classes: [public, internal]
        allowed_regions: [configured_at_runtime]
        primary: registry-policy-answer-primary
        fallback: null
        timeout_ms: 30000
        max_attempts: 2
        release_gate: policy-answer-regression-v3

这里使用 registry alias，不把当期 model ID 散落在业务代码。具体型号、价格和区域在使用时核验。

9. Gateway Contract Tests

1. 未授权 tenant/model 被拒绝。
2. Sensitive data 不进入未允许 provider/region。
3. Unsupported control 在请求前失败。
4. 429 只触发有限、带预算重试。
5. Fallback 被禁用时明确返回 unavailable。
6. Structured Output failure 不被包装成 success。
7. Trace 能还原 routing decision，但不泄露 PII。
8. Kill switch 能阻止新请求并保留审计。

完成标准

• Gateway 统一业务 contract，但 provider adapter 保留差异。
• Routing 先执行 permission/data/region/capability 硬约束。
• 跨供应商 fallback 需要显式 policy。
• 重试有上限、预算和 idempotency 边界。
• Model registry、trace、regression、canary 与 kill switch 可用。
• 未知访问、价格或地区状态标记 unavailable，不做猜测。