litellm

LiteLLM AI 网关运维

使用此技能将 LiteLLM 作为组织的 AI 网关运行：启动代理 （litellm --config config.yaml），通过一个兼容 OpenAI 的 API 将请求路由到 100 多家 LLM 提供商，管理模型列表、路由与可靠性、虚拟密钥、团队、预算和速率限制、缓存、护栏、可观测性和支出，并通过证据诊断故障。LiteLLM 提供两种使用方式：Python SDK （litellm.completion()，进程内运行）和代理（运行于端口 4000 的 FastAPI 服务，包含密钥、预算和管理界面）。这是针对指定工具的工具技能。 引擎选择和服务方法属于 ml-engineering；单个引擎的运维属于 vllm 或 llama-cpp。

运维约定

1. 调整配置前先记录部署信息。 在代理配置记录中记录固定的镜像或 pip 版本、config.yaml、模型列表、路由、预算、环境变量引用和数据存储。该记录是回滚的基本单位。
2. 变更前确认目标、范围和回滚路径。 只读探查（健康探测、/v1/models、日志、支出查询）无需确认即可进行。变更——配置修改、创建或撤销密钥、重启、镜像升级、数据库迁移——必须有明确的人类指令，并指明部署目标。
3. 代理有响应不代表代理能正常提供服务。 /health/liveliness 返回 200 只能证明代理存活。请在交付边界验证：有代表性的 /v1/chat/completions 请求能返回令牌，且 x-litellm-model-id 指向预期的部署。
4. 控制证据的范围。 概述日志和配置；绝不要在聊天中完整输出日志、.env 内容、主密钥或提供商凭据。支出日志和调试输出可能包含提示词内容——分享前请先脱敏。
5. 固定版本。 LiteLLM 每周发布更新并更改默认值；此处所有说法均已根据 1.97.0（2026-08-22）核实。依赖与版本有关的行为前，请对照已安装的版本重新核实。

litellm-health 脚本

scripts/litellm-health 是用于探测运行中代理的只读工具。它仅发送 GET 请求，不写入文件，并且输出范围受限。

scripts/litellm-health --help                                   # no proxy needed
scripts/litellm-health --url http://127.0.0.1:4000 --json
scripts/litellm-health --check health --check readiness --json
scripts/litellm-health --check models --check model_info \
  --key "$LITELLM_MASTER_KEY" --json

退出代码：0 表示所有检查均通过，1 表示发现问题或发生致命错误，2 表示用法错误， 124 表示超时。检查项：health（GET /health/liveliness，无需身份验证）、readiness （GET /health/readiness，无需身份验证；配置的数据库不可访问时返回 503）、models （GET /v1/models，需要密钥）和 model_info（GET /model/info， 需要密钥）。密钥通过 Authorization: Bearer <key> 发送。脚本只会向你指定的代理发送数据。

运维流程

1. 识别部署：固定的版本或镜像摘要、运行方式（裸机、Docker、Compose、Helm）、配置来源（文件、store_model_in_db 或两者兼有）和数据存储（Postgres？Redis？）。
2. 收集证据：litellm-health --json；使用密钥调用 GET /v1/models 和 /model/info；响应标头（x-litellm-call-id、 x-litellm-model-id、x-litellm-model-api-base、x-litellm-version）； 使用 --detailed_debug 日志或 LITELLM_LOG=DEBUG 查看出站请求。
3. 根据症状进行分诊：判断是提供商错误还是网关错误（参见 故障排除）；检查冷却状态、 预算和数据库连接。
4. 确认后操作：收到人类指令后，执行范围明确、影响受控的变更；首先说明回滚路径。
5. 验证：重新运行探测，并在交付边界发送有代表性的聊天请求。

快速入门：一份配置，支持多个提供商

model_list:
  - model_name: gpt-4o                     # name clients request
    litellm_params:
      model: openai/gpt-4o                 # routed string (provider prefix required)
      api_key: os.environ/OPENAI_API_KEY   # resolved inside the proxy process
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY   # require auth on every call

运行 litellm --config config.yaml --port 4000 开始使用。成功时日志会显示 Proxy initialized with Config, Set models:。客户端调用 OpenAI 接口： /v1/chat/completions、/chat/completions、/v1/embeddings、/v1/images/generations、 /v1/audio/transcriptions，以及 /responses、兼容 Anthropic 的 /messages、 /model/info、/health/liveliness、/health/readiness。任何 OpenAI SDK 都可以 直接使用，无需修改：openai.OpenAI(base_url="http://localhost:4000", api_key=<virtual key>)。 详情和 SDK 接口：快速入门参考。

配置和路由

