企业官网建设流程全解析

1. 为什么需要 LiteLLM 这层代理，以及它到底解决什么问题

如果你手上同时有 OpenAI、Anthropic、Google、DeepSeek 这几家的 Key，项目里又散落着各种 SDK 调用代码，那你大概率经历过这种场景：某个模型临时限流，想把请求切到另一家，结果发现要改代码、改环境变量、改鉴权头，改完还要重新测一遍。LiteLLM 就是冲着这个痛点来的——它是一个开源的 AI 代理网关，对外暴露一套 OpenAI 兼容的/v1/chat/completions接口，对内帮你把请求路由到任意厂商的模型上。

用一句话概括：LiteLLM 是一个统一 AI 代理平台，能把 100 多家模型厂商的 API 收敛成一个入口、一把 Key、一套调用格式。它适合三类人：一是需要频繁切换模型做对比测试的算法同学；二是要给团队内部多个项目统一发 Key、控预算的运维或平台开发者；三是想把模型调用从业务代码里解耦出来的后端工程师。

它和直接调厂商 API 的区别，我用一张表说清楚：

我实测下来，最省心的点在于「模型切换只改一个字符串」。比如你原来调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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册账号，然后在控制台里生成 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

生成 Key 的时候注意两点：一是 Key 只在创建时完整显示一次，记得立刻复制保存；二是可以给 Key 起个名字，比如litellm-proxy，方便以后区分用途。

TaoToken 的 API Base URL 是https://taotoken.net/api，注意这个地址不带任何查询参数。在 LiteLLM 的配置里，我们会把它作为api_base填进去。

如果你不确定有哪些模型可用，可以先在模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 里试一下，或者直接调/v1/models接口拉列表。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的模型 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 Key），config.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.yml：

version: "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" - "--port=4000" - "--num_workers=2" 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 文件

同目录下新建.env：

POSTGRES_PASSWORD=换成你自己的数据库密码 LITELLM_MASTER_KEY=sk-换成你自己的管理员密钥 TAOTOKEN_API_KEY=你的TaoTokenKey

LITELLM_MASTER_KEY建议以sk-开头，这是 LiteLLM 的惯例，虽然不强制但能避免一些工具误判。三个值都别用默认的，尤其是数据库密码。

3.3 config.yaml

这是模型路由的核心配置。新建config.yaml：

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: 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 大概几十 MB，LiteLLM 镜像稍大一些。等两个容器都起来后，用下面的命令看状态：

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.yaml，command里读的也是/app/config.yaml。这两个路径必须一致，否则容器里读不到配置。如果你改了挂载路径，command里的路径也要同步改。这个坑我在早期部署时踩过，容器起来了但模型列表是空的，查了半天才发现是路径对不上。

4. 验证请求与模型切换测试

服务起来之后，别急着接业务代码，先用 curl 把链路验证一遍。这一步能帮你快速定位问题出在 LiteLLM 还是 TaoToken 通道。

4.1 健康检查

先看服务本身活没活：

curl http://localhost:4000/health/liveliness

返回"I'm 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-sonnet：

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": "用一句话解释什么是代理网关"}] }'

再换成deepseek-chat试一次。三次请求除了model字段不同，其他完全一样。这就是统一代理的意义——业务代码不用感知底层是哪家模型。

4.5 用 Python SDK 验证

实际项目里更多是用 SDK 调用。因为 LiteLLM 是 OpenAI 兼容的，直接用 openai 库就行：

from openai import OpenAI client = OpenAI( base_url="http://localhost:4000/v1", api_key="你的LITELLM_MASTER_KEY" ) for model_name in ["gpt-4o", "claude-sonnet", "deepseek-chat"]: resp = client.chat.completions.create( model=model_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 -d

5.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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。日常验证模型效果，用模型对话页面就够了。接入过程中遇到鉴权或路由问题，接入文档里有更细的说明，API Key 管理在控制台里操作。

最后提醒一句，LiteLLM 的配置改完后记得重启容器让配置生效，docker compose restart litellm就行。数据库数据是持久化的，重启不会丢 Key 和用量记录。整套跑下来，你就有了一套自己的统一 AI 代理平台，后面接多少模型、发多少 Key，都在这一个入口里管。