LLM 网关与多模型路由：统一入口、策略分流与故障转移

网关不做的事（避免「胖网关」反模式）：
□ 不做提示词工程（那是应用的职责）
□ 不做模型推理（只转发到后端引擎）
□ 不做重业务逻辑（会变成难维护的中间层）
□ 尽量无状态（状态外置到 Redis 等）

# 路由配置示例
routes:
  - match: { model: "gpt-4o" }
    backend: openai
    upstream: "gpt-4o-2024-08-06"
  - match: { model: "fast" }
    backend: self-hosted
    upstream: "http://vllm-fast:8000"
  - match: { model: "claude-*" }
    backend: anthropic

成本路由示例：
□ 输入 < 500 token 且无工具调用 → 小模型（7B）
□ 需要长上下文（> 32K）         → 长上下文模型
□ 命中缓存                       → 直接返回，不走模型
□ 其余                          → 主力大模型

性能路由示例：
□ 延迟敏感（交互）→ 低 TTFT 后端
□ 吞吐敏感（批处理）→ 高吞吐后端
□ 无 SLA 约束 → 排队到最空闲的副本

# 概念示意：用 embedding 相似度选路由
routes = {
    "code":    embed("写代码、调试、编程问题"),
    "math":    embed("数学计算、证明、公式"),
    "chat":    embed("闲聊、问答、通用对话"),
}
def route(query):
    q = embed(query)
    best = max(routes, key=lambda k: cosine(q, routes[k]))
    return model_for(best)   # code→强代码模型，chat→小模型

负载策略：
□ 轮询 / 加权轮询：简单，适合同构副本
□ 最少连接：适合长流式请求（避免某副本堆积）
□ 一致性哈希：带会话亲和（多轮对话复用 KV cache）
□ 优先级：付费租户优先

健康检查：
□ 主动探活（/health）→ 剔除故障副本
□ 被动熔断（错误率/超时率超阈值）→ 临时摘除
□ 半开恢复（试探性放量）→ 恢复后回归

路由决策的组合顺序（典型）：
1. 鉴权 + 配额检查（超限直接拒）
2. 缓存命中检查（命中直接返回）
3. 显式模型指定？（有 → 静态路由）
4. 策略路由（成本/语义/性能）
5. 负载均衡选副本（含健康过滤）
6. 转发 + 记录成本与指标

# 网关内部：把统一请求翻译成各家格式
def to_anthropic(req):
    system = [m["content"] for m in req["messages"] if m["role"] == "system"]
    msgs = [m for m in req["messages"] if m["role"] != "system"]
    return {
        "model": req["model"],
        "system": system[0] if system else None,
        "messages": msgs,
        "max_tokens": req.get("max_tokens", 1024),
        "stop_sequences": req.get("stop", []),
    }

流式转发的关键点：
□ 逐块转发，别缓冲整个响应（否则失去流式意义）
□ 统一 SSE 事件格式（各家 event 名不同）
□ 客户端断连时及时取消上游请求（省算力）
□ 计费：流式下 token 数从 usage 或累计块推算
□ 超时：流式请求的超时应是「首块超时 + 空闲超时」双阈值

限流维度（从粗到细）：
□ 全局：保护整个网关不被打爆
□ 租户/API Key：防单租户挤占
□ 模型：某模型的总并发上限
□ 请求级：单请求 max_tokens 上限（防超长生成）

限流算法：
□ 令牌桶：允许突发，适合交互
□ 漏桶：平滑输出，适合保护后端
□ 滑动窗口：精确计数，适合配额
□ 并发信号量：限制同时在飞请求数（LLM 最常用）

# 配额配置示例
tenants:
  - id: team-a
    rpm: 600          # 每分钟请求
    tpm: 200000       # 每分钟 token
    concurrent: 32    # 最大并发
    models: ["gpt-4o", "fast"]
    monthly_budget_usd: 2000

成本计算（网关侧）：
cost = input_tokens × 单价_in + output_tokens × 单价_out
按租户累加 → 与预算对比 → 超限告警/限流
→ 单位经济学（$/1K 请求、$/用户）可反推定价

高可用设计要点：
□ 网关无状态化 → 多副本水平扩展 + 负载均衡
□ 配置外置（DB/配置中心）→ 副本共享路由规则
□ 优雅重启 → 在飞请求不中断
□ 依赖隔离 → 缓存/计费挂了不阻塞主链路

故障转移策略：
□ 重试：同后端换副本重试（幂等前提下）
□ 降级：大模型不可用 → 路由到小模型兜底
□ 熔断：错误率超阈值 → 摘除该后端，定期半开试探
□ 超时分层：连接超时 / 首块超时 / 总超时

# 熔断器概念示意
class Breaker:
    def __init__(self, threshold=0.5, window=60):
        self.fail, self.total, self.state = 0, 0, "closed"
    def call(self, fn):
        if self.state == "open":
            raise BackendUnavailable()
        try:
            r = fn(); self._ok(); return r
        except Exception:
            self._fail()
            if self.fail / max(self.total, 1) > self.threshold:
                self.state = "open"      # 熔断，走降级
            raise

降级链示例：
主模型（GPT-4o） → 备用（Claude） → 小模型（本地 7B） → 静态兜底话术
每一级都设超时与熔断，避免「降级也超时」拖垮整体

网关侧必采指标：
□ 请求量 / 错误率 / 延迟（按模型、租户、路由规则分维度）
□ 各后端健康度（成功率、P99 延迟、熔断状态）
□ 缓存命中率（精确 + 语义）
□ token 消耗与成本（按租户/模型）
□ 路由分布（各后端承接了多少流量）
□ 限流触发次数（谁被限了、限了多少）

灰度发布：
□ 新模型/新提示词按流量比例灰度（如 5%）
□ 对比新旧版本的质量与成本指标
□ 支持按租户/用户定向放量
□ 出问题一键回滚（路由配置切回旧版本）