团队有三个服务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 SDKbase_url指向 gateway环境变量LLM_GATEWAY_URLmonitoring-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 指标 P1Guardrails/PII 脱敏集中做敏感信息擦除 / 拦截 P1语义缓存相似 prompt 命中缓存省 token P1重试/降级/熔断上游不可用时优雅退化引擎可替换性gateway 让后端对业务透明网关维护一张逻辑模型名 → 具体后端的映射逻辑模型名后端tool_select/param本地小模型gpt-*Azureclaude*Bedrockqwen*百炼阿里调用方只认逻辑名后端切换对业务透明。换推理引擎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 链同模型跨厂商故障转移对业务透明重试/降级上游超时/不可用时自动切换备用后端需二次开发的能力治理耦合层这些是通用网关不具备、但本项目治理必须的定制能力能力二次开发方式技术路径语义缓存08callback hookLiteLLM Proxy 的request/responsecallback 注册缓存命中短路逻辑跨平面 PII 脱敏06/07中间件链在 LiteLLM 的 request/response 管道中插入脱敏中间件控制编排顺序三道注入检测10中间件链 callback输入/输出侧用中间件拦截工具参数用 callback 检测治理钩子编排顺序先注入→后脱敏→再缓存自定义中间件栈替换 LiteLLM 默认管道确保检测链条的纵深防御顺序失控循环防护05callback hook在requestcallback 中加入指纹检测与熔断逻辑预算熔断03callback hook在请求前校验租户预算超限即短路monitoring-agent RCA 对接04export callback在responsecallback 中聚合 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 源码 
