作业17 · 模型路由配置发布 Runbook（一页）

对象：LiteLLM / 等价网关的 模型路由 YAML（本环境 207:4000）。
原则：配置即发布 — 有 PR/检查清单、有备份、有验收、有审计、能回滚。

0. 什么算「模型路由配置」

文件	内容
`patches_cursor/LiteLLM部署/config.yaml`	生产源（同步到 `/opt/litellm/config.yaml`）
`litellm-routing-primary-backup.yaml`	主备 + fallbacks 样例（作业17）
作业13 `config.yaml`	测试 `:4010`，压测/主备演练

关键字段：model_name（对外名）、api_base（upstream）、fallbacks、timeout、max_retries。

1. 发布前（Pre-flight）

#	检查项	命令/方法
1	变更在 Git 分支，非 SSH 手改	`git diff patches_cursor/LiteLLM部署/config.yaml`
2	测试环境已验证（`:4010` 或 staging）	curl primary / backup
3	备份现网 config	`cp config.yaml config.yaml.bak.$(date +%Y%m%d_%H%M%S)`
4	业务低峰 / 已通知	—
5	回滚命令写在 PR	见 §4
6	GPU/上游健康（若改 upstream）	116 `nvidia-smi`；vLLM `/health`
7	K8s 侧（若同步发 Deployment）	Operator + `Insufficient nvidia.com/gpu` 预查

2. 发布执行

2.1 仅改 LiteLLM 路由（207 现网路径）

bash

# 207
cd /opt/litellm
cp config.yaml config.yaml.bak.$(date +%Y%m%d_%H%M%S)
# 合并新 config（rsync/scp 自 workbuddy patches）
docker compose restart litellm
docker compose logs litellm --tail 30

2.2 改备模 / 增 fallback

增加 model_name: xxx-backup 指向备 upstream
在 litellm_settings.fallbacks 增加 primary: [backup]
重启后必须验证 fallback（staging 停 primary 或作业13 模拟）

2.3 同步 K8s Deployment（实验集群）

bash

kubectl apply --dry-run=server -f vllm-qwen-deployment.yaml -n ai-inference
kubectl apply -f vllm-qwen-deployment.yaml -n ai-inference
kubectl rollout status deployment/vllm-qwen3-6-27b -n ai-inference
kubectl get events -n ai-inference --sort-by='.lastTimestamp' | grep -iE 'nvidia|gpu'

3. 发布后验收

bash

# LiteLLM
curl -sS http://192.168.110.207:4000/v1/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

curl -sS http://192.168.110.207:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.6-27b","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

# vLLM 排队（116）
curl -sS http://116.62.10.183:8000/metrics | grep vllm_num_requests_waiting

| 通过标准 | | |----------|--| | /v1/models 含目标模型 | ✓ | | chat 200 且有 content | ✓ | | 无大规模 5xx/429（对比发布前 5 分钟） | ✓ | | Langfuse 抽样 Trace 正常 | 可选 |

4. 回滚

LiteLLM 配置回滚

bash

cd /opt/litellm
cp config.yaml.bak.YYYYMMDD_HHMMSS config.yaml
docker compose restart litellm
# 再跑 §3 验收

K8s 回滚

bash

kubectl rollout undo deployment/vllm-qwen3-6-27b -n ai-inference
kubectl rollout status deployment/vllm-qwen3-6-27b -n ai-inference

顺序：先回滚路由（避免流量打到坏 upstream），再回滚 Deployment（若相关）。

5. 审计记录（必填一行）

字段	示例
时间	2026-08-27 10:30
操作人	oncall
Ticket/PR	OPS-1234 / #56
变更	增 backup fallback；primary api_base 不变
备份路径	`/opt/litellm/config.yaml.bak.20260827_103000`
验收	curl OK；waiting=0
回滚演练	季度/重大变更前在 staging 做过

6. kubectl · NVIDIA 失败速查（与路由发布同日）

bash

kubectl describe pod -n ai-inference -l app=vllm-qwen
kubectl get events -n ai-inference | grep -iE 'nvidia|gpu|Insufficient'
kubectl logs -n gpu-operator -l app=nvidia-device-plugin-daemonset --tail=30

7. 相关

PR 模板生成：hw17_01_发布检查清单PR模板.py
主备压测：作业13 Runbook
上游 429/5xx：作业13 值班单页