1. 为什么需要 LiteLLM 这层代理以及它到底解决什么问题如果你手上同时有 OpenAI、Anthropic、Google、DeepSeek 这几家的 Key项目里又散落着各种 SDK 调用代码那你大概率经历过这种场景某个模型临时限流想把请求切到另一家结果发现要改代码、改环境变量、改鉴权头改完还要重新测一遍。LiteLLM 就是冲着这个痛点来的——它是一个开源的 AI 代理网关对外暴露一套 OpenAI 兼容的/v1/chat/completions接口对内帮你把请求路由到任意厂商的模型上。用一句话概括LiteLLM 是一个统一 AI 代理平台能把 100 多家模型厂商的 API 收敛成一个入口、一把 Key、一套调用格式。它适合三类人一是需要频繁切换模型做对比测试的算法同学二是要给团队内部多个项目统一发 Key、控预算的运维或平台开发者三是想把模型调用从业务代码里解耦出来的后端工程师。它和直接调厂商 API 的区别我用一张表说清楚维度直连各厂商经过 LiteLLM 代理调用格式每家 SDK 不同统一 OpenAI 格式鉴权每个项目持有厂商 Key项目只拿代理 Key模型切换改代码改配置改一个 model 字段用量统计分散在各厂商后台按用户/Key/模型汇总预算控制基本没有按用户/团队设上限故障切换手动配置 fallback 自动切我实测下来最省心的点在于「模型切换只改一个字符串」。比如你原来调gemini-2.5-pro想换成claude-sonnet业务代码一行不用动只把请求体里的model换掉就行。这对做 A/B 测试或者临时降级特别友好。这篇指南聚焦本地部署与多模型路由管理我会给出可直接复制的docker-compose.yml和config.yaml演示怎么通过 TaoToken 的统一 Key 和 API 通道把模型列表接进来最后附上 curl 验证请求和日志排查步骤。目标很明确让你一次性把代理网关跑通并完成一次模型切换测试。整个过程不需要你去逐个申请各家厂商的账号TaoToken 这边一把 Key 就能覆盖多个模型省掉大量注册和配置时间。需要提前说明的是LiteLLM 本身是代理层它不生产模型能力只做转发和治理。所以你的模型来源可以是官方直连也可以是像 TaoToken 这样的统一通道。本文用后者做演示因为对个人开发者和中小团队来说统一 Key 的接入成本最低。2. 前置准备TaoToken 统一 Key 与 LiteLLM 的对接思路在动手写配置之前先把「谁提供模型、谁做代理」这件事理清楚。LiteLLM 是代理网关它自己不提供模型需要在下游配置真实的模型来源。TaoToken 在这里扮演的就是「统一模型通道」的角色——它对外提供 OpenAI 兼容的 API 接口你拿一把 Key 就能调用它支持的多个模型。所以整体链路是这样的你的业务代码 → LiteLLM 代理本地 4000 端口→ TaoToken API 通道 → 具体模型。LiteLLM 负责鉴权、路由、统计、预算TaoToken 负责把请求送到真正的模型上。2.1 拿到 TaoToken 的 Key 和 Base URL第一步是准备接入凭证。访问 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台里生成 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成 Key 的时候注意两点一是 Key 只在创建时完整显示一次记得立刻复制保存二是可以给 Key 起个名字比如litellm-proxy方便以后区分用途。TaoToken 的 API Base URL 是https://taotoken.net/api注意这个地址不带任何查询参数。在 LiteLLM 的配置里我们会把它作为api_base填进去。如果你不确定有哪些模型可用可以先在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 里试一下或者直接调/v1/models接口拉列表。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的模型 ID 对照表。2.2 本地环境需要什么LiteLLM 官方推荐用 Docker 部署这也是最省事的方式。你需要Docker 和 Docker Compose版本 20.10 以上即可一个 PostgreSQL 数据库用来存 Key、用户、用量数据。本地测试可以直接用 docker-compose 起一个至少 2GB 可用内存LiteLLM 镜像本身不大但跑起来加上数据库会占一些如果你只是想快速验证不接数据库也能跑但那样就没有 UI 管理和用量统计了。本文按「带数据库的完整版」来写因为标题里提到了「管理」没有数据库的管理是残缺的。2.3 目录结构规划我习惯把配置集中放在一个目录里方便备份和迁移。建议这样组织litellm-proxy/ ├── docker-compose.yml ├── config.yaml └── .env.env放敏感信息数据库密码、TaoToken Keyconfig.yaml放模型路由规则docker-compose.yml放服务编排。这样.env可以加进.gitignore不会误提交。2.4 关于模型 ID 的说明LiteLLM 的config.yaml里每个模型有两个名字model_name是对外暴露的名字你的业务代码里用的litellm_params.model是实际发给下游的模型标识。因为我们走 TaoToken 通道所以litellm_params里要指定openai/前缀加上 TaoToken 支持的模型 ID同时把api_base指向 TaoToken。举个例子你想对外暴露一个叫gpt-4o的模型实际走 TaoToken配置大概长这样- model_name: gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY这里的openai/前缀是告诉 LiteLLM 用 OpenAI 兼容协议去请求而不是说模型一定是 OpenAI 的。TaoToken 的接口是 OpenAI 兼容的所以统一用这个前缀。3. 可复制的 docker-compose 与 config.yaml 配置这一节是全文的核心配置能直接复制跑。我按「先起数据库、再起 LiteLLM」的顺序写每一步都给出完整文件内容。3.1 docker-compose.yml在litellm-proxy/目录下新建docker-compose.ymlversion: 3.9 services: postgres: image: postgres:16 container_name: litellm-postgres restart: unless-stopped environment: POSTGRES_USER: litellm POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: litellm volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U litellm] interval: 10s timeout: 5s retries: 5 networks: - litellm-net litellm: image: ghcr.io/berriai/litellm:main-latest container_name: litellm-proxy restart: unless-stopped depends_on: postgres: condition: service_healthy ports: - 4000:4000 volumes: - ./config.yaml:/app/config.yaml command: - --config/app/config.yaml - --port4000 - --num_workers2 environment: LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY} DATABASE_URL: postgresql://litellm:${POSTGRES_PASSWORD}postgres:5432/litellm TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} STORE_MODEL_IN_DB: True healthcheck: test: [CMD-SHELL, curl -f http://localhost:4000/health/liveliness || exit 1] interval: 30s timeout: 5s retries: 3 start_period: 60s networks: - litellm-net volumes: pgdata: networks: litellm-net: driver: bridge几个关键点说明一下。STORE_MODEL_IN_DB: True这个环境变量很重要它让 LiteLLM 把模型配置也写进数据库这样你在 UI 里改模型能持久化。LITELLM_MASTER_KEY是管理员密钥UI 登录和调管理接口都用它一定要设一个强密码。depends_on配合condition: service_healthy保证数据库先就绪再启动 LiteLLM避免启动时连不上库。3.2 .env 文件同目录下新建.envPOSTGRES_PASSWORD换成你自己的数据库密码 LITELLM_MASTER_KEYsk-换成你自己的管理员密钥 TAOTOKEN_API_KEY你的TaoTokenKeyLITELLM_MASTER_KEY建议以sk-开头这是 LiteLLM 的惯例虽然不强制但能避免一些工具误判。三个值都别用默认的尤其是数据库密码。3.3 config.yaml这是模型路由的核心配置。新建config.yamlmodel_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: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: claude-sonnet litellm_params: model: openai/claude-sonnet-4-20250514 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: claude-haiku litellm_params: model: openai/claude-3-5-haiku-20241022 api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: deepseek-chat litellm_params: model: openai/deepseek-chat api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: gemini-flash litellm_params: model: openai/gemini-2.5-flash api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: os.environ/DATABASE_URL litellm_settings: drop_params: true set_verbose: false request_timeout: 600这里每个模型都指向https://taotoken.net/api用同一把TAOTOKEN_API_KEY。drop_params: true是个实用选项它会自动丢弃下游模型不支持的参数避免因为传了某个厂商特有的字段导致报错。request_timeout: 600把超时设成 10 分钟长文本生成不容易断。模型 ID 这块claude-sonnet-4-20250514、gemini-2.5-flash这些具体名称要以 TaoToken 文档里的为准不同时间可用的模型会有调整。你可以在模型对话页面确认当前可用的 ID再填进配置。3.4 启动服务配置齐了在litellm-proxy/目录下执行docker compose up -d第一次会拉取镜像Postgres 大概几十 MBLiteLLM 镜像稍大一些。等两个容器都起来后用下面的命令看状态docker compose ps正常的话litellm-postgres和litellm-proxy都应该是running或healthy。如果 LiteLLM 一直重启先看日志docker compose logs -f litellm最常见的启动失败原因是数据库连接串写错或者config.yaml缩进有问题YAML 对缩进极其敏感建议用两个空格别用 Tab。3.5 关于配置文件的路径一致性有一点要特别注意docker-compose.yml里挂载的是./config.yaml:/app/config.yamlcommand里读的也是/app/config.yaml。这两个路径必须一致否则容器里读不到配置。如果你改了挂载路径command里的路径也要同步改。这个坑我在早期部署时踩过容器起来了但模型列表是空的查了半天才发现是路径对不上。4. 验证请求与模型切换测试服务起来之后别急着接业务代码先用 curl 把链路验证一遍。这一步能帮你快速定位问题出在 LiteLLM 还是 TaoToken 通道。4.1 健康检查先看服务本身活没活curl http://localhost:4000/health/liveliness返回Im alive!就说明 LiteLLM 进程正常。再看模型就绪状态curl http://localhost:4000/health/readiness这个接口会尝试连一下下游如果返回里某个模型是unhealthy说明那个模型的配置或 Key 有问题。4.2 拉取模型列表用管理员 Key 拉一下 LiteLLM 对外暴露的模型curl http://localhost:4000/v1/models \ -H Authorization: Bearer $LITELLM_MASTER_KEY返回的 JSON 里data数组应该包含你在config.yaml里定义的gpt-4o、claude-sonnet、deepseek-chat等。如果这里是空的八成是config.yaml没被正确加载回去检查挂载路径和 YAML 缩进。4.3 发一次真实对话请求拿gpt-4o试一下curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer $LITELLM_MASTER_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 用一句话解释什么是代理网关}] }如果返回里有正常的choices[0].message.content说明整条链路通了LiteLLM 收到请求 → 转发到 TaoToken → TaoToken 送到模型 → 结果原路返回。4.4 模型切换测试这是 LiteLLM 最核心的价值验证一下切换是否真的只改一个字段。把上面的model换成claude-sonnetcurl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer $LITELLM_MASTER_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: 用一句话解释什么是代理网关}] }再换成deepseek-chat试一次。三次请求除了model字段不同其他完全一样。这就是统一代理的意义——业务代码不用感知底层是哪家模型。4.5 用 Python SDK 验证实际项目里更多是用 SDK 调用。因为 LiteLLM 是 OpenAI 兼容的直接用 openai 库就行from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_key你的LITELLM_MASTER_KEY ) for model_name in [gpt-4o, claude-sonnet, deepseek-chat]: resp client.chat.completions.create( modelmodel_name, messages[{role: user, content: 回复 OK 两个字母即可}] ) print(model_name, -, resp.choices[0].message.content)跑一遍三个模型都能返回说明多模型路由完全可用。注意base_url指向的是 LiteLLM 的地址不是 TaoToken 的地址这是很多人第一次配会搞混的地方。4.6 流式输出验证如果你的应用需要流式返回也测一下curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer $LITELLM_MASTER_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: 数到五}], stream: true }正常的话你会看到一行行data: {...}陆续输出最后以data: [DONE]结束。如果卡住不动多半是下游超时或者网络问题去日志里找线索。4.7 在 UI 里做一次对话测试LiteLLM 自带一个测试界面。浏览器打开http://localhost:4000/ui用户名填admin密码填你的LITELLM_MASTER_KEY。登录后在左侧找到「Test Key」或「Chat」入口选一个模型直接对话。这个界面适合快速验证不用写 curl。UI 里还能看到每次请求的耗时、Token 用量、费用估算。如果你接了多个模型这里能直观对比哪个模型更贵、更慢。5. 常见报错排查对照配置过程中最容易卡在几个固定报错上我把它们和排查方法整理出来遇到时直接对照。5.1 401 Unauthorized这是最高频的报错。分两种情况第一种调 LiteLLM 时 401。说明你请求头里的 Key 不对。检查Authorization: Bearer xxx里的xxx是不是LITELLM_MASTER_KEY的值注意别把 TaoToken 的 Key 填到这里。LiteLLM 的鉴权和下游是两套。第二种LiteLLM 转发到 TaoToken 时 401。这种在 LiteLLM 日志里会看到类似AuthenticationError的字样。说明TAOTOKEN_API_KEY无效或过期。去 TaoToken 控制台确认 Key 状态必要时重新生成一把更新.env后重启容器docker compose down docker compose up -d5.2 local proxy failed / connection refused日志里出现local proxy failed或者Connection refused通常是 LiteLLM 连不上下游。先确认api_base写的是https://taotoken.net/api别多写或少写路径。再确认容器能访问外网docker compose exec litellm curl -I https://taotoken.net/api如果这条命令超时说明容器网络有问题检查宿主机的网络配置和 DNS。5.3 reading choices 相关报错有时候日志里会看到Error reading choices或者返回体解析失败。这多半是下游返回了非标准格式或者模型 ID 写错了导致 TaoToken 返回了错误信息而不是正常的 completion 结构。先确认litellm_params.model里的模型 ID 在 TaoToken 那边确实存在可以在模型对话页面核对。另外drop_params: true能减少这类问题因为它会过滤掉下游不认的参数。5.4 OAuth / token 相关报错如果你看到OAuth或者token expired之类的字样一般是 Key 的鉴权方式不对。TaoToken 用的是 Bearer Token 方式配置里api_key直接填 Key 值即可不需要额外的 OAuth 流程。检查是不是把api_key写成了os.environ/引用但环境变量没传进容器。用docker compose exec litellm env | grep TAOTOKEN确认环境变量在容器里存在。5.5 数据库连接失败日志里出现could not connect to server或password authentication failed检查.env里的POSTGRES_PASSWORD和DATABASE_URL里的密码是否一致。DATABASE_URL是在docker-compose.yml里拼的用的是同一个变量理论上不会不一致除非你手动改了其中一处。另外确认postgres容器的健康检查通过了LiteLLM 是等它 healthy 才启动的。5.6 模型列表为空/v1/models返回空数组但容器是 running 状态。九成是config.yaml没加载成功。检查三点挂载路径对不对、command里的--config路径对不对、YAML 缩进有没有用 Tab。YAML 里 Tab 是非法字符必须用空格。可以用在线 YAML 校验工具先过一遍。5.7 预算或限流导致的拒绝如果某个 Key 突然调不通返回 429 或预算超限提示去 UI 的「Usage」页面看这个 Key 的用量。LiteLLM 支持按 Key 设max_budget和rpm_limit超了就会拒绝。这是设计行为不是 bug。调整预算或等周期重置即可。5.8 排查通用套路遇到任何报错先看 LiteLLM 日志docker compose logs -f litellm日志里会打印请求的模型、下游地址、返回状态码。如果 LiteLLM 这边看起来正常再去 TaoToken 控制台看调用记录确认请求有没有到达。两边对照问题出在哪一段就清楚了。这个「分段排查」的思路比盲目改配置高效得多。6. 把统一 Key 接入落到日常开发里配置跑通只是第一步真正省时间的是把它用起来。这里说几个我实际用下来觉得有价值的点。第一业务代码里只保留一个base_url和一个 Key。所有模型调用都走 LiteLLM切换模型改model字段。这样以后换模型供应商业务代码零改动。你可以把 LiteLLM 的地址配成环境变量本地开发指向localhost:4000测试环境指向内网地址代码完全一致。第二给不同项目发不同的 Key。在 UI 里创建用户再给用户生成 Key设置模型白名单和预算。比如聊天机器人项目只给gpt-4o-mini和claude-haiku控制成本数据分析项目给gpt-4o和claude-sonnet。这样即使某个项目的 Key 泄露影响范围也可控。第三善用 fallback。LiteLLM 支持配置模型降级比如主模型超时就自动切备用模型。在config.yaml的litellm_settings里加litellm_settings: fallbacks: [{gpt-4o: [claude-sonnet, deepseek-chat]}]意思是gpt-4o调不通时依次尝试claude-sonnet和deepseek-chat。这对提升服务稳定性很有帮助尤其是高峰期。第四定期看用量报表。UI 里能按模型、按用户、按天看调用量和费用。我一般每周扫一眼看看有没有异常调用或者某个模型成本涨得特别快。这些数据在直连各厂商时是分散的统一代理后才好汇总。如果你需要长期跑编码类任务或者 Agent 工作流可以考虑 Coding Plan它在调用额度和稳定性上更适合高频场景具体可以看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。日常验证模型效果用模型对话页面就够了。接入过程中遇到鉴权或路由问题接入文档里有更细的说明API Key 管理在控制台里操作。最后提醒一句LiteLLM 的配置改完后记得重启容器让配置生效docker compose restart litellm就行。数据库数据是持久化的重启不会丢 Key 和用量记录。整套跑下来你就有了一套自己的统一 AI 代理平台后面接多少模型、发多少 Key都在这一个入口里管。