1. 为什么你的多模型调用总是乱成一锅粥如果你同时用过 OpenAI、Claude、通义千问、本地 Ollama大概率经历过这种场面每个厂商的 SDK 长得不一样鉴权方式不一样返回结构也不一样。今天想从 GPT-4o 换到本地 qwen2.5-coder 跑个离线任务结果发现代码里到处是if model xxx的分支判断改一处漏一处。更别提团队协作时每个人的 Key 散落在各自的.env里谁用了多少额度、哪个模型超支了全靠猜。LiteLLM 就是来解决这个问题的。它是一个开源的 LLM 网关和 SDK核心能力是把 100 多种大模型的调用方式统一转换成 OpenAI 兼容格式。你只需要学会一套 OpenAI 的调用姿势就能无缝切换 Anthropic、Google、Azure、HuggingFace、Ollama、vLLM 等后端。对开发者来说这意味着业务代码里只认base_url和model两个变量背后换什么模型都不用动代码。这篇文章面向的是需要在多个模型之间频繁切换的开发者尤其是那些想让 Claude Code、Cline 这类工具接入本地模型或者想给团队搭一个统一 AI 入口的人。我会交付可复制的 LiteLLMconfig.yaml、TaoToken 统一 Key 的接入示例以及调用验证和错误排查的完整步骤。你跟着做能跑通一个「一个 Key 管所有模型」的网关。先说清楚 LiteLLM 的两种使用模式这决定了你后面怎么落地。第一种是 Python SDK适合在代码里直接集成最轻量第二种是 Proxy Server把 LiteLLM 跑成一个独立 HTTP 服务任何语言都能调适合生产环境和多团队协作。大部分人的痛点其实在第二种因为一旦有了统一网关前端、后端、脚本工具就都只认一个地址了。我试过在本地同时跑 Ollama 和几个云端模型最开始也是每个项目单独配 Key后来发现 LiteLLM 的 Proxy 模式能把这事收拢到一个配置文件里。下面从环境准备开始一步步把网关搭起来。2. TaoToken 统一 Key 与 LiteLLM 网关的前置准备在动手写配置之前先把「Key 从哪来」这件事理清楚。LiteLLM 本身是一个路由层它不生产模型能力只负责把请求转发到各个后端。所以你需要为每个后端准备凭证。如果每个厂商都单独申请 Key管理成本还是很高。这时候可以用 TaoToken 作为统一入口它提供 OpenAI 兼容的 API 地址一个 Key 就能访问多种模型省去在 LiteLLM 里维护一堆厂商 Key 的麻烦。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为api_base使用。你需要在控制台生成一个 API Key这个 Key 就是后面 LiteLLM 配置里api_key字段的值。生成 Key 的入口在控制台的 API Keys 页面登录后就能看到创建按钮。如果你还没账号可以先到官网了解整体能力再决定要不要接入。这里要强调一个概念LiteLLM 的model_list里每个条目代表一个「对外暴露的模型名」到「实际后端」的映射。你可以把 TaoToken 当成一个后端也可以把本地 Ollama 当成另一个后端两者在 LiteLLM 里是平级的。这样设计的好处是业务侧只看到你定义的model_name完全不用关心背后是云端还是本地。前置准备清单如下Python 3.9 以上环境LiteLLM 对版本有要求太低会装不上、pip 包管理工具、一个 TaoToken API Key、以及可选的本地 Ollama 服务。如果你打算用 Docker 部署还需要 Docker 和 Docker Compose。我建议先用 pip 方式跑通确认逻辑没问题再上 Docker这样排错更直观。安装 LiteLLM 的 proxy 版本命令是pip install litellm[proxy]。注意引号不能省否则 shell 可能把方括号当成通配符处理。装完之后用litellm --version验证一下能输出版本号就说明环境 OK。这一步如果卡在依赖编译上通常是 Python 版本太老或者缺少编译工具链升级 Python 或安装 build-essential 即可。3. 可复制的 LiteLLM config.yaml 与 TaoToken 接入配置这一节是全文的核心直接给你能用的配置文件。先建一个工作目录比如litellm-gateway在里面创建config.yaml。下面这份配置同时接了 TaoToken 和本地 Ollama你可以按需删减。model_list: - model_name: tao-gpt-4o litellm_params: model: openai/gpt-4o api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: tao-claude-sonnet litellm_params: model: openai/claude-3-5-sonnet api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY - model_name: local-qwen-coder litellm_params: model: ollama/qwen2.5-coder:7b api_base: http://localhost:11434 litellm_settings: drop_params: true set_verbose: true general_settings: master_key: sk-litellm-local-2024逐段解释一下。model_list里每一项的model_name是你对外暴露的名字调用时用它litellm_params.model是 LiteLLM 内部识别的后端标识openai/前缀表示走 OpenAI 兼容协议ollama/前缀表示走 Ollama 协议。TaoToken 因为是 OpenAI 兼容的所以用openai/前缀把api_base指向https://taotoken.net/api就行。api_key: os.environ/TAOTOKEN_API_KEY这种写法表示从环境变量读取不要把 Key 硬编码进配置文件否则提交到 Git 就泄露了。启动前先设置环境变量export TAOTOKEN_API_KEY你的实际KeyWindows PowerShell 用$env:TAOTOKEN_API_KEY你的实际Key。drop_params: true的作用是当某个后端不支持某些参数时自动丢弃避免报错这个在多后端场景下很实用。master_key是 LiteLLM 自己的管理密钥用来保护管理接口和生成虚拟 Key跟后端厂商的 Key 是两回事。启动网关litellm --config config.yaml --port 4000看到Uvicorn running on http://0.0.0.0:4000就说明起来了。如果你想让配置更工程化可以用 Docker Compose 部署把config.yaml挂载进容器同时接一个 Postgres 存用量数据。Docker 方式的docker-compose.yml里environment段设置DATABASE_URL和STORE_MODEL_IN_DBTruevolumes段把本地config.yaml映射到容器内的/app/config.yaml启动命令加上--config /app/config.yaml。这样重启容器配置不丢用量也能持久化。关于模型 ID 的写法有个坑要提醒TaoToken 侧的模型名要跟它文档里列出的保持一致不要自己臆造。如果你不确定某个模型 ID 是否可用先用模型对话页面手动发一条消息验证确认能通再写进配置。LiteLLM 的model_name可以随便起但litellm_params.model里的后半段必须是后端真实认的 ID。4. 验证请求从 curl 到 Claude Code 接入的完整链路配置写好了接下来验证它真的能通。最直接的方式是用 curl 打 LiteLLM 的/v1/chat/completions接口curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-litellm-local-2024 \ -H Content-Type: application/json \ -d { model: tao-gpt-4o, messages: [{role: user, content: 用一句话解释什么是网关}] }注意这里的Authorization用的是 LiteLLM 的master_key不是 TaoToken 的 Key。LiteLLM 收到请求后会根据model字段找到对应的后端再用配置里的api_key去请求 TaoToken。如果返回里有choices[0].message.content说明整条链路通了。如果返回 401先检查master_key是否跟配置一致如果返回的是后端鉴权错误检查TAOTOKEN_API_KEY环境变量有没有生效。Python 侧调用更简单用 openai 库指向 LiteLLM 即可import openai client openai.OpenAI( api_keysk-litellm-local-2024, base_urlhttp://localhost:4000 ) resp client.chat.completions.create( modeltao-claude-sonnet, messages[{role: user, content: 写一个二分查找}] ) print(resp.choices[0].message.content)换模型只改model参数其他一行不动。这就是统一网关的价值。接下来是很多人关心的场景让 Claude Code 接入。Claude Code 默认走 Anthropic 协议但 LiteLLM 可以把它转成 OpenAI 兼容。设置两个环境变量export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-litellm-local-2024 claude启动后在 Claude Code 里输入/model选择你在config.yaml里定义的model_name比如local-qwen-coder就能用本地模型跑 tools 调用了。这里的关键是ANTHROPIC_BASE_URL指向 LiteLLM而不是直连 Ollama因为直连会因协议不兼容失败。LiteLLM 在中间做了协议转换Claude Code 以为自己连的是 OpenAI 兼容服务实际后端是本地模型。如果你用的是 Cline 或 CC Switch 这类工具配置逻辑一样Base URL 填http://localhost:4000API Key 填master_keyModel ID 填model_name。三件套缺一不可尤其是 Model ID 必须跟配置文件里的model_name完全一致大小写敏感。验证本地 Ollama 那条链路时先确认ollama list里有qwen2.5-coder:7b没有的话先ollama pull。然后 curl 打local-qwen-coder如果返回超时多半是 Ollama 没启动或者端口不是 11434。Ollama 默认监听127.0.0.1:11434LiteLLM 在容器里跑的话localhost指向容器自身需要改成宿主机的实际 IP 或用host.docker.internal。5. 常见报错排查401、local proxy failed 与 reading choices排错是绕不开的环节下面按真实报错逐个拆。401 Unauthorized。这个最常见分两种来源。第一种是 LiteLLM 层拒绝说明请求头里的Authorization跟master_key不匹配检查有没有多空格或者用了 TaoToken 的 Key 去调 LiteLLM。第二种是后端拒绝LiteLLM 日志里会显示上游返回 401这时候检查TAOTOKEN_API_KEY环境变量是否在当前 shell 生效echo $TAOTOKEN_API_KEY看一眼。环境变量在启动 LiteLLM 的同一个终端里设置才有效换个窗口就没了。local proxy failed / connection refused。这个通常出现在 Docker 部署时。LiteLLM 容器里配置api_base: http://localhost:11434但localhost在容器内指向容器自己不是宿主机。解决办法是把api_base改成http://host.docker.internal:11434Mac/WindowsLinux 下用宿主机的局域网 IP。另外确认 Ollama 是否允许外部访问默认只监听本地回环需要设置OLLAMA_HOST0.0.0.0再重启。reading choices of undefined。这个报错说明返回结构里没有choices字段通常是上游返回了错误信息但被当成正常响应解析了。打开set_verbose: true看 LiteLLM 的完整日志找到上游实际返回的 JSON。常见原因是模型 ID 写错了TaoToken 侧返回了model not found。对照文档核对litellm_params.model里的模型名别把gpt-4o写成gpt4o。OAuth / token 相关报错。如果你在 Claude Code 里看到 OAuth 报错说明它还在尝试走 Anthropic 官方鉴权。确认ANTHROPIC_AUTH_TOKEN已设置并且ANTHROPIC_BASE_URL指向 LiteLLM。有些版本还需要设置ANTHROPIC_API_KEY为空字符串来强制走 token 模式。模型切换后 tools 调用失败。不是所有模型都支持 function calling。本地小模型如果没经过 tools 训练Claude Code 的工具调用会失败。这时候换一个支持 tools 的模型或者用 TaoToken 侧的云端模型验证。LiteLLM 的drop_params只能丢参数不能给模型补能力。排查通用套路先看 LiteLLM 终端日志它会打印请求转发到哪个后端、上游返回什么状态码再用 curl 直接打后端地址绕过 LiteLLM 确认后端本身可用最后检查配置文件里的model_name和调用时传的model是否一致。三步下来基本能定位。6. 把网关用起来从验证到长期编码的落地建议跑通验证只是第一步真正让网关产生价值的是把它用进日常开发流。如果你主要在编辑器里写代码可以把 Cline 或 Claude Code 的 Base URL 固定指向 LiteLLM这样切换模型不用改编辑器配置只改config.yaml重启即可。对于需要长期跑 Agent 任务的场景建议用 Coding Plan 这类方案配合网关把额度管理和模型路由统一起来避免每个工具单独配 Key。团队协作时用 LiteLLM 的虚拟 Key 功能给每个成员或项目发独立 Key设置预算上限。生成虚拟 Key 的接口是/key/generate请求头带master_keybody 里指定models、budget、duration。这样谁超支了直接拒绝用量日志也能追溯。虚拟 Key 只能调授权的模型不能碰管理接口安全性比直接发master_key高。配置维护上把config.yaml纳入版本管理但 Key 走环境变量或密钥管理服务。每次加新模型先在模型对话页面验证模型 ID 可用再写进配置。改完配置重启 LiteLLM 生效Docker 方式用docker-compose restart litellm。如果配置写错了导致启动失败LiteLLM 会在终端打印 YAML 解析错误按行号定位即可。最后给一个实用技巧在config.yaml里给常用模型起短名字比如fast、smart、local业务代码里用这些别名背后映射到具体模型。这样以后换后端只改映射调用方完全无感。网关的价值不在于接了多少模型而在于让模型切换这件事对业务透明。把配置管好剩下的就是安心写代码了。