企业官网建设流程全解析

先给一个判断：LiteLLM Router 真正值钱的地方，不是把一堆模型接进来，而是把模型调用的预算、限流、重试、fallback 和日志放到同一个网关里治理。架构图本身没问题，真正让项目卡住的是落地时 Key 越攒越多：OpenAI 一把、Anthropic 一把、Google 一把，每把还要单独看余额、单独续费、单独排查限额。TaoToken 的做法是把这些 Key 收拢成一把，再喂给同一个 LiteLLM Router。要拿这一把 Key，先去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content= 注册并创建 API Key；Router 里的 Base URL 统一填 https://taotoken.net/api，末尾不要加 /v1。下面是迁移时实际要改的文件和验证步骤。

1. 这张架构图没错，麻烦的是 Key 越攒越多

1.1 Router 管的是策略，不是 Key 本身

很多人把 LiteLLM Router 理解成「一个接口连十个模型」，其实更准确的说法是：它是一套网关策略。请求进来后走哪个模型、失败重试几次、超预算怎么办、上游挂了是否降级到备用模型，都由 router_settings 和每个 model 的 litellm_params 控制。这些规则才是 Router 的核心资产，API Key 只是执行这些规则时需要的通行证。

既然通行证只是凭据，那一叠 Key 散落在各家控制台里就是最不该有的运维负担。某个 Key 过期、某个 Key 超限、某团队偷偷用了不该用的模型，排查起来都要先经历一个「先确认是哪个 Key」的过程。把这些 Key 收到一处，不改变规则本身，只改变规则执行时的认证方式。架构图不用重画，中间只是多了一条统一通道。

1.2 迁移前后对比：三把 Key 收成一把

需要说清楚：TaoToken 不是把三家模型合并成一个模型。GPT 仍是 GPT，Claude 仍是 Claude，Gemini 仍是 Gemini。Router 决定的 model_name 完全不变，变化的只是上游 Base URL 和认证凭据。这样做的收益是：以后新增模型时不需要再让运维去申请另一家平台的 Key，只需在配置里把新模型的 api_key 也填上同一把，再核对模型广场的 ID。

2. 拿 Key：先到模型广场对一下模型 ID

2.1 注册、创建 API Key 和模型 ID 都在同一个地方

打开 TaoToken，注册登录后，在控制台创建 API Key，再把 Key 复制到剪贴板备用。模型 ID 不用到别处记，模型广场那一页就有当时上线的模型列表。我迁移时习惯先把 config.yaml 里用到的模型名抄到文本里，再和模型广场逐行对照，确认每个模型都处于可调用状态，然后才动配置。

这一步容易踩的坑是：网上各种配置片段里经常出现带日期后缀或「更强」字样的模型名。这些名字不一定在模型广场上线，直接复制过来，Router 会把请求发给上游但上游不认识这个模型，最终报 Invalid model 或 404。所以请记住：模型 ID 一律以模型广场当时列表为准，不要照搬别的文章的配置。

2.2 兼容通道本身不参与路由决策

TaoToken 在 LiteLLM 里的角色就是一条兼容通道。它不参与路由决策，不决定哪个请求走哪个模型，更不干预失败重试。路由决策仍然由 LiteLLM Router 做：这里配置的重试次数、超时时间、冷却时间、预算告警，迁移后原样生效。

可以把 Router 想成外卖平台的调度中心，各家餐厅是模型供应商，配送规则是路由策略。原来调度中心需要分别和各餐厅结算，每接一家餐厅就要押一张卡；TaoToken 相当于把所有餐厅的结算收到同一个账房，Router 依然按自己的规则派单、催单、取消订单。理解这一点后，迁移范围就很清楚了：只动 model_list 里的 api_key 和 api_base，其它一切保持原状。

3. 改动只落在 config.yaml 的 model_list

3.1 迁移前的状态：三个 litellm_params 三把 Key

假设你现在的 config.yaml 长这样：

model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: sk-123456 - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet api_key: sk-ant-abcdef - model_name: gemini-pro litellm_params: model: gemini/gemini-pro api_key: AIzaSy-xyz

三个模型，三把 Key，三家控制台。任何一把失效或超限，Router 都会在线上表现出「某个模型突然不可用」，但你很难第一时间判断是 Key 的问题还是模型本身的问题，因为在 Router 日志里看到的是同一个错误码。长期维护下来，哪个 Key 什么时候过期基本靠人肉记。

3.2 迁移后的状态：api_key 全部替换，api_base 固定

把上面片段改成下面这样：

model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: YOUR_API_KEY api_base: https://taotoken.net/api - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet api_key: YOUR_API_KEY api_base: https://taotoken.net/api - model_name: gemini-pro litellm_params: model: gemini/gemini-pro api_key: YOUR_API_KEY api_base: https://taotoken.net/api

注意下面几点：

上面示例里的 claude-sonnet 只是示意，你迁移时保持 config.yaml 里原来的模型名即可，不必改成示例里的缩写。如果你 Key 习惯放在环境变量里，检查一下.env中的OPENAI_API_KEY、ANTHROPIC_API_KEY这类配置，替换成同一把新 Key，否则环境变量优先级会盖过 config.yaml。

3.3 router_settings 保持原样，限流降级不用重写

很多文章会把迁移写成「换 Key」一件事，但真正要关注的是别的配置不要被动到。比如你的 router_settings 里可能已经配了这些：

router_settings: num_retries: 2 request_timeout: 30 allowed_fails: 3 cooldown_time: 30 routing_strategy: usage-based-routing-v2

