1. LiteLLM 报 model 缺厂商前缀到底卡在哪一步你如果正在用 LiteLLM Proxy 搭一个统一的大模型接口网关大概率见过这个报错model字段找不到对应厂商或者请求发出去直接被上游拒掉。LiteLLM 本身能封装 100 多个厂商的接口OpenAI、Claude、Gemini、Ollama、DeepSeek 都能接但它的model命名规则分两种场景很多人就是在这里踩坑。简单说LiteLLM 有两种用法一种是 Python SDK 直接调另一种是 Proxy 网关服务。SDK 直调时model必须写成厂商前缀/模型名比如openai/gpt-4o、deepseek/deepseek-chat、ollama/qwen2.5:7b少了前缀 LiteLLM 不知道往哪家发。而 Proxy 网关不一样客户端请求的是你在config.yaml里定义的model_name别名前缀是在litellm_params里写的客户端不用管。这篇就按排障视角把上游那段「常见踩坑」改掉用 TaoToken 作为统一上游在每条litellm_params里把api_base指向 TaoToken 的接口地址api_key填 TaoToken 创建的 KeyLiteLLM 只负责把model别名分发出去。适合已经在跑 LiteLLM Proxy、但被前缀和上游配置绕晕的人。2. 先把 TaoToken 的 Key 和接口地址准备好在改config.yaml之前得先有一把能用的上游 Key。打开https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注册账号进控制台创建 API Key。这个 Key 就是你后面填进litellm_params.api_key的那把请求最终消耗的是这把 Key 的额度。接口地址这块要记牢TaoToken 的 API 根地址是https://taotoken.net/api。填进配置文件时不要带/v1也不要带任何 utm 参数。LiteLLM 会自己在后面拼/v1/chat/completions这类路径你多写一段/v1就会变成/api/v1/v1/...直接 404。注意api_base只写到https://taotoken.net/api为止后面的路径交给 LiteLLM 处理。如果你还没建 Key进控制台后找 API Keys 页面新建一把复制出来先存好。这个 Key 只在创建时完整显示一次丢了就得重建。模型对话、Coding Plan、控制台、API Keys、接入文档这些入口都在官网导航里按需点进去就行。3. 改 config.yaml把 litellm_params 指到 TaoToken核心改动就一处每条litellm_params里加api_baseapi_key换成 TaoToken 的 Key。model字段这里写的是带厂商前缀的完整名因为这是 LiteLLM 内部用来识别上游协议的和客户端请求的model_name别名是两回事。model_list: # DeepSeek 别名客户端请求 deepseek-chat - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_base: https://taotoken.net/api api_key: sk-你的TaoTokenKey # OpenAI 别名 - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_base: https://taotoken.net/api api_key: sk-你的TaoTokenKey # Claude 别名 - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_base: https://taotoken.net/api api_key: sk-你的TaoTokenKey general_settings: master_key: sk-master-123456 # 客户端访问网关用的密钥自定义几个关键点对照一下字段写什么易错点model_name客户端请求用的别名随便起客户端认这个litellm_params.model带厂商前缀的完整名漏前缀 LiteLLM 找不到上游litellm_params.api_basehttps://taotoken.net/api别带/v1、别带 utmlitellm_params.api_keyTaoToken 创建的 Key别和 master_key 写串general_settings.master_key客户端访问网关的密钥和上游 Key 是两把这里最容易搞混的就是两把 Keymaster_key是客户端调你本地网关时用的api_key是 LiteLLM 转发到 TaoToken 时用的。写串了就是 401后面排障会细说。4. 起服务并验证转发链是否打通配置写完启动 Proxylitellm --config config.yaml --host 0.0.0.0 --port 4000看到Proxy running on http://0.0.0.0:4000就说明服务起来了。然后用 OpenAI 的 Python 客户端请求本地网关base_url仍然是http://localhost:4000/v1api_key填master_keymodel填你在 yaml 里定义的别名from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-master-123456 # 这里用 master_key不是 TaoToken Key ) resp client.chat.completions.create( modeldeepseek-chat, # 用 yaml 里的 model_name 别名 messages[{role: user, content: hello world}] ) print(resp.choices[0].message.content)能打印出内容说明整条链路通了客户端 → 本地 LiteLLM 网关 → TaoToken 上游 → 模型返回。你也可以用 curl 快速测一把curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-master-123456 \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: hi}] }返回 JSON 里choices[0].message.content有内容就说明model别名分发正常api_base和 Key 都没写错。这一步过了后面接前端、接各类 OpenAI 兼容工具都只是换个base_url的事。5. 本篇常见错排查401、找不到模型、404排障时按报错类型对号入座基本能覆盖九成问题。报 401 Unauthorized先分清是哪把 Key 出错。客户端请求本地网关报 401说明master_key对不上检查请求头里的 Bearer 和 yaml 里general_settings.master_key是否一致。如果 LiteLLM 日志里显示转发到上游时 401那就是litellm_params.api_key写错了或者 Key 被删了、额度用完了回控制台核对。报找不到模型 / model not found两种可能。一是客户端请求的model别名在 yaml 里没有对应的model_name拼写对不上二是litellm_params.model漏了厂商前缀比如写成deepseek-chat而不是deepseek/deepseek-chatLiteLLM 不知道往哪家发。SDK 直调必须带前缀Proxy 里litellm_params.model也必须带只有客户端请求的model_name是别名。报 404 / 路径不对八成是api_base多写了/v1。正确写法是https://taotoken.net/apiLiteLLM 自己拼后续路径。写成https://taotoken.net/api/v1就会变成重复路径。另外确认没把 utm 参数粘进去配置文件里只留干净的根地址。Ollama 相关报错如果你同时接了本地 Ollama那条litellm_params必须补api_base: http://localhost:11434否则 LiteLLM 不知道本地服务在哪。这条和 TaoToken 的配置是并列的别混在一起。提示改完 yaml 一定要重启litellm --config config.yaml配置不会热加载。6. 接入文档与后续分流转发链验证通过后日常用起来就简单了客户端只认本地网关的http://localhost:4000/v1和master_key模型切换只改请求里的model别名上游的 Key 和地址都锁在config.yaml里不用每个程序各配一遍。如果你要长期跑编码类任务或 Agent可以看 Coding Plan把额度规划清楚单纯想验证某个模型效果直接进模型对话页面试接入细节和参数说明在接入文档里API Keys 页面负责创建和管理 Key。地址统一从https://taotoken.net/api走配置里别带/v1和 utm这两条记住基本不会再被前缀和路径问题卡住。