隔一段时间不跟一遍生态就会发现自己有点跟不上。LLM应用开发最近火到什么程度光是切换模型这一步就能让人烦到怀疑人生。今天聊的这个项目叫litellm一句话说清楚它是一个开源的LLM网关也叫统一代理层用一套API格式把市面上主流大模型服务商的接口全部包起来。简单讲你的业务代码不用再为不同模型写不同的调法直接走litellm这一个口子后端是接通的还是通义、是本地部署的模型还是别家闭源的接口对上层调用者完全透明。很多团队一开始觉得用不着这种中间层结果项目一跑起来就发现模型A效果不好想切模型B结果B的请求参数格式完全不一样再往后又发现几个人共用几个API Key月底账单对不上再往后想限个流、给不同部门分配额度发现根本没有现成的机制。这些问题litellm都能管而且它本身是个开源项目不是封闭的商业平台部署在自己服务器上数据内容不经过第三方中间链路。这篇文章我会从实际使用的角度把它的核心设计拆开来看再给出完整的部署步骤、配置示例和排错经验适合正在做AI应用开发的后端工程师、想给团队搭一套模型治理基础设施的技术负责人以及那些被多模型切换折磨过的独立开发者。1. 为什么需要一个LLM代理层1.1 多模型接口的接入痛点先看一个具体场景。你的应用要同时接入多家模型服务一个用于日常闲聊先上A家的通用大模型一个用于专业写作试试B家的长文本模型再部署一个本地的开源模型处理敏感数据。每个服务商的SDK风格都不同有的用messages数组有的用prompt字符串有的流式返回的字段叫delta有的叫choices还有的干脆把所有输出包在一个JSON字符串里。我见过不少团队的第一版集成方案是写一个LLMClient接口每个服务商写一个实现类。一开始只有两家还好第三家接入时就要处理超时配置、重试策略、错误码映射、流式解析、模型名称映射、计费格式转换……这套代码越写越厚最终变成项目里最难维护的一块。而且这种紧耦合带来的问题不止是代码层面。业务方想从A模型切到B模型光靠发版已经不够还得同步修改配置中心、重启服务、刷掉缓存。如果还牵扯到上游依赖的接口协议那一次切换基本等于一次小型重构。1.2 litellm 的定位与优势litellm做的事情就是一个转换层它对外暴露一个标准的OpenAI兼容接口同时把所有常见服务商的原生接口翻译成这个标准格式。你只需要按OpenAI的ChatCompletion方式调用剩下的内容、鉴权、重试、流式协议全部交给litellm处理。部署完成之后你的业务代码里再也不会直接出现某个具体服务商的SDK最多维护一份模型到服务的映射配置。想要切换模型改配置文件或者重新指定model参数就行业务代码一行都不用动。除了接口统一之外litellm还自带几个对生产环境很重要的能力预算管理为每个Key、每个用户、每个团队设置额度上限。限流控制按请求数或Token数做速率限制防止单个应用把配额打爆。负载均衡同一模型配置多个上游Key自动分配请求实现故障转移。日志追踪记录每一次请求的模型、Token消耗、延迟和费用方便对账。多租户管理多个团队共享同一代理各自用完各自的预算。这些能力不是额外插件而是代理层本身的一部分所以接入成本非常低。1.3 什么时候你不需要它也必须说清楚不是所有项目都适合引入这层代理。如果你的应用只调用一家模型服务并且没有切换模型的可能性也没有多人共享Key、预算管理、日志审计的需求那litellm属于过度设计。每多一层就多一个故障点这个判断要尊重实际情况。适合用的场景一般至少占一到两条多模型并存、多人/多应用共享API成本、需要做精细的配额管控、需要对模型调用做审计留痕。如果你的近期规划里还没有这些东西那先别急着上代理层把业务跑通更重要。2. 核心功能拆解它到底做了什么2.1 统一API格式与转换机制litellm的核心是建立在OpenAI的接口规范上的。为什么偏偏选OpenAI格式而不是另创一套因为OpenAI的ChatCompletion接口已经被大量开源工具和框架默认支持各种Agent框架、向量库插件、IDE插件默认就能对接它。litellm顺势而为把OpenAI接口作为中间格式兼容成本最小。它的转换层工作方式可以理解为一张映射表把目标服务商的请求参数结构翻译成OpenAI的messages、model、temperature、max_tokens等字段再把目标服务商的响应结构翻译成OpenAI统一的choices、message、finish_reason结构。流式场景下SSE数据格式也会被转换客户端解析逻辑完全不需要区分背后是哪个模型。这种设计直接带来了一个好处你的业务服务里只需要维护OpenAI SDK一种依赖换模型、换服务商只是改一个model字符串的事。2.2 预算、限流与权限控制预算管理是litellm特别好用也最容易被忽视的功能。很多开发团队拿到API Key就开始写代码月底账单出来才发现某个测试脚本烧了几百美元这种例子我见过不止一次。litellm支持在代理层设置多级预算全局预算整个网关的总花费上限。Key级预算某个虚拟Key的最大花费超过后直接拒绝请求并返回429或自定义错误。用户级预算按用户ID维度管控适合面向C端的产品。团队级预算按团队维度分配资源。限流方面litellm可以让每个虚拟Key在一分钟、一小时、一天内最多处理多少请求或消耗多少Token。配置很灵活max_parallel_requests控制并发tpm_limit和rpm_limit控制每分钟的Token和请求数。权限控制体现在虚拟Key体系上。你可以为不同的业务线创建不同的Key并给每个Key绑定允许访问的模型列表。比如A应用只能用基础对话模型B应用才能用高成本的长文本模型从源头卡住滥用。2.3 智能路由与负载均衡这是litellm在生产环境里真正值钱的部分。当你在同一个模型下配置了多个上游服务商的API Key时litellm默认会轮询转发请求被均匀分散到各个Key上。更进阶的做法是配置routing_strategy。它支持几种策略simple-shift简单轮询。usage-based-routing基于每个Key当前配额消耗的实时状态路由尽量让配额充足的Key多承担请求。latency-based-routing优先选择历史延迟更低的Key。least-busy选择当前并发请求数最少的Key。多Key轮询不只是为了提高可用性还承担了配额管理的职责。假设你订阅了某个服务商的两个档位一个基础档一个高级档希望优先耗完基础档的额度再走高级档那可以把基础档的Key权重配高一些或者直接用usage-based-routing让它自适应分配。另外值得一提的还有故障转移。某个上游Key如果返回401、403或者429litellm可以自动把这次请求转发到下一个可用Key上对客户端无感知。这个机制在某个服务商突发故障或者单个Key被限流时特别管用。2.4 日志记录与可观测性凡是涉及钱的系统没有日志就是瞎子。litellm内置了请求日志表每一条请求都会记录模型名、虚拟Key标识、用户标识、请求时间、延迟、Token用量、预估费用。它还支持把日志写到传统数据存储里比如PostgreSQL、MySQL甚至S3、GCS这类对象存储。你也可以接监控工具通过Prometheus暴露指标在Grafana上画看板实时观察整条链路的调用量和费用走势。我现在维护的一套系统就是每天凌晨跑一个统计任务把litellm日志表按团队维度和模型维度做汇总输出到成本报表里。财务那边再也不用月底看账单猜每一个模型调用花了多少钱都能追溯到具体应用和具体Key。3. 从零部署一套代理服务3.1 环境准备与安装litellm是个Python项目安装方式很常规。我建议在部署前先确认机器有没有满足条件的Python版本我自己用的是Python 3.11跑起来很稳。然后直接执行安装pip install litellm[proxy]这里安装的是带代理服务的版本和纯SDK版本不同。如果只想用Python库装litellm本体就够了但我们现在要搭代理层所以装[proxy]扩展。装完之后验证一下版本litellm --version这个命令会输出当前版本号看到版本信息出来就说明装好了。安装过程依赖的包比较多如果是国内网络环境可能需要给pip配置镜像源否则下载会非常慢。这个不是litellm的问题是Python生态的老问题。3.2 准备模型凭证准备凭证的意思是在启动代理之前得让litellm知道你有哪些上游API Key可以用。有两种方式第一种是放在环境变量里。litellm对主流服务商都有固定的环境变量命名规则比如某个服务商的Key对应的环境变量名就非常直观一般是服务商名加_API_KEY的格式。启动前把Key注入环境变量即可官方文档可以直接查到每个服务商对应的变量名。第二种是写在配置文件的model_list里这种方式更可控也便于版本化维护。每个模型条目里写明model_name对外暴露的模型名和litellm_params实际调用的模型名和API Key。我当前的配置长这样model_list: - model_name: gpt-demo litellm_params: model: gpt-xxx api_key: sk-xxx - model_name: claude-demo litellm_params: model: claude-xxx api_key: sk-xxx - model_name: local-model litellm_params: model: openai/本地模型服务地址 api_base: http://localhost:8000/v1配置里model_name是对接业务方时使用的名字业务代码只认这个名字。litellm_params.model填的是上游真实模型名。api_base用于自建服务或网关比如本地用vLLM部署的开源模型就指到对应的服务地址上。3.3 编写核心配置文件litellm支持通过命令行参数直接启动但生产环境建议用一个YAML配置文件把所有配置归拢起来。下面是一个我在测试环境用的基础配置注释都写得比较清楚model_list: - model_name: gpt-demo litellm_params: model: gpt-xxx api_key: sk-xxx litellm_settings: drop_params: true set_verbose: false num_retries: 3 request_timeout: 30 retry_after: 0.5 general_settings: master_key: sk-your-master-key database_url: postgresql://user:passlocalhost:5432/litellm otel: false几个关键参数解释一下drop_params当传入的参数对某个上游模型不支持时直接丢弃而不是报错。这个开关很实用因为不同模型对参数的宽容度不一样。num_retries请求失败后的重试次数。我一般设成3太多容易把上游接口打得更忙。request_timeout上游请求超时时间。注意这个值要结合模型实际响应速度来设不能拍脑袋。master_key代理服务的总管理Key。所有向litellm发起的请求都要带上这个Key它是代理层权限体系的根。database_url可选但强烈推荐。接上数据库之后预算、配额、日志这些能力才能启用。如果一开始不想接数据库也可以本地起一个SQLite来用。先让日志和预算功能跑通之后再迁移到PostgreSQL。3.4 启动服务并验证配置写好后启动代理服务只需要一条命令litellm --config ./config.yaml --port 4000服务起来之后验证接口是否正常。litellm兼容OpenAI格式直接用一个请求试一下curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-master-key \ -d { model: gpt-demo, messages: [{role: user, content: 你好}] }返回正常的choices结构就说明代理链路已经通了。在这之后你的业务代码里所有指向某个上游服务商Base URL的地方全部换成http://你的服务器地址:4000即可。3.5 客户端SDK接入接入方式兼容OpenAI官方SDK所以代码改动很小。用Python举例from openai import OpenAI client OpenAI( base_urlhttp://你的服务器地址:4000/v1, api_keysk-your-master-key ) resp client.chat.completions.create( modelgpt-demo, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)如果你用的是Node.js的官方SDK配置也差不多把baseURL指到litellm的地址就行。业务代码的感知只是换了一个端点其他都不用改。这里容易踩一个坑litellm管理端也会占用/路径的路由你如果直接用浏览器打开http://服务器地址:4000看到的是管理后台或者健康检查的提示。/v1/chat/completions才是真正的API入口别搞混。4. 我踩过的坑与排查实录4.1 请求一直超时但不是代理的问题有一次我部署到一台新机器上代理服务已经起来了curl测试时一直报timeout。一开始以为是配置问题反复修改request_timeout和num_retries都没有效果。后来检查发现那台机器所在的安全组没有放行上游服务商的出口IP代理服务本地的4000端口确实开着但出站请求被网络策略拦了。这个排查走了不少弯路因为litellm的日志里只显示上游连接超时完全没有提示是网络策略导致的。遇到超时问题先分三步排查第一步确认上游服务商接口能不能直接访问通第二步确认代理容器或进程所在的机器有没有出站限制第三步再怀疑配置。顺序反了会很浪费时间。4.2 模型名对不上导致404litellm里最经典的报错是请求返回404响应里的错误信息是model not found。这个问题的原因几乎永远是业务请求里写的model和你model_list里定义的model_name不一致。有一次排查某团队的问题他们代码里写的是gpt-4但配置文件里暴露的模型名是gpt-demo两边自己说自己的代理层自然不认识。这类问题不是litellm的bug而是定义不统一导致的。一个习惯是尽快把模型名配置版本化并给不同的业务环境用不同的前缀区分。比如prod-gpt-chat和test-gpt-chat一目了然从根源上减少沟通误解。4.3 预算清零后服务异常但不报错预算功能上线后某个测试环境的模型突然大量返回空内容去日志里看又没有任何错误。仔细查才发现是给这个环境配置的预算已经用完了litellm默认策略是直接拦截请求而客户端那边把拦截响应当成了正常响应处理。这个问题的教训是代理端的拦截响应和模型正常响应都应该有清晰的状态标志客户端拿到响应时不能只取content字段就完事还要检查HTTP状态码。另外测试环境的预算不要设得太死不然你根本分不清是模型坏了还是配额用完了。4.4 并发高时出现排队和雪崩有段时间某个模型服务的响应延迟突然变得很高litellm日志里看到大量请求排队的迹象。后来发现是上游某个Key的并发限制很低而我配置的max_parallel_requests没有针对这个Key设置导致请求全部拥堵在一起。litellm有专门的超时和并发保护参数。当你给某个上游Key配置了rpm_limit或tpm_limit同时设置了max_parallel_requests之后超出并发限制的请求会进入等待队列而不是直接打给上游。这个机制保护了上游服务也让客户端不至于被瞬时熔断。但反过来也说明并发配置一定要基于上游服务商的实际限制来定不要拍脑袋。最好先在测试环境压一轮把真实的极限摸出来再加一点余量作为兜底。5. 生产环境落地建议5.1 单机部署还是集群部署很多团队一开始都是单机部署litellm因为它的性能开销很小一个2核4G的小实例就能支撑几百个并发请求的转发和转换。如果只是给团队内几十个人做接入单机完全够用。但一旦服务于线上业务单机就成了单点。litellm本身是无状态的所有状态都放在PostgreSQL或者Redis里所以部署多个实例做负载均衡非常容易。我推荐的生产形态是前置一个负载均衡器后面挂两个或三个litellm实例共享同一个数据库。这样可以做到一个实例挂了另一个自动接管请求。还有一个要注意的点litellm的并发和性能还取决于上游模型的响应时间。模型响应长连接被占用的时间就长同样内存下可承载的并发请求数就少。这个和请求量是两回事评估容量时不要只看QPS。5.2 密钥管理与安全litellm的master_key是最高权限凭证谁拿到它谁就能创建新的虚拟Key、修改预算配置。一旦泄露等于整个模型网关的钥匙交了出去。我的做法是不在代码仓库里保存master_key而是通过环境变量注入。每个业务线使用独立的虚拟Key不要共用主Key。定期轮换虚拟Key并把不再使用的Key删除。开启数据库审计功能留痕每一次Key创建和修改操作。如果部署在云环境还可以配合云厂商的密钥管理服务把主Key放到加密存储里应用服务启动时再从那里读取而不是写死在配置文件。5.3 成本治理与多团队协作litellm在多团队协作模式下的价值十分突出。每个团队一个虚拟Key每个Key绑定自己的模型白名单和预算上限。这样一来成本责任直接落到使用方你再不用去追着问“这个月为什么花了这么多”。我自己的团队里还固定了一个成本巡检的节奏每周看一次按Key和模型维度的汇总发现异常增长的条目就顺着日志追下去看看是哪个应用、哪个用户在调用。很多失控的花费其实并不是恶意滥用而是某个测试脚本忘了关定时任务。有了日志五分钟就能定位到问题。如果要接企业内部的统一认证体系litellm也支持对接自定义鉴权可以在请求到达代理层之前做一次用户身份校验。这部分的配置稍微复杂一些但值得花时间做尤其当你面向多个外部业务方开放模型能力的时候。5.4 扩展玩法从代理到内部模型平台litellm用熟了之后你会发现自己不知不觉在做一件比“接口代理”更大的事你在搭一个内部模型接入平台。比如说你可以在代理层统一记录每次请求的反馈数据沉淀成一份内部模型评估集。哪个模型在某个业务上面表现好不再靠主观感受而是看真实调用的延迟、Token成本和用户反馈。再比如说你可以把不同模型的测试通道统一暴露给产品同学让他们自己对比效果而不是每次都要找你改代码。这个方向听起来有点远但它确实是litellm这类统一网关最终会带你去的地方。基础设施准备好了上层能力的叠加就是水到渠成的事。根据我个人的经验litellm最让人舒服的一点是它没有把一个复杂问题变得更复杂而是用一个几乎无感的转换层把后续所有模型的接入、切换、治理问题都收拢到了统一出口。你只需要花一下午把基础配置跑通接下来就能看着它稳定地替你挡掉一大批鸡毛蒜皮的杂事。如果你正被多模型集成、Key管理、成本对账这些事折磨花点时间认真把litellm搭起来不亏。
隔一段时间不跟一遍生态就会发现自己有点跟不上。LLM应用开发最近火到什么程度光是切换模型这一步就能让人烦到怀疑人生。今天聊的这个项目叫litellm一句话说清楚它是一个开源的LLM网关也叫统一代理层用一套API格式把市面上主流大模型服务商的接口全部包起来。简单讲你的业务代码不用再为不同模型写不同的调法直接走litellm这一个口子后端是接通的还是通义、是本地部署的模型还是别家闭源的接口对上层调用者完全透明。很多团队一开始觉得用不着这种中间层结果项目一跑起来就发现模型A效果不好想切模型B结果B的请求参数格式完全不一样再往后又发现几个人共用几个API Key月底账单对不上再往后想限个流、给不同部门分配额度发现根本没有现成的机制。这些问题litellm都能管而且它本身是个开源项目不是封闭的商业平台部署在自己服务器上数据内容不经过第三方中间链路。这篇文章我会从实际使用的角度把它的核心设计拆开来看再给出完整的部署步骤、配置示例和排错经验适合正在做AI应用开发的后端工程师、想给团队搭一套模型治理基础设施的技术负责人以及那些被多模型切换折磨过的独立开发者。1. 为什么需要一个LLM代理层1.1 多模型接口的接入痛点先看一个具体场景。你的应用要同时接入多家模型服务一个用于日常闲聊先上A家的通用大模型一个用于专业写作试试B家的长文本模型再部署一个本地的开源模型处理敏感数据。每个服务商的SDK风格都不同有的用messages数组有的用prompt字符串有的流式返回的字段叫delta有的叫choices还有的干脆把所有输出包在一个JSON字符串里。我见过不少团队的第一版集成方案是写一个LLMClient接口每个服务商写一个实现类。一开始只有两家还好第三家接入时就要处理超时配置、重试策略、错误码映射、流式解析、模型名称映射、计费格式转换……这套代码越写越厚最终变成项目里最难维护的一块。而且这种紧耦合带来的问题不止是代码层面。业务方想从A模型切到B模型光靠发版已经不够还得同步修改配置中心、重启服务、刷掉缓存。如果还牵扯到上游依赖的接口协议那一次切换基本等于一次小型重构。1.2 litellm 的定位与优势litellm做的事情就是一个转换层它对外暴露一个标准的OpenAI兼容接口同时把所有常见服务商的原生接口翻译成这个标准格式。你只需要按OpenAI的ChatCompletion方式调用剩下的内容、鉴权、重试、流式协议全部交给litellm处理。部署完成之后你的业务代码里再也不会直接出现某个具体服务商的SDK最多维护一份模型到服务的映射配置。想要切换模型改配置文件或者重新指定model参数就行业务代码一行都不用动。除了接口统一之外litellm还自带几个对生产环境很重要的能力预算管理为每个Key、每个用户、每个团队设置额度上限。限流控制按请求数或Token数做速率限制防止单个应用把配额打爆。负载均衡同一模型配置多个上游Key自动分配请求实现故障转移。日志追踪记录每一次请求的模型、Token消耗、延迟和费用方便对账。多租户管理多个团队共享同一代理各自用完各自的预算。这些能力不是额外插件而是代理层本身的一部分所以接入成本非常低。1.3 什么时候你不需要它也必须说清楚不是所有项目都适合引入这层代理。如果你的应用只调用一家模型服务并且没有切换模型的可能性也没有多人共享Key、预算管理、日志审计的需求那litellm属于过度设计。每多一层就多一个故障点这个判断要尊重实际情况。适合用的场景一般至少占一到两条多模型并存、多人/多应用共享API成本、需要做精细的配额管控、需要对模型调用做审计留痕。如果你的近期规划里还没有这些东西那先别急着上代理层把业务跑通更重要。2. 核心功能拆解它到底做了什么2.1 统一API格式与转换机制litellm的核心是建立在OpenAI的接口规范上的。为什么偏偏选OpenAI格式而不是另创一套因为OpenAI的ChatCompletion接口已经被大量开源工具和框架默认支持各种Agent框架、向量库插件、IDE插件默认就能对接它。litellm顺势而为把OpenAI接口作为中间格式兼容成本最小。它的转换层工作方式可以理解为一张映射表把目标服务商的请求参数结构翻译成OpenAI的messages、model、temperature、max_tokens等字段再把目标服务商的响应结构翻译成OpenAI统一的choices、message、finish_reason结构。流式场景下SSE数据格式也会被转换客户端解析逻辑完全不需要区分背后是哪个模型。这种设计直接带来了一个好处你的业务服务里只需要维护OpenAI SDK一种依赖换模型、换服务商只是改一个model字符串的事。2.2 预算、限流与权限控制预算管理是litellm特别好用也最容易被忽视的功能。很多开发团队拿到API Key就开始写代码月底账单出来才发现某个测试脚本烧了几百美元这种例子我见过不止一次。litellm支持在代理层设置多级预算全局预算整个网关的总花费上限。Key级预算某个虚拟Key的最大花费超过后直接拒绝请求并返回429或自定义错误。用户级预算按用户ID维度管控适合面向C端的产品。团队级预算按团队维度分配资源。限流方面litellm可以让每个虚拟Key在一分钟、一小时、一天内最多处理多少请求或消耗多少Token。配置很灵活max_parallel_requests控制并发tpm_limit和rpm_limit控制每分钟的Token和请求数。权限控制体现在虚拟Key体系上。你可以为不同的业务线创建不同的Key并给每个Key绑定允许访问的模型列表。比如A应用只能用基础对话模型B应用才能用高成本的长文本模型从源头卡住滥用。2.3 智能路由与负载均衡这是litellm在生产环境里真正值钱的部分。当你在同一个模型下配置了多个上游服务商的API Key时litellm默认会轮询转发请求被均匀分散到各个Key上。更进阶的做法是配置routing_strategy。它支持几种策略simple-shift简单轮询。usage-based-routing基于每个Key当前配额消耗的实时状态路由尽量让配额充足的Key多承担请求。latency-based-routing优先选择历史延迟更低的Key。least-busy选择当前并发请求数最少的Key。多Key轮询不只是为了提高可用性还承担了配额管理的职责。假设你订阅了某个服务商的两个档位一个基础档一个高级档希望优先耗完基础档的额度再走高级档那可以把基础档的Key权重配高一些或者直接用usage-based-routing让它自适应分配。另外值得一提的还有故障转移。某个上游Key如果返回401、403或者429litellm可以自动把这次请求转发到下一个可用Key上对客户端无感知。这个机制在某个服务商突发故障或者单个Key被限流时特别管用。2.4 日志记录与可观测性凡是涉及钱的系统没有日志就是瞎子。litellm内置了请求日志表每一条请求都会记录模型名、虚拟Key标识、用户标识、请求时间、延迟、Token用量、预估费用。它还支持把日志写到传统数据存储里比如PostgreSQL、MySQL甚至S3、GCS这类对象存储。你也可以接监控工具通过Prometheus暴露指标在Grafana上画看板实时观察整条链路的调用量和费用走势。我现在维护的一套系统就是每天凌晨跑一个统计任务把litellm日志表按团队维度和模型维度做汇总输出到成本报表里。财务那边再也不用月底看账单猜每一个模型调用花了多少钱都能追溯到具体应用和具体Key。3. 从零部署一套代理服务3.1 环境准备与安装litellm是个Python项目安装方式很常规。我建议在部署前先确认机器有没有满足条件的Python版本我自己用的是Python 3.11跑起来很稳。然后直接执行安装pip install litellm[proxy]这里安装的是带代理服务的版本和纯SDK版本不同。如果只想用Python库装litellm本体就够了但我们现在要搭代理层所以装[proxy]扩展。装完之后验证一下版本litellm --version这个命令会输出当前版本号看到版本信息出来就说明装好了。安装过程依赖的包比较多如果是国内网络环境可能需要给pip配置镜像源否则下载会非常慢。这个不是litellm的问题是Python生态的老问题。3.2 准备模型凭证准备凭证的意思是在启动代理之前得让litellm知道你有哪些上游API Key可以用。有两种方式第一种是放在环境变量里。litellm对主流服务商都有固定的环境变量命名规则比如某个服务商的Key对应的环境变量名就非常直观一般是服务商名加_API_KEY的格式。启动前把Key注入环境变量即可官方文档可以直接查到每个服务商对应的变量名。第二种是写在配置文件的model_list里这种方式更可控也便于版本化维护。每个模型条目里写明model_name对外暴露的模型名和litellm_params实际调用的模型名和API Key。我当前的配置长这样model_list: - model_name: gpt-demo litellm_params: model: gpt-xxx api_key: sk-xxx - model_name: claude-demo litellm_params: model: claude-xxx api_key: sk-xxx - model_name: local-model litellm_params: model: openai/本地模型服务地址 api_base: http://localhost:8000/v1配置里model_name是对接业务方时使用的名字业务代码只认这个名字。litellm_params.model填的是上游真实模型名。api_base用于自建服务或网关比如本地用vLLM部署的开源模型就指到对应的服务地址上。3.3 编写核心配置文件litellm支持通过命令行参数直接启动但生产环境建议用一个YAML配置文件把所有配置归拢起来。下面是一个我在测试环境用的基础配置注释都写得比较清楚model_list: - model_name: gpt-demo litellm_params: model: gpt-xxx api_key: sk-xxx litellm_settings: drop_params: true set_verbose: false num_retries: 3 request_timeout: 30 retry_after: 0.5 general_settings: master_key: sk-your-master-key database_url: postgresql://user:passlocalhost:5432/litellm otel: false几个关键参数解释一下drop_params当传入的参数对某个上游模型不支持时直接丢弃而不是报错。这个开关很实用因为不同模型对参数的宽容度不一样。num_retries请求失败后的重试次数。我一般设成3太多容易把上游接口打得更忙。request_timeout上游请求超时时间。注意这个值要结合模型实际响应速度来设不能拍脑袋。master_key代理服务的总管理Key。所有向litellm发起的请求都要带上这个Key它是代理层权限体系的根。database_url可选但强烈推荐。接上数据库之后预算、配额、日志这些能力才能启用。如果一开始不想接数据库也可以本地起一个SQLite来用。先让日志和预算功能跑通之后再迁移到PostgreSQL。3.4 启动服务并验证配置写好后启动代理服务只需要一条命令litellm --config ./config.yaml --port 4000服务起来之后验证接口是否正常。litellm兼容OpenAI格式直接用一个请求试一下curl http://localhost:4000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-master-key \ -d { model: gpt-demo, messages: [{role: user, content: 你好}] }返回正常的choices结构就说明代理链路已经通了。在这之后你的业务代码里所有指向某个上游服务商Base URL的地方全部换成http://你的服务器地址:4000即可。3.5 客户端SDK接入接入方式兼容OpenAI官方SDK所以代码改动很小。用Python举例from openai import OpenAI client OpenAI( base_urlhttp://你的服务器地址:4000/v1, api_keysk-your-master-key ) resp client.chat.completions.create( modelgpt-demo, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)如果你用的是Node.js的官方SDK配置也差不多把baseURL指到litellm的地址就行。业务代码的感知只是换了一个端点其他都不用改。这里容易踩一个坑litellm管理端也会占用/路径的路由你如果直接用浏览器打开http://服务器地址:4000看到的是管理后台或者健康检查的提示。/v1/chat/completions才是真正的API入口别搞混。4. 我踩过的坑与排查实录4.1 请求一直超时但不是代理的问题有一次我部署到一台新机器上代理服务已经起来了curl测试时一直报timeout。一开始以为是配置问题反复修改request_timeout和num_retries都没有效果。后来检查发现那台机器所在的安全组没有放行上游服务商的出口IP代理服务本地的4000端口确实开着但出站请求被网络策略拦了。这个排查走了不少弯路因为litellm的日志里只显示上游连接超时完全没有提示是网络策略导致的。遇到超时问题先分三步排查第一步确认上游服务商接口能不能直接访问通第二步确认代理容器或进程所在的机器有没有出站限制第三步再怀疑配置。顺序反了会很浪费时间。4.2 模型名对不上导致404litellm里最经典的报错是请求返回404响应里的错误信息是model not found。这个问题的原因几乎永远是业务请求里写的model和你model_list里定义的model_name不一致。有一次排查某团队的问题他们代码里写的是gpt-4但配置文件里暴露的模型名是gpt-demo两边自己说自己的代理层自然不认识。这类问题不是litellm的bug而是定义不统一导致的。一个习惯是尽快把模型名配置版本化并给不同的业务环境用不同的前缀区分。比如prod-gpt-chat和test-gpt-chat一目了然从根源上减少沟通误解。4.3 预算清零后服务异常但不报错预算功能上线后某个测试环境的模型突然大量返回空内容去日志里看又没有任何错误。仔细查才发现是给这个环境配置的预算已经用完了litellm默认策略是直接拦截请求而客户端那边把拦截响应当成了正常响应处理。这个问题的教训是代理端的拦截响应和模型正常响应都应该有清晰的状态标志客户端拿到响应时不能只取content字段就完事还要检查HTTP状态码。另外测试环境的预算不要设得太死不然你根本分不清是模型坏了还是配额用完了。4.4 并发高时出现排队和雪崩有段时间某个模型服务的响应延迟突然变得很高litellm日志里看到大量请求排队的迹象。后来发现是上游某个Key的并发限制很低而我配置的max_parallel_requests没有针对这个Key设置导致请求全部拥堵在一起。litellm有专门的超时和并发保护参数。当你给某个上游Key配置了rpm_limit或tpm_limit同时设置了max_parallel_requests之后超出并发限制的请求会进入等待队列而不是直接打给上游。这个机制保护了上游服务也让客户端不至于被瞬时熔断。但反过来也说明并发配置一定要基于上游服务商的实际限制来定不要拍脑袋。最好先在测试环境压一轮把真实的极限摸出来再加一点余量作为兜底。5. 生产环境落地建议5.1 单机部署还是集群部署很多团队一开始都是单机部署litellm因为它的性能开销很小一个2核4G的小实例就能支撑几百个并发请求的转发和转换。如果只是给团队内几十个人做接入单机完全够用。但一旦服务于线上业务单机就成了单点。litellm本身是无状态的所有状态都放在PostgreSQL或者Redis里所以部署多个实例做负载均衡非常容易。我推荐的生产形态是前置一个负载均衡器后面挂两个或三个litellm实例共享同一个数据库。这样可以做到一个实例挂了另一个自动接管请求。还有一个要注意的点litellm的并发和性能还取决于上游模型的响应时间。模型响应长连接被占用的时间就长同样内存下可承载的并发请求数就少。这个和请求量是两回事评估容量时不要只看QPS。5.2 密钥管理与安全litellm的master_key是最高权限凭证谁拿到它谁就能创建新的虚拟Key、修改预算配置。一旦泄露等于整个模型网关的钥匙交了出去。我的做法是不在代码仓库里保存master_key而是通过环境变量注入。每个业务线使用独立的虚拟Key不要共用主Key。定期轮换虚拟Key并把不再使用的Key删除。开启数据库审计功能留痕每一次Key创建和修改操作。如果部署在云环境还可以配合云厂商的密钥管理服务把主Key放到加密存储里应用服务启动时再从那里读取而不是写死在配置文件。5.3 成本治理与多团队协作litellm在多团队协作模式下的价值十分突出。每个团队一个虚拟Key每个Key绑定自己的模型白名单和预算上限。这样一来成本责任直接落到使用方你再不用去追着问“这个月为什么花了这么多”。我自己的团队里还固定了一个成本巡检的节奏每周看一次按Key和模型维度的汇总发现异常增长的条目就顺着日志追下去看看是哪个应用、哪个用户在调用。很多失控的花费其实并不是恶意滥用而是某个测试脚本忘了关定时任务。有了日志五分钟就能定位到问题。如果要接企业内部的统一认证体系litellm也支持对接自定义鉴权可以在请求到达代理层之前做一次用户身份校验。这部分的配置稍微复杂一些但值得花时间做尤其当你面向多个外部业务方开放模型能力的时候。5.4 扩展玩法从代理到内部模型平台litellm用熟了之后你会发现自己不知不觉在做一件比“接口代理”更大的事你在搭一个内部模型接入平台。比如说你可以在代理层统一记录每次请求的反馈数据沉淀成一份内部模型评估集。哪个模型在某个业务上面表现好不再靠主观感受而是看真实调用的延迟、Token成本和用户反馈。再比如说你可以把不同模型的测试通道统一暴露给产品同学让他们自己对比效果而不是每次都要找你改代码。这个方向听起来有点远但它确实是litellm这类统一网关最终会带你去的地方。基础设施准备好了上层能力的叠加就是水到渠成的事。根据我个人的经验litellm最让人舒服的一点是它没有把一个复杂问题变得更复杂而是用一个几乎无感的转换层把后续所有模型的接入、切换、治理问题都收拢到了统一出口。你只需要花一下午把基础配置跑通接下来就能看着它稳定地替你挡掉一大批鸡毛蒜皮的杂事。如果你正被多模型集成、Key管理、成本对账这些事折磨花点时间认真把litellm搭起来不亏。
