LiteLLM 高级功能与用法

环境：192.168.110.207:4000（生产 systemd）；测试主备 :4010（作业13）
基础部署：见 LiteLLM 部署
HTML：docs/html_cursor/LiteLLM_高级功能与用法_cursor.html

0. 这篇专题解决什么

LiteLLM 在本平台不只是「把 OpenAI 格式转发到 vLLM」。运维和开发常问的五件事：

能力	一句话
密钥	进门用 Master Key；打上游用各条 `api_key`
多厂商 / 多上游路由	客户端 `model` 决定走 vLLM 还是 Xinference
Fallback	主模型失败自动切备模型
Token / 成本	单次看 `usage`；汇总走 Langfuse + 作业4
网关指标	健康检查 + SLA Exporter + 上游 vLLM metrics

flowchart LR
  Client[Dify / curl / SDK]
  LLM[LiteLLM :4000]
  VLLM[116 vLLM :8000]
  XF[207 Xinference :9997]
  LF[Langfuse :3000]
  SLA[SLA Exporter :8781]

  Client -->|Bearer sk-litellm-...| LLM
  LLM -->|model=chat| VLLM
  LLM -->|model=bge-m3| XF
  Client -.->|Tracing| LF
  SLA -.->|组件探活| LLM

1. 配置文件与生效路径

文件	角色
`patches_cursor/LiteLLM部署/config.yaml`	源头（Git 管）
`/opt/litellm/config.yaml`	运行时（systemd 读这份）
`patches_cursor/LiteLLM部署/.env`	`LITELLM_MASTER_KEY`
`/etc/systemd/system/litellm.service`	环境变量 + 启动命令

改配置标准流程：

bash

# Windows 项目根
python scripts_cursor/00_部署_workbuddy到207.py
python scripts_cursor/LiteLLM部署/LiteLLM_01_部署.py
# 或 207 上：
cp /opt/workbuddy/patches_cursor/LiteLLM部署/config.yaml /opt/litellm/config.yaml
sed -i 's#http://host.docker.internal:9997/v1#http://127.0.0.1:9997/v1#g' /opt/litellm/config.yaml
systemctl restart litellm

生产路由变更请对照作业17 模型路由配置发布 Runbook：备份 → diff → 重启 → curl 验收 → 审计。

2. 密钥（两层，别混）

2.1 两层 Key 对照

类型	方向	本环境示例	配置位置
Master Key	客户端 → LiteLLM	`sk-litellm-bocheng-207`	`.env`、`litellm.service`
上游 api_key	LiteLLM → vLLM / Xinference	`123456`、`xf-...`	`model_list` 各条

text

你的 curl / Dify
  │  Authorization: Bearer sk-litellm-bocheng-207   ← 进门钥匙
  ▼
LiteLLM :4000
  │  按 model 选路由，代填上游 key
  ├─ vLLM      api_key: "123456"
  └─ Xinference api_key: "xf-..."

2.2 查看 Master Key

bash

cat patches_cursor/LiteLLM部署/.env
grep LITELLM_MASTER_KEY /etc/systemd/system/litellm.service

config 引用环境变量（不写死）：

yaml

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

2.3 轮换 Master Key

bash

openssl rand -hex 24
# 或
python -c "import secrets; print('sk-' + secrets.token_urlsafe(24))"

改 .env 与 litellm.service 的 LITELLM_MASTER_KEY
systemctl daemon-reload && systemctl restart litellm
同步改：Dify 模型供应商 Key、Higress 探测、各脚本 _config.py

2.4 虚拟 Key（按应用分权 / 限额）

LiteLLM 原生支持为不同团队发独立 Key、设预算，但需要 PostgreSQL + Admin UI，当前 :4000 未启用——全平台共用一把 Master Key。

若二期要开：配 DB → 启 LiteLLM UI → 为「客服 Agent」「运维 Agent」各发 Key → Dify 供应商填子 Key 而非 Master Key。

3. 多厂商 / 多上游路由

3.1 路由规则

Key 管能不能进门；model 管进门后走哪条上游。

客户端 `"model"`	命中 `model_name`	上游
`qwen3.6-27b` / `qwen`	同名或别名	116 vLLM
`bge-m3`	`bge-m3`	207 Xinference
`demo-lb`	同名多条	负载均衡

3.2 新增一条路由

在 model_list 追加（示例 demo-chat）：

yaml

  - model_name: demo-chat
    litellm_params:
      model: openai/qwen3.6-27b
      api_base: http://116.62.10.183:8000/v1
      api_key: "123456"
      timeout: 300
      max_retries: 2
      extra_body:
        chat_template_kwargs:
          enable_thinking: false

