1. 为什么你需要 LiteLLM多模型调用的真实痛点如果你刚开始接触大语言模型开发大概率经历过这样的场景项目里想同时接入几个不同厂商的模型做对比结果发现每家的 SDK 都不一样。OpenAI 用openai包Anthropic 用anthropic包Google 又是另一套google-generativeai。光是记住这些库的初始化参数、消息格式、返回结构就够写一个下午的适配层了。更麻烦的是密钥管理。你手里可能有好几个渠道的 Key每个 Key 对应不同的 Base URL、不同的模型名、不同的计费方式。代码里到处if provider xxx的分支改一个模型要动好几处。等到要做重试、降级、限流的时候每个厂商的错误码还不一样处理逻辑又得重写一遍。LiteLLM 就是来解决这个问题的。它本质上是一个统一接口层把 100 多个大语言模型提供商的 API 全部标准化成 OpenAI 的调用格式。你只需要记住一套completion(model..., messages...)的写法底层它会自动帮你转换成对应厂商的请求。对于刚接触多模型调用的开发者来说这意味着学习成本从「学 N 套 SDK」降到「学一套格式」。它适合谁我总结下来是三类人一是做模型对比评测的需要快速切换不同模型跑同一批 prompt二是做应用原型的不想在适配层上花太多时间三是已经在用多个渠道、想统一管理密钥和路由的。这篇内容我会带你从零跑通本地环境包括安装、配置统一 Key 与 API 通道、发起第一个跨模型请求最后用 curl 和 Python 两种方式验证模型列表能正常返回。整个流程我会给出可复制的config.yaml和.env示例你跟着敲一遍就能跑起来。中间踩过的坑我也会标出来省得你重复试错。2. 前置准备用 TaoToken 统一 Key 打通 API 通道在开始装 LiteLLM 之前得先解决「Key 从哪来」的问题。LiteLLM 本身只是个转发层它需要下游有真实的 API 通道才能工作。如果你手头有多个厂商的 Key当然可以直接配但管理起来比较散。我实测下来更省事的做法是用一个统一的 API 通道作为 LiteLLM 的下游这样 LiteLLM 里只需要配一个 Base URL 和一个 Key就能访问到多种模型。TaoToken 就是这样一个统一通道。它的 API 地址是https://taotoken.net/api兼容 OpenAI 的接口格式。也就是说你在 LiteLLM 里把它当成一个 OpenAI 兼容的 provider 来配就行。这样做的好处是LiteLLM 的配置文件里不用写一堆厂商分支模型列表也集中在一个地方管理。具体怎么拿 Key访问官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后在控制台里创建 API Key。控制台地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content进去之后找到 API Keys 页面点新建复制生成的 Key 保存好。这个 Key 就是后面.env文件里要填的值。这里有个细节要注意TaoToken 的 Base URL 是https://taotoken.net/api注意结尾没有/v1。有些 OpenAI 兼容的客户端会自动补/v1有些不会。LiteLLM 在配置api_base的时候我建议你直接写完整的https://taotoken.net/api然后在模型名前缀上用openai/让 LiteLLM 按 OpenAI 协议去请求。如果遇到 404先检查是不是路径拼接出了问题。另外如果你后面打算长期做编码类任务或者 Agent 开发可以了解一下 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。它针对代码场景做了优化配合 LiteLLM 用起来会更顺。不过这篇是入门我们先把基础通道跑通。准备好 Key 之后建议先别急着装 LiteLLM用最简单的 curl 测一下通道是否通。命令如下curl https://taotoken.net/api/models \ -H Authorization: Bearer 你的Key如果返回一个 JSON里面有data数组说明通道正常。这一步能帮你排除掉「Key 错了」「网络不通」这类基础问题免得后面 LiteLLM 报错时你分不清是配置问题还是通道问题。3. 可复制配置安装 LiteLLM 并写 config.yaml 与 .env环境准备分两步装包和写配置。先装 LiteLLM。我建议用虚拟环境避免和系统里的其他包冲突。python -m venv litellm-env source litellm-env/bin/activate # Windows 用 litellm-env\Scripts\activate pip install litellm[proxy]litellm[proxy]这个 extras 会把代理服务器需要的依赖一起装上包括 FastAPI、uvicorn 这些。如果你只写 Python 脚本调用装pip install litellm就够了。但既然我们要跑通完整路径代理模式更实用因为它能提供一个统一的 HTTP 端点curl 和 Python 都能打。装完之后验证一下版本litellm --version能打印出版本号就说明装好了。接下来写配置文件。在项目目录下新建两个文件.env和config.yaml。先写.env把 Key 和 Base URL 放进去# .env TAOTOKEN_API_KEYsk-你从控制台复制的Key TAOTOKEN_API_BASEhttps://taotoken.net/api注意.env文件不要提交到 git记得加到.gitignore里。Key 泄露了要去控制台吊销重发。然后写config.yaml。这是 LiteLLM 代理的核心配置定义了模型列表和每个模型对应的参数# config.yaml model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_base: os.environ/TAOTOKEN_API_BASE api_key: os.environ/TAOTOKEN_API_KEY - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_base: os.environ/TAOTOKEN_API_BASE api_key: os.environ/TAOTOKEN_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: openai/claude-3-5-sonnet api_base: os.environ/TAOTOKEN_API_BASE api_key: os.environ/TAOTOKEN_API_KEY general_settings: master_key: sk-litellm-local-123 litellm_settings: drop_params: true这里有几个关键点解释一下。model_name是你对外暴露的别名调用时用这个名字litellm_params.model是实际发给下游的模型标识。因为 TaoToken 兼容 OpenAI 协议所以这里统一用openai/前缀后面跟模型名。api_base和api_key用os.environ/语法引用环境变量这样 Key 不会硬编码在 yaml 里。general_settings.master_key是 LiteLLM 代理自己的访问密钥客户端调代理时要用它。本地开发随便设一个就行生产环境要换成强随机值。drop_params: true的作用是当某个模型不支持某个参数时自动丢弃而不是报错这在跨模型调用时很有用。启动代理服务器litellm --config config.yaml --port 4000看到类似Uvicorn running on http://0.0.0.0:4000的输出就说明代理起来了。这个终端保持开着后面验证请求要用。4. 验证请求curl 与 Python 双路确认模型列表返回代理起来之后第一件事是确认模型列表能正常返回。LiteLLM 提供了一个/v1/models端点和 OpenAI 的格式一致。先用 curl 测curl http://localhost:4000/v1/models \ -H Authorization: Bearer sk-litellm-local-123正常的话会返回一个 JSONdata数组里包含你在config.yaml里定义的三个模型别名gpt-4o-mini、gpt-4o、claude-3-5-sonnet。如果返回 401说明 master_key 不对如果返回空数组说明 config.yaml 没被正确加载。接着测一次真实的对话请求确认通道能打通到下游curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-litellm-local-123 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话解释什么是统一接口层}] }如果返回里有choices[0].message.content说明整条链路通了curl → LiteLLM 代理 → TaoToken 通道 → 模型 → 原路返回。再用 Python 验证一遍。装好openai包LiteLLM 代理兼容 OpenAI SDKpip install openai写一个测试脚本# test_litellm.py from openai import OpenAI client OpenAI( api_keysk-litellm-local-123, base_urlhttp://localhost:4000/v1 ) # 1. 拉取模型列表 models client.models.list() print(可用模型) for m in models.data: print(f - {m.id}) # 2. 发起跨模型请求 for model_name in [gpt-4o-mini, claude-3-5-sonnet]: try: resp client.chat.completions.create( modelmodel_name, messages[{role: user, content: 回复 OK 两个字母即可}] ) print(f\n[{model_name}] - {resp.choices[0].message.content}) except Exception as e: print(f\n[{model_name}] 调用失败: {e})运行python test_litellm.py你应该能看到模型列表打印出来然后两个模型分别返回内容。到这一步说明你已经用一套 Key、一个端点成功调用了多个大语言模型。这就是 LiteLLM 的核心价值客户端代码完全不用改只换model参数就行。如果你还想在浏览器里直接对比不同模型的输出可以用模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content手动切换模型看效果和 LiteLLM 的批量调用互补。5. 常见报错排查401、local proxy failed 与 reading choices这一节我把实际配置过程中最容易撞上的几个报错列出来对照着排查能省不少时间。报错一401 Unauthorized{error: {message: Authentication Error, type: invalid_request_error}}这个分两种情况。如果是调 LiteLLM 代理时报的检查请求头里的Authorization: Bearer后面是不是config.yaml里设的master_key。如果是 LiteLLM 转发到下游时报的检查.env里的TAOTOKEN_API_KEY是否正确以及环境变量有没有被加载。LiteLLM 读os.environ/是在启动时读的如果你改了.env但没重启代理新值不会生效。重启命令就是重新跑一遍litellm --config config.yaml --port 4000。报错二local proxy failed / Connection refusedlitellm.proxy.proxy_server - local proxy failed这个通常是端口被占用或者代理没起来。先确认 4000 端口有没有别的进程在用lsof -i :4000 # macOS/Linux netstat -ano | findstr :4000 # Windows如果被占用换个端口启动比如--port 4001同时记得把客户端里的base_url也改掉。还有一种情况是config.yaml语法错误导致启动失败用python -c import yaml; yaml.safe_load(open(config.yaml))验证一下 yaml 格式。报错三Error reading choices / KeyError: choicesKeyError: choices这个报错说明返回的 JSON 结构里没有choices字段通常是下游返回了错误信息但被当成正常响应解析了。常见原因是模型名写错了下游返回了 404 的 JSON而 LiteLLM 没正确识别。检查config.yaml里litellm_params.model后面的模型名是否真实存在。你可以先用 curl 直接打 TaoToken 的/api/models看看有哪些模型可用再对照着填。报错四OAuth / api_key client option must be setOpenAIError: The api_key client option must be set这是 Python 客户端没拿到 Key。检查OpenAI(api_key...)有没有传或者环境变量OPENAI_API_KEY有没有设。用 LiteLLM 代理时客户端传的是代理的 master_key不是下游的 Key别搞混了。报错五model not foundlitellm.exceptions.BadRequestError: model not found这个一般是model_name和调用时传的model对不上。config.yaml里定义的model_name才是对外暴露的名字调用时必须用这个名字。比如你定义的是claude-3-5-sonnet调用时写claude-3.5-sonnet就会报错注意连字符和点号的区别。排查的时候有个通用技巧把 LiteLLM 的日志级别调高启动时加--detailed_debug它会把每次请求的完整 URL、请求头、响应体都打出来定位问题非常快。6. 下一步把统一 Key 接入你的编码工作流跑通基础调用之后你可以把 LiteLLM 代理接到日常的编码工具里。因为 LiteLLM 暴露的是 OpenAI 兼容端点所以任何支持自定义 Base URL 的客户端都能接。配置三件套是固定的Base URL 填http://localhost:4000/v1Key 填config.yaml里的 master_keyModel ID 填你在model_list里定义的别名。比如在 Cline 或者类似的 VS Code 插件里找到 OpenAI Compatible 的 provider 选项把上面三个值填进去就能用统一 Key 调用多个模型了。如果你用的是 Claude Code 这类工具它本身走 Anthropic 协议可以通过 LiteLLM 的 Anthropic 兼容端点来转发或者在工具里配置自定义 API 地址指向 LiteLLM。具体接入文档可以参考https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content里面有各客户端的配置示例。如果你需要更细粒度地管理 Key比如给不同项目发不同的虚拟 Key、设置预算上限可以去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建多个 Key然后在 LiteLLM 的config.yaml里按需分配。这样即使某个 Key 泄露影响范围也可控。最后提醒一个实操细节LiteLLM 代理默认是前台运行的终端一关就停了。如果你想让它在后台常驻可以用nohup litellm --config config.yaml --port 4000 或者用 systemd、supervisor 这类进程管理工具。本地开发用前台跑就行方便看日志。等你把模型列表和跨模型请求都验证通过这套统一 Key 的通道就算搭好了后面加新模型只需要在config.yaml里加一段model_list条目重启代理即可客户端代码一行都不用动。