最近在做大模型应用落地手里同时握着好几家主流模型的 API Key结果发现最痛苦的其实不是效果调优而是工程侧怎么把这么多接口统一管理起来。各家调用的报文格式不一样、鉴权方式不一样、返回结构也不一样模型一多代码里全是 if-else 和适配层。后来我把 LiteLLM 用进了项目里这个轻量级 Python 库把“接入不同大模型 API”这件事收敛成了一个标准入口实际跑下来确实省掉大量重复劳动。这篇就把我的使用过程、踩过的坑、值得关注的核心功能都梳理一遍如果你也在纠结多模型接入和统一网关这里应该有你需要的答案。1. 先搞清楚LiteLLM 解决的到底是哪一类问题1.1 多模型接入的混乱比想象中更严重你可能觉得接大模型 API 嘛无非就是发个 POST 请求。真上手才知道每一家都有自己的脾气。有的用Authorization: Bearer有的要把 key 写在自定义请求头里有的返回choices[0].message.content有的返回response下面的嵌套字段有的支持max_tokens有的偏要叫max_new_tokens。这些差异单独看都是小事但模型一多适配工作就变成了“给每家写一套 client 封装再统一转成自己的内部结构”。更麻烦的是切换成本。你今天用模型 A 做摘要明天发现模型 B 效果更好改的不只是模型名还有鉴权、超时、重试、流式输出方式。这些重复劳动很容易把团队拖进维护泥潭结果就是大家明明在做业务却在不停折腾 API 对接。1.2 LiteLLM 的核心定位一道标准化适配层LiteLLM 做的事情一句话概括就是把各家大模型 API 统一成一套 OpenAI 风格的调用格式。你只需要学会litellm.completion()一个函数把model参数换成不同模型标识其他细节全部交给它去转换。它本身不生产模型能力也不代理算力就是一个非常薄的适配层。你可以把它理解成“USB-C 转接头”——不同设备的充电口五花八门但转接之后都走同一个标准口。LiteLLM 就扮演这个转接头对接的是各家 LLM API对外输出的是统一格式的调用入口。它适合谁我觉得主要是这几类人做了多个大模型横向对比、想快速切换模型做效果验证的开发者。团队里有内部 AI 工具平台需要把多个模型封装成同一个接口给业务方调用的后端同学。想在代理网关层做请求转发、负载均衡、成本统计的工程负责人。想在自己本地接开源模型比如通过 Ollama 起的服务又不想改业务代码的人。1.3 为什么推荐它而不是自己封装一层自己封装当然可以做我在早期项目里就干过。但封装到后面会发现你其实是在重复造轮子重试策略、超时控制、流式解析、异常归一化、成本统计、模型白名单这些每个模型服务商都有细微差别你都得自己处理。LiteLLM 把这些东西沉淀成了公共逻辑社区也在持续补充新模型、新参数跟着走比自研划算得多。还有个很重要的点LiteLLM 支持代理网关模式Proxy。也就是说它不只是程序里的一个库还可以独立跑成一个服务对外暴露一个 OpenAI 兼容的/chat/completions接口。这样业务方甚至不需要知道后端是 GPT 还是 Claude只需要按照标准接口发请求后端怎么路由就是平台侧的事了。2. 核心能力拆解它凭什么能当“统一入口”2.1 统一的补全接口与消息格式LiteLLM 最直观的能力是completion接口。不管背后是哪家模型你都用同一套 messages 结构传对话上下文import litellm response litellm.completion( modelgpt-4o, messages[ {role: system, content: 你是一个帮助用户总结内容的助手}, {role: user, content: 请用三句话总结这篇文章} ] )想换成 Claude 系列模型只需要改 model 字符串response litellm.completion( modelclaude-3-5-sonnet-20241022, messages[{role: user, content: 你好}] )这里面的转化包括了请求参数的迁移比如max_tokens在部分平台叫max_new_tokens也包括返回结构的标准化最后统一成 OpenAI 风格的response.choices[0].message.content。对于已经按 OpenAI 格式写好上层逻辑的项目切换底层模型几乎是零成本。2.2 鉴权信息管理各家 API Key 的管理也比较省心。你可以在环境变量里配置LiteLLM 会自动读取export OPENAI_API_KEYsk-xxx export ANTHROPIC_API_KEYsk-ant-xxx也可以在代码里显示传入api_key参数。它还支持从本地配置文件读取 key后续我会在代理模式里再展开。2.3 模型路由、重试与负载均衡单模型调用只是基础LiteLLM 真正有价值的是模型路由能力。你可以定义一组候选模型系统会根据策略自动选择。比如一个简单轮询策略将请求分散到配置好的多个模型实例上避免单点过热或者配置 fallback 模型A 模型失败自动切到 B 模型。在代理模式下路由规则写在配置文件里一个最小示例model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY这里model_name是对外暴露的名字业务方只认这个名字litellm_params.model是真正发给上游的模型标识。你对外叫“快捷模型”对内映射到若干具体模型哪天想换实现改配置就行业务方无感知。2.4 成本与 Token 用量统计多模型混用之后最容易被忽视的问题是钱花到哪了LiteLLM 内置了成本追踪能力会根据各家模型官方单价估算每次调用的费用并记录 token 消耗。代理模式下它还提供/spend相关接口可以按 API Key、模型、用户维度查看消费明细。这功能在自建平台上尤其有用。我见不少团队把多个模型开放给内部使用月底一看账单吓一跳就是因为缺了这块统计。LiteLLM 至少能让你把账算明白。3. 实操上手从安装到跑通多模型切换3.1 安装与基础环境准备LiteLLM 的安装很简单直接用 pippip install litellm[proxy]如果你只打算在代码里调用不需要跑代理服务装基础版本就行pip install litellm建议在虚拟环境里操作避免污染全局 Python 环境。Python 版本 3.8 以上基本都兼容我实测在 3.10 和 3.11 下没有遇到问题。装完之后先验证一下版本pip show litellm提示如果后续要跑代理功能[proxy]这个 extra 依赖很关键它会额外安装 FastAPI、uvicorn 等组件。只装litellm的话启动litellm --config会报缺少模块。3.2 代码方式完成第一次多模型调用先准备两个环境变量用来存放不同平台的 API Keyexport OPENAI_API_KEY你的OpenAI风格密钥 export ANTHROPIC_API_KEY你的Anthropic风格密钥写一个最简单的脚本请求不同模型并打印结果import os import litellm messages [{role: user, content: 用一句话介绍你自己}] for model in [gpt-4o, claude-3-5-sonnet-20241022]: try: resp litellm.completion( modelmodel, messagesmessages, api_keyos.environ.get( OPENAI_API_KEY if model.startswith(gpt) else ANTHROPIC_API_KEY ) ) print(f模型 {model} 返回{resp.choices[0].message.content}) except Exception as e: print(f模型 {model} 调用失败{e})这里有几个细节值得注意。第一model参数是 LiteLLM 全局唯一的模型标识不是随便填的。它由“提供商名/模型ID”组成比如openai/gpt-4o。但实际使用时有的代码里不写openai/前缀也能识别因为 LiteLLM 会自动推断不过为了严谨建议显式写全避免在切换模型时因为前缀问题报 404。第二api_key显式传入时不同的模型对应不同的 Key。如果只有一个默认 Key可以用litellm.api_key统一设置但这只适合单个提供商场景。多提供商场景还是建议通过环境变量或者后面讲的代理配置来管理。第三返回对象是 OpenAI 风格的结构但如果拿不到内容检查一下resp.choices[0].message.content是否为 None。有的平台在 content 为空时会返回refusal字段这在部分推理模型上会出现。3.3 把 Mini 代理跑起来代码调用熟悉之后我强烈建议你试试代理模式因为这才是 LiteLLM 在工程化落地中的高价值形态。它让你拥有一个本地 OpenAI 兼容服务所有业务系统按标准格式调用底层随便换模型。创建一个配置文件config.yamlmodel_list: - model_name: assistant-lite litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: assistant-pro litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY litellm_settings: drop_params: true set_verbose: true然后在终端启动litellm --config config.yaml --port 8000看到类似Uvicorn running on http://0.0.0.0:8000的输出就说明代理服务起来了。用 curl 测试curl http://localhost:8000/chat/completions \ -H Content-Type: application/json \ -d { model: assistant-lite, messages: [{role: user, content: 你好}] }注意这里model填的是你在配置里定义的model_name也就是对外暴露的模型名。用户不需要知道后端到底是 GPT 还是 ClaudeLiteLLM 负责把请求转发到真实模型上去。注意代理模式默认不校验 API Key。如果你把它暴露到内网之外一定要设置LITELLM_MASTER_KEY环境变量否则任何知道地址的人都能白嫖你的模型额度。3.4 环境变量在配置文件中的写法配置文件中api_key: os.environ/OPENAI_API_KEY是 LiteLLM 的约定写法含义是从环境变量读取值。启动代理前必须保证环境变量已设置好否则会遇到 key 为空的报错。另一种方式是直接在配置文件里写明文 Keyapi_key: sk-xxxx我不推荐在配置文件里写明文尤其是配置文件会被提交到代码仓库时。一旦泄露损失是全部模型额度。使用环境变量或者密钥管理服务更安全。4. 进阶玩法本地模型接入与容错配置4.1 接入 Ollama 本地模型很多项目既要体验云端大模型又想用本地开源模型做隐私数据推理。LiteLLM 对本地模型的支持也做得不错最常见的是接 Ollama。如果你本地已经启动了 Ollama 服务并且拉好了模型比如ollama pull llama3.1那么用 LiteLLM 调用它的方式为resp litellm.completion( modelollama/llama3.1, messages[{role: user, content: 你好}], api_basehttp://localhost:11434 )这里有个关键点ollama/llama3.1中ollama/是必须的LiteLLM 靠这个前缀识别走 Ollama 协议。api_base如果不写默认也是http://localhost:11434但显式写出来更稳妥尤其是在容器化部署时指向宿主机 IP。接入本地模型后你可以把本地模型也加进代理配置和云模型混在一个服务里。比如配置一个“始终免费”的内部模型走 Ollama配置一个“高精度”的外部模型走云端 API。业务方按需选择无需关心部署位置。4.2 通过配置实现失败重试和超时控制模型服务不可能永远稳定超时、限流、5xx 都是常客。LiteLLM 提供了重试和超时配置。在代码中设置import litellm litellm.num_retries 3 litellm.request_timeout 30在代理配置文件中可以针对全局或者单个模型设置litellm_settings: request_timeout: 30 num_retries: 2 retry_policy: AuthenticationError: retries: 0 RateLimitError: retries: 3我个人比较建议在retry_policy里做精细化配置。比如鉴权失败重试没意义多半是 Key 配置错了重试 10 次还是失败而限流或者 5xx 则值得重试几次因为过几秒可能就好了。LiteLLM 允许你按异常类型单独设置重试次数这个设计很实用。4.3 设置模型别名与权重路由代理配置里的model_name其实天然就是“模型别名”。你可以做一层业务语义映射。比如model_list: - model_name: code-review litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: code-review-fast litellm_params: model: anthropic/claude-3-5-haiku-20241022 api_key: os.environ/ANTHROPIC_API_KEY业务侧在代码评审场景调用code-review在轻量摘要场景调用code-review-fast。后续如果发现某模型效果下降直接改配置映射无需业务代码变更。如果想做两个模型之间的负载均衡还可以用routing_strategyrouter_settings: routing_strategy: simple-shuffle num_retries: 2simple-shuffle是随机打散请求属于最简单的负载均衡。更复杂的策略还包括基于优先级、基于最低延迟等按需选择即可。5. 常见问题与排查实录5.1 API Key 相关报错十有八九是没配对最常见的报错是AuthenticationError。这个错误真正原因大多数不是网络问题而是 Key 配错了提供商。你拿 OpenAI 的 Key 去调 Claude 接口当然会被拒。排查思路很简单确认配置文件里litellm_params.api_key对应的环境变量是否正确指向该模型的平台 Key。确认环境变量是否在当前终端会话生效用echo $OPENAI_API_KEY看一眼。确认 Key 有没有多余的空格或换行读取环境变量时容易被忽略。我在本地调试时遇到过一种情况代理服务是通过后台守护方式启动的没继承当前 shell 的环境变量结果 Key 为空导致所有请求 401。这类问题跟 LiteLLM 本身无关但容易误导排查方向。5.2 “Model Not Found” 其实是模型标识写错了litellm.exceptions.NotFoundError或者上游返回 404大概率是 model 参数不完整。比如把claude-3-5-sonnet写成了claude-3-5或者漏了anthropic/前缀。LiteLLM 并不是所有平台都能自动补全前缀建议严格按文档填写完整标识。如果使用的是代理接口还需要确认model_name在配置里是否存在。有一个很隐蔽的错误定义了model_name: assistant-lite实际调用时却传了assistant_lite中间的下划线不同LiteLLM 不会做名称归一直接 404。排查时可以打开调试日志export LITELLM_LOGDEBUG这样能在日志里看到完整的请求转发地址和模型标识问题一眼就能看出来。5.3 代理模式下drop_params的作用与误用好多模型对参数的容忍度不一样。你在 OpenAI 上传了response_format但换到某个开源模型时对方不接受这个参数调用就报错。配置里的drop_params: true会在请求转发前自动丢弃上游不支持的参数。听起来很方便但要注意副作用它可能会静默丢弃你本意想传的参数导致模型行为不符合预期。我的建议是先不开drop_params把参数写对只有确认某模型确实因参数不兼容而报错时再针对该模型单独处理。全局开启是一把双刃剑。5.4 代理服务内存和并发问题LiteLLM 代理底层是 FastAPI默认可以应对一定并发但如果你开的是多模型大并发转发建议在前面再套一层负载均衡或者设置合理的超时时间。碰到代理进程卡死先看是不是上游模型响应太慢把request_timeout调小一点避免请求堆积。另外代理模式默认会对请求做日志记录。日志量大会占用磁盘空间我记得有次本地跑了一整天日志文件涨到了几百 MB排查问题时才发现。建议在配置里关掉无关紧要的日志或者配置日志轮转。5.5 本地模型接入时的端口与协议问题接 Ollama 时如果长时间没有返回先确认本地端口是否真的可访问curl http://localhost:11434/api/tags如果这个请求都不通说明 Ollama 服务根本没起或者地址写错。其次确认api_base是否以/结尾导致拼接问题。LiteLLM 在拼接 URL 时对斜杠比较敏感多一个少一个都可能 404。6. 一些从实操里沉淀下来的心得6.1 小团队做内部平台可以直接把 LiteLLM 当网关用如果你所在团队有内部 AI 工具与其让每条业务线各自写模型调用代码不如统一部署一个 LiteLLM 代理。业务方只拿到一个标准端点用自己的内部账号访问平台侧在代理层做模型路由、限速和成本统计。我参与过的模拟项目里这种方式让后端同事从繁琐的模型适配里解放了出来新模型接入从几天缩短到改一行配置。6.2 用“配置优先级”思路管理多环境本地调试、测试环境、生产环境用的模型组合往往不一样。我建议把 config 文件拆成多份通过环境变量或者启动参数切换。比如本地用 Ollama 模型测试用便宜云模型生产用高精度模型配置内容不同但对外暴露的model_name保持一致。这样从开发到上线的代码路径完全一致只是配置变了。6.3 成本统计不是事后诸葛亮要提前接好很多团队上多模型之后才发现成本失控我自己的体会是成本统计应该从第一天就接入。不需要很复杂至少做到“每天能按模型维度看到 token 消耗和费用”。LiteLLM 自带这套能力代理模式启动后甚至可以直接查/spend。把这些数据接到现有的监控告警体系里超过阈值就提醒比月底看账单再后悔要好得多。6.4 不要小看模型标识规范团队协作里最容易出问题的就是模型标识不统一。有人写gpt-4o有人写openai/gpt-4o还有人写gpt-4o-mini看似差不多实际走的模型完全不同。我的做法是内部统一只用代理层暴露的model_name底层模型标识只在配置中心管理。业务代码里禁止出现具体模型 ID这样也方便后续迁移。最后再分享一个小技巧当你用代理模式接入了各种模型之后可以给同一个model_name配置多组参数比如 temperature 不同、max_tokens 不同相当于提供“快速版”“详细版”“严格版”等多个预设。调用方不需要理解参数含义只需要按业务需求选一个预设名。这个设计在业务接入时非常受欢迎是我在实践里最常用的一招。