做AI应用开发的人早晚会遇到一个很现实的问题——同时对接多家大模型API。今天想聊的litellm就是专门解决这个问题的开源网关工具。litellm本质上是一个大模型API网关/代理层它把不同厂商的API协议统一成OpenAI格式让底层模型随便换但上层业务代码一行都不用动。你只需要把它部署在服务端前端程序统一请求litellm它再帮你转发到各家大模型服务商那里。这就好比一个语言翻译中心你的团队说普通话后面各家服务商有人说英语、有人说日语、有人说法语翻译中心负责把普通话翻译成对方能听懂的语言再把他们的话翻回普通话给你听。我最初接触这个工具是在一个实际项目里当时开发的应用需要同时调用三个不同服务商的模型来做效果对比还要在不同的模型之间做自动切换。一开始的想法很粗暴直接在每个模型服务商的SDK上都写一套代码封装一层Feign接口结果发现光是统一请求格式、统一错误码、统一超时重试这些事就够写几千行样板代码了。后来在某技术社区看到有人在分享litellm研究了一下源码和设计思路果断把方案换掉了。这篇文章我把这段时间的实际使用经验整理出来包括litellm的核心功能拆解、部署实战、配置方法以及在实际项目中踩过的坑。适合谁看后端开发、AI应用工程师、想给团队搭一套统一模型接入层的技术负责人还有那些刚接触AI应用开发、正在纠结怎么接多家API的同学。1. 项目整体设计与思路拆解litellm的设计理念用一个词概括就是标准化适配层。它不参与模型推理自己只做转发和治理所有路由、鉴权、限流、预算控制、日志记录这些横切关注点全被它抽到了网关层。1.1 为什么需要一个API网关层先想清楚一个基础问题服务商很多接口协议却不统一。OpenAI的接口格式是一套JSON SchemaAnthropic那边是另一套Google Gemini又是不同的调法这样十几家厂商就有十几套协议还不算国内各家兼容OpenAI但细节上又有差异的实现。如果你的业务代码里直接调用各家SDK会产生什么后果每次新增一个模型服务商你得写一套新的调用代码适配它的鉴权方式、参数格式、返回结构、错误定义、限流策略。模型切换不是改个配置就完事是要动代码的。更麻烦的是上游接口一旦升级或变动你要跟着改底层模型出问题要排查你得去翻每一家服务商的日志。有了litellm专门做适配这个复杂度就从业务代码中被隔离出来了。业务侧统一用OpenAI的SDK或HTTP接口model字段填你自定义的模型别名就行真正的路由和适配由litellm完成。这样做的收益非常直观切换模型从修改和发布代码降级为改一行配置或调一次管理接口。1.2 litellm相比自研网关的核心优势有些团队会想既然要做适配层我自己写一个不行吗说实话能写但性价比不高。私有的API适配脚本能解决的问题有限。第一不能直接支持OpenAI格式的SDK接入因为业务侧通常希望无缝切换第二异常处理逻辑各厂商返回的错误格式五花八门有的是HTTP状态码区分限流有的是自定义错误码有的是错误信息里带着具体原因自己处理很容易遗漏第三成本统计和预算管控做起来很费劲尤其是多用户场景。litellm把这些问题都预置好了。它支持100多家模型服务商不需要你逐个手写适配逻辑而且内置了虚拟Key管理、预算控制、限流、重试、缓存、落库日志等全套能力开箱即用。我之前自己梳理过一个对比情况这里分享给各位参考对比维度自研调用层litellm统一网关新服务商接入时长2-3天适配协议与测试1小时内改配置文件统一错误处理需自己踩坑积累内置标准错误体系多用户配额管理需自主开发虚拟Key预算规则日志与可观测性需对接日志系统内置表结构自动落库日常维护成本高需维护适配代码低关注版本升级即可1.3 网关层在整体架构中的位置一个典型的litellm部署方案上游接各类LLM服务商下游接你的业务服务。可以在业务和模型之间加了一层代理所有实际模型调用都经过这里。这个位置决定了它可以做很多事。除了转发还有一个隐藏的价值问题定位。它记录了每一个请求走的是哪个模型别名、实际调的是哪家服务商、链路耗时多少、费用消耗多少。出问题的时候可以先查litellm的日志快速判断是模型服务商出问题还是业务代码的问题不用再傻傻地抓瞎排查。2. 核心功能拆解统一接口、模型路由与Key管理litellm的核心价值我总结成三个大块统一API入口、模型路由与故障转移、虚拟Key管理与预算控制。理解了这三块其余功能基本就是围绕它们展开的组合。2.1 OpenAI格式的统一入口兼容性极强litellm对外暴露的就是一个OpenAI兼容的接口。这意味着你现有代码里用了OpenAI的SDK不需要做任何迁移只需要把base_url指向litellm的服务地址即可。比如你原来用Python的openai库from openai import OpenAI client OpenAI( api_keysk-1234, base_urlhttp://localhost:4000/v1 ) response client.chat.completions.create( modelmy-test-models, # 别名 messages[{role: user, content: 你好}] ) print(response.choices[0].message.content)业务侧可以继续沿用这套写法需要切换模型时只改model字段。甚至你在多个语言或框架里都能这样用Java的HTTP客户端、JavaScript的openai-node、curl命令都支持这种方式。它对OpenAI官方接口的覆盖程度目前已经比较全了包括Chat Completions、Completions、Embeddings、Images、Audio、Moderation等端点大都支持。如果你的项目只依赖这些常见能力完全可以平滑过渡。2.2 路由与模型映射别名机制让切换模型成本趋近于零模型映射是litellm最亮眼的设计。你在配置里可以定义一个自己的模型名比如写一个叫gpt-mini的别名然后把它对应到真实的某个商用模型或者自部署的开源模型。配置大概长这样model_list: - model_name: gpt-mini litellm_params: model: gpt-3.5-turbo api_key: os.environ/OPENAI_API_KEY - model_name: claude-mini litellm_params: model: claude-3-haiku-20240307 api_key: os.environ/ANTHROPIC_API_KEY业务侧并不需要知道gpt-mini到底调的是哪家服务商、多大参数量的模型它只知道这个名字对应一个可用模型。某天你觉得gpt-3.5-turbo效果不理想想换成gpt-4o-mini改配置文件重启一下服务就行业务代码完全不用动。还可以配置路由策略让同一个别名请求由多个模型轮询转发做负载均衡。比如你有多个相同能力的服务商账号想把调用压力分散开可以这样配model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_1 - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY_2litellm会自动做轮询把请求分配给不同Key对应的服务商。2.3 虚拟Key管理与团队配额控制在正式团队协作的场景里这可能是最实用的功能之一。你不用把服务商的上游Key直接暴露给每个团队成员而是在litellm里生成虚拟Key给A同学配一个、给B项目配一个各自具备独立的预算和速率限制。这意味着即使某个虚拟Key泄露了它影响的只是这个Key的预算范围不会威胁到上游服务商主Key的安全。这个安全性上的价值在企业内部使用时尤为关键。生成虚拟Key时你可以赋予具体的预算上限也可以配每秒调用次数限制。比如给A项目分配每天500万token的预算给B项目分配200万token的预算超出设置的值就会自动拒绝请求并报错提示额度不足。2.4 缓存、重试与成本追踪litellm内置了响应缓存机制支持在Redis里做缓存。同样的prompt短时间内重复请求可以直接返回缓存的响应不用再真实调用模型一次。这对问答类应用、客服工作流这类固定问题较多的场景非常有用。缓存命中与否直接从模型调用费用上就能直观感受到差异。重试机制做得也挺好。上游模型服务商偶尔会返回限流错误或5xx内部错误litellm支持配置自动重试判断哪些状态码值得重试、最多重试几次、每次间隔多少秒这些都可以定制。成本追踪是它的另一个亮点。每个请求用了哪个模型、消耗了多少token、换算成多少钱它会记录到SQLite或PostgreSQL里也提供了查询接口和仪表盘界面。我经常用它来核对每月的账单看看消耗最大的模型和调用最多的用户分别是谁这个信息对调优模型使用策略很有帮助。3. 实操从部署到跑通第一个请求理论说完进入动手环节。这一节我从零开始演示一遍搭建过程Docker部署litellm、写初始配置文件、用curl验证连通性最后接入业务代码。3.1 环境准备与Docker部署litellm有Python的pip包也有Docker镜像我的建议是正式环境优先用Docker。原因有几点免去本地Python环境的依赖冲突版本管理更省心方便远程部署。准备好docker-compose文件version: 3.9 services: litellm: image: ghcr.io/berriai/litellm:main-latest container_name: litellm ports: - 4000:4000 volumes: - ./litellm_config.yaml:/app/config.yaml - ./data:/app/data environment: - LITELLM_MASTER_KEYsk-master-123456 - STORE_MODEL_IN_DBFalse command: [--config, /app/config.yaml, --port, 4000]启动前要特别留意两个配置。一个是LITELLM_MASTER_KEY这是litellm的主管理员Key后续生成虚拟Key时要用它做鉴权务必设置成强随机字符串不要用默认值。另一个是STORE_MODEL_IN_DB这个环境变量如果不设置为Falselitellm会把模型配置存进数据库这时修改config.yaml文件不会自动生效很多人在这一步踩过坑部署半天配了模型就是不加载最后查文档才发现是数据库配置优先。第一次部署我建议把数据目录挂载出来这样就算容器重建日志数据和SQLite数据库还在不会丢历史记录。3.2 编辑基础配置文件配置文件是litellm的命脉所有路由规则、模型映射、参数开关都在这里定义。先做一个最小可用的配置model_list: - model_name: gpt-test litellm_params: model: openai/gpt-3.5-turbo api_key: os.environ/OPENAI_API_KEY - model_name: claude-test litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY litellm_settings: set_verbose: False drop_params: true general_settings: database_url: sqlite:////app/data/litellm.db需要解释几个关键字段model_name你在业务代码里要用的名字可以自己随便起但建议起得有意义方便后续维护。litellm_params.model真实的模型标识要带上服务商前缀比如openai/、anthropic/、gemini/。前缀的作用是让litellm知道去加载哪个适配器。api_key可以写环境变量也可以直接写明文但除非是本地测试否则建议统一用环境变量别把Key直接写进配置文件。fallbacks这个字段后面细说是配置故障转移用的。启动容器后访问 http://localhost:4000 能看到一个管理界面可以用主Key登进去查看和配置模型。3.3 用curl验证首次调用验证是否跑通直接用curl最直观。我习惯先用一个最简单的对话请求来测试curl -X POST http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-master-123456 \ -d { model: gpt-test, messages: [{role: user, content: 你好请简单介绍一下你自己}] }正常情况下你能看到litellm返回一个标准的OpenAI格式响应。如果出现401就是Master Key不对出现404大概率是路由路径错了确认一下请求的是/v1/chat/completions不是/chat/completions出现400重点看messages字段格式是不是标准结构。3.4 实际项目中的接入方式项目里接入litellm几乎就是改base_url这一个操作。以Python端为例from openai import OpenAI client OpenAI( api_keysk-master-virtual-key-xxx, base_urlhttp://your-litellm-host:4000/v1, ) messages [ {role: system, content: 你是一个专业的客服助手}, {role: user, content: 我的订单已经3天没发货了怎么办} ] resp client.chat.completions.create( modelgpt-test, messagesmessages, temperature0.7 ) print(resp.choices[0].message.content)有一点要注意业务侧的api_key建议使用litellm生成的虚拟Key而不是直接使用主Key。虽然都能调通但虚拟Key在预算和权限控制上更加精细更重要的是安全隔离不会因为一个业务线的Key泄露导致整个平台被滥用。生成虚拟Key可以通过管理界面也可以调用管理接口需要先注册这个Key。3.5 进阶配置多模型fallback与重试真实生产环境里单模型裸奔心里一点底都没有。模型服务商偶尔会抖动限流、超时、5xx错误都可能发生。litellm的fallback功能就是为了应对这种情况。配置方式也简单在单个模型下加一个fallbacks字段model_list: - model_name: production-model litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY fallbacks: [{model: claude-3-5-sonnet, api_key: os.environ/ANTHROPIC_API_KEY}]这样当主模型openai/gpt-4o调用失败时litellm会自动转向备用的Claude模型继续处理对业务侧完全是透明的。请求还是同一个请求客户端不会感知到尾部的切换。重试参数的调整也很关键太多会拖慢响应太少又起不到容错效果。我个人的实践经验是对429状态码限流和5xx状态码配置最多2次重试间隔时间用指数退避策略把首次重试延迟设为1秒左右比较合理。重试太多会导致整体响应时间被拖到几十秒用户那边早就等得不耐烦了。4. 常见问题与排查技巧实录工具用得越深踩的坑也越多。这里整理一下我在实际使用时遇到过的问题和解决办法希望对你有参考价值。4.1 模型调用超时与连接异常有段时间排在litellm后面的某个模型服务商经常性地响应很慢导致litellm默认的600秒超时都撑不住前端表现为所有请求排队整体系统感觉被拖垮了。排查思路是这样的先看litellm的日志里有没有timeout或upstream_error的报错再看看是哪个模型别名对应的上游慢。确认是某个服务商持续高延迟后解决方案是用fallbacks把它指向更快的备用模型同时给litellm配置更合理的超时时间避免长时间占用连接池。在litellm中超时有两种一种是连接超时connect_timeout一种是读超时read_timeout。合理的做法是把连接超时设短一些比如10秒快速判断上游不可达读超时设得稍长比如60秒给模型生成留出时间。具体值根据你的应用场景来调如果客户预期响应时间在10秒以内那内部模型的读超时就该往20秒以内压不能放任默认值拖后腿。4.2 模型映射配置不停报错配置模型映射是高频出错点。最常见的情况是model参数忘了加服务商前缀或者加错了前缀。litellm的model字段格式一般要求是前缀加模型名比如openai/gpt-4o、anthropic/claude-3-5-sonnet。如果你只写了gpt-4olitellm会默认按OpenAI格式处理这个还好。但如果你的模型名字本身比较复杂或者服务商的标识比较特殊最好严格按文档来前缀写错会导致litellm完全不知道用哪个适配器来转发请求。还有一个隐蔽的坑有些模型服务商的自定义端点部署模型需要设置api_base参数。配置方法是在litellm_params里加上api_base字段指向你的自定义网关地址不是只有api_key那么简单。如果只填了model默认走的是官方地址自然会调不通。4.3 缓存命中率低甚至缓存根本没生效缓存是litellm省钱的重要工具但默认配置下命中率可能并不理想。原因是litellm默认会按完整请求体生成缓存Key只要prompt里有一个字符的细微差别或者temperature设置了不同的值缓存就直接跳过。优化方法是开启语义缓存。litellm支持缓存相似请求它是根据embedding的相似度来判断两个prompt是不是等价从而复用响应。这个在客服问答场景里效果很好用户提问的表述有点差异但语义相同就能命中缓存。不过语义缓存需要配置embedding模型和相似度阈值加了一定的实现复杂度可以根据场景权衡再决定是否启用。4.4 日志查询与持久化细节litellm默认把日志写入SQLite数据库这个设计简单方便但数据量一大就会出现瓶颈。一个日调用量达到上万次的场景SQLite的并发写能力就会不足日志写入延迟会影响整体性能。我建议在正式环境改用PostgreSQL来存储日志。配置很容易general_settings: database_url: postgresql://user:passwordhost:5432/litellm_db换成PostgreSQL后日志查询的性能会明显提升。另一个建议是部署时加一个定时清理任务定期清理过老的日志数据避免数据库无限膨胀。日志数据再有用也不能让数据库变成时间黑洞。4.5 版本升级的注意事项litellm的迭代速度很快功能更新频繁但版本升级有时会带来配置兼容性问题。我遇到过的情况是某次升级后原来配置里的某个参数名称变了旧配置被直接忽略导致模型路由策略失效。我的建议是生产环境升级前先在一个独立的测试环境部署新版本用现有的配置文件跑一轮完整的冒烟测试包括模型调用、fallback切换、虚拟Key鉴权这几个核心链路。确认没问题后再升级。同时关注官方CHANGELOG特别是配置格式变更和废弃字段的说明。5. 个人使用心得与扩展方向litellm用了这段时间整体感受是它把模型接入这个本应琐碎麻烦的事情变成了改配置文件为主的轻量操作。团队里现在要接一个新模型不需要谁专门花几天去写适配代码改改yaml配好Key和路由马上就能用起来。模型挂了也不用人肉切换fallback机制自动接管省了半夜被叫起来处理线上告警的痛苦。我在实际使用中的一个体会是litellm更适合作为团队基础能力去建设而不只是个人开发时的便利工具。一旦团队多个业务线都要接模型统一入口的价值就会放大很多倍。它天然就能解决的问题包括各项目共用一套模型服务商的Key管理、预算分账、调用审计、模型灰度切换。这些在野蛮生长的阶段可以凑合但业务稳定后都是必须补的课。如果你已经有一套业务在直连OpenAI或者别家的SDK迁移成本其实很低。接口和解耦层面的收益很快就回本了。建议从非核心业务开始试点跑通一个最简链路之后再逐步把所有模型调用都收拢到litellm网关里。最后再分享一个小技巧litellm可以直接对接本地部署的开源模型比如vLLM部署的模型服务配置上只需要把model指向本地服务地址就可以和商用模型统一纳管。这样一来你的模型资源池里就可以混用商用和开源模型根据场景灵活选择。成本高但效果好的商用模型留给关键场景成本低的本地模型处理高频简单需求这套组合拳用起来很顺手。