model_name：客户端填的逻辑名
litellm_params.model：openai/ + 上游真实模型 id
api_base / api_key：该上游地址与密钥

验证：

bash

curl -s http://192.168.110.207:4000/v1/models \
  -H "Authorization: Bearer sk-litellm-bocheng-207"

curl -s http://192.168.110.207:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-litellm-bocheng-207" \
  -H "Content-Type: application/json" \
  -d '{"model":"demo-chat","messages":[{"role":"user","content":"你好"}],"max_tokens":64}'

3.3 走 LiteLLM 时还要不要带 `xf-...`？

不要。 客户端只带 Master Key；Xinference 的 xf-... 已在 bge-m3 那条配置里，由 LiteLLM 代填。

bash

curl -s http://192.168.110.207:4000/v1/embeddings \
  -H "Authorization: Bearer sk-litellm-bocheng-207" \
  -H "Content-Type: application/json" \
  -d '{"model":"bge-m3","input":"测试文本"}'

3.4 经 Higress 总入口

对外 Base URL 可改为 http://192.168.110.207:18080/llm/v1，Key 仍是 sk-litellm-bocheng-207。详见 Higress 之三。

4. 负载均衡（同名多机）

4.1 自动均衡

同一个 model_name 写多条 → LiteLLM 视为同一逻辑模型的多台部署：

yaml

  - model_name: demo-lb
    litellm_params:
      model: openai/fake-qwen-a
      api_base: http://127.0.0.1:18001/v1
      api_key: "fake-key-a"
      timeout: 10
      max_retries: 0

  - model_name: demo-lb
    litellm_params:
      model: openai/fake-qwen-b
      api_base: http://127.0.0.1:18002/v1
      api_key: "fake-key-b"
      timeout: 10
      max_retries: 0

router_settings:
  routing_strategy: simple-shuffle

客户端始终 "model":"demo-lb"；/v1/models 对外只显示一个逻辑名。

学习示例里 18001/18002 故意不存在，调用失败属预期；生产换成两台真实 vLLM 即可。

4.2 钉死某一台（排障 / 灰度）

为每台再挂唯一别名：

客户端 `model`	行为
`demo-lb`	自动 shuffle
`demo-lb-a`	钉死 A 机
`demo-lb-b`	钉死 B 机

5. Fallback（主备自动切换）

5.1 配置形态

主、备各一条 model_list（model_name 可不同）
在 litellm_settings.fallbacks 声明映射

测试环境（作业13，:4010，勿覆盖生产 :4000）：

yaml

# patches_cursor/作业13_虚拟模型主备/config.yaml
litellm_settings:
  fallbacks:
    - primary: [backup]

启动：

bash

python -m litellm --config patches_cursor/作业13_虚拟模型主备/config.yaml --port 4010

生产主备样例（作业17）：

yaml

  - model_name: qwen3.6-27b
    litellm_params:
      api_base: http://116.62.10.183:8000/v1   # primary

  - model_name: qwen3.6-27b-backup
    litellm_params:
      api_base: http://116.62.10.183:8001/v1   # backup

litellm_settings:
  fallbacks:
    - qwen3.6-27b: [qwen3.6-27b-backup]

完整样例文件：patches_cursor/作业17_K8s与模型路由/litellm-routing-primary-backup.yaml

5.2 操作要点

步骤	说明
先在 `:4010` 练	用模拟 upstream 停 primary 观察是否切 backup
备份现网 config	`cp config.yaml config.yaml.bak.$(date +%Y%m%d_%H%M%S)`
重启	`systemctl restart litellm`
验收	chat 200；故意打挂 primary 看 fallback

客户端 model 仍填主名（如 qwen3.6-27b），切换由网关内部完成。

6. Token / 成本统计

6.1 三层能力

层级	怎么看	本环境
单次	响应 `usage` 字段	LiteLLM 直接返回
汇总 / 排行 / 告警	Langfuse UI + 脚本	主路径
LiteLLM 内置 Spend	Admin UI + DB	未启用

6.2 单次 Token（LiteLLM 响应）

bash

curl -s http://192.168.110.207:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-litellm-bocheng-207" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.6-27b","messages":[{"role":"user","content":"hi"}],"max_tokens":32}'
# usage: { "prompt_tokens", "completion_tokens", "total_tokens" }

6.3 平台级汇总（Langfuse）

能力	文档 / 工具
Trace / Generation / 成本视图	Langfuse 部署教程；UI `:3000`
字段规范 + Top10	作业14
日预算告警 + 超阈值降级	作业4 成本熔断
周报 Token 汇总	作业6

