团队有三个服务（shop-agent / gateway / monitoring-agent），每个都在调 LLM。有一天老板问："上个月 LLM 花了多少钱？"------没人答得上来，因为三个服务各调各的，账单分散在阿里云、Azure、Bedrock 三个供应商后台。这还不是最糟的：一次客服请求里 shop-agent 内部要调 3 次 LLM + 1 次 embedding，如果直连供应商，限流、脱敏、成本计量全漏。我们需要一道闸口，把所有 LLM 流量收敛到一处。
核心论点
LLM 治理（路由 / 限流 / 成本 / 合规 / 可观测）只有把「所有服务对 LLM 供应商的调用」收敛到一道独立网关，才能完整生效。但"独立"不等于"100% 覆盖"------前提是出口网络策略强制流量经网关，否则"唯一出口"只是约定，不是保证。
三个位置要先分清
很多人把 LLM 网关混为一谈，实际上有三个完全不同的位置：
| 位置 | 能管什么 | 管不到什么 |
|---|---|---|
| 外部入口网关（挡在 shop-agent HTTP 前） | 进来的 HTTP 请求 | shop-agent 内部的 LLM 子调用 |
| 内嵌模块（进程内 SDK 包装） | 当前进程内的所有 LLM 调用 | 跨服务的调用、其他语言栈 |
| 独立服务（本系列方案） | 所有服务的所有 LLM 流量 | 前提是客户端都指向它 |
最容易踩的坑是只做"外部入口网关"------请求进了 shop-agent 之后发生的子调用全部穿透，治理形同虚设。内嵌模块能抓全进程内调用，但跨服务不共享、语言绑定、与业务耦合，扩展到多服务时处处补丁。
决策：独立网关 = 治理 100% 覆盖，前提是流量强制经网关。内嵌 = 跨服务必然有缝。
调用拓扑
外部/前端 → shop-agent → gateway → 托管云(百炼/Azure/Bedrock) / 本地推理(Ollama)
↑
monitoring-agent 探 /health（不过网关）关键关系：
- shop-agent 的 LLM SDK
base_url指向 gateway（环境变量LLM_GATEWAY_URL） - monitoring-agent 探
gateway/health但不过网关，否则污染 LLM 计量 - K8s 内走
gateway:8001；裸跑回退真实供应商（一套代码三环境）
这个位置天然把 LLM 流量切成三段可观测/可拦截的边界，也是注入检测的三道闸门：
- 入向（shop-agent → gateway 入口）：Prompt 注入检测的第一道闸
- 治理面（gateway 内部）：脱敏、合规护栏、语义缓存命中均在此发生
- 出向（gateway → 供应商出口）：出站校验（如供应商回传内容里的间接注入 / 数据外泄）
网关必备的四大核心能力
按岗位优先级排序：
| 优先级 | 能力 | 说明 |
|---|---|---|
| 🔴 P0 | 统一入口 + 多供应商路由 | OpenAI 兼容 /v1/chat/completions，后端可切换 |
| 🔴 P0 | 限流 / 配额 / 租户隔离 | 全局令牌桶，按 API Key/tenant |
| 🔴 P0 | 成本治理 | token 计量 + 按 tenant 记账 + 超预算熔断 |
| 🔴 P0 | 可观测性 | Langfuse trace + Prometheus 指标 |
| 🟡 P1 | Guardrails/PII 脱敏 | 集中做敏感信息擦除 / 拦截 |
| 🟡 P1 | 语义缓存 | 相似 prompt 命中缓存，省 token |
| 🟡 P1 | 重试/降级/熔断 | 上游不可用时优雅退化 |
引擎可替换性：gateway 让后端对业务透明
网关维护一张"逻辑模型名 → 具体后端"的映射：
| 逻辑模型名 | 后端 |
|---|---|
tool_select / param |
本地小模型 |
gpt-* |
Azure |
claude* |
Bedrock |
qwen* |
百炼（阿里） |
调用方只认逻辑名，后端切换对业务透明。换推理引擎（vLLM↔Ollama）只改 gateway 一处配置------这是独立网关的核心收益。网关只认 OpenAI 兼容端点，背后是 Ollama 还是 vLLM 对业务无感。
为什么是独立服务，而不是内嵌模块
三个理由：
- 独立扩缩：网关无状态转发层，可水平扩容；shop-agent 占内存，扩缩节奏不同
- 独立发布：改路由策略 / 加供应商 / 调阈值，不动 shop-agent
- 治理完整性：独立部署才能抓全所有服务的流量
但独立部署有代价------网关自身成为关键依赖，需要 HA / 多副本。更关键的是：必须配出口网络策略封死 shop-agent 直连供应商。
这里用了两层硬化：
- 代码级 ：
resolve_llm_base_url()缺网关地址即抛GatewayNotConfigured拒启，不再有公网 fallback - 网络级：K8s NetworkPolicy 白名单禁止 shop-agent 出公网，gateway 是唯一可出网 443 的负载
HA 不可破坏无旁路不变量
多副本只为网关自身 HA，故障切换目标必须仍是另一实例网关，绝不能退回直连供应商------否则"100% 覆盖"在切换瞬间破防，前面所有治理白做。
网关宕机时的处置边界也需要显式决策：
- fail-closed：拒绝全部 LLM 流量（合规优先级高时选此）
- fail-open：放行绕过（非敏感流量可选）
选型决策：基于 LiteLLM 二次开发
MVP 不再选纯自研骨架，而是以 LiteLLM Proxy 为底座，缺失能力二次开发。理由：
LiteLLM 开箱即用的能力（零开发）
| 能力 | 说明 |
|---|---|
| 多厂商路由 | 支持百炼/Azure/Bedrock/Ollama 等主流后端，按模型名分流 |
| OpenAI 兼容接口 | 对外暴露 /v1/chat/completions，业务 SDK 零改动 |
| 基础限流 | 内置 token bucket，按 API Key/tenant 隔离 |
| 基础成本追踪 | 按请求计量 token 消耗，接 Prometheus 指标 |
| fallback 链 | 同模型跨厂商故障转移，对业务透明 |
| 重试/降级 | 上游超时/不可用时自动切换备用后端 |
需二次开发的能力（治理耦合层）
这些是"通用网关"不具备、但本项目治理必须的定制能力：
| 能力 | 二次开发方式 | 技术路径 |
|---|---|---|
| 语义缓存（08） | callback hook | LiteLLM Proxy 的 request/response callback 注册缓存命中短路逻辑 |
| 跨平面 PII 脱敏（06/07） | 中间件链 | 在 LiteLLM 的 request/response 管道中插入脱敏中间件，控制编排顺序 |
| 三道注入检测（10） | 中间件链 + callback | 输入/输出侧用中间件拦截，工具参数用 callback 检测 |
| 治理钩子编排顺序（先注入→后脱敏→再缓存） | 自定义中间件栈 | 替换 LiteLLM 默认管道，确保检测链条的纵深防御顺序 |
| 失控循环防护（05） | callback hook | 在 request callback 中加入指纹检测与熔断逻辑 |
| 预算熔断（03） | callback hook | 在请求前校验租户预算，超限即短路 |
| monitoring-agent RCA 对接（04） | export callback | 在 response callback 中聚合 golden signal 指标 |
二次开发的技术原则
- 优先 callback/hook 机制 ：LiteLLM Proxy 提供了丰富的 callback 接口（
before_request/after_request/before_response/after_response），绝大多数定制能力通过注册 callback 即可实现，无需 fork 源码 - 严格控制编排顺序用中间件链：当需要强制"先注入检测→后 PII 脱敏"的纵深防御顺序时，用自定义中间件链替代 LiteLLM 默认管道，确保检测链条无缝
- 不 fork LiteLLM 源码：fork 会导致升级困难，所有定制通过 callback 或中间件实现，保持与上游同步
为什么选这种混合架构
- 路由/限流/成本等通用能力：LiteLLM 已做成熟，自研是重复造轮子，且容易遗漏边界 case
- 治理耦合层：语义缓存、PII 脱敏、注入检测等能力与治理逻辑深度耦合，是 LiteLLM 的通用定位不覆盖的区域，也是本项目的核心价值所在
- 零额外网络跳：二次开发的中间件/callback 与 LiteLLM 同进程，不引入额外网络延迟，保持"治理同生命周期"的架构优势
- 升级友好：不 fork 源码，跟随 LiteLLM 版本升级，持续获得新后端支持与 bug 修复
核心要点
- 网关不是"多一层"，而是治理完整性的前提；它让 shop-agent 无感知地获得路由 / 限流 / 成本 / 合规 / 可观测。
- 100% 治理覆盖的前提是出口网络策略强制流量经网关，否则"唯一出口"只是约定。
- 引擎可替换性是独立网关的核心收益------换后端只改网关配置。
- HA 不能破坏无旁路不变量------切换目标是另一实例网关，绝不能退回直连。
- 基于 LiteLLM 二次开发：通用能力（路由/限流/成本）用现成，治理耦合层（语义缓存/PII/注入检测）通过 callback hook + 中间件链定制，不 fork 源码