• 共享同一 model_name 的条目会组成一个负载均衡组；每个条目都是一个部署， 有自己的哈希 model_id，用于健康状态和冷却跟踪。
• router_settings.routing_strategy — simple-shuffle（默认，推荐； 根据 litellm_params 下的 rpm/tpm 或 weight 加权）、least-busy、 latency-based-routing、usage-based-routing（文档不建议在生产环境中使用）、 cost-based-routing。
• 可靠性：litellm_settings.num_retries（支持按部署和请求级别覆盖； num_retries 不是提供商 SDK 的 max_retries）、 fallbacks / context_window_fallbacks / content_policy_fallbacks、 冷却设置（allowed_fails、cooldown_time）、用于指定优先级的部署 order， 以及通过 enable_pre_call_checks: true 在调用前强制检查上下文窗口和区域筛选条件 （需主动启用）。
• 启用 store_model_in_db: true 后，UI/API 写入的内容会与 Postgres 中的 YAML 深度合并， 并在键冲突时优先使用数据库中的值；只要数据库行仍然存在，之后编辑这些 YAML 键都不会生效。 详情：配置和路由参考。

密钥、团队、预算和支出

• general_settings.master_key（必须以 sk- 开头）是管理员凭据和 UI 密码。虚拟密钥（POST /key/generate）可按工作负载限制模型、预算和 rpm/tpm； 密钥以哈希形式存储，绝不包含提供商凭据。
• 预算需要 Postgres。 如果未连接数据库，预算检查会默认放行（启动警告是唯一提示），密钥端点会返回 No connected db. — 对预算敏感的部署绝不能在没有数据库的情况下运行。
• 团队密钥只强制执行团队（及团队成员）预算；所有者的个人预算不适用。代理管理员不受速率限制约束。 支出记录在 /spend/logs 和 /global/spend 中；store_prompts_in_spend_logs 默认为 false。 详情：密钥和预算参考。

缓存和防护措施

• 响应缓存：设置 litellm_settings.cache: true，并将 cache_params.type: redis 用于 多实例生产环境（内存缓存按进程隔离；也支持磁盘/S3/GCS）。单个请求的控制选项： 在请求体中设置 cache: {ttl, no-cache, namespace}。
• 语义缓存（qdrant-semantic、redis-semantic、valkey-semantic）会嵌入整个 messages 数组， 并可能在相似的多轮对话之间重放过期答案 — 文档建议将 Agent 流量排除在语义缓存之外。
• 防护措施可在 pre_call、post_call、during_call 或 logging_only 阶段运行（没有 all 模式）；Presidio PII 屏蔽功能为 OSS。违规时会返回 HTTP 400，并包含判定结果； x-litellm-applied-guardrails 会列出实际运行的防护措施。 详情：缓存和防护措施参考。

可观测性和日志记录

• 回调：litellm_settings.success_callback / failure_callback / callbacks （Langfuse、OTel、Prometheus、Datadog、Sentry 等）。自 1.85.0 起，Prometheus /metrics 需要身份验证 — 为抓取程序提供 bearer 密钥，或设置 require_auth_for_metrics_endpoint: false。
• 取证响应头：x-litellm-call-id、x-litellm-model-id、 x-litellm-model-api-base、x-litellm-version、x-litellm-response-cost。
• 隐私：turn_off_message_logging: true 会保留元数据，但不将内容传递给回调；redact_user_api_key_info: true 会对密钥、用户和团队标识符进行脱敏。 使用 --detailed_debug、LITELLM_LOG=DEBUG 或针对单个请求设置 "litellm_request_debug": true 进行调试。 详情：可观测性参考。

部署

• 密钥、团队、支出、预算和 UI 状态都必须使用 Postgres；实例数量超过 1 时，必须使用 Redis >=7（共享速率限制计数器、冷却状态和缓存）。
• 固定镜像标签（ghcr.io/berriai/litellm:vX.Y.Z — 自 1.84.0 起使用 semver 标签；已移除 -stable 后缀，main-latest 已弃用）。镜像已使用 cosign 签名。
• 默认在启动时运行 Prisma 迁移；在 Kubernetes 上使用迁移作业模式，并在服务 Pod 上设置 DISABLE_SCHEMA_UPDATE=true。每个 Pod 使用一个 Uvicorn 工作进程；按 MAX_DB_CONNECTIONS / (instances x workers) 计算数据库连接池大小。 详情：部署参考。

安全与公开托管

