1. 为什么说litellm是大模型时代的万能插座1.1 一个接口接所有大模型解决的不只是格式问题先说个真实场景。去年我同时接了三个项目一个用某主流大模型商的对话接口做客服机器人一个要接国内厂商的模型做文档抽取还有一个得连企业内部部署的开源模型跑推理。那段时间我的代码里塞满了各家SDK的初始化逻辑每家的鉴权方式还不一样有的用Header传密钥有的要求先换临时Token有的只提供服务区内的Endpoint。最折磨人的是切模型需求一变代码里的客户端实例就要推倒重来。后来我意识到问题不在某一家模型的接口难用而在一套代码对接N家服务这件事本身就是灾难。litellm解决的就是这个点——它把各种模型商的API全部包装成统一的格式你在业务代码里只需要维护一种客户端、一种鉴权方式、一种请求结构剩下的事情全部交给网关处理。它的调用方式和某主流大模型的官方接口几乎完全一致你只需要把请求地址改成litellm的地址把密钥换成litellm生成的密钥其他都不用动。这意味着什么意味着你以前写的调用代码、Prompt组装逻辑、流式解析逻辑通通不用改换个地址就能用上新模型。1.2 litellm的本质一个可以自己部署的API网关很多人第一次接触litellm会把它当成一个普通SDK实际上它是标准的代理服务架构。你的应用发一个请求到litellmlitellm根据你指定的模型名称去查配置表找到真实的模型供应商、密钥、请求地址然后把请求转发出去拿到响应后再按统一格式返回给你。这个过程里litellm做的事情远不止转发这么简单。它帮你托管了所有供应商的密钥业务方不需要直接接触各家后台它在转发前可以做参数兼容性处理把不支持的参数自动丢弃它还能记录每一次请求的Token消耗、延迟、费用形成完整的调用链路日志。这些能力合在一起让litellm从格式转换器升级成了模型调用中枢。我把它放在整个架构里的位置简单描述一下业务代码 (OpenAI SDK / LangChain / curl) ↓ 统一格式请求 litellm proxy 服务 ↙ ↓ ↓ ↘ 模型商A 模型商B 私有化模型 开源模型业务侧完全感知不到后面的复杂性litellm在中间把一切差异都消化掉了。2. 从零搭建litellm代理服务环境准备与最小可用配置2.1 安装与启动两条路怎么选litellm的部署方式主要有两种Docker和pip直接装。# 方式一Docker推荐生产环境使用 docker pull ghcr.io/berriai/litellm:main-latest docker run -d -p 4000:4000 \ -e LITELLM_MASTER_KEYsk-your-master-key \ ghcr.io/berriai/litellm:main-latest # 方式二pip适合本地调试 pip install litellm[proxy] litellm --config ./config.yaml --port 4000我个人的建议是本地调试用pip方式方便改配置重启正式环境一律Docker资源隔离、扩容、回滚都省心。启动后先别急着配模型用健康检查接口确认服务活着curl http://localhost:4000/health/liveliness返回一串状态信息就说明服务正常。这时候访问/health/liveness和/health/readiness前者探活后者确认配置是否加载成功两个都过一遍再继续。2.2 config.yaml里的第一份模型配置litellm的配置核心是一个YAML文件默认叫config.yaml。第一次接触的时候你只需要理解最上面的一张表——model_list它定义了对外模型名和真实模型商的映射关系。model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo api_key: sk-xxx - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet api_key: sk-ant-xxx这段配置的含义是业务方请求modelgpt-3.5-turbo时litellm会把它转发给对应的模型商请求modelclaude-3-5-sonnet时转发给另一家。注意model字段里的前缀连接Anthropic要写全anthropic/连接其他厂商也有各自的标识规则这个前缀就是litellm识别目标供应商的依据。启动之后用一行命令验证整个链路curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-master-key \ -d { model: gpt-3.5-turbo, messages: [{role: user, content: 你好请介绍一下你自己}] }能拿到和官方接口一致格式的返回说明配置成功。2.3 我建议的本地调试三部曲新手最容易犯的错是一上来就调litellm出问题根本分不清是哪一层的锅。我总结了一个三步排查法先用官方原生的Endpoint直连模型商确认密钥有效、请求参数正确。这一步能排除密钥错了账号没钱了模型名写错等低级问题。再通过litellm的接口以完全相同的参数调一次对比返回结果。如果这里失败去看litellm的启动日志它会详细打印请求转发到了哪个地址、目标返回了什么。最后才在业务代码里换用litellm的地址验证SDK层面的兼容性。我见过太多人跳过第一步结果发现是测试账号的额度用完了白白浪费一下午。先把底层链路打通再往上叠加litellm逻辑上最稳。3. 核心配置拆解统一网关背后的四张表3.1 model_list模型注册表model_list是litellm配置的核心也是大多数人最常改动的地方。不同供应商的接入差异基本都在litellm_params里体现。比如连Azure的模型需要在参数里带上api_base指向你的资源部署地址连AWS Bedrock需要换成aws_access_key_id、aws_secret_access_key、region_name这一套连本地跑的Ollama模型只需要指向局域网内的Ollama服务地址。表格对比一目了然目标供应商litellm_params中model字段关键额外参数某主流云模型商gpt-4oapi_keyAnthropicanthropic/claude-3-5-sonnetapi_keyAzureazure/gpt-4oapi_key、api_baseAWS Bedrockbedrock/anthropic.claude-3-sonnetaws_access_key_id、aws_region_name本地Ollamaollama/llama3.1api_base还有一个很实用的用法同一个逻辑模型名可以挂多个供应商形成冗余。model_list: - model_name: my-chat-model litellm_params: model: gpt-4o api_key: sk-aaa - model_name: my-chat-model litellm_params: model: anthropic/claude-3-5-sonnet api_key: sk-bbb这样业务方眼里只有一个my-chat-modellitellm内部可以按策略在两家中选一家转发。3.2 litellm_settings全局行为开关litellm_settings管的是网关自身的运行时行为几个关键开关值得逐个搞清楚。litellm_settings: drop_params: true set_verbose: true max_budget: 100 budget_duration: 30ddrop_params是我最看重的一个开关。业务方如果用某主流模型的SDK默认会带上temperature、top_p、presence_penalty这些采样参数但并不是所有模型商都支持这些字段有的OpenAI系兼容服务遇到不认识的参数会直接报错。开启drop_params之后litellm会在转发前自动把目标供应商不支持的参数过滤掉从源头避免这种兼容性问题。代价是参数被丢弃后采样行为会偏离你的预期但这个开关的收益远大于风险。budget_duration用在这里控制全局总预算整个网关一个月内累计费用超过100美元就自动拒绝新请求。这个数值要按自己的实际用量谨慎设置。3.3 general_settings密钥与访问控制general_settings这一节管的是安全问题最核心的是master_key。general_settings: master_key: sk-your-master-key database_url: postgresql://user:passlocalhost:5432/litellm如果你不设置master_keylitellm启动后会警告你处于无鉴权状态任何能访问到这个端口的人都可以白嫖你的模型额度。生产环境必须设置。database_url是另一个容易被忽略的配置。前面光靠内存运行密钥、日志、用量统计重启就丢了挂上PostgreSQL之后虚拟密钥、预算记录、调用日志全部持久化重启不丢数据。从玩玩到正经用数据库是分水岭。3.4 router_settings路由策略的心脏router_settings决定了当一个逻辑模型名背后挂了多个真实供应商时请求到底发给谁。router_settings: routing_strategy: usage-based-routing-v2 allowed_fails: 3 cooldown: 60 fallbacks: - my-chat-model: [gpt-4o-mini]routing_strategy有好几种后面会展开对比。allowed_fails表示某个供应商连续失败多少次之后被临时拉黑cooldown是拉黑多长时间后再给它一次机会fallbacks定义主模型失败时切换到哪个备用模型。这几组参数合在一起构成了litellm的高可用基础。它不是一个单纯的转发器而是一个有能力做故障转移的智能路由。4. 路由策略与高可用当主模型宕机时系统在做什么4.1 不同路由策略的选型逻辑litellm配置里最值得花时间研究的模块就是路由器。我说的路由器指的是多个供应商之间如何分配流量的决策机制。拿我实际调试过的几种策略来做个对比策略名称原理适用场景simple-shuffle随机打乱顺序轮流分发小流量、各供应商能力一致的场景least-busy统计每个供应商当前在途请求数发给最闲的异步任务多、长耗时请求占比高的场景usage-based-routing-v2实时跟踪每分钟Token消耗动态调整分配权重大流量、有成本控制诉求的场景我自己的经验是日请求量在几千到几万级别时simple-shuffle就够了实现简单行为可预期出问题也好排查。当量级上来之后usage-based-routing-v2的按每分钟Token消耗动态调节权重更合理但它依赖default_max_budget和default_budget_duration这两个参数统计预算水位配置不完整会静默退回简单策略。选型的原则是复杂策略只有在你能理解它的决策依据时才值得用否则出故障你都不知道它为什么这么转。4.2 fallback配置模型故障时的自动转移流程化地讲litellm的高可用主要靠fallbacks实现。我用一个示例说明router_settings: fallbacks: - gpt-4o: [gpt-4o-mini, anthropic/claude-3-haiku] cooldown: 30 allowed_fails: 3这段配置的意思是当主模型gpt-4o连续失败3次之后后续请求自动切换到备选列表里的模型先尝试gpt-4o-mini再不行就切到Claude Haiku。切换逻辑是有记忆的不是说每个请求都重新试一次主模型而是主模型进入冷却期30秒之后才恢复尝试。一次真实的故障演练让我印象深刻。某天下午我故意把主模型的密钥改错然后连续发请求日志里能看到前三次请求报401错误第四次开始自动转到了备用模型上业务侧毫无感知调用方甚至连一次超时都没遇到。这种无感知降级对生产系统来说价值巨大。需要提醒的是fallback的粒度是model_name级别的也就是说你得在model_list里先把备用模型注册好否则litellm找不到目标时会直接抛错而不是自动切换。4.3 每次请求的体检报告在哪里看路由跑起来之后你一定会关心每个请求的实际表现到底走了哪个模型、消耗了多少Token、花了多少钱、延迟多少。litellm把这些信息都记在了日志里。最直观的入口是/spend/logs接口curl http://localhost:4000/spend/logs \ -H Authorization: Bearer sk-your-master-key返回的数据里能看到每次请求的时间戳、模型名、供应商、Prompt Token数、Completion Token数、总费用。单位是美元精度到小数点后六位。这套数据对成本分摊非常有用——到了月底财务要对账直接从litellm导出各项目的费用明细不用你自己拿Excel硬算。生产环境里我还会在litellm_settings里多开两个开关litellm_settings: set_verbose: true json_logs: trueset_verbose打开之后litellm会在启动日志里打印每个请求的完整转发明细包括目标地址、请求头、响应状态码排查问题时的信息完整度完全不一样。json_logs把日志输出改成JSON格式方便接日志收集系统统一检索。日志量会明显增大但换来的是可观测性值。5. 生产环境避坑实录鉴权、日志、Docker与多团队管理5.1 master_key与虚拟Key别把主钥匙到处给刚开始用litellm的时候我图省事直接把master_key写在前端代码里让几个前端同事直接拿去调接口。后来发现不对劲——所有人都用一个密钥根本分不清流量是谁产生的出了问题也不知道找谁。litellm专门设计了虚拟密钥机制来解决这个问题。它是这么用的拿着master_key管理员权限调用密钥生成接口创建多个带独立标识的子密钥每个子密钥可以限定预算、限定可访问的模型、设置过期时间然后把子密钥分发给不同的业务方。curl -X POST http://localhost:4000/key/generate \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d { models: [gpt-4o, gpt-4o-mini], max_budget: 50, budget_duration: 30d }返回的key就是虚拟密钥把这个密钥给对应的项目组用。后续每个项目的用量、费用都能按虚拟密钥分开统计出了事故也能精准定位。预算上限也变成了硬约束——某个项目组的额度刷爆了litellm直接拒绝它的新请求而不是月底给财务一张让人血压飙升的账单。这个机制在生产环境的地位怎么强调都不过分。5.2 Docker部署最容易忽略的三个参数Docker部署litellm本身不难但有几个参数很容易踩坑。第一是LITELLM_MASTER_KEY环境变量。如果你在docker run命令里不显式传这个变量而配置文件中也没写master_key服务会以无鉴权模式启动端口暴露出去就是灾难。正确做法是启动命令里显式传入或者挂载的config.yaml里写明。第二是数据库的持久化。默认情况下litellm把所有数据存在内存里容器一重启密钥、日志、配额全部归零。生产环境必须挂PostgreSQLdocker-compose里用一个postgres服务litellm连过去。第三是端口暴露范围。litellm默认监听4000端口docker run的时候别直接-p 4000:4000把端口裸奔到公网。我习惯用-p 127.0.0.1:4000:4000只绑本机前面再用Nginx做反向代理加一层HTTPS和访问控制。基础但重要。一个最小可用的docker-compose示例version: 3.8 services: litellm: image: ghcr.io/berriai/litellm:main-latest ports: - 127.0.0.1:4000:4000 environment: - LITELLM_MASTER_KEYsk-your-master-key - DATABASE_URLpostgresql://litellm:passwordpostgres:5432/litellm volumes: - ./config.yaml:/app/config.yaml restart: unless-stopped depends_on: - postgres postgres: image: postgres:15 environment: - POSTGRES_DBlitellm - POSTGRES_USERlitellm - POSTGRES_PASSWORDpassword volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata:5.3 日志排障的几条实战命令跑生产之后我手机里存了几条固定的排障命令遇到问题直接上# 查看所有已注册模型及其健康状态 curl http://localhost:4000/model/info \ -H Authorization: Bearer sk-your-master-key # 按虚拟密钥查消费明细 curl http://localhost:4000/spend/keys \ -H Authorization: Bearer sk-your-master-key # 查某一个key的详细信息 curl http://localhost:4000/key/info \ -H Authorization: Bearer sk-your-master-key遇到报错litellm错误信息里带清晰的类型标记。常见的几类我总结成了口诀报错类型含义处理方式AuthenticationError目标模型商的密钥无效检查config.yaml里对应的api_keyRateLimitError触达目标供应商限流检查是否超额考虑配fallback切换ContextWindowExceededError上下文超长业务侧做截断或换大窗口模型NotFoundError模型名不存在检查model_list里的真实模型名是否写对大部分连不上问题日志里都会明确告诉你litellm尝试连接的目标地址是什么、目标返回的状态码是什么顺着这两条信息去排查基本不会迷路。6. 从代理到平台的进阶路线不止是转发请求6.1 用量追踪与成本分摊litellm用久了你就会发现它天然变成了团队的模型调用控制台。前面提到的/spend/keys接口按虚拟密钥把每个项目的Token消耗和费用全部摊开每个团队一个月用多少、花多少钱清清楚楚。我自己最常用的一个场景是月底给合作方报账。以前是找各家模型商的账单一个项目一个项目地加还要手动换算不同计价单位。现在litellm每个请求都有记录按虚拟密钥一筛Excel直接导出来就能用。对于要批量接模型做产品的团队来说这套数据就是基础财务设施。6.2 多租户隔离与团队管理当团队多起来之后单靠虚拟密钥还不够——你还需要把多个虚拟密钥归到统一的团队下统一设置这个团队的模型白名单和总预算。# 创建团队 curl -X POST http://localhost:4000/team/new \ -H Authorization: Bearer sk-your-master-key \ -H Content-Type: application/json \ -d {team_alias: data-group, max_budget: 200}拿到team_id后生成虚拟密钥时把team_id带进去这个密钥就自动归属到团队下。团队的所有密钥共享预算池一个项目多个服务共用额度管理粒度比一人一key更合理。6.3 接入端SDK与兼容性说明litellm上线后接入方一般有三种方式第一种是直接用某主流大模型厂商的SDK只改base_url和api_key。这是最省事的方式代码零改动把环境变量里的OPENAI_BASE_URL指向litellm地址就行。from openai import OpenAI client OpenAI( api_keysk-your-litellm-virtual-key, base_urlhttp://your-litellm-host:4000/v1 ) resp client.chat.completions.create( modelmy-chat-model, messages[{role: user, content: 你好}] )第二种是LangChain集成ChatOpenAI传base_url参数同样可以工作第三种是curl直调适合快速验证。我特别想说的是接入方式越简单团队成员越不容易因为不想改代码而绕过网关自己连原厂。这个细节直接决定了统一网关能不能真正落地。6.4 我对litellm的整体评价和适用边界回顾这段时间的使用我的判断是litellm最适合的场景是那些需要在多个大模型之间做切换、同时还要管预算和权限的团队。无论是做多模型路由的高可用架构还是给不同项目做模型资源隔离它都能比自研省下大量时间。但它也不是银弹。如果你的业务只固定用一个模型商的接口没有切换需求也不涉及多团队协作那引入litellm等于白白增加一层网络跳转和部署维护成本。另外它对延迟极度敏感的场景不太友好——每多一跳代理理论上都会增加毫秒级的网络开销虽然实际体感不明显但如果你做的是高频实时交互、量化交易话务这种场景需要先做压测再决定要不要前置这一层网关。部署位置也值得想清楚。把litellm部署在离业务代码最近的VPC内网里和业务服务同区域然后让模型商的Endpoint走公网这样代理链路增加的那一跳延迟几乎可以忽略。我后来把litellm从公网服务器迁到业务同网段之后接口P95延迟基本没有变化。如果你正被一套代码对接多家模型商这个问题困扰或者团队里每个人各抱一个密钥、账单乱成一锅粥我建议先把litellm装起来跑通一个最小链路试试。先从最简单的model_list配置开始把一条请求完整跑通再逐步加上fallback、虚拟密钥、预算控制。litellm最大的优点就是配置项足够直白你不需要理解它的全部机制就能先跑起来跑起来之后才有手感才知道自己的业务到底应该把哪些能力用足。