05 线上稳定性与可观测

谁能调用？调用哪个模型？超量了怎么办？模型挂了怎么办？
延迟升高怎么办？负载有波峰波谷怎么扩缩？
输出质量变差怎么发现？每调用一次花了多少钱？

普通 API Gateway          AI Gateway（额外能力）
─────────────────        ──────────────────────
路由 / 限流 / 鉴权       模型路由 / token 计费
负载均衡 / 重试          Virtual Key / 租户隔离
                         成本统计 / 模型 Fallback
                         Prompt 审计 / Guardrails
                         context window fallback

model_list:
  - model_name: gpt-4o-mini           # 业务侧看到的模型名（alias）
    litellm_params:
      model: openai/gpt-4o-mini        # 实际后端
      api_key: os.environ/OPENAI_API_KEY
  - model_name: llama-70b-internal
    litellm_params:
      model: openai/default
      api_base: http://vllm-llama70b:8000/v1
      api_key: EMPTY
  - model_name: deepseek-v3
    litellm_params:
      model: openai/default
      api_base: http://sglang-deepseek:30000/v1
      api_key: EMPTY

router_settings:
  routing_strategy: usage-based-routing-v2
  fallbacks:
    - gpt-4o-mini: ["claude-sonnet", "qwen-max"]
  context_window_fallbacks:
    - gpt-4o-mini: ["claude-sonnet"]   # prompt 超长时自动切大上下文模型

general_settings:
  master_key: sk-master-xxx
  database_url: postgresql://...

# 为业务线创建 Virtual Key
curl http://litellm:4000/key/generate \
  -H "Authorization: Bearer sk-master-xxx" \
  -d '{
    "key_alias": "team-nlp-prod",
    "models": ["gpt-4o-mini", "llama-70b-internal"],
    "max_budget": 500.0,
    "budget_duration": "30d",
    "tpm_limit": 100000,
    "rpm_limit": 500,
    "metadata": {"team": "nlp", "env": "prod"}
  }'

请求 → Gateway
      ├─ 鉴权（Virtual Key → 可用模型白名单）
      ├─ 路由决策
      │   ├─ cost-based：选最便宜的
      │   ├─ latency-based：选历史延迟最低的
      │   ├─ usage-based：选当前负载最低的
      │   └─ kv-aware：选 KV Cache 命中最长的节点
      ├─ Fallback（如果主模型不可用）
      └─ 限流（超过 RPM/TPM → 拒绝或排队）

# 业务侧用语义化别名，底层模型可替换
fast-small: gpt-4o-mini / qwen-turbo / llama-8b
fast-medium: gpt-4o / qwen-max / llama-70b
smart: claude-sonnet / gpt-5.5 / deepseek-v4
local-only: vllm-internal（不 fallback 到公网）

# LiteLLM 支持三级限流
tpm_limit: 100000     # tokens per minute
rpm_limit: 500        # requests per minute
max_budget: 500.0     # 预算上限（美元/30天）

router_settings:
  fallbacks:
    - gpt-4o-mini: ["claude-sonnet", "qwen-max"]
  context_window_fallbacks:
    - gpt-4o-mini: ["claude-sonnet"]  # prompt 超长时自动兜底
  allowed_fails: 3                     # 失败 N 次进入冷却
  cooldown_time: 60                    # 冷却 60 秒

主模型：gpt-4o-mini（便宜，快）
  ├─ fallback 1：claude-sonnet（贵但稳）
  └─ fallback 2：qwen-max（国产备选）

注意：fallback 模型可能更贵，不要兜底到比主模型贵 10x 的模型上

router_settings:
  num_retries: 2    # 重试次数（只对 5xx，4xx 不重试）
  timeout: 30       # 单次请求超时（秒）

v1 模型（在线）                  v2 模型（新版本）
     │                               │
     ├─ 90% 流量 ─────────────────────┤
     └─ 10% 流量 ─────────────────→  │
                                     │
                              观察 TTFT/TPOT/质量
                              无异常 → 逐步提升到 100%
                              有异常 → 回滚

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: vllm-hpa
spec:
  scaleTargetRef:
    name: vllm-deployment
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Pods
      pods:
        metric:
          name: vllm_num_requests_waiting  # 排队请求数
        target:
          type: AverageValue
          averageValue: "10"
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 85

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: vllm-keda
spec:
  scaleTargetRef:
    name: vllm-deployment
  minReplicaCount: 1
  maxReplicaCount: 10
  cooldownPeriod: 300          # 缩容冷却 5 分钟
  triggers:
    - type: prometheus
      metadata:
        serverAddress: http://prometheus:9090
        metricName: vllm_queue_depth
        query: vllm:num_requests_waiting
        threshold: "5"

# KServe + KEDA 实现 scale-to-zero
apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
spec:
  predictor:
    minReplicas: 0  # 允许缩到零
    maxReplicas: 5
    scaleTarget: 0
    scaleMetric: concurrency

