1. 直连 SDK 的坑我在第三个项目才真正踩明白如果你正在搜 LiteLLM 怎么配、模型网关怎么搭、OpenAI 兼容 base_url 怎么统一这篇就是给你写的。LiteLLM 是一个能把 100 模型统一成 OpenAI 接口的 Python 库兼代理进程跑起来之后对外只暴露一个/v1地址业务侧永远只认一个 base_url。它适合谁适合那些项目里同时接了 OpenAI、Claude、国产模型代码里到处是if model gpt的开发者也适合想把模型调用收拢成一层、方便做路由和成本核算的团队。我最早做 AI 应用的时候调用层是这样的OpenAI 用openai包Claude 用anthropic包本地模型再手写一个requests.post。三个 client三套参数命名三套异常类型。等到要加第四个模型或者某个供应商突然 429整条链路就崩了因为没有任何降级逻辑。更麻烦的是老板月底问「这个月 token 花了多少、哪个业务线最烧钱」我只能翻日志一条条数。后来我把这层抽出来用 LiteLLM 做成一个独立网关进程。业务代码从此只认一个base_url后端换模型、加供应商、做 Fallback全在网关的配置文件里改业务侧零改动。这篇文章就把这套落地过程拆开从装包到 config.yaml 骨架再到用 curl 验证转发和故障回退目标是 10 分钟内跑通一个能上生产的模型网关。2. 前置准备TaoToken 统一 Key 与 API 通道在写 config.yaml 之前先把「模型从哪来」这件事解决掉。直连各家官方 API 的问题是你得分别注册、分别充值、分别管理 key而且每个供应商的 base_url 和鉴权方式都不一样。我现在的做法是走 TaoToken 的统一通道它提供 OpenAI 兼容的接口一个 Key 就能覆盖多个模型省掉了多供应商账号管理的麻烦。具体操作分三步。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号。第二步进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建一个 API Key这个 Key 就是你后面填进 config.yaml 的凭证。第三步记住 API 通道地址是 https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base_url 使用。注意API Key 只在创建时完整显示一次创建后立刻复制保存。如果丢了只能重新生成一把旧的作废。拿到 Key 之后你可以先在模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里手动发一条消息确认 Key 能用、额度正常。这一步别跳过因为后面网关报错时你得先排除「Key 本身有问题」这个变量。确认没问题后把 Key 存进环境变量别硬编码进配置文件export TAOTOKEN_API_KEYsk-你复制的那串key如果你打算长期跑编码类任务或者 Agent可以顺手看一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对高频调用场景做了额度优化。不过这篇的重点是网关本身Key 准备好就够了。3. 可复制配置LiteLLM config.yaml 骨架与启动先装包。LiteLLM 的 proxy 模式需要额外依赖所以装的时候带上[proxy]pip install litellm[proxy]装完确认一下版本后面配置字段名跟版本有关litellm --version然后新建config.yaml。下面这份骨架是我实际在用的把 TaoToken 作为主通道同时留了一个本地模型的占位配置你可以按需删减model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: claude-sonnet litellm_params: model: openai/claude-sonnet-4 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: local-qwen litellm_params: model: openai/Qwen2.5-72B-Instruct api_base: http://localhost:8000/v1 api_key: fake router_settings: routing_strategy: least-busy fallbacks: - {gpt-4o: [claude-sonnet]} timeout: 30 num_retries: 2 general_settings: master_key: os.environ/LITELLM_MASTER_KEY telemetry: false几个关键点解释一下。model_name是业务侧调用的名字litellm_params.model是 LiteLLM 内部识别的真实模型标识。因为 TaoToken 提供的是 OpenAI 兼容接口所以这里统一用openai/前缀再通过api_base指向 TaoToken 的通道地址。这样写的好处是LiteLLM 把它当成一个标准 OpenAI 后端处理鉴权和请求格式都不用特殊适配。fallbacks的格式是{源模型: [目标模型]}意思是 gpt-4o 调用失败时自动切到 claude-sonnet。routing_strategy我选了least-busy它会挑当前并发最低的实例适合多实例部署。如果你只有一个后端这个字段影响不大。启动网关前先设好 master key值必须以sk-开头export LITELLM_MASTER_KEYsk-your-master-key-1234 litellm --config config.yaml --port 4000看到Uvicorn running on http://0.0.0.0:4000就说明起来了。这个 master key 是网关自己的管理密钥跟 TaoToken 的 Key 是两回事别搞混。4. 验证请求curl 测转发与故障回退网关起来之后第一件事是确认转发链路通。用 curl 直接打网关的/v1/chat/completionscurl -X POST http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-your-master-key-1234 \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 用一句话解释什么是模型网关}] }如果返回里能看到choices[0].message.content有正常内容说明网关成功把请求转发到了 TaoToken 通道模型也正常响应了。这一步通了业务侧就可以接入了。接着验证故障回退。把 config.yaml 里 gpt-4o 的api_base临时改成一个不存在的地址比如https://taotoken.net/api-invalid重启网关再发一次同样的请求。这时候你应该看到返回的模型变成了 claude-sonnet因为 gpt-4o 调用失败触发了 fallbacks。验证完记得把地址改回来。业务侧接入就更简单了用官方 openai 包只改 base_urlfrom openai import OpenAI client OpenAI( api_keysk-your-master-key-1234, base_urlhttp://localhost:4000, ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)想换模型只改model字段想加供应商只改 config.yaml业务代码一行不动。这就是网关的核心价值。5. 本篇常见错排查报错model not found八成是model_name和业务侧传的model对不上或者litellm_params.model写错了。LiteLLM 的模型名会随供应商迭代变化跑不通先litellm --models看当前版本支持哪些标识别照抄旧文档。报错Authentication Error先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在echo $TAOTOKEN_API_KEY看一眼。如果 Key 是对的检查api_base是不是写成了https://taotoken.net/api/带尾斜杠有些版本对尾斜杠敏感。Fallback 没生效Fallback 只在「调用失败」时触发比如超时、429、503。如果模型返回了 200 但答非所问网关不会回落这是语义层面的问题得靠评测和重试策略解决网关管不到。master_key 没设就公网上线这是最危险的。不设 master key任何人都能免密调用你的网关等于把额度敞开。生产环境务必设LITELLM_MASTER_KEY并且前面加一层反向代理做鉴权。配置字段名对不上router_settings和general_settings的字段随版本演进跑不通先litellm --version对照官方文档。我踩过的坑是旧版本里fallbacks的写法不一样升级后配置直接报错。本地模型别名冲突openai/名字里的名字要在model_list里先声明否则网关找不到路由。多个本地模型时别名必须唯一。6. 后续怎么接Key 管理与长期编码场景网关跑通之后下一步是给不同业务线发虚拟 Key做独立限流和成本核算。这需要接一个 Postgres在general_settings.database_url里配连接串启用后才有虚拟 Key、预算和 Spend Tracking。连接串用标准postgresql://格式别写成postgresqlasyncpg://那是 SQLAlchemy 异步驱动的写法LiteLLM 不认。虚拟 Key 的生成接口是POST /key/generate带上 master key 鉴权请求体里可以指定models、max_budget、rpm_limit、tpm_limit。返回的 token 就是下发给业务线的 Key注销也只吊销这一把不影响其他业务。如果你主要跑的是编码类任务或者 Agent调用频率高、上下文长可以看看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它在高频场景下额度更划算。API Key 的管理入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置过程中遇到字段问题可以先翻文档对照版本。最后说个实际经验网关这层别省。我见过太多项目把供应商适配散落在业务代码里等到要换模型或者做降级时改一处漏三处。LiteLLM 加 TaoToken 这套组合把「模型从哪来」和「模型怎么调」解耦开业务侧只认一个 base_url剩下的路由、Fallback、限流、记账全交给网关。10 分钟搭起来后面省的是几十个小时的维护时间。