作为开发团队里负责工具链的人我这两年几乎每天都在跟各种大模型API打交道。OpenAI、Claude、国产开源模型一个项目里接三四个供应商是常态每个SDK的请求格式还不一样调完这个调那个维护起来相当痛苦。后来我把接入层全部收口到Litellm情况才彻底好转。这篇文章就把我实际使用Litellm的方案、踩过的坑和部署细节完整梳理一遍。1. 项目概述Litellm到底是干什么的Litellm其实是一个开源的LLM网关LLM Gateway和统一API代理层。它做的事情可以简单理解成这样你原本需要分别对接OpenAI、Anthropic、百度千帆、阿里通义等各家SDK写不同封装层切换模型时还得改代码。用Litellm之后你只需要按照OpenAI格式的请求统一发给Litellm它负责把请求转换成对应厂商的协议格式再转发给真正的模型服务。这个项目最核心的价值在于三点统一API格式对外只暴露一个OpenAI兼容的/chat/completions接口内部路由到任何模型。统一密钥管理你的应用只持有Litellm的API Key不直接接触各云厂商的SecretKey安全性和审计性都好很多。统一运营能力在代理层实现请求日志、消费统计、预算控制、负载均衡、限流——这些能力如果自己造轮子工程量非常大。如果你是以下几种情况之一就特别适合用Litellm主力开发框架是Python/Node.js但需要快速切换或同时调用多个不同大模型。公司内部开发了多个AI应用希望统一控制成本和访问权限。自建了本地模型比如通过Ollama、vLLM起服务希望让应用代码不感知底层是本地还是云端。我个人的定位是把它当做一个“大模型API的路由器”来用。它不提供模型能力本身但是把所有模型入口管理得干干净净。2. 核心思路与方案选型为什么不直接写代码适配多家API不少团队遇到多模型接入问题时第一反应是自己在代码里写一个适配层——定义一个统一消息结构然后为每家写一个转换函数。这个方案在模型数量少、调用方可控的时候确实是可行的。但一旦模型数量超过3个、调用方超过两个团队立刻会遇到几个非常现实的麻烦接口差异不只格式一层。OpenAI的temperature取值范围是0到2Google的Gemini对temperature等参数的处理逻辑不同国产某些平台对max_tokens改成了max_output_tokens。字段映射只是表象参数语义差异才是隐藏炸弹。鉴权方式不统一。有的是Header带Bearer Token有的需要额外传api_key字段有的用签名有的用临时Token。如果自己做适配业务代码会越来越脏。故障处理无法统一。某一路供应商限流、超时、欠费你是不是希望在网关层就能快速切换流量自己做这个开关和维护工作量和踩坑量都很大。Litellm选择了一个聪明的方案它本身就是基于SDK二次封装同时自己实现了完整的代理服务。这意味着两种使用模式嵌入式SDK模式from litellm import completion可以在代码里直接使用它做多模型调用不走网络代理。代理服务模式启动一个本地的proxyHTTP服务应用通过网络接口访问相当于在公司内部架设一个LLM API网关。我在实际项目里主要使用的是第二种模式。原因很简单一旦决定统一入口就应该让所有应用代码都只认识一个Base URL而不是让每个服务都依赖一个Python库版本。提示从维护角度看代理模式天然比SDK模式更解耦。应用端不需要关心底层实际调用的是哪个模型也不需要关心Litellm是否升级。只要OpenAI兼容接口不变应用代码就始终不用改动。选型方面还有一个关键考量因素是否需要自托管成本。如果是云上提供托管服务的网关因为数据会经过第三方的中间层不少有数据安全要求的公司会直接否决。Litellm支持完全自托管数据在自己内网转发这个优点在高合规场景中价值很大。3. 环境部署与基础配置我的运行环境是Docker Compose方式部署放在内网一台4核8G的Linux机器上实际跑下来非常稳定。下面直接给出一份我实测过的标准配置。3.1 Docker Compose部署假定项目目录是/opt/litellm先建好目录结构/opt/litellm ├── docker-compose.yml ├── config.yaml ├── logs/ └── data/docker-compose.yml内容如下version: 3.8 services: litellm: image: ghcr.io/berriai/litellm:main-latest container_name: litellm restart: always ports: - 4000:4000 volumes: - ./config.yaml:/app/config.yaml - ./logs:/app/logs - ./data:/app/data environment: - LITELLM_LOGINFO - DATABASE_URLpostgresql://litellm:litellmpostgres:5432/litellm depends_on: - postgres command: [--config, /app/config.yaml, --port, 4000] postgres: image: postgres:16-alpine container_name: litellm-db restart: always environment: - POSTGRES_USERlitellm - POSTGRES_PASSWORDlitellm - POSTGRES_DBlitellm volumes: - ./data/postgres:/var/lib/postgresql/data这里我特别说明一下很多人刚开始部署时不用PostgreSQL直接用SQLite就能跑起来。但从实际项目出发如果你要管理多个API Key、查看历史消费记录SQLite在高并发下会有锁竞争问题而且UI管理页面部分功能需要数据库支撑。所以起一个PostgreSQL容器其实更省心数据也不容易丢。3.2 轻量级测试安装如果你只是想在本地快速体验功能也可以不用Docker直接通过pip来跑pip install litellm litellm --config ./config.yaml --port 4000这样启动之后本机的http://localhost:4000就会提供一个OpenAI兼容的服务端点。3.3 主配置文件config.yamlLitellm的核心配置全部在config.yaml里它决定了你接入哪些模型、哪些用户可以用、怎么计费。一份典型的配置长这样model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY model_info: mode: completion cost_per_million_prompt_tokens: 0.15 cost_per_million_output_tokens: 0.6 - model_name: claude-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY model_info: mode: completion cost_per_million_prompt_tokens: 3.0 cost_per_million_output_tokens: 15.0 - model_name: orama-mixtral litellm_params: model: ollama_chat/mixtral:8x7b api_base: http://192.168.1.5:11434 model_info: mode: completion - model_name: qwen-max litellm_params: model: openai/qwen-max api_key: os.environ/DASHSCOPE_API_KEY api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 model_info: mode: completion cost_per_million_prompt_tokens: 0.8 cost_per_million_output_tokens: 2.0这个文件里面的几个关键点model_name是给应用层看的逻辑名你可以随意起名字。应用只认这个名字不认实际模型。litellm_params.model是实际映射的模型标识格式是厂商/模型名比如openai/gpt-4o、anthropic/claude-3-5-sonnetLitellm会自动识别并转换协议。api_key支持从环境变量读取避免敏感信息直接写在配置文件里。api_base可以自定义这意味着你可以把Litellm指向任何兼容OpenAI协议的服务包括本地vLLM、Ollama、某些国产云厂商的兼容端点。3.4 启动与管理配置好之后执行cd /opt/litellm docker compose up -d然后查看启动日志docker logs -f litellm正常情况下日志中会出现Proxy Server Running的信息监听端口4000。此时可以做一个快速连通性校验curl http://localhost:4000/health/liveliness返回OK就说明服务正常。4. 模型路由与统一调用实操代理跑起来之后下一个核心环节就是真正的业务调用。这一章我把从统一接口调用到高级路由策略完整展开。4.1 配置API Key体系应用要访问网关不能裸连。Litellm提供了一套Master Key体系启动时通过环境变量MASTER_KEY设定管理密钥所有HTTP请求需要在Header里带上这个Key或者使用它在UI面板创建的子Key。在配置中加上general_settings: master_key: sk-1234 database_url: postgresql://litellm:litellmpostgres:5432/litellm然后应用调用时请求头就像这样curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好介绍一下你自己}] }如果你不想在应用代码里硬编码这个Key也可以把Litellm内置的管理面板打开。访问http://localhost:4000/ui用Master Key登录后可以在界面上创建虚拟API Key。这些Key可以绑定特定模型、设定预算上限甚至设置过期时间。在多团队协作时这个功能非常有用——每个项目一个Key关掉谁的权限就是一行配置的事。4.2 在代码中统一调用我用Python比较多接Litellm最直观的方式就是直接用OpenAI SDK只要把base_url指到Litellmfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-1234 ) response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个专业的日志分析助手}, {role: user, content: 分析最近一小时日志中的错误分布} ], temperature0.3 ) print(response.choices[0].message.content)这里有一个关键点你的代码里完全不需要关心gpt-4o-mini背后到底是哪个真实模型。运维人员在config.yaml里可以把gpt-4o-mini指向任何兼容OpenAI协议的模型——比如某天你想把线上流量从OpenAI切到本地模型只需要修改配置业务代码一行不动。这种架构弹性带来的是实实在在的便利。如果不想引入OpenAI SDK也可以用Litellm自己的Python包import litellm response litellm.completion( modelgpt-4o-mini, messages[{role: user, content: 写一首诗}], )但注意这种模式必须保证调用方装了litellm库并且直连的是你本地代理。所以对于面向外部或跨语言的项目我还是推荐HTTP模式。4.3 负载均衡与多后端配置大模型供应商偶尔会限流或故障Litellm支持把一个逻辑模型映射到多个真实后端自动做负载均衡和故障转移。配置示例model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_1 model_info: mode: completion - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_2 model_info: mode: completion - model_name: gpt-4o litellm_params: model: azure/gpt-4o api_key: os.environ/AZURE_API_KEY api_base: https://xxx.openai.azure.com api_version: 2024-02-01 model_info: mode: completion三个后端都叫gpt-4oLitellm会轮流把请求分发到这三个后端。如果其中某一个返回限流错误它会自动把请求转发到下一个可用的后端。对于企业应用来说这套能力减少了“单点供应商挂掉导致全站不可用”的尴尬局面。如果希望同一个逻辑模型分流量比例可以再加router_settings: routing_strategy: weighted-round-robin配合model_group_alias或者权重配置实现灰度和灰度切流。不过这部分我目前只用到了基本轮询和故障转移更精细的权重路由还在逐步摸索中。4.4 缓存与重试Litellm内置了响应缓存可以在网关层直接命中相同请求的返回结果减少重复调用费用。配置如下general_settings: cache: true cache_params: mode: default ttl: 3600但要注意缓存的Key默认包含完整请求体意味着temperature等参数不一致也不会命中。对于业务上需要稳定响应的场景比如知识库问答、固定模板生成我建议开启缓存并设一个合理TTL能节约很大一笔Token成本。不过对话类场景的个性回复不建议开缓存容易出现答非所问。重试机制也是网关层少不了的。我踩过一个坑某国产模型偶尔出现5xx错误如果业务代码不重试整个请求就失败了。Litellm配置里加上general_settings: retry: true num_retries: 3这3次重试会按指数退避间隔执行大幅降低偶发网络抖动造成的影响。5. 密钥管理、成本追踪与审计网关还有一项特别值得说的功能把所有供应商密钥收拢在一个地方基于这个集中点再做完整的消费记录。这是很多团队选择它入坑的原因。5.1 密钥管理在config.yaml的general_settings里我们可以配置master_key作为管理密钥。用这个密钥访问UI后台可以创建多个虚拟Key。每个虚拟Key支持绑定允许访问的模型白名单每分钟请求数限制RPM预算上限美元过期时间这样在团队协作时比如某个实习生需要每天跑几百个测试请求你可以给他一个预算5美元、过期时间在本周末的Key。用完即失效不可能超支。比起把供应商的Root Key直接发到群里这个机制在安全层面强了不止一个档次。5.2 成本追踪Litellm支持在config.yaml里为每个模型定义单价cost_per_million_prompt_tokens和cost_per_million_output_tokens然后网关每次转发时就会自动计算费用并把数据记录到数据库里。UI面板中有一个专门的用量页面可以按模型、按API Key、按时间查看Token消耗和费用。这个功能对管理者很有价值——能直观看到哪个项目消耗了80%的预算然后据此调整模型配置或触发告警。我自己最常用的是API方式拉取成本数据方便对接公司内部的对账系统。比如获取某个Key在当天的消费curl http://localhost:4000/spend/keys -H Authorization: Bearer sk-1234返回格式是JSON里面有总花费、输入Token数、输出Token数、模型调用次数。如果项目需要做成本报表直接定时拉取即可。5.3 请求日志与审计所有经过网关的请求都会被记录下来包括请求发起方IP请求的API Key标识模型名输入输出Token数响应延迟请求时间由于这里记录的是元数据而不是完整对话内容对隐私保护也算一个折中方案。如果你的合规要求更高需要在转发后立即清理敏感日志那就要在部署层面额外加日志清洗步骤。这一点需要和法务或安全团队对齐需求后再做决定。6. 常见问题与排查技巧实录用Litellm这大半年我整理了几个团队经常踩的坑逐个说明一下现场表现和解法。6.1 模块格式带错导致404或400错误症状使用openai/gpt-4o这种格式却配了gpt-4o请求返回404或者模型不存在的报错或使用anthropic/claude-...时API Key填错位置导致401。原因Litellm的模型标识有严格的provider/model格式要求。如果省略了provider部分它没法知道应该走哪个SDK的协议。排查步骤# 检查配置是否加载成功列出真实识别的模型列表 curl http://localhost:4000/v1/models -H Authorization: Bearer sk-1234如果列表里没有预期的逻辑模型多半是config.yaml里YAML格式缩进不对或者模型名重复了。解决办法严格按照厂商/模型名格式。如果用的是OpenAI兼容的自建服务属于openai/模型名并在api_base里自定义端点。6.2 环境变量没有传给容器症状Docker部署后日志出现Missing api_key。原因config.yaml里写了api_key: os.environ/OPENAI_API_KEY但Docker容器启动时环境变量没有正确映射导致网关拿不到密钥。排查docker exec -it litellm env | grep OPENAI_API_KEY解决在docker-compose.yml中显式传递environment: - OPENAI_API_KEY${OPENAI_API_KEY}同时宿主机确保.env文件存在。6.3 请求超时症状接口响应慢网关返回504或Timeout。原因Litellm默认的请求超时时间可能偏短大模型本身推理耗时几十秒很常见尤其在分布式部署或本地模型时。解决在config.yaml中调大超时general_settings: request_timeout: 300同时检查上游模型服务自身是否过载。如果是本地Ollama要看GPU使用率是否达到满负荷如果是云厂商要看是否触发限流。6.4 中外供应商协议差异导致参数报错不同云厂商对参数的容忍度并不一样。输给OpenAI的参数直接转发到某些国产模型时偶尔会报未知参数错误。Litellm在转换时已经做了大量兼容处理但如果你在请求里传了自定义字段或者vendor extension字段它可能还是会原样传上去导致上游拒绝。排查方向在Litellm日志中查看发到上游的真实请求体确认参数是否有异常。如果问题来自业务侧传入了非标准字段就在网关前拦截掉或者在应用代码中过滤自定义参数。6.5 数据隐私担忧常见疑问用了Litellm代理对话内容是不是会留存在代理层实际Litellm默认只记录元数据和Token数量具体对话内容默认不落在服务器的持久化存储中。如果你自己开启了完整请求日志比如turn_message_logging: true则内容会写库。决定前必须明确自己的隐私级别需求必要时禁用内容日志。重要提醒代理部署在一个团队能控制的内网是所有隐私考量的基础。不建议使用第三方公共代理来管理公司内部密钥。6.6 常见问题速查表问题现象可能原因解决方案404模型不存在模型格式没有带provider前缀改为openai/xxx、anthropic/xxx格式401认证失败api_key不是Master Key或未正确映射环境变量核对环境变量检查Authorization头499/504超时默认超时过短request_timeout: 300某路供应商持续报错供应商密钥出错或账户欠费临时将该model_name映射到备用后端Token数统计为0模型单价配置缺失在model_info中配置cost参数高并发下排队SQLite锁竞争迁移到PostgreSQL数据库与自定义API无法连通api_base地址错误或协议不完全兼容使用curl先直连上游验证连通7. 经验与扩展基于Litellm搭建企业级AIGC平台当一个团队习惯了使用Litellm之后它就会逐步从“工具”进化为“平台底座”。我目前正在做的一个模拟项目X就是基于这套网关扩展。7.1 把它们挂在统一网关下的三种场景线上业务实时推理比如客服助手要求高吞吐、低延迟需要把多副本后端的负载均衡和故障转移能力用起来。离线数据处理脚本比如定时批量分析工单日志用队列调用Litellm配合预算Key控制成本上限。内部测试环境给每个开发者分配独立的虚拟Key限制模型白名单和日预算。发出去的账号权限清晰、可回收。7.2 与LangChain等框架集成很多团队已经使用LangChain、LlamaIndex这类开发框架来构建复杂应用。接入Litellm的方式非常简单只要把ChatOpenAI的base_url指向Litellm的出口地址就行。from langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen-max, base_urlhttp://localhost:4000/v1, api_keysk-1234 )由于协议完全兼容OpenAI所以LangChain生态里的Agent、Memory、Retriever都不需要改动。这一点让历史项目接入成本变得极低。实际上我甚至觉得Litellm这个OpenAI兼容层是对接生态的最佳方式——不管底层模型换了几轮上层的AIPC、Agent应用都无感知。7.3 监控指标接入PrometheusLitellm原生暴露运维指标。按照官方文档配置好prometheus端点之后可以给每个模型添加迟延、Token消耗等指标面板。例如给GPT系、Claude系、qwen系模型分别建仪表盘出现异常能第一时间看到曲线异常爬升。再加上Webhook告警模型侧的故障和预算抖动都能快速发现。我在生产中还加了一个Alerta风格的告警通道当单日成本超过设定阈值时自动给管理员发通知。这样整个网关不仅是一个透明的转发层还变成了一个实际的成本控制层。8. 写在最后我对Litellm的真实体会如果让我用一个词概括Litellm我会说是“LLM基础设施”。它并不花哨但解决了实际开发中大量令人烦躁的琐碎问题。以前一个新模型接入需要写适配、发版、改配置现在只需要在config.yaml里增加一条记录然后热加载。以前想统计项目A今天花了多少钱需要去各地厂商控制台翻账单现在直接一条API拉全量。我认为最值得投入时间去啃的部分其实是config里的model_info成本参数和router_settings路由策略。因为这两块决定了网关生产可用的成熟度——能不能做预算核算、能不能做故障漂移。最后建议你自己动手搭一遍。不需要很高的机器配置先用Docker在本机把Litellm跑起来接一个免费模型本地Ollama也行再用OpenAI SDK发一条消息过去。感受一下统一入口带来的开发体验变化你会理解为什么只要经历过一次多模型混杂项目就会立刻爱上这个“路由器”。