做后端开发这几年最烦的一件事就是接各种AI服务的SDK。OpenAI一套、Anthropic一套、Google一套参数风格、返回结构、鉴权方式全都不一样。每接一个新模型代码就要改一遍。直到我遇到Litellm这个开源项目它把这些乱七八糟的API全部统一成了一个标准格式——OpenAI兼容格式。也就是说只要你写过OpenAI的接口调用接别的模型基本就只改一个base_url剩下的代码完全不用动。这篇就从一个实际使用者的角度聊聊我在生产环境用Litellm当AI网关的完整经验包括核心功能拆解、部署配置、高级玩法和一路踩过的坑。1. 为什么后端团队需要一个LLM网关1.1 多模型接入的痛点先说痛点。很多团队的现状是代码里直接调OpenAI的SDK写死了https://api.openai.com/v1。后来想接国内模型降低成本或者想用Anthropic的Claude跑复杂任务问题就来了——你的代码是照着OpenAI的SDK写的换一家就得重新适配还要重新处理prompt格式、流式输出、tool call的结构差异。我见过最夸张的情况是某团队接了三家大模型代码里硬扛着三个SDK实例每个调用逻辑各写一套等于把同样的业务逻辑抄了三遍。后面AI模型迭代快今天这个便宜明天那个更强想切换就得动业务代码风险极大。1.2 网关层解决的核心问题Litellm这种LLM网关解决的就是这层问题。它在你的业务代码和各家模型API之间架了一层代理把不同厂商的API全部翻译成统一的OpenAI格式。业务代码永远只跟网关打交道网关负责跟各个大模型打交道。这样做的好处非常直接代码只需维护一套所有接入的模型都走OpenAI格式换模型就是改配置不用改代码。密钥全部收口各家API Key不用下发到业务服务器只存在网关这一层安全可控。成本集中管理每个模型多少钱、每个应用烧了多少token网关统一记账月底对账不用再翻账单。灰度切换的余地A模型效果不好想换B模型配置里改一下路由规则就行不用发版上线新代码。说白了Litellm把“接入AI”这件事从“写代码适配各家SDK”变成了“配置文件里改几个参数”。这对需要同时使用多个模型的团队来说价值是实打实的。1.3 什么人适合用Litellm如果你是个人开发者本地写个脚本调ChatGPT那Litellm确实有点重。但如果你是这样的情况我建议你认真考虑它公司有多个业务线都要接AI能力你不想每条线都重复造轮子接一遍SDK。你的应用要做模型A/B对比或者根据场景动态选择不同的模型。你需要对外提供AI能力给内部其他团队又不想把厂商API Key暴露出去。你要做成本统计、调用审计、限流控费。这些场景下Litellm是一个值得花半天时间研究的东西。2. Litellm核心功能拆解2.1 统一API格式OpenAI兼容的魔力Litellm的核心能力就是兼容。你的请求发给它格式是OpenAI的chat/completions结构它会自动转成目标模型要的格式。比如Anthropic要的是messages里带content数组Google Gemini要的是不同的system指令结构这些转换细节完全不用你操心。我举个例子。下面这个请求是我实际在用的只改了测试数据from openai import OpenAI client OpenAI( api_keysk-1234, # LiteLLM生成的虚拟Key base_urlhttp://localhost:4000/v1 # LiteLLM地址 ) response client.chat.completions.create( modelclaude-3-5-sonnet, # 这里写的是LiteLLM配置里的模型别名 messages[ {role: user, content: 帮我写一段Python斐波那契数列} ], streamTrue ) for chunk in response: print(chunk.choices[0].delta.content or , end)注意base_url指向Litellm的地址model字段写的是Litellm配置中定义好的模型名。这个模型名的背后可能是Anthropic的Claude、也可能是任何一家兼容或非兼容的模型。这对业务代码来说是透明的——你根本不知道后面实际调的是谁。2.2 模型路由与负载均衡Litellm支持把同一个模型名配置到多个供应商上然后根据路由策略分发请求。它支持多种路由算法包括简单的轮询多个Key轮流用适合把请求分摊到多个账号。成本优先优先选择成本最低的模型适合对成本比较敏感的批量场景。延迟优先优先选择响应最快的模型适合对实时性有要求的交互场景。自定义权重可以给不同模型配流量比例比如一个模型给80%流量、另一个给20%。这个功能在生产环境很实用。比如你同时开通了多个账号希望把负载分散开以免某个账号触发限流。配置一下就自动轮询了比自己在代码里写负载均衡强得多。2.3 虚拟Key与权限隔离这是我特别喜欢的一个功能。Litellm可以生成它自己的虚拟API Key业务方拿这个Key来调用而真正的厂商Key对业务方完全透明。你可以给每个应用、每个团队分配不同的虚拟Key单独设置额度、过期时间、允许访问的模型范围。也就是说某业务线一个月只有10万token预算那就给他生成一个Key配上预算额度。用超了会直接报错从机制上杜绝超额。如果某条业务线的Key泄露了也只要把它吊销掉不会影响网关背后的真实厂商Key。2.4 缓存、限流与预算控制这三个功能在生产环境都是刚需。Litellm支持Redis缓存可以配置语义缓存或简单的精确缓存。对于那种大量重复问答的场景比如客服知识库的常见问题命中缓存可以省下一大笔API费用响应时间也能从秒级降到毫秒级。限流方面Litellm支持按虚拟Key、按IP、按模型配置每秒请求数或每分钟token数限制。预算控制则是针对每个Key或每个团队设置整月或按天的花费上限。我实际使用下来的感受是这套机制跟云服务的API网关很像把安全和成本控制的细节全部下沉到网关层业务侧完全无感知。3. 从零部署一套LiteLLM代理服务3.1 安装与基础配置Litellm的安装非常简单它是Python写的直接pip安装就行pip install litellm[proxy]建议用虚拟环境装免得污染系统Python环境。装完以后核心就是一个配置文件加一个启动命令。3.2 手动配置config.yaml实际部署时所有模型、路由、预算等配置都写在config.yaml里。下面是一个能跑通的基础配置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 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-qwen litellm_params: model: openai/qwen2.5-7b-instruct api_base: http://localhost:8000/v1 api_key: dummy_key general_settings: master_key: sk-master-123456 database_url: postgresql://user:passwordlocalhost:5432/litellm关键点解释一下model_name是暴露给调用方看的模型名可以随便起。只要调用方传这个字符串网关就会按配置找到真正的模型。litellm_params里面写的是真实模型标识和Key信息。模型标识格式为供应商/模型Litellm自动做格式转换。api_base用于指定自定义接口地址。这非常有用比如企业内部部署的本地模型只要兼容OpenAI协议就能接进来。general_settings.master_key相当于网管的超级管理员Key用它来生成和管理虚拟Key。database_url建议配上PostgreSQL这样虚拟Key、预算、日志才能持久化。不加的话很多功能会受限且重启后数据丢失。启动服务就用一条命令litellm --config config.yaml --port 4000一切顺利的话服务会在4000端口监听。3.3 首次调用验证服务起来了先用master_key生成一个虚拟Keycurl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-master-123456 \ -H Content-Type: application/json \ -d {models: [gpt-4o-mini], max_budget: 5}返回里会带一个key字段这就是你给业务方用的虚拟Key。然后拿这个Key去测试调用curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-生成的虚拟Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: user, content: 你好简单介绍一下你自己} ] }如果配置正确你会收到一个标准的OpenAI格式响应。到这一步最基础的代理就通了。业务代码里把base_url指到这个服务地址模型名传gpt-4o-mini就能正常对话了。3.4 虚拟Key管理的实用建议我在生产环境里的经验是虚拟Key的命名和管理要制度化。比如Key的名称可以包含业务线、所属团队、用途像bi-report-wang这种。这样即使Key多了也能快速知道它是干什么的。另外过期时间一定要设置。哪怕内部使用长期不过期的Key总有一天会埋雷。4. 生产环境的高级玩法4.1 多模型自动故障转移单个模型供应商不可能是永远稳的总有接口报错、限流、超时的时候。Litellm支持配置多个同义模型来实现故障转移。比如你要让主模型是A厂商备用模型是B厂商配置可以这样写model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: gpt-4o litellm_params: model: azure/gpt-4o api_key: os.environ/AZURE_API_KEY api_base: https://xxx.openai.azure.com/当第一个模型返回错误时Litellm会自动把请求转向备用的模型。这对那些对可用性要求比较高、不能断供的场景太重要了。不用在业务代码里写任何重试或降级逻辑网关层全部搞定。4.2 语义缓存的正确姿势Litellm的缓存分为两种精确缓存和语义缓存。精确缓存就是相同请求直接返回相同响应适合固定模板类的任务。语义缓存则是计算向量相似度相似的请求不一定非要用完全相同的字符串才能命中。实际使用中我建议精确缓存开在Redis上TTL不要设太久几小时到一天比较合适。语义缓存建议先小流量测试因为语义匹配对阈值敏感阈值太高命中率低阈值太低容易返回不相关内容影响回答质量。缓存键建议把temperature等参数纳入考量否则同一个prompt在temperature0和temperature1下命中缓存结果会很奇怪。配置大致长这样general_settings: cache: true cache_params: type: redis host: localhost port: 6379 ttl: 36004.3 可观测性日志、指标与调用追踪生产环境跑起来没有监控等于裸奔。Litellm支持把调用日志写入数据库同时也对接Prometheus暴露指标。你可以看到各模型的请求量、成功率、平均延迟。各虚拟Key/各团队的Token消耗和费用。限流命中的次数、缓存命中率。错误类型的分布情况。这些指标对接Grafana可以做出很直观的看板。我个人是把/metrics端口单独保护起来只在内网开放避免暴露调用量等内部信息。对于排障Litellm的日志里会记录每一次请求的请求体、响应体、模型、耗时、费用、状态码。出问题的时候直接查数据库里的日志表基本能定位是上游问题、网络问题还是参数问题。这个能力在生产排障中价值巨大。4.4 Docker部署与水平扩展正式环境我建议用Docker Compose或Kubernetes部署Litellm而不是直接用pip跑。Litellm官方提供的镜像可以直接拉取。下面是一个精简的Docker Compose配置version: 3.8 services: litellm: image: ghcr.io/berriai/litellm:main-latest ports: - 4000:4000 volumes: - ./config.yaml:/app/config.yaml environment: - DATABASE_URLpostgresql://user:passpostgres:5432/litellm - OPENAI_API_KEYxxx - ANTHROPIC_API_KEYxxx depends_on: - postgres postgres: image: postgres:15 environment: POSTGRES_USER: user POSTGRES_PASSWORD: pass POSTGRES_DB: litellm请求量大了以后Litellm是无状态的服务数据库和Redis存储状态所以可以水平扩多个副本前面挂负载均衡器。Redis和PostgreSQL单独部署保证稳定性。5. 常见问题与排查技巧实录5.1 配置改了不生效这个是我被问到最多的问题。改完config.yaml里的模型列表发现调用还是老样子。原因是Litellm启动时加载了配置改文件并不会自动热更新。你需要重启服务或者用管理接口动态添加模型。在测试环境我建议加一个轻量重启脚本每次改配置后自动重启并检查健康状态省得手动操作。5.2 请求很容易超时有段时间上游模型响应偶尔要十几秒但Litellm默认超时设置可能只有10分钟左右不对实际我遇到的是反过来的——有些内部对接方设置了很短的HTTP超时导致等待上游模型时被断开。需要理清超时到底发生在哪一层调用方到Litellm这一层如果调用方设置了过短超时可以考虑在网关层用流式响应提升首包速度首字更快到达客户端不容易断开。Litellm到上游模型这一层可以通过修改litellm_params中的timeout参数调整等待时间。还有网络层面的问题比如出口IP被目标供应商限流或风控表现也是超时率高。排查方法并不神秘直接看Litellm日志里的耗时分布先定位瓶颈在哪一层再动手改。5.3 虚拟Key权限不对报403这个通常是生成Key的时候没有指定好models参数Key默认只能访问配置里允许的模型。如果你给调用方生成的Key上没加某个模型的权限调用时就会遇到权限不足的错误。解决的简单做法是在生成Key时不带models参数让它默认继承所有模型权限。但从安全角度我不建议这么干。谁负责哪条业务线就给哪个Key配上哪些模型权限最小化才是正道。5.4 Token统计和费用对不上Litellm的费用计算是基于大模型的usage字段来估算的。但每个模型的定价是动态调整的Litellm里面内置的价格表不一定是最新的自行部署更新不及时就会出现费用估算偏差。我的处理是定期更新Litellm版本同时对于费用比较敏感的业务不要完全依赖网关给的数字应该以厂商的账单为准。网关的数字用来做趋势分析和环比监控是够用的用来做精确财务对账则不够严谨。再提一个细节如果用了prompt caching这类功能厂商的计费逻辑会更复杂账单差异会更大这一点需要提前有心理准备。5.5 我自己踩过的几个坑第一不要把master_key当业务Key直接用。master_key权限太大泄露等于所有的虚拟Key都能被管理。我见过有人图省事前端直接拿master_key发起请求这在生产环境是非常危险的做法。第二数据库连接字符串的密码里如果有特殊字符要记得URL编码。我之前配置文件里密码带了个解析出来数据库连接一直报错排查了半天才发现是连接字符串没做编码导致截断。第三流式请求的日志量非常大。如果你还在把每一次streamtrue请求的完整内容落库磁盘增长会快得吓人。建议生产环境把请求内容记录关掉或只记录非流式请求日志表定期清理。第四跟其他网关组件混跑时要小心端口冲突。Litellm默认跑在4000端口如果你的监控系统或者其他服务也占了4000启动就会失败。统一规划端口在配置里显式写清楚比较好。6. 写在最后的经验总结Litellm这个项目我实际用了一年多从最初只当模型代理用到后来把路由、缓存、预算、审计全用上最大的体会是AI应用开发的重心正在从“怎么调模型”转移到“让调模型这件事更可控”。底层模型会不停地换更便宜、更强的新模型不断出现如果能用一层网关把这种变化隔离在业务之外团队就能把精力放在真正有价值的业务逻辑上。如果你正准备在公司内部引入多个AI模型我的建议是不要先写一堆胶水代码先把Litellm跑起来配两条不同供应商的模型让业务代码用OpenAI格式同时调通它们。等你体会到改一行配置就切换模型的感觉就明白这层网关有多值了。最后再分享一个小技巧Litellm版本更新很快新功能层出不穷。如果你在配置里写了某个参数但不生效先查官方文档确认参数名是否已变更。这个项目已经相对成熟但破坏性更新的情况偶尔也有升级版本前一定记得看Changelog先把配置备份好。