这些参数定义的是 Router 的重试、超时、冷却和路由策略。迁移时建议原样保留，先观察一段时间再微调。如果担心上游新通道的并发能力，可以在每个 litellm_params 下保留原来的 rpm/tpm 限流值，不要因为 Key 统一了就把限流放宽，否则某个项目突发流量会把整个通道打满，连带其它项目也受影响。

4. 验证：/health 过了之后再发一次真实请求

4.1 本地启动 Router，先看 readiness

配置保存后，先用命令行把 Router 跑起来：

litellm --config ./config.yaml --port 4000

然后请求本地的健康检查端点：

curl http://localhost:4000/health/readiness

返回 {"status":"OK"} 说明配置能被正常解析，Router 处于就绪状态。需要注意的是，readiness 只代表 Router 本身没问题，它不会真的去上游模型发一次请求。所以健康检查之后，一定要再做一次实际调用。

4.2 用本地代理发一条消息，看它走到哪个模型

LiteLLM 启动后会在本地暴露一个 OpenAI 兼容入口，直接向它发请求即可：

curl http://localhost:4000/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}] }'

把 model 依次换成 config.yaml 里定义的其他别名，比如 claude-sonnet、gemini-pro，分别看是否正常返回。如果某个模型报错，先把报错信息和该模型的 litellm_params 对照一遍，再决定是改 Key 还是改模型 ID。同时看一眼 Router 日志里实际命中的模型字段，确认没有因为 fallback 被悄悄换到别的模型。

4.3 回控制台对一下这次调用是否记账

请求成功后，回 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content= 的控制台看调用记录。刚才三次请求应该都能看到对应的用量。这一步能证明流量确实经过了 TaoToken 通道，而不是因为环境变量残留走到了别的上游。

如果控制台没有记录，先查 Router 进程的环境变量里是否还有旧的 ANTHROPIC_BASE_URL 或 OPENAI_BASE_URL，这类变量会覆盖 config.yaml 里的 api_base，导致请求根本没发到 https://taotoken.net/api。清理掉之后重启 Router 再验一次。

5. 复制这张迁移检查表

5.1 先从低风险项目开始收拢

收拢 Key 解决的是凭据管理问题，不是治理问题。原来 Router 做的预算、限流、重试、审计，迁移后一样不少。建议先拿一个低风险项目做试点，跑一两天确认稳定，再逐步把其它项目的 Router 实例都切到同一套配置上。

5.2 键统一之后更要管住降级边界

Key 统一之后，切换模型的成本肉眼可见地降低，这时候最容易顺手把高风险任务的 fallback 打开，让失败请求自动转到更便宜的模型上。便宜模型能接住很多低风险任务，但高风险任务需要的是稳定、可追踪、可解释的失败记录。默认 fallback 不该把审计要求高的请求悄悄带到其它供应商。

6. 换 Key 之后最常见的三个报错

6.1 401 Unauthorized：Key 本身的问题

换成 YOUR_API_KEY 后如果收到 401，先按顺序排查三件事：复制 Key 时有没有多出空格或换行；Key 是不是在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content= 控制台创建的；有没有把官网登录密码当成 API Key 填进去。这三处都正常，再看 Router 日志里实际发出的 Authorization 头，确认不是被系统环境变量里的旧 Key 覆盖。

6.2 model not found：模型 ID 没对齐模型广场

这个报错在迁移后最常见。原因是 config.yaml 里 litellm_params.model 写了一个模型广场里没有上线的 ID，或者前缀写错，LiteLLM 把 openai/ 写成了别的供应商前缀。打开模型广场，把报错模型的名字逐字对照一遍。另外要区分 model_name 和 litellm_params.model：前者是 Router 内部用的别名，后者必须能被上游真实识别。两者不一致时，Router 可能成功选路，但上游拒绝执行。

6.3 请求变慢或者频繁失败：重试参数和冷却时间不合适

如果请求不是直接报错，而是慢、偶尔成功偶尔失败，问题通常在 router_settings 的 num_retries、allowed_fails、cooldown_time。上游通道短暂抖动时，Router 会按配置重试，重试次数太多会把超时时间叠得很长。还有一种隐蔽情况：api_base 写成了 https://taotoken.net/api/v1，末尾多出的 /v1 会让上游返回 404，Router 把这当成失败又自动重试，最后表现为「请求明显变慢」。核对一下 api_base，再看限流值是否和模型广场标明的速率一致。

7. 迁移收尾：用同一把 Key 跑一次对话再离开

7.1 先到模型对话页验证 Key 可用性

如果手头没有现成的 LiteLLM 环境，可以在 模型对话页 先用同一把 Key 发一条消息。这样能把「Key 的问题」和「配置的问题」隔离开：对话页正常，说明 Key 和模型 ID 都没错，问题在 LiteLLM 配置；对话页也报错，那就先回控制台重新创建 Key 再看模型名单。

7.2 按调用记录评估 Coding Plan，再决定要不要继续调整

验证通过后，回到 API Keys 控制台 看这把 Key 在 Router 迁移期间的调用记录，确认每次请求都记在账上。如果团队接下来会频繁用 Router 跑任务，可以打开 Coding Plan 看套餐是否匹配用量。至于 Claude Code 这类命令行工具，接入思路一致：环境变量里的 Base URL 同样填 https://taotoken.net/api，具体字段对照 Claude Code 接入文档。先把 Router 这条主线跑稳，再逐步把其它工具切到同一把 Key 上。