02 · 配置项全景

本文是 LiteLLM 心跳所有可配置参数的速查手册。按照"YAML 全局 → 环境变量 → 单模型字段 → HTTP 端点"四层组织。

字段来源代码位置在每个表格脚注里给出，便于校对版本差异。

---

1. YAML 全局：general_settings

1.1 主表

写在 proxy_server_config.yaml 的 general_settings: 下。读取点：proxy_server.py:3170-3181。

字段	类型	默认	作用	影响
background_health_checks	bool	false	是否启动后台心跳 task	关闭时完全没有任何主动模型 ping，只有手动调 /health 才打
use_shared_health_check	bool	false	是否启用 Redis 协调（多 Pod 去重）	仅 litellm_settings.cache: true + cache_params.type: redis 也成立时才生效
health_check_interval	int	300（秒）	后台 loop 的 tick 间隔	只控制 tick 频率，不直接控制真实 ping 频率（详见下文）
health_check_details	bool	true	/health 端点返回的字段精简度	不影响请求数，只影响响应内容

1.2 health_check_interval 与"真实 ping 节奏"的关系

这是最容易踩的概念坑：

模式	真实 ping 节奏由谁决定
DIRECT（manager 没创建）	health_check_interval，每个 tick 都打模型
SHARED（manager 创建了）	DEFAULT_SHARED_HEALTH_CHECK_TTL（cache TTL）。health_check_interval 只影响"多快能感知到 cache 过期"，绝大部分 tick 都是 cache hit、不打模型

→ 生产上若用 SHARED 模式，把 health_check_interval 设成 30 秒、TTL 设成 1800 秒是合理组合：tick 高频但绝大多数是缓存命中、几乎零成本；TTL 决定真实 ping 频率。

1.3 配置示例

完全关闭后台心跳：

general_settings:
  background_health_checks: false

单 Pod 部署、不需 Redis 协调：

general_settings:
  background_health_checks: true
  use_shared_health_check: false
  health_check_interval: 600    # 每 10 分钟全打一遍

多 Pod 部署、Redis 协调：

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: os.environ/REDIS_HOST
    port: os.environ/REDIS_PORT
    password: os.environ/REDIS_PASSWORD

general_settings:
  background_health_checks: true
  use_shared_health_check: true
  health_check_interval: 30     # tick 高频
  health_check_details: false   # /health 响应更紧凑

---

2. 环境变量

LiteLLM 心跳相关常量定义在 litellm/constants.py:1357-1365：

DEFAULT_HEALTH_CHECK_INTERVAL = int(
    os.getenv("DEFAULT_HEALTH_CHECK_INTERVAL", 300)
)  # 5 minutes
DEFAULT_SHARED_HEALTH_CHECK_TTL = int(
    os.getenv("DEFAULT_SHARED_HEALTH_CHECK_TTL", 300)
)  # 5 minutes - TTL for cached health check results
DEFAULT_SHARED_HEALTH_CHECK_LOCK_TTL = int(
    os.getenv("DEFAULT_SHARED_HEALTH_CHECK_LOCK_TTL", 60)
)  # 1 minute - TTL for health check lock

2.1 主表

环境变量	默认（秒）	作用	何时生效
DEFAULT_HEALTH_CHECK_INTERVAL	300	YAML 没给 health_check_interval 时的兜底	启动时一次性读取
DEFAULT_SHARED_HEALTH_CHECK_TTL	300	shared 模式下真实 ping 节奏的真正控制项	启动时一次性读取，运行中改无效
DEFAULT_SHARED_HEALTH_CHECK_LOCK_TTL	60	leader 抢锁的过期时间，需 ≥ 单次心跳所需总时间	同上

2.2 ⚠️ "导入即冻结"陷阱

上述常量都是模块顶层 os.getenv 调用，只在 Python 第一次 import 该模块时执行一次。一旦 proxy 进程启动，常量值就被冻结，运行中改 env var 不会被读取。

K8s 场景必须确保：

1. 修改 deployment 的 env 后，触发 rolling restart：

   kubectl rollout restart deployment <litellm-deployment>
   kubectl rollout status deployment <litellm-deployment>
   

2. 用 ConfigMap / Secret 注入 env 时，确认 deployment 真的引用了最新版本（不是 stale 的旧 ref）

验证 env 是否进入 Pod 进程：

POD=$(kubectl get pods -l app=litellm-proxy -o jsonpath='{.items[0].metadata.name}')

# A. 看 Pod env
kubectl exec $POD -- env | grep DEFAULT_SHARED_HEALTH_CHECK_TTL

# B. 看 Python 常量真实值（最权威）
kubectl exec $POD -- python -c \
  "from litellm.constants import DEFAULT_SHARED_HEALTH_CHECK_TTL; print(DEFAULT_SHARED_HEALTH_CHECK_TTL)"

详细排障步骤见 04-troubleshooting.md §1.

---

3. 单模型 model_info 字段

写在 model_list 每条目的 model_info: 下，或在 UI 模型编辑页配置。

3.1 主表

字段	类型	默认	作用	代码位置
disable_background_health_check	bool	false	该 deployment 不参与后台轮询	proxy_server.py:2168
health_check_model	string	—	心跳时把 litellm_params.model 替换成此模型	health_check.py:144-146
health_check_timeout	int（秒）	60	单次心跳超时	health_check.py:96
health_check_voice	string	"alloy"	仅 mode=audio_speech 时使用，TTS 测试用 voice	health_check.py:147-148
mode	string enum	自动推断	决定走哪种心跳调用（chat / embedding / 等）	main.py:7104-7118

3.2 mode 合法值（12 种）

依据 litellm/main.py:7041-7058 的 Literal 声明 + health_check_helpers.py:get_mode_handlers 的实际派发：