Dify 模型指到 http://192.168.110.207:4000/v1 且 Tracing 开 Langfuse 后，按应用/会话聚合 Token。

6.4 为何不用 LiteLLM 自带成本面板

LiteLLM Spend / 按 Key 预算需 PostgreSQL 与 Admin UI。本环境成本治理走 Langfuse + 作业4，与 Dify Agent 熔断联动，不重复建一套 LiteLLM 账本。

7. 网关侧指标输出

7.1 当前已有什么

层级	地址	用途
LiteLLM 存活	`:4000/health/liveliness`	网关是否活着
平台 SLA	`:8781/metrics`	组件 up/down、可用率
Prometheus	`:9092`	抓 SLA exporter
Grafana	`:3001`	大盘
vLLM 推理	`116.62.10.183:8000/metrics`	排队、吞吐
链路级	Langfuse `:3000`	延迟、错误、Token

值班最小命令集：

bash

curl -sf http://192.168.110.207:4000/health/liveliness
curl -sf http://192.168.110.207:8781/metrics | grep ai_platform
curl -s http://116.62.10.183:8000/metrics | grep vllm_num_requests

详见集成环境部署 · Prometheus + Grafana + SLA、作业8 SLA 监控大盘。

7.2 LiteLLM 原生 Prometheus（未开，可扩展）

当前 config.yaml 未启用 LiteLLM 自身 /metrics。若需网关级 QPS/延迟 histogram，可在验证版本兼容后追加：

yaml

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  enable_prometheus_metrics: true

并在 patches_cursor/作业8_SLA监控大盘/prometheus/prometheus.yml 增加 scrape job 指向 :4000/metrics。

8. 场景速查

我想…	改什么	在哪练
换进门钥匙	`.env` + systemd + Dify Key	生产前先在 staging curl
加一个新模型别名	`model_list` 加一条	`LiteLLM_02_验收.py`
同一名字打两台 vLLM	同名两条 + `router_settings`	`demo-lb` 示例
主挂掉自动切备	`fallbacks`	作业13 `:4010`
看谁烧 Token 最多	Langfuse + hw14	`:3000`
日预算爆了告警	作业4 脚本	Langfuse 累计
看 vLLM 排队	116 metrics	排错 SOP
发布路由变更	Git PR + 备份 + 重启	作业17 Runbook

9. 相关文档

文档	关系
LiteLLM 部署	安装、验收、基础 curl、学习案例 Q&A
作业13 虚拟模型主备	Fallback + 压测到 429
作业17 模型路由发布	生产 config 当发布
作业14 Langfuse Token	成本汇总规范
作业4 成本熔断	日预算 + 降级
Higress 之五新增接口场景	何时改 LiteLLM / Higress

10. 排错速表

现象	优先查
401	Bearer 是否 `sk-litellm-bocheng-207`
找不到 model	`model` 拼写；`/v1/models` 列表
chat 空 content	Qwen thinking 占 token；`enable_thinking: false`
embeddings 失败	Xinference `:9997`；config 里 `api_base` 是否已 sed 成 `127.0.0.1`
fallback 没切	`fallbacks` 语法；primary 是否真失败；看 `journalctl -u litellm`
改了 config 不生效	是否 cp 到 `/opt/litellm/` 并 restart

LiteLLM 高级功能与用法

LiteLLM 高级功能与用法

0. 这篇专题解决什么

1. 配置文件与生效路径

2. 密钥（两层，别混）

2.1 两层 Key 对照

2.2 查看 Master Key

2.3 轮换 Master Key

2.4 虚拟 Key（按应用分权 / 限额）

3. 多厂商 / 多上游路由

3.1 路由规则

3.2 新增一条路由

3.3 走 LiteLLM 时还要不要带 xf-...？

3.4 经 Higress 总入口

4. 负载均衡（同名多机）

4.1 自动均衡

4.2 钉死某一台（排障 / 灰度）

5. Fallback（主备自动切换）

5.1 配置形态

5.2 操作要点

6. Token / 成本统计

6.1 三层能力

6.2 单次 Token（LiteLLM 响应）

6.3 平台级汇总（Langfuse）

6.4 为何不用 LiteLLM 自带成本面板

7. 网关侧指标输出

7.1 当前已有什么

7.2 LiteLLM 原生 Prometheus（未开，可扩展）

8. 场景速查

9. 相关文档

10. 排错速表

3.3 走 LiteLLM 时还要不要带 `xf-...`？