1. 多模型切换的痛点与 LiteLLM 的定位如果你手上同时握着 OpenAI、Anthropic、Gemini 甚至国内几家模型的 Key大概率经历过这种场景项目里写了一套 OpenAI SDK 的调用代码想换成 Claude 试试效果结果发现请求体字段不一样、返回结构不一样、流式协议细节也不一样改代码改到怀疑人生。更麻烦的是每个厂商的 Key 分散在各自的配置文件里轮换一次要翻好几个后台。LiteLLM 就是来解决这个问题的。它本质上是一个「统一网关 路由层」对外暴露完全兼容 OpenAI 的接口格式对内把请求翻译成各家 provider 的原生协议。你只需要记住一个 Base URL、一个 Key、一套模型名就能在几十上百个模型之间自由切换。它适合三类人一是需要在多个模型间做 A/B 对比的算法同学二是要给团队提供统一模型入口的平台开发者三是想用一套代码兼容多家模型、又不想维护多套 SDK 封装的后端工程师。我这次的做法是用 LiteLLM Proxy 作为本地/内网网关把上游统一指向 TaoToken 的 API 地址这样所有模型请求都走同一个 Key 出口配置集中、切换成本极低。下面从环境准备开始一步步把 config.yaml 写出来再跑一次真实的模型切换验证。在动手之前先明确一个概念LiteLLM 有两种用法。一种是作为 Python SDK 直接import litellm在代码里调用另一种是作为 Proxy Server 独立部署提供 HTTP 接口。本文聚焦后者因为「统一 Key 打通多模型」这个诉求用 Proxy 模式最自然——所有客户端只认一个地址模型路由在网关层完成。LiteLLM 的配置核心就是一份config.yaml它由几大块组成model_list定义有哪些模型可用litellm_settings控制路由、重试、缓存等全局行为router_settings或general_settings处理更细粒度的网关参数。理解了这几块你就掌握了 LiteLLM 的命脉。接下来的章节会围绕这份配置文件展开把每个关键参数讲清楚最后用一次实际的模型切换请求来验证整套链路是否打通。2. TaoToken 前置准备与 LiteLLM 安装2.1 拿到统一出口的 Base URL 和 KeyTaoToken 在这里扮演的角色是「上游模型供应商的统一入口」。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口规范。也就是说LiteLLM 在配置上游 provider 时可以把api_base指向这个地址api_key填你在 TaoToken 控制台生成的 Key。具体操作路径先访问官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册并登录然后进入控制台创建 API Key。控制台地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在 API Keys 页面可以生成和管理密钥对应的 deep link 是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。生成后把 Key 复制下来形如sk-xxxxxxxx后面配置里会用到。这里有个细节要注意TaoToken 的接口是 OpenAI 兼容的所以在 LiteLLM 里配置时provider 前缀可以用openai/然后把api_base指向 TaoToken 的地址。这样 LiteLLM 会按照 OpenAI 协议发请求TaoToken 再根据你请求里的模型名路由到对应的上游。模型名怎么写取决于 TaoToken 支持的模型列表建议先在模型对话页面确认一下可用模型标识。如果你想先快速验证 Key 是否可用可以打开模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite直接在里面发一条消息确认能正常返回。这一步能排除掉 Key 本身的问题避免后面配置排查时混淆变量。2.2 安装 LiteLLM 与依赖LiteLLM 的安装推荐用 pipPython 版本要求 3.8 以上。官方提供了两种安装方式基础包litellm和带 Proxy 的litellm[proxy]。我们要跑网关所以装后者。python -m venv litellm-env source litellm-env/bin/activate # Windows 用 litellm-env\Scripts\activate pip install litellm[proxy] -U装完之后验证一下版本LiteLLM 1.50 对路由和缓存的支持比较完整litellm --version如果输出类似LiteLLM: Current Version 1.50.x说明安装成功。这里建议固定一个版本避免生产环境因为自动升级导致配置行为变化。可以在 requirements 里写死litellm[proxy]1.50.0这类精确版本。另外如果你打算启用 Redis 缓存或 PostgreSQL 做预算管理还需要额外准备这两个服务。本文的验证阶段先用内存缓存跑通链路Redis 部分会在配置章节给出模板按需启用即可。2.3 目录结构规划建议把配置和启动脚本放在同一个目录下结构清晰litellm-gateway/ ├── config.yaml ├── .env └── start.sh.env放敏感信息Key、Redis 密码等config.yaml放模型和路由配置start.sh封装启动命令。这样 Key 不会硬编码进 YAML也方便用环境变量注入。接下来就进入配置环节。3. config.yaml 参数模板与统一 Key 接入3.1 完整可复制的 config.yaml下面这份配置是我实测跑通的模板把上游统一指向 TaoToken同时挂载了多个逻辑模型名方便后续做切换验证。你可以直接复制修改。model_list: # 逻辑模型名 gpt-4o实际走 TaoToken 的 OpenAI 兼容接口 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY timeout: 60 stream_timeout: 120 input_cost_per_token: 0.0000025 output_cost_per_token: 0.00001 # 逻辑模型名 claude-sonnet同样走 TaoToken 出口 - model_name: claude-sonnet litellm_params: model: openai/claude-3-5-sonnet-20241022 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY timeout: 60 stream_timeout: 120 input_cost_per_token: 0.000003 output_cost_per_token: 0.000015 # 逻辑模型名 gemini-pro - model_name: gemini-pro litellm_params: model: openai/gemini-1.5-pro api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY timeout: 90 stream_timeout: 180 litellm_settings: drop_params: true num_retries: 3 retry_after: 1 request_timeout: 600 set_verbose: false cache: true cache_params: type: local ttl: 600 max_size: 2000 general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: os.environ/DATABASE_URL这份配置里有几个关键点需要展开说。第一model字段写的是openai/gpt-4o这种格式。这里的openai/是 LiteLLM 的 provider 前缀表示「用 OpenAI 协议发请求」。因为 TaoToken 兼容 OpenAI 接口所以用这个前缀最省事。后面的gpt-4o是实际传给上游的模型标识TaoToken 会据此路由。如果你不确定某个模型在 TaoToken 里的准确标识去模型对话页面查一下或者直接发一条测试请求看返回。第二api_key: os.environ/TAOTOKEN_API_KEY这种写法表示从环境变量读取避免明文。对应的.env文件长这样TAOTOKEN_API_KEYsk-你的TaoToken密钥 LITELLM_MASTER_KEYsk-litellm-master-自定义一个强密码 DATABASE_URLpostgresql://litellm:passwordlocalhost:5432/litellmLITELLM_MASTER_KEY是 LiteLLM 网关自己的管理密钥客户端调用网关时用它做鉴权和上游的 TaoToken Key 是两回事。DATABASE_URL如果暂时不用预算管理可以先注释掉LiteLLM 会跳过数据库相关功能。第三drop_params: true这个参数很实用。不同 provider 对参数支持程度不一样比如某些模型不支持top_p或frequency_penalty开启后 LiteLLM 会自动丢弃上游不认识的参数避免报错。多模型切换场景强烈建议打开。第四缓存部分先用type: local内存缓存跑通生产环境换成 Rediscache_params: type: redis host: os.environ/REDIS_HOST port: 6379 password: os.environ/REDIS_PASSWORD ttl: 3600 namespace: prod-gateway3.2 启动网关配置写好后用一条命令启动litellm --config config.yaml --port 4000 --host 0.0.0.0如果想后台运行可以配合nohup或写个 systemd 服务。启动日志里会打印加载了哪些模型、监听端口、缓存状态。看到Uvicorn running on http://0.0.0.0:4000就说明起来了。这里有个容易踩的坑--host 0.0.0.0是为了让容器外或局域网内其他机器能访问。如果你只在本地测试用默认的127.0.0.1更安全。生产环境记得配防火墙规则别把网关裸奔在公网。3.3 客户端如何接入网关起来后客户端调用方式和调 OpenAI 完全一样只是把base_url换成网关地址api_key换成LITELLM_MASTER_KEY。以 Python 为例from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000, api_keysk-litellm-master-自定义一个强密码 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 用一句话解释什么是网关}] ) print(resp.choices[0].message.content)注意model字段填的是config.yaml里的model_name也就是逻辑名不是上游真实模型名。这就是统一 Key 的核心价值客户端只认逻辑名底层换哪个 provider、哪个真实模型对调用方完全透明。4. 模型切换调用验证与结果解读4.1 用 curl 做一次切换验证配置和启动都完成后最直接的验证方式是用 curl 打两次请求分别指定不同的逻辑模型名看是否都能正常返回。第一次请求gpt-4ocurl -s http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-master-自定义一个强密码 \ -d { model: gpt-4o, messages: [{role: user, content: 回复模型A已连通}], max_tokens: 50 } | python -m json.tool第二次请求claude-sonnet只改model字段curl -s http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-master-自定义一个强密码 \ -d { model: claude-sonnet, messages: [{role: user, content: 回复模型B已连通}], max_tokens: 50 } | python -m json.tool两次都返回choices[0].message.content且内容符合预期就说明统一 Key 打通多模型的目标达成了。整个过程客户端没有改任何代码只是换了个model字符串。4.2 返回结构解读LiteLLM 返回的 JSON 结构和 OpenAI 官方一致关键字段包括id、model、choices、usage。其中usage里的prompt_tokens和completion_tokens是成本追踪的依据配合配置里的input_cost_per_token/output_cost_per_tokenLiteLLM 能算出每次请求的花费。如果你在配置里开了set_verbose: true启动日志会打印每次请求的路由决策过程比如「选择了哪个 deployment、是否命中缓存、重试了几次」。调试阶段可以临时打开生产环境记得关掉否则日志量会很大。4.3 流式响应验证多模型场景下流式协议差异是最容易出问题的地方。LiteLLM 会把各家的流式响应统一成 OpenAI 的 SSE 格式。验证方式curl -N http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-litellm-master-自定义一个强密码 \ -d { model: claude-sonnet, messages: [{role: user, content: 数到五}], stream: true }正常的话你会看到一串data: {...}的 SSE 事件最后以data: [DONE]结束。如果中途卡住或报错多半是stream_timeout设得太短或者上游 provider 的流式实现有差异可以适当调大超时再试。4.4 缓存命中验证配置里开了cache: true后重复发同一条请求第二次会明显更快。你可以在返回的响应头里找x-litellm-cache-key之类的字段或者对比两次请求的耗时。缓存命中时LiteLLM 不会真的打到上游usage里的 token 数可能仍然显示但实际没有产生上游费用。这个特性在 FAQ、固定 prompt 场景下能省不少成本。5. 常见报错排查对照配置过程中最容易撞上的几类报错这里按真实错误信息对照排查。401 Authentication Error。报错形如litellm.AuthenticationError: OpenAIException - Incorrect API key provided。原因通常是TAOTOKEN_API_KEY没读到或者 Key 本身失效。排查步骤先在模型对话页面确认 Key 可用再检查.env是否被正确加载LiteLLM 不会自动读.env需要用export $(cat .env | xargs)或dotenv方式注入最后确认api_key字段写的是os.environ/TAOTOKEN_API_KEY而不是直接写值。local proxy failed / Connection refused。报错形如litellm.APIConnectionError: OpenAIException - Connection error。这通常是api_base写错或者网关进程没起来。检查api_base是否为https://taotoken.net/api注意结尾不要多加/v1LiteLLM 会自己拼用curl https://taotoken.net/api确认网络可达确认 LiteLLM 进程在监听。reading choices 相关报错。报错形如KeyError: choices或list index out of range。这多半是上游返回了非预期结构常见于模型名写错导致上游返回错误 JSON。检查model字段里的真实模型标识是否在 TaoToken 支持列表内开启set_verbose: true看原始返回确认drop_params: true已开启避免参数不兼容导致上游拒绝。OAuth / token 相关报错。如果你用的是需要 OAuth 的 provider报错可能涉及 token 刷新。TaoToken 走的是 API Key 模式一般不会遇到。如果出现检查是否误配了oauth相关字段或者 Key 权限不足。模型未找到。报错形如litellm.BadRequestError: Model not found。这是客户端请求的model名和config.yaml里的model_name对不上。LiteLLM 只认逻辑名不认上游真实名。检查客户端传的model是否和配置里的model_name完全一致大小写敏感。缓存相关报错。如果开了 Redis 缓存但连不上会报redis.exceptions.ConnectionError。检查REDIS_HOST、REDIS_PORT、REDIS_PASSWORD是否正确确认 Redis 服务在跑防火墙是否放行。临时排查可以把cache设为false先跑通主链路。数据库相关报错。如果配了DATABASE_URL但 PostgreSQL 没起来启动时会报连接失败。如果暂时不用预算管理把database_url注释掉即可。要用的话确认连接串格式、数据库已创建、用户有权限。排查的通用思路是先看 LiteLLM 启动日志有没有报错再看请求返回的具体错误信息然后逐层往上排查——客户端到网关、网关到上游、上游到模型。set_verbose: true在排查阶段非常有用能看到完整的请求和响应链路。6. 把统一入口用起来配置跑通之后你可以把 LiteLLM 网关作为团队的统一模型入口。所有项目只配一个 Base URL 和一个 Key模型切换在网关层完成。后续要加新模型只需要在config.yaml的model_list里加一条重启网关即可客户端零改动。如果你需要长期跑编码类任务或 Agent 工作流可以考虑用 Coding Plan 来获得更稳定的调用配额入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。需要查看完整接入文档的话文档地址是https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。API Keys 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite模型对话验证在https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite。最后分享一个实用技巧把config.yaml纳入版本管理但.env加进.gitignore。模型配置的变更走代码评审Key 的轮换走环境变量这样既保证了配置可追溯又不会泄露密钥。另外生产环境建议至少挂两个 deployment 到同一个model_name下配合num_retries和fallbacks单点故障时能自动切换可用性会好很多。