mode	调用	适合的模型类型
chat	acompletion	多数 chat 模型（GPT / Claude / Gemini / Qwen 等）
completion	atext_completion	古早 completion API（GPT-3 davinci 等）
embedding	aembedding	text embedding（最便宜的心跳模式）
audio_speech	aspeech	TTS（OpenAI / 11labs 等）
audio_transcription	atranscription	STT（whisper 等）
image_generation	aimage_generation	DALL-E / Flux 等
video_generation	avideo_generation	Sora / Veo 等
rerank	arerank	Cohere rerank / 同类
realtime	WebSocket connect-only	OpenAI Realtime
batch	alist_batches	OpenAI / Anthropic batch
responses	aresponses	OpenAI Responses API
ocr	aocr	OCR（Mistral 等）

3.3 配置示例

3.3.1 让贵模型不被自动 ping

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      disable_background_health_check: true   # ← 完全跳过

UI 录入的模型：在模型编辑页找 "Disable background health check" 勾选，或直接 SQL：

UPDATE "LiteLLM_ProxyModelTable"
SET model_info = jsonb_set(
    coalesce(model_info, '{}'::jsonb),
    '{disable_background_health_check}',
    'true'::jsonb
)
WHERE model_name IN ('gpt-4o', 'claude-opus-4-7', 'gemini-2-5-pro');

3.3.2 改打便宜的同家族模型

model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      mode: chat                    # 强制 chat（避免 cost map 里推断成奇怪的）
      health_check_model: gpt-4o-mini   # 心跳时实际打 gpt-4o-mini
      health_check_timeout: 20      # 短一点的超时

适用场景：你信任 gpt-4o-mini 的可用性能反映 gpt-4o（同 region、同 endpoint），但 mini 成本只有 1/30。

3.3.3 通配符 + 替换

model_list:
  - model_name: openai-anything
    litellm_params:
      model: openai/*
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      mode: chat
      health_check_model: gpt-4o-mini   # 通配符也能用

通配符的扇出问题（最多 12 次 / 单 deployment）见 03-cost-reduction.md §wildcard-的隐性放大。

3.3.4 TTS / STT 心跳

model_list:
  - model_name: tts-1
    litellm_params:
      model: openai/tts-1
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      mode: audio_speech
      health_check_voice: nova      # 默认 alloy，可改其他

---

4. HTTP 探针端点速查

这部分是上游能力，列出来方便对照。详见上游 https://docs.litellm.ai/docs/proxy/health 。

端点	文件位置	是否真实 ping 模型	用途
GET /health/liveliness（也可 /liveness）	_health_endpoints.py:1275	❌	K8s liveness probe，永远 200
GET /health/readiness	_health_endpoints.py:1218	❌	K8s readiness probe，检查 DB / Cache / Callback
GET /health	_health_endpoints.py:763	看模式	默认读后台 task 的内存结果；带 ?model=/?model_id=/?cache_off=true 可强制实时 ping
GET /health/services	_health_endpoints.py:186	❌	汇总后台心跳结果 + 服务状态（DB / Redis / Logger 等）
GET /health/latest	_health_endpoints.py:894	❌	从 DB 读最新一次每模型状态（LiteLLM_HealthChecks 表）
GET /health/history	_health_endpoints.py:843	❌	从 DB 读历史状态变化

4.1 /health 强制实时 ping 的姿势

如果想"绕过缓存、立刻打一次某个模型"：

# 单个模型
curl -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  "http://your-proxy/health?model=gpt-4o"

# 单个 deployment
curl -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  "http://your-proxy/health?model_id=25a8bd00-b1ba-489d-92f6-d878bbe46bae"

# 全量并强制不读缓存
curl -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  "http://your-proxy/health?cache_off=true"

⚠️ cache_off=true 会真打所有 deployment，不要在生产 Prometheus scrape 里频繁触发。

---

5. 完整配置组合速查

5.1 推荐：多 Pod + Redis + 重模型跳过

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: os.environ/REDIS_HOST
    port: os.environ/REDIS_PORT
    password: os.environ/REDIS_PASSWORD

router_settings:
  routing_strategy: latency-based-routing
  redis_host: os.environ/REDIS_HOST
  redis_port: os.environ/REDIS_PORT
  redis_password: os.environ/REDIS_PASSWORD

general_settings:
  background_health_checks: true
  use_shared_health_check: true
  health_check_interval: 30          # tick，不影响真实节奏
  health_check_details: false

# Deployment env
- name: DEFAULT_SHARED_HEALTH_CHECK_TTL
  value: "1800"                      # 真实 ping 每 30 min 一次
- name: DEFAULT_SHARED_HEALTH_CHECK_LOCK_TTL
  value: "180"                       # 锁要大于单次 health check 总耗时（28 模型实测 12-30s）

🔧 在本 fork 中，lock_ttl 同时是 follower 等待 leader 写入 cache 的总超时上限（修复了 follower fallback 自打 bug，详见 04 §5）。所以这个值必须确实大于 leader 真实运行时间，否则会出现双 leader。

UI 里给每个贵 deployment 勾选 disable_background_health_check。

5.2 极简：完全关闭心跳，靠 cooldown 自然探测

general_settings:
  background_health_checks: false

完全没有主动心跳，故障感知靠： - Router 的 cooldown 机制（错误请求会自动冷却 deployment 一段时间） - 业务请求自然探测 - 你主动调 /health?model=xxx

5.3 单 Pod 开发环境

general_settings:
  background_health_checks: true
  use_shared_health_check: false
  health_check_interval: 600

直接每 10 分钟把 model_list 全量 ping 一次，简单粗暴。

---

下一步

• 三类成本都怎么来、怎么压：03-cost-reduction.md
• 配置改完没效果：04-troubleshooting.md