冷启动超时
├─ 模型加载时间：70B 模型约 3-5 分钟
├─ 优化方案：
│  ├─ 权重预缓存到本地 NVMe（不从 NFS 加载）
│  ├─ keep-warm 至少 1 副本（不完全 scale-to-zero）
│  ├─ startupProbe 给足够时间（failureThreshold > 60）
│  ├─ 客户端 timeout 匹配（不要 30s 就超时）
│  └─ 预热请求（启动后先发一个短 prompt 预热 KV Cache 和 CUDA Graph）
└─ 权衡：不完全 scale-to-zero vs 冷启动延迟

-- LiteLLM SpendLogs 按团队 × 模型的花费矩阵
SELECT
    metadata->>'team' AS team,
    model,
    SUM(spend) AS spend,
    SUM(total_tokens) AS tokens
FROM "LiteLLM_SpendLogs"
WHERE startTime > NOW() - INTERVAL '30 days'
GROUP BY 1, 2 ORDER BY spend DESC;

-- GPU 闲置成本
SELECT
    node,
    (1 - AVG(gpu_utilization)) * gpu_hourly_cost AS idle_cost
FROM dcgm_metrics
GROUP BY 1;

1. 离线评测：定期跑 benchmark（MMLU/HumanEval/C-Eval）
2. 在线采样：1% 生产流量 → 自动评分（LLM-as-a-Judge）
3. RAG 一致性：生成内容 vs 检索文档的 NLI（自然语言推理）分数
4. 用户反馈：点赞/点踩 → 质量信号

L1: GenAI 系统（system, model, provider）
    gen_ai.system: "vllm"
    gen_ai.request.model: "qwen2.5-72b"
    gen_ai.provider: "litellm"

L2: 请求属性（max_tokens, temperature, top_p）
    gen_ai.request.max_tokens: 1024
    gen_ai.request.temperature: 0.3
    gen_ai.request.top_p: 0.9

L3: Token 用量（input_tokens, output_tokens, total_tokens）
    gen_ai.usage.input_tokens: 150
    gen_ai.usage.output_tokens: 320
    gen_ai.usage.total_tokens: 470

L4: 响应属性（finish_reasons, response_id）
    gen_ai.response.finish_reasons: ["stop"]   # 官方为数组
    gen_ai.response.id: "chatcmpl-xxx"

L5: 成本属性（注意：OTel 官方约定目前并无 cost 语义属性，
    以下为 LiteLLM 等厂商的自定义扩展，跨系统不保证一致）
    gen_ai.response.cost.amount: 0.0023        # 非官方
    gen_ai.response.cost.currency: "USD"       # 非官方

L6: Agent/MCP 工具调用（tool_name, tool_call_id, mcp_server）
    gen_ai.tool.name: "search_web"
    gen_ai.tool.call.id: "call_xxx"
    gen_ai.tool.mcp.server: "mcp-search"

# vLLM 启动时启用 OTel
vllm serve Qwen/Qwen2.5-72B-Instruct \
  --otlp-traces-endpoint http://otel-collector:4317

# LiteLLM Proxy 配置 OTel
litellm_settings:
  otel:
    endpoint: http://otel-collector:4317
    service_name: litellm-proxy

# GPU 温度过高
- alert: GPUHighTemperature
  expr: DCGM_FI_DEV_GPU_TEMP > 85
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "GPU {{ $labels.gpu }} 温度过高"

# KV Cache 接近用满
- alert: KVCacheAlmostFull
  expr: vllm:gpu_cache_usage_perc > 0.95
  for: 10m
  labels:
    severity: critical

# 请求排队超过阈值
- alert: VLLMHighQueueDepth
  expr: vllm:num_requests_waiting > 20
  for: 1m
  labels:
    severity: warning

# P99 TTFT 超过 SLA
- alert: HighP99TTFT
  expr: histogram_quantile(0.99, vllm:time_to_first_token_seconds_bucket) > 10
  for: 2m
  labels:
    severity: critical

# 单 Team 日消费异常
- alert: LLMDailyCostSpike
  expr: increase(litellm_spend_metric[1h]) / increase(litellm_spend_metric[1h] offset 1d) > 3
  for: 10m
  labels:
    severity: warning

# NCCL 错包（硬件故障信号）
- alert: NCCLErrorCount
  expr: increase(nccl_errors_total[5m]) > 0
  labels:
    severity: critical

AI Gateway（鉴权/路由/隔离/额度/审计）
    ↓
稳定性（限流/熔断/fallback/超时/重试/灰度/回滚）
    ↓
弹性伸缩（HPA(KEDA) / scale-to-zero / 冷启动 / GPU-aware 指标）
    ↓
可观测（系统指标 + 成本指标 + 效果指标）
    ↓
技术栈（OTel GenAI / DCGM / Prometheus / Grafana / Loki / Jaeger / Langfuse）