5. 核心模块
一句话理解：LLM Gateway 的功能可以被拆成若干独立模块，每个模块只负责一个横切关注点，并通过配置组合成完整的数据面流水线。
模块总览
1. Config Manager
职责：加载、校验、热更新网关配置。
配置通常分为：
- provider 配置：endpoint、model alias、timeout、retry、weight、priority。
- 路由规则：按 model / tenant / header / prompt 特征匹配。
- 限流策略：token bucket 参数、作用维度。
- 密钥映射：api_key → tenant / quota / allowed_models。
- 转换模板：OpenAI ↔ 上游私有协议的字段映射。
支持格式：YAML、JSON，生产环境常从对象存储或配置中心（Consul、etcd、Kubernetes ConfigMap）加载。
热更新要求：
- 配置变更后数据面不重启即可生效。
- 部分变更（如 provider 权重）应原子切换，避免 half state。
- 错误配置不应直接 panic，而是标记为 invalid 并保留旧配置。
2. Provider Registry
职责：管理所有上游 provider 的元数据与健康状态。
每个 provider 包含：
providers:
openai-primary:
kind: openai
api_base: https://api.openai.com/v1
api_key_ref: vault://openai/api-key
models: [gpt-4o, gpt-4o-mini]
timeout: 30s
weight: 70
priority: 1
health_check:
path: /v1/models
interval: 30sRegistry 需要：
- 按 model alias 索引 provider 列表。
- 维护 provider 健康状态（healthy / unhealthy / degraded）。
- 支持动态上下线，例如 canary 发布。
- 把真实 API key 的获取委托给 Secret Manager。
3. Auth Middleware
职责：验证请求身份，并注入 tenant / user / allowed_models 等上下文。
常见实现：
- API Key：从
Authorization: Bearer <key>提取，查表得到 tenant。 - JWT/OAuth2：校验 token 签名与 scope，解析出用户身份。
- mTLS：服务间调用使用客户端证书。
关键注意：
- key 不要明文落盘；使用 hash 或外部 secret store。
- 认证失败立即返回 401，减少后续资源消耗。
- 可以在上下文中注入
request_id，用于全链路 tracing。
4. Rate Limiter
职责：按多维度控制请求速率，保护上游与自身。
常用 Token Bucket 实现：
class TokenBucket:
def __init__(self, capacity, refill_rate):
self.capacity = capacity
self.tokens = capacity
self.refill_rate = refill_rate
self.last_refill = time.monotonic()
def allow(self, tokens=1):
now = time.monotonic()
self.tokens = min(self.capacity,
self.tokens + (now - self.last_refill) * self.refill_rate)
self.last_refill = now
if self.tokens >= tokens:
self.tokens -= tokens
return True
return False生产要点：
- 维度键：
<tenant>:<model>、<api_key>、<user>等。 - 分布式场景用 Redis 存储 bucket 状态，
INCR+EXPIRE实现滑动窗口。 - 响应头里返回剩余配额，方便客户端自适应降速。
5. Router
职责：根据策略从候选 provider 中选择目标。
常见策略已在 核心思想 中介绍。Router 内部通常抽象为：
def select(model_alias, context, candidates) -> Provider:
strategy = get_strategy(model_alias, context)
return strategy.pick(candidates, context)Router 还要处理：
- 模型别名冲突：优先级与 tenant 隔离。
- provider 不可用：过滤掉不健康实例。
- A/B 测试：按 header / user_id 切流量。
6. Load Balancer
职责：在 provider 内部选择一个具体实例。
在自托管 vLLM/Triton 集群中，provider 往往有多个实例：
providers:
vllm-cluster:
kind: openai
instances:
- url: http://10.0.1.10:8000
- url: http://10.0.1.11:8000
- url: http://10.0.1.12:8000算法：
- Round-robin：简单公平。
- Least-connections：避免长连接堆积。
- Least-queue / KV-cache-aware：需要暴露实例内部队列长度或显存状态，较为高级。2025 年后这一档成为自托管集群的标配：通过 Gateway API Inference Extension 的 Endpoint Picker 读取 vLLM 各副本的 KV cache 前缀命中与队列深度做路由（详见 架构设计），Higress 的 AdaptiveScore 负载均衡也综合了首 Token 延迟、并发与失败率打分。
7. Retry / Fallback / Circuit Breaker
职责：把上游的不稳定性封装起来，对外提供稳定服务。
Retry
- 只对可重试错误（5xx、429、网络超时）。
- 指数退避：
backoff = min(base * 2^attempt, max_backoff)。 - 带 jitter，避免惊群。
Fallback
- 主 provider 失败后，降级到备用 provider 或更便宜模型。
- fallback 链：
primary → backup → cheapest → static error。 - 注意：fallback 模型可能能力 weaker，业务需能容忍。
Circuit Breaker
- 状态机：
CLOSED → OPEN → HALF-OPEN → CLOSED。 - 触发条件：连续失败数或时间窗口失败率。
- 冷却时间与半开探测流量防止抖动。
8. Transformer
职责：统一不同 provider 的请求/响应格式。
OpenAI-compatible provider（vLLM、Triton OpenAI frontend、LiteLLM）通常直接透传。
非标准 provider 需要转换：
- 字段映射：
messages→prompt。 - 参数适配：
temperature范围不一致时做 clamp。 - 流式格式：统一 SSE chunk schema。
- 错误码映射：把各 provider 的自定义错误码转成 OpenAI 风格。
9. Metrics
职责：采集并暴露网关运行指标。
核心指标：
| 指标名 | 类型 | 标签 | 说明 |
|---|---|---|---|
llm_gateway_requests_total | Counter | model, provider, status | 请求总数 |
llm_gateway_latency_seconds | Histogram | model, provider, stage | 各阶段延迟 |
llm_gateway_tokens_total | Counter | model, provider, type | input/output token 数 |
llm_gateway_cost_usd_total | Counter | model, provider | 预估成本 |
llm_gateway_rate_limited_total | Counter | model, tenant | 被限流次数 |
llm_gateway_fallback_total | Counter | from, to | fallback 次数 |
llm_gateway_circuit_breaker_state | Gauge | provider | 熔断器状态 |
2026 年后需补充两类指标：tokens 指标按 input / output / cached / reasoning 分档（cached 计量决定缓存经济账是否算得清），以及 MCP 网关场景下按 Mcp-Method / 工具名聚合的调用量与失败率。
暴露方式：
- Prometheus
/metrics文本端点。 - OpenTelemetry trace：记录请求在各模块的耗时。
- 结构化日志：JSON 格式，包含 request_id、tenant、model、latency、token 用量。
10. Policy Plugin（可选扩展）
职责：执行更高级的安全与治理策略。
- PII 检测：识别并过滤身份证号、手机号、信用卡号。
- 敏感词/越狱检测：基于规则或小型分类模型。
- Prompt 缓存：对重复 prompt 直接返回缓存结果。
- 响应后处理：统一 format、长度限制、引用来源。
Policy Plugin 通常作为可插拔的 hook 链：
request hook -> route -> upstream -> response hook -> return11. Semantic Cache（2025 后普及）
职责：在上游调用前拦截重复/近义请求，直接降低延迟与成本。
request ──► exact hash 查询 ──命中──► 返回
│
└未命中► embedding ──► 向量库近邻搜索 ──命中──► 返回
│
└未命中► 调上游 ──► 写回两级缓存要点：
- 两级级联：精确缓存（Redis 哈希）成本极低，先做；语义缓存（embedding + 向量库）命中率高但每次都花 embedding 费用。
- 相似度阈值：典型 0.85~0.95，业务可配；对答案一致性要求高的场景应偏高或禁用。
- 流式支持：缓存与回放都按 SSE chunk 格式存储，命中时逐 chunk 回放。
- 数据安全：含 PII/机密内容的请求标记为不可缓存；缓存本身也要加密与设 TTL。
12. Guardrails（2025 后普及）
职责：请求与响应两侧的内容安全策略执行。
- 输入：PII 检测/脱敏、越狱与 Prompt Injection 识别、敏感词过滤、Token 用量预检（超长 prompt 直接拒绝）。
- 输出：内容审核、敏感信息回显检查、长度与格式约束。
- 实现形态：内置规则引擎（Kong
ai-prompt-guard、APISIXai-prompt-guard）、hook 外接（LiteLLM guardrails hook 可接 AWS Bedrock Guardrails、Lakera 等）、或内置 50+ 规则（Portkey）。 - 性能：检测在请求关键路径上，必须用异步或小模型做，避免成为延迟瓶颈。
13. MCP Gateway（2025-2026 新增）
职责：面向 Agent 的 MCP 协议接入与工具治理。
- 工具聚合：把多个上游 MCP Server 的工具列表聚合成统一入口，按调用方身份过滤可见工具。
- 工具级鉴权：deny-by-default 白名单 + 按虚拟 key / JWT claims 授权（Agent Router 用
MCPRouteSecurityPolicy+ CEL 表达式实现）。 - 工具级限流与计量：按工具名限流、计费、出指标。
- 协议桥接：modern（无状态 HTTP Tools）↔ legacy（握手 + 会话）双向转换；Higress v2.2.4 起在协议层把方法与工具名放入 HTTP Header，网关无需解析 JSON Body 即可路由与计量。
- 存量 API 转化：Higress 支持把存量 REST API “零代码”包装成 MCP Server，是存量系统接入 Agent 的低成本路径。
本章小结
LLM Gateway 的核心模块——Config、Registry、Auth、Rate Limiter、Router、Load Balancer、Retry/Fallback/CB、Transformer、Metrics、Policy Plugin，加上 2025 年后普及的 Semantic Cache、Guardrails、MCP Gateway——覆盖了从配置到调用、从缓存到安全、从模型到工具的全链路。理解每个模块的职责边界，有助于在真实选型与自研时做出合理拆分。
参考来源