LiteLLM指南：62k星LLM网关，100+模型统一调用与成本管控

项目：BerriAI/litellm | 星数：62298 | 语言：Python | 协议：开源协议 | GitHub仓库

更新日期：2026-10-29 · 作者：CodeArts 编辑部

问题从第三家模型开始出现

只用一个模型时，直接调官方 SDK 就好。一旦项目要同时接 OpenAI、Claude、Gemini、通义、本地 Ollama，麻烦就来了：每家请求体字段名不同、返回结构不同、流式实现不同、错误码不同、价格表要各家去查、想做降级要写一堆 if-else。代码里的 provider 分支会迅速失控。

LiteLLM 的解法是：所有模型都包成 OpenAI 格式。62298 星，主打"最快的 AI 网关"，提供 Rust 核心 + Python SDK 双形态，既能当库用，也能当独立代理服务部署。

两种用法：SDK 与代理

pip install litellm

from litellm import completion

resp = completion(
    model='claude-3-5-sonnet-latest',
    messages=[{'role': 'user', 'content': '用一句话解释向量数据库'}]
)
print(resp.choices[0].message.content)

同一个函数，把 model 换成 gpt-4o、gemini/gemini-1.5-pro、ollama/qwen2.5 都能跑。模型名前缀决定路由到哪家，返回对象结构完全一致。litellm.completion_cost(resp) 还能直接算出这次调用花了多少钱，这在多模型对比时非常实用。

部署代理：一个 YAML 管全部

pip install 'litellm[proxy]'
litellm --config config.yaml --port 4000

model_list:
  - model_name: fast
    litellm_params:
      model: gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
    model_info:
      input_cost_per_token: 0.00000015
      output_cost_per_token: 0.0000006

  - model_name: smart
    litellm_params:
      model: claude-3-5-sonnet-latest
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: local
    litellm_params:
      model: ollama/qwen2.5:7b
      api_base: http://localhost:11434

litellm_settings:
  drop_params: true
  set_verbose: false

general_settings:
  master_key: sk-1234

起好后它就是标准的 OpenAI 接口：POST http://localhost:4000/v1/chat/completions。所有现有用 OpenAI SDK 的代码，只要把 base_url 改过来、api_key 填 master_key，就能无缝切到多模型后端。这一点的工程价值极高——迁移成本几乎为零。

路由与降级：生产必备

x:
router_settings:
  routing_strategy: usage-based-routing-v2
  fallbacks: [{"fast": ["local"]}, {"smart": ["fast"]}]
  num_retries: 2
  timeout: 30
  allowed_fails: 3
  cooldown_time: 60

这段配置的意思是：主模型失败两次后降级到备用模型，某模型连续失败 3 次就冷却 60 秒不再打它。usage-based-routing-v2 会按 TPM/RPM 余量挑负载最低的部署。对于"必须可用"的业务，这套机制比自己在业务代码里 retry 靠谱得多。

同一模型配多个 key 就能做横向扩展：

  - model_name: fast
    litellm_params:
      model: gpt-4o-mini
      api_key: os.environ/KEY_A
  - model_name: fast
    litellm_params:
      model: gpt-4o-mini
      api_key: os.environ/KEY_B

同名即同一个逻辑模型，网关自动轮询并跟踪各自额度。这是大用量项目突破单 key 限速最省事的做法。

虚拟密钥：多项目分账

curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-1234" \
  -d '{"models": ["fast"], "max_budget": 50, "budget_duration": "30d"}'

给每个业务方发一把虚拟 key，限制可用模型和月度预算，用量到顶自动拒绝。配合 /spend/logs 和 /spend/report 两个端点，谁花了多少钱一目了然。团队里最容易失控的就是"大家都用同一个 key"，这套机制能根治。

可观测性接哪

• 内置：/ui 界面看请求量、花费、延迟。
• Langfuse / Helicone：配 success_callback: ["langfuse"] 直接推。
• Prometheus：暴露 /metrics，接 Grafana 做告警。
• 成本告警：max_budget + 定时报表，比月末看账单再后悔强。

几个真实的坑

1. 参数不通用：某些模型不支持 response_format 或 tools，设 drop_params: true 自动丢弃，代价是功能静默失效，务必测试。
2. 流式差异：不同厂商在 usage 字段上的行为不同，需要统计成本时显式传 stream_options: {"include_usage": true}。
3. 成本表过期：价格由内置映射决定，模型调价后可能需要升级版本或自定义 model_info，别把账目当财务依据。
4. 本地模型并发：Ollama 默认串行处理，网关再快也堵在后面，需调 OLLAMA_NUM_PARALLEL。

要不要上

只接一家模型、单服务调用，直接调官方 SDK 更简单。出现下列任一情况时，LiteLLM 的收益立刻超过引入成本：接了两家以上模型、需要成本可视、多项目共享额度、需要降级兜底、想统一日志审计。它的定位不是"更强的模型"，而是"把模型使用变成可管理的基础设施"。