1. 为什么需要 LiteLLM 网关统一管理大模型项目里接第一个模型的时候大家通常都很随意代码里写死一个base_url再配一个api_key跑通就完事。等到第二个、第三个模型进来麻烦就开始了。有人用 OpenAI 的 SDK有人用 Anthropic 的 SDK还有人直接requests.post拼 JSONKey 散落在.env、CI 变量、同事的本地笔记里月底看账单谁也说不清哪个服务烧了多少钱。LiteLLM 网关要解决的就是这个「怎么管」的问题。它本身不是模型而是一个统一的大模型代理层——对外暴露 OpenAI 兼容 API对内可以接 OpenAI、Anthropic、Gemini、Dashscope也能接本地 vLLM、Ollama。应用侧只需要认一个地址、一个 Virtual Key后面到底走哪家模型、怎么限额、怎么计费全部交给网关处理。我试过在一个小团队里同时维护四五个模型的调用最痛的不是模型效果而是「换模型要改代码、查问题要翻五个平台」。LiteLLM 把这些问题收敛到一个入口之后排查和切换的成本明显下降。这篇文章按一条能真正跑起来的路线走先用 Docker Compose 把 LiteLLM 部署起来再通过 TaoToken 的统一 Key/API 通道接入模型最后用 curl 和 OpenAI SDK 验证多模型路由与鉴权。适合正在做多模型接入、想统一管理 Key 和预算的后端或平台同学。2. TaoToken 前置准备统一 Key 与 API 通道LiteLLM 部署好之后它自己不会凭空变出模型。你需要给它配置上游模型的访问凭证。这里有两种常见做法一种是每个模型单独配一家的 Key另一种是通过 TaoToken 这样的统一通道用一个 Key 访问多家模型。TaoToken 的定位是统一的大模型 API 通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的好处是LiteLLM 的config.yaml里不用为每个厂商写一套鉴权逻辑统一用 OpenAI 兼容格式指向 TaoToken 的 API 地址即可。前置准备分三步。第一步拿到 TaoToken 的 API Key。登录控制台后进入 API Keys 页面创建地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。生成的 Key 只显示一次复制保存好后面要写进 LiteLLM 的.env。第二步确认你要用的模型 ID。TaoToken 的模型列表和文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面会列出当前支持的模型名称。LiteLLM 的config.yaml里model_name是你自己起的别名litellm_params.model要按 LiteLLM 的命名规则写比如openai/gpt-4o、anthropic/claude-3-5-sonnet这类。第三步想清楚你的调用场景。如果只是验证模型能不能通用模型对话页面直接测最省事https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。如果是长期编码或 Agent 场景建议直接上 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 这样预算和额度更可控。这里有个容易踩的坑LiteLLM 的config.yaml里如果写model: openai/gpt-4o它会默认去api.openai.com。要让它走 TaoToken必须同时配api_base并且把api_key指向 TaoToken 的 Key。下面第三节会给出完整片段。3. 可复制配置docker-compose.yml、config.yaml 与 .env这一节是全文最核心的部分所有片段都可以直接复制。目录结构保持简洁litellm/ ├── docker-compose.yml ├── config.yaml └── .env先写docker-compose.yml。相比只跑一个容器Compose 的好处是配置可复现、升级迁移成本低。注意db的 volumes 路径要改成你自己机器上的真实路径。services: litellm: image: docker.litellm.ai/berriai/litellm:main-stable ports: - 4000:4000 volumes: - ./config.yaml:/app/config.yaml command: - --config/app/config.yaml environment: DATABASE_URL: postgresql://llmproxy:dbpassword9090db:5432/litellm STORE_MODEL_IN_DB: True env_file: - .env depends_on: - db healthcheck: test: - CMD-SHELL - python3 -c import urllib.request; urllib.request.urlopen(http://localhost:4000/health/liveliness) interval: 30s timeout: 10s retries: 3 start_period: 40s db: image: postgres:16 restart: always container_name: litellm_db environment: POSTGRES_DB: litellm POSTGRES_USER: llmproxy POSTGRES_PASSWORD: dbpassword9090 ports: - 5432:5432 volumes: - /home/data/litellm/postgres/data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -d litellm -U llmproxy] interval: 1s timeout: 5s retries: 10接着写.env。LITELLM_MASTER_KEY是登录管理后台用的密码也是调用管理 API 的凭证。TAOTOKEN_API_KEY放你从 TaoToken 控制台拿到的 Key。LITELLM_MASTER_KEYsk-1234 STORE_MODEL_IN_DBTrue TAOTOKEN_API_KEYsk-your-taotoken-key然后是config.yaml这是模型路由的核心。下面配了三个模型别名全部指向 TaoToken 的 API 地址。model_name是应用侧调用的名字litellm_params.model是 LiteLLM 内部识别的模型标识api_base统一写https://taotoken.net/api。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: anthropic/claude-3-5-sonnet-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 general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: os.environ/DATABASE_URL这里有个细节api_key: os.environ/TAOTOKEN_API_KEY这种写法让 LiteLLM 从环境变量读取不要把 Key 硬编码进config.yaml否则提交到 Git 就泄露了。启动服务docker compose -p litellm up -d启动后访问http://localhost:4000用户名admin密码就是.env里的LITELLM_MASTER_KEY。如果页面打不开先看容器日志docker compose -p litellm logs -f litellm4. 验证请求curl 与 OpenAI SDK 多模型路由服务起来之后先别急着改业务代码用 curl 验证鉴权和路由。LiteLLM 暴露的是 OpenAI 兼容接口所以请求格式和 OpenAI 一样只是base_url换成http://localhost:4000。先测最基础的模型列表接口确认网关活着curl http://localhost:4000/v1/models \ -H Authorization: Bearer sk-1234返回里应该能看到gpt-4o、claude-sonnet、deepseek-chat三个别名。如果返回 401说明Authorization头里的 Key 和LITELLM_MASTER_KEY不一致。接着测一次对话请求走gpt-4o别名curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 用一句话解释什么是大模型网关}] }如果返回里有choices[0].message.content说明 LiteLLM 已经成功把请求转发到 TaoToken再路由到对应模型。换claude-sonnet再测一次验证多模型路由curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: 写一个 Python 快速排序}] }用 OpenAI SDK 验证更贴近真实业务。Python 示例from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-1234, ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 返回 JSON{\ok\: true}}], ) print(resp.choices[0].message.content)Node.js 示例import OpenAI from openai; const client new OpenAI({ baseURL: http://localhost:4000/v1, apiKey: sk-1234, }); const resp await client.chat.completions.create({ model: gpt-4o, messages: [{ role: user, content: 你好 }], }); console.log(resp.choices[0].message.content);实测下来只要config.yaml里api_base写对、.env里 Key 有效三个模型别名都能正常返回。如果某个模型报model not found多半是litellm_params.model的命名和 TaoToken 支持的模型 ID 对不上去文档页核对一下。5. 本篇常见错排查401、local proxy failed、reading choices部署和调用过程中报错基本集中在几个地方。下面按真实报错对照排查。401 Unauthorized。两种可能一是调用时Authorization头里的 Key 不是LITELLM_MASTER_KEY二是config.yaml里api_key没读到TAOTOKEN_API_KEY。先确认.env文件在docker-compose.yml同级目录且env_file配置正确。然后进容器看环境变量docker compose -p litellm exec litellm env | grep TAOTOKEN如果输出为空说明.env没被加载检查文件名是不是.env而不是.env.txt。local proxy failed / connection refused。这类报错通常是 LiteLLM 容器访问不到api_base。如果你在config.yaml里写了http://localhost:xxxx容器内的localhost指向容器自己不是宿主机。正确做法是写 TaoToken 的公网地址https://taotoken.net/api或者用host.docker.internal指向宿主机。reading choices 报错 / KeyError choices。这通常说明上游返回的不是标准 OpenAI 格式或者返回了错误信息但被当成正常响应解析。先看 LiteLLM 日志里上游的原始返回docker compose -p litellm logs -f litellm | grep -i error如果日志里显示上游返回 400 或 403多半是模型 ID 写错或 Key 额度不足。去 TaoToken 控制台确认 Key 状态和余额。OAuth / 鉴权失败。如果你用的是 Claude Code 或 Codex 这类工具它们可能走 OAuth 流程而不是简单 API Key。这种情况下LiteLLM 的config.yaml里要确保api_key是有效的 TaoToken Key并且api_base指向https://taotoken.net/api。如果工具本身要求填 Base URL、Key、Model ID 三件套就按这个填Base URL 用http://localhost:4000/v1Key 用LITELLM_MASTER_KEYModel ID 用config.yaml里的model_name别名。数据库连接失败。db容器的 volumes 路径如果没改成真实路径Postgres 可能启动失败。检查docker compose -p litellm ps如果db状态是unhealthy看它的日志docker compose -p litellm logs db路径不存在或权限不足都会导致启动失败改成你有写权限的目录即可。6. 长期使用建议与接入入口跑通之后下一步是把 LiteLLM 真正用起来。几个实用建议。第一Virtual Key 要按用途拆。不要所有服务共用一个 Key而是按团队、按项目、按环境分别创建。LiteLLM 支持给每个 Virtual Key 设预算和速率限制这样某个服务跑飞了也不会拖垮整体账单。第二模型别名要稳定。应用侧只认gpt-4o、claude-sonnet这种别名底层换模型时只改config.yaml业务代码不动。这是网关最大的价值之一。第三配置进版本控制Key 不进。docker-compose.yml和config.yaml可以提交.env要加进.gitignore。团队协作时用 CI 变量或密钥管理服务注入。第四定期看 LiteLLM 后台的用量统计。它能按模型、按 Key、按时间维度看请求量和花费比翻各家平台账单省事得多。如果你还没开始接入建议先去 TaoToken 控制台创建 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各模型的详细参数。想先验证模型效果用模型对话页面最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。如果是长期编码或 Agent 场景直接看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后提醒一句LiteLLM 的config.yaml改完要重启容器才生效docker compose -p litellm restart litellm就行。别改完配置直接测然后对着旧配置排查半天。