• 任何可从互联网访问的代理，最低版本为 >=1.83.7（CVE-2026-42208 预认证 SQLi、CVE-2026-42203 SSTI、CVE-2026-42271 命令注入，以及用于 CVE-2026-48710 Host 头攻击链的 Starlette >=1.0.1）。其中两项漏洞于 2026 年被列入 CISA KEV，并遭到积极利用。
• 切勿公开管理路由（/key/*、/user/*、/team/*、/config/*、 /model/*、/spend/*、/ui、/prompts/test、/mcp-rest/*）。通过 allowed_routes 锁定路由仅适用于 Enterprise — 在 OSS 版本中，请在反向代理上强制执行。
• LITELLM_SALT_KEY 用于加密存储在数据库中的提供商凭据；设置后切勿更改，尤其是在添加模型后。只有通过文档说明的流程才能轮换主密钥。
• 2026 年 3 月的供应链事件：遭植入后门的 litellm==1.82.7/.8 PyPI wheel （持续约 40 分钟）。优先使用经过 cosign 验证的固定标签镜像，而非未固定版本的 pip 安装。 加固清单：安全参考。

故障排除：核心诊断规则

如果错误中包含 <Provider>Exception，则是提供商故障 — 而非网关故障。 AnthropicException、OpenAIException、BedrockException 等表示已发起上游调用，其响应就是证据。如果错误中没有提供商名称，则是网关本身拒绝了调用（LiteLLM 密钥错误、模型未知、处于冷却状态或超出预算）。

症状	首要处理方式
Invalid model name passed in model=X	名称不在 model_list 中，或未授权给该密钥；使用同一密钥检查 GET /v1/models
No deployments available for selected model, Try again in N seconds	所有部署都处于冷却状态（通常是上游返回 429），或 litellm_params.model 缺少提供商前缀
AnthropicException - Overloaded（HTTP 500，Anthropic 返回 529）	提供商端过载；重试或故障转移 — 并非网关错误
Authentication Error ... ExceededTokenBudget	密钥或团队预算已耗尽；检查 GET /key/info
启动时出现 ImportError: cannot import name 'get_flat_dependant'	fastapi 版本过新，与固定版本的 litellm 不兼容；使用 1.97.0 时固定为 fastapi==0.136.3

完整分类和修复方法：故障排除参考。

参考文档路由

加载时机	参考文档
来源、版本观察、刷新流程	references/00-source-index.md
代理快速入门、config.yaml、Python SDK、OpenAI-SDK 即插即用	references/01-quickstart-and-sdk.md
model_list、路由策略、重试/回退/冷却	references/02-config-and-routing.md
虚拟密钥、团队、预算、速率限制、支出	references/03-keys-teams-budgets-spend.md
响应缓存和防护措施	references/04-caching-and-guardrails.md
回调、Prometheus、标头、隐私开关	references/05-observability-and-logging.md
Docker/Compose/K8s/Helm、扩展、迁移、升级	references/06-deployment.md
面向公众的安全加固、CVE 底线、供应链	references/07-security-and-public-hosting.md
错误分类、故障模式、调试工作流	references/08-troubleshooting.md

包含的构件

• scripts/litellm-health：只读代理探测工具（仅依赖标准库，支持 --json、--check 子集、用于需要身份验证的路由的 --key，以及在没有服务时使用的 --help）。
• tests/test_litellm_health.py：针对本地 HTTP 模拟服务的确定性测试，包括只读约定测试。
• templates/proxy-config-record.md 和 templates/proxy-deployment.md：可填写的 记录——配置记录是回滚单元；部署记录会固定运行时配置（镜像摘要、端口、环境变量、数据存储、探测、回滚）。
• references/：九份带日期、按来源编目的参考文档，涵盖上述主题。
• evals/evals.json：六个输出质量评估用例。

验证范围

声明	最低证据要求
代理处于运行状态	litellm-health --check health 报告 /health/liveliness 返回 200
代理已就绪	--check readiness 报告 /health/readiness 返回 200（503 表示数据库不可用）
已注册正确的模型	/v1/models（使用调用方的密钥）列出预期别名
部署配置正确	/model/info 显示预期的 litellm_params，且密钥已脱敏
推理正常工作	有代表性的 /v1/chat/completions 请求返回令牌，且 x-litellm-model-id 指向预期部署
预算得到执行	已验证连接数据库（readiness），且 /key/info 显示正在跟踪该密钥的支出
诊断可靠	在提出结论前已收集证据（错误字符串、标头、日志），并通过重新运行探测和有代表性的请求验证修复

严格限制

• 未经明确的人类指令（指明目标并说明回滚路径），绝不修改生产代理（配置、密钥、团队、预算、镜像、数据库）。可自由进行只读检查。
• 绝不在信任边界之外暴露主密钥、管理路由或 /ui；身份验证不能替代网络和 TLS 控制。
• 绝不在任何位置提交提供商密钥、DATABASE_URL、LITELLM_MASTER_KEY 或 LITELLM_SALT_KEY；请使用 os.environ/ 引用和密钥管理器。
• 未配置 Postgres 时，绝不运行对预算敏感的公网部署——没有 Postgres 时，预算会默认放行。
• 绝不将 /health/liveliness 返回 200 视为网关正常提供服务的证明；请在交付边界进行验证。

不适用场景

• 引擎选择、服务方法、量化决策、评估设计——请参阅 ml-engineering。
• 运行单个推理引擎——vLLM 请参阅 vllm，llama.cpp 技术栈请参阅 llama-cpp。LiteLLM 会将请求路由到引擎，但不会取代引擎自身的运行管理。
• Kubernetes/Docker 基础知识以及反向代理/TLS 配置——请参阅 kubernetes、docker-compose 和 traefik；此技能涵盖 LiteLLM 专属的部分。
• 基于大模型 API 构建应用（应用架构、Agent 框架）——这属于后端/前端工程；此技能负责网关及其 SDK。