你有没有过这种经历项目里接了三家不同的大模型API再加一个本地拉起来的开源模型结果每家的SDK都不一样。A家的消息格式是messagesB家要把系统提示词拆成system字段C家连超参命名都不一样。业务代码里到处是if provider xxx的分支换一次模型就像做一次小重构。我见过太多团队把时间浪费在这件事上后来接触到litellm这个开源项目才意识到问题可以有一个更干净的解法。litellm本质上是一个大模型API网关它对客户端暴露一套完全兼容OpenAI接口规范的HTTP服务然后自己在后端把请求翻译、路由到几十家模型服务商也可以转发到本地通过vLLM、Ollama这类服务部署的模型。对上层业务来说你只需要记住一个base_url、一个虚拟密钥至于流量最终落在Claude还是GPT还是国产开源模型上业务方完全不用关心。这篇文章我会从网关的底层流转开始讲再给出可直接照抄的Docker部署方案、业务接入方式最后梳理生产环境必须处理的密钥、限流、成本、高可用问题以及我实际踩过的一些坑。适合正在做多模型接入、想统一管理模型密钥和成本、或者打算把模型能力平台化的团队参考。1. 统一API网关从“每次换模型都要改代码”说起litellm解决的第一个痛点就是“接入成本随模型数量线性膨胀”的问题。很多人一开始觉得不过是封装一层SDK而已等模型数量多了才发现SDK封装远没有想象中简单。1.1 三个最常见的模型接入痛点场景第一个场景是模型选型与效果对比。你手头要评估五六个模型在同一个任务上的表现比如摘要、分类、意图识别。这些模型分散在不同的服务商每个都有自己独立的鉴权方式、消息格式、错误码和限流策略。写个评测脚本的时候光是适配各家接口就要糊一大堆胶水代码。第二个场景是多团队共享模型资源。公司里数据组要调嵌入模型做向量化算法组要调大模型做推理前端也在接对话能力如果直接把各家服务商的API Key发下去密钥管理基本失控。谁在调、调了多少、花了多少钱完全是一笔糊涂账。第三个场景是本地模型与云端模型混合接入。你在GPU机器上部署了一个开源模型API风格是OpenAI兼容的但端口、版本、超参都不一样。业务方希望像调用其他云端模型一样调用这个本地模型不感知部署细节。这三个场景表面上是“接口不统一”的问题深层其实是“模型接入层缺少一个治理点”。有了统一网关模型切换、密钥下发、成本核算都能收敛到一个地方完成。1.2 自研封装vs现成网关为什么我不建议自己写我在不少项目里都见过团队自研“模型调用工具类”封装一个chat()函数内部用if-else分发到各家SDK。坦白说模型只有一两家的时候这个方案没有太大问题。但一旦要支持流式、异步、函数调用、图片输入、嵌入向量工作量会迅速失控。对比维度自研SDK封装litellm网关方案接入成本每增加一个模型都要开发适配层配置一个litellm_params条目即可协议差异处理要自己处理消息格式转换、参数别名网关统一翻译客户端只认OpenAI格式密钥管理Key散落在各服务或环境变量里虚拟密钥统一签发可绑定模型和预算成本统计要自己记录token、算单价网关侧自动记录每次请求用量与估算费用故障转移基本没有报错就挂支持同一模型多上游配置、重试与冷却维护成本自己写的代码自己维护业务越重越难改上游持续更新适配新模型由社区完成当然自研封装在极度简单的场景下依然可行。但如果你已经感受到“模型多了管不过来”与其继续给自研封装打补丁不如提前切到网关方案。litellm不需要你改业务代码只是把原来的请求地址换成一个网关地址迁移成本非常低。我后面会演示具体怎么做。2. litellm在底层做了什么一次请求的完整流转如果要给litellm定位我会说它不是一个“AI应用框架”而是一个“模型流量网关”。它的核心工作是把一个OpenAI格式的HTTP请求翻译成目标模型服务商期望的格式再把响应翻译回OpenAI格式返回给客户端。2.1 请求进来后认证、路由、翻译、转发、回传整个流转过程可以分成五步。第一步是认证。客户端带着一个虚拟密钥访问litellm的/chat/completions接口网关先校验这个密钥是否有效、有没有超出配额、是否被允许访问请求中的模型名。第二步是路由。litellm根据请求体里的model字段在配置的model_list里找到对应条目。比如客户端传的是model: gpt-4o网关发现这个名称被映射到了OpenAI的真实模型如果客户端传的是model: claude-3-5-sonnet网关就把它映射到Anthropic对应的模型。第三步是翻译。这是最核心的一步。litellm拿到OpenAI格式的请求体后会根据目标服务商的SDK规范把参数名和消息结构重新组装。比如OpenAI的messages数组里包含role和content而某些服务商要求系统提示词放在单独的字段里或者对max_tokens的命名不一致这些转换都在这一步完成。第四步是转发。litellm调用目标服务商的原生SDK或者HTTP接口把请求发出去同时处理鉴权、重试、超时、限流等网络细节。第五步是回传。litellm拿到上游响应后把内容重新包装成OpenAI的choices结构同时记录本次请求的token用量、延迟、费用等元数据最后返回给客户端。对上层业务而言整个网关是透明的。你发出去的请求和收到的响应看起来和直连OpenAI没有任何区别这就是它能无缝替换的原因。2.2 不只是转发参数差异和单位差异才是麻烦所在网关做得对不对关键就看“翻译”够不够细。我举几个实际存在的差异点你感受一下。消息结构上OpenAI统一用messages数组表达对话历史而一些服务商对系统提示词、多轮历史、图片内容的字段要求完全不同。litellm需要把这些结构映射过去有些模型不支持图片时还会自动丢弃或报错这都需要配置控制。超参命名上max_tokens这个词在不同服务商里五花八门有的叫max_tokens_to_sample有的叫max_new_tokens有的放在generation_config里。还有temperature的取值范围有的服务商支持0到2有的只允许0到1。网关要负责把OpenAI的通用参数翻译成目标服务商的合法范围。token统计和计价上OpenAI按prompt_tokens和completion_tokens返回其他服务商字段名不一样。litellm在记录日志时会统一归一化并根据你配置的单价估算费用。这也是它能做成本追踪的基础。说白了litellm替你把各家API的“方言”翻译成了普通话。如果你只在代码层做封装这些差异迟早会漏到业务代码里。3. 快速跑通Docker部署一个最小可用网关理论说那么多不如直接跑起来。这一节我给出一个最小可用的部署方案你照着做十分钟内就能通过网关调用真实模型。3.1 先写好config.yaml理解model_list的映射关系litellm的网关配置核心是一个YAML文件里面最重要的就是model_list。它做的事情非常直观给上游每个模型起一个客户端可见的名字再指定上游的真实模型标识和API Key。下面是一个同时接入OpenAI、Anthropic和本地Ollama模型的配置示例model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20240620 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama3 litellm_params: model: ollama/llama3 api_base: http://localhost:11434这里有几个关键点要说明。model_name是客户端调用时使用的名字你可以随意命名不必和上游真实模型名一致。比如你想让业务方无感切换可以统一叫chat然后在配置里把这个名字映射到不同真实模型。litellm_params.model是上游模型标识。OpenAI系模型直接写模型ID非OpenAI系的模型前面要加provider前缀比如anthropic/、ollama/、bedrock/、vertex_ai/、vllm/。这个前缀告诉litellm该用哪套翻译逻辑。api_key推荐写成os.environ/环境变量名的形式让litellm从进程环境变量里读取避免密钥明文写进配置文件。如果接的是本地vLLM服务写法类似- model_name: local-qwen litellm_params: model: openai/qwen2.5-7b-instruct api_base: http://localhost:8000/v1 api_key: dummy注意这里用了openai/前缀因为vLLM对外暴露的是OpenAI兼容接口litellm会把请求直接转发过去。3.2 启动容器并验证接口配置写好后用Docker启动网关是最省事的方式docker run -d \ --name litellm-gateway \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ -e OPENAI_API_KEYsk-xxxx \ -e ANTHROPIC_API_KEYsk-ant-xxxx \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml生产环境不要用latest后缀建议固定镜像版本号避免上游更新引入不兼容变化。本地试验阶段用main-latest倒是无妨。启动后先看健康检查接口curl http://localhost:4000/health/liveliness一切正常后用OpenAI SDK风格调用一次对话式接口curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 你好用一句话介绍你自己}] }这里你可能注意到了我填的Bearer令牌是sk-1234。默认情况下litellm需要一个master_key也就是管理员主密钥。如果你没配置网关启动时会打印一个随机生成的临时主密钥上面这个请求里的sk-1234需要换成你自己的主密钥。如果你想禁用主密钥校验可以在配置里加上general_settings: master_key: sk-1234然后把上面的请求头原样发出去即可。生产环境务必换一个足够复杂的master_key并妥善保管。3.3 管理界面与模型测试litellm自带一个Web管理界面默认路由是/ui。打开http://localhost:4000/ui用管理员账号登录后你可以直观地看到已配置的模型列表、虚拟密钥列表、请求日志和成本数据还能在界面上直接创建新的虚拟密钥、设置模型访问权限。初次跑通时建议先在UI的“测试”页面里选择一个模型输入一段prompt确认能拿到正常回复。这一步通过后再往下游接业务代码排查问题时会省力很多。4. 接入现有代码一个base_url能解决多少事网关部署好之后最爽的事情来了你现有的OpenAI调用代码几乎不用改。4.1 用OpenAI SDK切换base_url的用法如果你已经在用OpenAI官方的Python SDK切换方式就一行代码的事from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-1234 ) response client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: 你是一个智能助手}, {role: user, content: 介绍一下litellm的用途} ], streamTrue ) for chunk in response: print(chunk.choices[0].delta.content or , end)这里面有个特别容易忽略的点base_url末尾要带上/v1因为litellm对外暴露的OpenAI兼容路由挂在/v1下。有些同学只填了http://localhost:4000结果请求一直404排查半天才发现是路径问题。流式响应、异步调用、工具调用functions/tools这些OpenAI SDK的能力都能透传。因为litellm返回的响应结构本身就是OpenAI格式SDK解析起来零压力。如果你原本用的是别的服务商的官方SDK那就需要把请求改造成OpenAI格式再指向网关。这也是我建议新项目直接按照OpenAI规范写调用层的原因——只要一次改造后期换成任何模型都不再动业务代码。4.2 给团队下发虚拟密钥和模型权限多个成员或服务要访问网关时不应该让他们直接使用master_key正确的做法是通过管理员接口创建虚拟密钥。curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { models: [gpt-4o, claude-3-5-sonnet], max_budget: 100, expires: 2025-12-31T23:59:59 }返回值里会有一个key字段这就是发给团队成员使用的虚拟密钥。它只允许访问models列表里指定的模型且在max_budget花完后自动失效。这样团队里每个成员都有自己的密钥谁的请求超了预算、谁的调用异常日志里一查便知。如果不想用命令行直接在UI的“Virtual Keys”页面点几下也能生成同样的密钥。5. 生产环境配置清单密钥、限流、成本与高可用本地跑通一个网关只是开始真要放到生产环境还要考虑负载均衡、故障转移、成本控制和数据安全这几个问题。这一节我给出一份可以直接参考的配置清单。5.1 多上游负载均衡与故障转移一个非常实用的能力是同一个model_name可以配置多个上游模型litellm会自动做负载均衡并在某个上游报错时切换到另一个。model_list: - model_name: chat litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion - model_name: chat litellm_params: model: anthropic/claude-3-5-sonnet-20240620 api_key: os.environ/ANTHROPIC_API_KEY配置里两个条目的model_name都叫chat业务方请求时只写model: chat网关会按策略自动把流量分给OpenAI或Anthropic。默认策略是简单轮询也可以在router_settings里调整router_settings: routing_strategy: simple-shuffle model_group_failover: true cooldown_time: 300model_group_failover开启后如果某个上游连续失败它会被临时标记为冷却状态后续请求自动打到健康的上游冷却时间结束后再恢复。cooldown_time300表示失败上游冷却5分钟。这套机制对“降级容灾”特别有用。生产环境可以把主模型和备用模型配成同一个model_name主模型限流或宕机时业务代码一行不用改流量自动切换。5.2 成本统计、预算限制与token治理litellm的管理界面里自带请求日志和成本汇总支持按虚拟密钥、按模型、按时间维度筛选。这是我最常用的功能之一。团队里谁调了什么模型、花了多少钱打开UI就能看到不需要再自己写日志统计。如果你想在网关层做硬性预算控制可以在general_settings里配置general_settings: master_key: sk-1234 max_budget: 500 budget_duration: 30d max_parallel_requests: 100这会限制整个网关每30天最多消耗500美元超出后拒绝新请求。更细粒度的预算则在生成虚拟密钥时设置每个密钥单独设限额。有一点要提醒litellm的成本统计依赖你在配置里给每个模型设置的单价。如果使用公共云模型的默认映射单价通常是内置的如果是自建模型或小众模型需要手动在model_info里补充计价参数否则成本统计可能偏差很大。这个我在后面踩坑部分还会详细说。5.3 缓存与速率限制生产环境还有一个高频需求是缓存。很多业务场景里相似的重读请求会反复打同一个模型白白消耗token。litellm支持在网关层做响应缓存litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379开启后命中缓存的请求会直接返回结果不再调用上游模型。小规模部署用内存缓存就够了多实例部署建议用Redis避免不同实例缓存不一致。速率限制也是生产环境必需品。litellm支持按虚拟密钥限制每分钟请求数、每秒token数等防止某个调用方把上游配额打满影响其他业务。general_settings: max_parallel_requests: 50也可以在每个虚拟密钥创建的时候指定rpm_limit和tpm_limit对调用方做隔离限流。5.4 安全边界内网部署、关闭调试日志、TLS有几点安全配置容易被忽略我单独拉出来说。第一网关会明文看到所有发给它的请求和响应包括prompt内容和模型输出。如果业务数据敏感网关必须部署在可信内网前面再挂一层公司的API网关做统一认证不要把litellm直接暴露到公网。第二生产环境务必关闭调试模式。litellm开启debug后会把完整的请求头、响应体打到日志里API Key也会跟着泄露。配置里不要设置debug: true日志级别保持默认。第三网关和上游服务商之间的通信默认走TLS这是安全的。但如果你通过HTTP方式访问网关网络链路上的数据就是明文内网通常可以接受跨公网必须加TLS。第四定期查看访问日志。litellm的日志支持按密钥、IP审计调用记录发现异常调用模式时能快速定位到具体密钥然后一键禁用。6. 实际踩坑记录与绕过办法工具好不好用只有踩过坑才知道。这一节我把自己实际遇到过的问题列出来每条都给出排查链路和解决方案希望对你有帮助。6.1 模型名不存在的报错与服务端配置不一致有次一个项目组来问我为什么调用时报“model not found”。我一看他们的请求model字段写的是gpt-3.5-turbo但网关注册的model_name是gpt-4o和claude-3-5-sonnet。解决方案很简单要么让业务方改请求里的模型名要么在model_list里给现有模型再加一个model_name别名。网关的模型名映射是精确匹配的不存在模糊匹配。建议在接入时就和业务方约定好模型命名规范并且把客户端默认模型名直接写成一个通用别名比如default-chat后续切换时只改网关配置。6.2 长推理场景下的超时和流式断开另一个高频问题是超时。默认情况下litellm对上游请求有内置超时时间如果模型推理时间较长响应可能被网关中止表现就是客户端收到异常中断。排查时可以先看网关日志里有没有timeout关键字的报错。解决办法是在config.yaml里配置一个足够宽松的超时litellm_settings: request_timeout: 600但光改这里还不够客户端SDK也有自己的超时时间特别是流式请求。OpenAI SDK默认的timeout值是600秒如果你的场景是长文本生成加上网络环境复杂建议显式调大client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-1234, timeout600, max_retries2 )6.3 debug日志泄漏API Key之前有一次在测试环境排查问题打开了debug模式结果在stdout日志里直接看到了完整的请求头里面带着各家上游的API Key。这个问题一旦出现在生产环境密钥基本等于裸奔。排查链路一般是确认config里有没有开debug查看日志输出文件里是否存在Authorization头然后立刻关闭debug并轮换所有已泄漏的密钥。建议生产环境直接禁用debug所有日志输出到统一日志系统并做关键词脱敏。6.4 本地模型api_base路径写错导致返回异常接入本地vLLM服务时api_base必须带上/v1路径后缀。比如vLLM服务跑在http://localhost:8000配置里要写http://localhost:8000/v1。漏掉/v1时请求会转发到一个不存在的路由返回404或奇怪的HTML错误。Ollama的配置也有类似问题。Ollama原生接口路径是/api/chat但litellm接入Ollama时用的api_base一般写http://localhost:11434不需要额外路径。反正记住一个原则不同上游对api_base的接受程度不一样接之前先看一眼官方示例别凭感觉填。6.5 成本统计偏差必须显式配置单价如果你发现管理界面的成本数字和上游账单对不上大概率是模型单价配置的问题。公共云模型内置了官方单价表但新模型上线、价格调整、自建模型接入时litellm有可能还没有对应的计价信息。解决办法是在模型配置里显式加上计价参数model_list: - model_name: local-qwen litellm_params: model: openai/qwen2.5-7b-instruct api_base: http://localhost:8000/v1 api_key: dummy model_info: input_cost_per_token: 0.000001 output_cost_per_token: 0.000002 mode: chat这样网关统计成本时就会按你给的单价计算。自建模型按实际GPU成本估算就好云端模型按服务商官网价格换算成“每token美元”填进去。7. 我的最后一点建议用litellm做模型网关我自己最顺手的用法是把它当成公司内部的“模型接入层”。所有业务系统只认一个base_url、一个虚拟密钥模型选型、版本切换、成本统计、密钥治理全部收敛到网关配置层面。上线新模型时先跑通配置再小范围放量稳定后切流量全程不碰业务代码。如果你正在纠结多模型接入问题我的建议是先别急着写抽象层先把litellm这类网关部署起来用最小流量跑一两周看看稳定性和成本数据是否符合预期。实际用下来你会发现它解决的不只是“换模型少改代码”这一个问题连同密钥管理、预算控制、调用审计这些麻烦事也一并有了落脚点。
你有没有过这种经历项目里接了三家不同的大模型API再加一个本地拉起来的开源模型结果每家的SDK都不一样。A家的消息格式是messagesB家要把系统提示词拆成system字段C家连超参命名都不一样。业务代码里到处是if provider xxx的分支换一次模型就像做一次小重构。我见过太多团队把时间浪费在这件事上后来接触到litellm这个开源项目才意识到问题可以有一个更干净的解法。litellm本质上是一个大模型API网关它对客户端暴露一套完全兼容OpenAI接口规范的HTTP服务然后自己在后端把请求翻译、路由到几十家模型服务商也可以转发到本地通过vLLM、Ollama这类服务部署的模型。对上层业务来说你只需要记住一个base_url、一个虚拟密钥至于流量最终落在Claude还是GPT还是国产开源模型上业务方完全不用关心。这篇文章我会从网关的底层流转开始讲再给出可直接照抄的Docker部署方案、业务接入方式最后梳理生产环境必须处理的密钥、限流、成本、高可用问题以及我实际踩过的一些坑。适合正在做多模型接入、想统一管理模型密钥和成本、或者打算把模型能力平台化的团队参考。1. 统一API网关从“每次换模型都要改代码”说起litellm解决的第一个痛点就是“接入成本随模型数量线性膨胀”的问题。很多人一开始觉得不过是封装一层SDK而已等模型数量多了才发现SDK封装远没有想象中简单。1.1 三个最常见的模型接入痛点场景第一个场景是模型选型与效果对比。你手头要评估五六个模型在同一个任务上的表现比如摘要、分类、意图识别。这些模型分散在不同的服务商每个都有自己独立的鉴权方式、消息格式、错误码和限流策略。写个评测脚本的时候光是适配各家接口就要糊一大堆胶水代码。第二个场景是多团队共享模型资源。公司里数据组要调嵌入模型做向量化算法组要调大模型做推理前端也在接对话能力如果直接把各家服务商的API Key发下去密钥管理基本失控。谁在调、调了多少、花了多少钱完全是一笔糊涂账。第三个场景是本地模型与云端模型混合接入。你在GPU机器上部署了一个开源模型API风格是OpenAI兼容的但端口、版本、超参都不一样。业务方希望像调用其他云端模型一样调用这个本地模型不感知部署细节。这三个场景表面上是“接口不统一”的问题深层其实是“模型接入层缺少一个治理点”。有了统一网关模型切换、密钥下发、成本核算都能收敛到一个地方完成。1.2 自研封装vs现成网关为什么我不建议自己写我在不少项目里都见过团队自研“模型调用工具类”封装一个chat()函数内部用if-else分发到各家SDK。坦白说模型只有一两家的时候这个方案没有太大问题。但一旦要支持流式、异步、函数调用、图片输入、嵌入向量工作量会迅速失控。对比维度自研SDK封装litellm网关方案接入成本每增加一个模型都要开发适配层配置一个litellm_params条目即可协议差异处理要自己处理消息格式转换、参数别名网关统一翻译客户端只认OpenAI格式密钥管理Key散落在各服务或环境变量里虚拟密钥统一签发可绑定模型和预算成本统计要自己记录token、算单价网关侧自动记录每次请求用量与估算费用故障转移基本没有报错就挂支持同一模型多上游配置、重试与冷却维护成本自己写的代码自己维护业务越重越难改上游持续更新适配新模型由社区完成当然自研封装在极度简单的场景下依然可行。但如果你已经感受到“模型多了管不过来”与其继续给自研封装打补丁不如提前切到网关方案。litellm不需要你改业务代码只是把原来的请求地址换成一个网关地址迁移成本非常低。我后面会演示具体怎么做。2. litellm在底层做了什么一次请求的完整流转如果要给litellm定位我会说它不是一个“AI应用框架”而是一个“模型流量网关”。它的核心工作是把一个OpenAI格式的HTTP请求翻译成目标模型服务商期望的格式再把响应翻译回OpenAI格式返回给客户端。2.1 请求进来后认证、路由、翻译、转发、回传整个流转过程可以分成五步。第一步是认证。客户端带着一个虚拟密钥访问litellm的/chat/completions接口网关先校验这个密钥是否有效、有没有超出配额、是否被允许访问请求中的模型名。第二步是路由。litellm根据请求体里的model字段在配置的model_list里找到对应条目。比如客户端传的是model: gpt-4o网关发现这个名称被映射到了OpenAI的真实模型如果客户端传的是model: claude-3-5-sonnet网关就把它映射到Anthropic对应的模型。第三步是翻译。这是最核心的一步。litellm拿到OpenAI格式的请求体后会根据目标服务商的SDK规范把参数名和消息结构重新组装。比如OpenAI的messages数组里包含role和content而某些服务商要求系统提示词放在单独的字段里或者对max_tokens的命名不一致这些转换都在这一步完成。第四步是转发。litellm调用目标服务商的原生SDK或者HTTP接口把请求发出去同时处理鉴权、重试、超时、限流等网络细节。第五步是回传。litellm拿到上游响应后把内容重新包装成OpenAI的choices结构同时记录本次请求的token用量、延迟、费用等元数据最后返回给客户端。对上层业务而言整个网关是透明的。你发出去的请求和收到的响应看起来和直连OpenAI没有任何区别这就是它能无缝替换的原因。2.2 不只是转发参数差异和单位差异才是麻烦所在网关做得对不对关键就看“翻译”够不够细。我举几个实际存在的差异点你感受一下。消息结构上OpenAI统一用messages数组表达对话历史而一些服务商对系统提示词、多轮历史、图片内容的字段要求完全不同。litellm需要把这些结构映射过去有些模型不支持图片时还会自动丢弃或报错这都需要配置控制。超参命名上max_tokens这个词在不同服务商里五花八门有的叫max_tokens_to_sample有的叫max_new_tokens有的放在generation_config里。还有temperature的取值范围有的服务商支持0到2有的只允许0到1。网关要负责把OpenAI的通用参数翻译成目标服务商的合法范围。token统计和计价上OpenAI按prompt_tokens和completion_tokens返回其他服务商字段名不一样。litellm在记录日志时会统一归一化并根据你配置的单价估算费用。这也是它能做成本追踪的基础。说白了litellm替你把各家API的“方言”翻译成了普通话。如果你只在代码层做封装这些差异迟早会漏到业务代码里。3. 快速跑通Docker部署一个最小可用网关理论说那么多不如直接跑起来。这一节我给出一个最小可用的部署方案你照着做十分钟内就能通过网关调用真实模型。3.1 先写好config.yaml理解model_list的映射关系litellm的网关配置核心是一个YAML文件里面最重要的就是model_list。它做的事情非常直观给上游每个模型起一个客户端可见的名字再指定上游的真实模型标识和API Key。下面是一个同时接入OpenAI、Anthropic和本地Ollama模型的配置示例model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5-sonnet litellm_params: model: anthropic/claude-3-5-sonnet-20240620 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-llama3 litellm_params: model: ollama/llama3 api_base: http://localhost:11434这里有几个关键点要说明。model_name是客户端调用时使用的名字你可以随意命名不必和上游真实模型名一致。比如你想让业务方无感切换可以统一叫chat然后在配置里把这个名字映射到不同真实模型。litellm_params.model是上游模型标识。OpenAI系模型直接写模型ID非OpenAI系的模型前面要加provider前缀比如anthropic/、ollama/、bedrock/、vertex_ai/、vllm/。这个前缀告诉litellm该用哪套翻译逻辑。api_key推荐写成os.environ/环境变量名的形式让litellm从进程环境变量里读取避免密钥明文写进配置文件。如果接的是本地vLLM服务写法类似- model_name: local-qwen litellm_params: model: openai/qwen2.5-7b-instruct api_base: http://localhost:8000/v1 api_key: dummy注意这里用了openai/前缀因为vLLM对外暴露的是OpenAI兼容接口litellm会把请求直接转发过去。3.2 启动容器并验证接口配置写好后用Docker启动网关是最省事的方式docker run -d \ --name litellm-gateway \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ -e OPENAI_API_KEYsk-xxxx \ -e ANTHROPIC_API_KEYsk-ant-xxxx \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml生产环境不要用latest后缀建议固定镜像版本号避免上游更新引入不兼容变化。本地试验阶段用main-latest倒是无妨。启动后先看健康检查接口curl http://localhost:4000/health/liveliness一切正常后用OpenAI SDK风格调用一次对话式接口curl http://localhost:4000/v1/chat/completions \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 你好用一句话介绍你自己}] }这里你可能注意到了我填的Bearer令牌是sk-1234。默认情况下litellm需要一个master_key也就是管理员主密钥。如果你没配置网关启动时会打印一个随机生成的临时主密钥上面这个请求里的sk-1234需要换成你自己的主密钥。如果你想禁用主密钥校验可以在配置里加上general_settings: master_key: sk-1234然后把上面的请求头原样发出去即可。生产环境务必换一个足够复杂的master_key并妥善保管。3.3 管理界面与模型测试litellm自带一个Web管理界面默认路由是/ui。打开http://localhost:4000/ui用管理员账号登录后你可以直观地看到已配置的模型列表、虚拟密钥列表、请求日志和成本数据还能在界面上直接创建新的虚拟密钥、设置模型访问权限。初次跑通时建议先在UI的“测试”页面里选择一个模型输入一段prompt确认能拿到正常回复。这一步通过后再往下游接业务代码排查问题时会省力很多。4. 接入现有代码一个base_url能解决多少事网关部署好之后最爽的事情来了你现有的OpenAI调用代码几乎不用改。4.1 用OpenAI SDK切换base_url的用法如果你已经在用OpenAI官方的Python SDK切换方式就一行代码的事from openai import OpenAI client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-1234 ) response client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: 你是一个智能助手}, {role: user, content: 介绍一下litellm的用途} ], streamTrue ) for chunk in response: print(chunk.choices[0].delta.content or , end)这里面有个特别容易忽略的点base_url末尾要带上/v1因为litellm对外暴露的OpenAI兼容路由挂在/v1下。有些同学只填了http://localhost:4000结果请求一直404排查半天才发现是路径问题。流式响应、异步调用、工具调用functions/tools这些OpenAI SDK的能力都能透传。因为litellm返回的响应结构本身就是OpenAI格式SDK解析起来零压力。如果你原本用的是别的服务商的官方SDK那就需要把请求改造成OpenAI格式再指向网关。这也是我建议新项目直接按照OpenAI规范写调用层的原因——只要一次改造后期换成任何模型都不再动业务代码。4.2 给团队下发虚拟密钥和模型权限多个成员或服务要访问网关时不应该让他们直接使用master_key正确的做法是通过管理员接口创建虚拟密钥。curl http://localhost:4000/key/generate \ -H Authorization: Bearer sk-1234 \ -H Content-Type: application/json \ -d { models: [gpt-4o, claude-3-5-sonnet], max_budget: 100, expires: 2025-12-31T23:59:59 }返回值里会有一个key字段这就是发给团队成员使用的虚拟密钥。它只允许访问models列表里指定的模型且在max_budget花完后自动失效。这样团队里每个成员都有自己的密钥谁的请求超了预算、谁的调用异常日志里一查便知。如果不想用命令行直接在UI的“Virtual Keys”页面点几下也能生成同样的密钥。5. 生产环境配置清单密钥、限流、成本与高可用本地跑通一个网关只是开始真要放到生产环境还要考虑负载均衡、故障转移、成本控制和数据安全这几个问题。这一节我给出一份可以直接参考的配置清单。5.1 多上游负载均衡与故障转移一个非常实用的能力是同一个model_name可以配置多个上游模型litellm会自动做负载均衡并在某个上游报错时切换到另一个。model_list: - model_name: chat litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY model_info: mode: completion - model_name: chat litellm_params: model: anthropic/claude-3-5-sonnet-20240620 api_key: os.environ/ANTHROPIC_API_KEY配置里两个条目的model_name都叫chat业务方请求时只写model: chat网关会按策略自动把流量分给OpenAI或Anthropic。默认策略是简单轮询也可以在router_settings里调整router_settings: routing_strategy: simple-shuffle model_group_failover: true cooldown_time: 300model_group_failover开启后如果某个上游连续失败它会被临时标记为冷却状态后续请求自动打到健康的上游冷却时间结束后再恢复。cooldown_time300表示失败上游冷却5分钟。这套机制对“降级容灾”特别有用。生产环境可以把主模型和备用模型配成同一个model_name主模型限流或宕机时业务代码一行不用改流量自动切换。5.2 成本统计、预算限制与token治理litellm的管理界面里自带请求日志和成本汇总支持按虚拟密钥、按模型、按时间维度筛选。这是我最常用的功能之一。团队里谁调了什么模型、花了多少钱打开UI就能看到不需要再自己写日志统计。如果你想在网关层做硬性预算控制可以在general_settings里配置general_settings: master_key: sk-1234 max_budget: 500 budget_duration: 30d max_parallel_requests: 100这会限制整个网关每30天最多消耗500美元超出后拒绝新请求。更细粒度的预算则在生成虚拟密钥时设置每个密钥单独设限额。有一点要提醒litellm的成本统计依赖你在配置里给每个模型设置的单价。如果使用公共云模型的默认映射单价通常是内置的如果是自建模型或小众模型需要手动在model_info里补充计价参数否则成本统计可能偏差很大。这个我在后面踩坑部分还会详细说。5.3 缓存与速率限制生产环境还有一个高频需求是缓存。很多业务场景里相似的重读请求会反复打同一个模型白白消耗token。litellm支持在网关层做响应缓存litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379开启后命中缓存的请求会直接返回结果不再调用上游模型。小规模部署用内存缓存就够了多实例部署建议用Redis避免不同实例缓存不一致。速率限制也是生产环境必需品。litellm支持按虚拟密钥限制每分钟请求数、每秒token数等防止某个调用方把上游配额打满影响其他业务。general_settings: max_parallel_requests: 50也可以在每个虚拟密钥创建的时候指定rpm_limit和tpm_limit对调用方做隔离限流。5.4 安全边界内网部署、关闭调试日志、TLS有几点安全配置容易被忽略我单独拉出来说。第一网关会明文看到所有发给它的请求和响应包括prompt内容和模型输出。如果业务数据敏感网关必须部署在可信内网前面再挂一层公司的API网关做统一认证不要把litellm直接暴露到公网。第二生产环境务必关闭调试模式。litellm开启debug后会把完整的请求头、响应体打到日志里API Key也会跟着泄露。配置里不要设置debug: true日志级别保持默认。第三网关和上游服务商之间的通信默认走TLS这是安全的。但如果你通过HTTP方式访问网关网络链路上的数据就是明文内网通常可以接受跨公网必须加TLS。第四定期查看访问日志。litellm的日志支持按密钥、IP审计调用记录发现异常调用模式时能快速定位到具体密钥然后一键禁用。6. 实际踩坑记录与绕过办法工具好不好用只有踩过坑才知道。这一节我把自己实际遇到过的问题列出来每条都给出排查链路和解决方案希望对你有帮助。6.1 模型名不存在的报错与服务端配置不一致有次一个项目组来问我为什么调用时报“model not found”。我一看他们的请求model字段写的是gpt-3.5-turbo但网关注册的model_name是gpt-4o和claude-3-5-sonnet。解决方案很简单要么让业务方改请求里的模型名要么在model_list里给现有模型再加一个model_name别名。网关的模型名映射是精确匹配的不存在模糊匹配。建议在接入时就和业务方约定好模型命名规范并且把客户端默认模型名直接写成一个通用别名比如default-chat后续切换时只改网关配置。6.2 长推理场景下的超时和流式断开另一个高频问题是超时。默认情况下litellm对上游请求有内置超时时间如果模型推理时间较长响应可能被网关中止表现就是客户端收到异常中断。排查时可以先看网关日志里有没有timeout关键字的报错。解决办法是在config.yaml里配置一个足够宽松的超时litellm_settings: request_timeout: 600但光改这里还不够客户端SDK也有自己的超时时间特别是流式请求。OpenAI SDK默认的timeout值是600秒如果你的场景是长文本生成加上网络环境复杂建议显式调大client OpenAI( base_urlhttp://localhost:4000/v1, api_keysk-1234, timeout600, max_retries2 )6.3 debug日志泄漏API Key之前有一次在测试环境排查问题打开了debug模式结果在stdout日志里直接看到了完整的请求头里面带着各家上游的API Key。这个问题一旦出现在生产环境密钥基本等于裸奔。排查链路一般是确认config里有没有开debug查看日志输出文件里是否存在Authorization头然后立刻关闭debug并轮换所有已泄漏的密钥。建议生产环境直接禁用debug所有日志输出到统一日志系统并做关键词脱敏。6.4 本地模型api_base路径写错导致返回异常接入本地vLLM服务时api_base必须带上/v1路径后缀。比如vLLM服务跑在http://localhost:8000配置里要写http://localhost:8000/v1。漏掉/v1时请求会转发到一个不存在的路由返回404或奇怪的HTML错误。Ollama的配置也有类似问题。Ollama原生接口路径是/api/chat但litellm接入Ollama时用的api_base一般写http://localhost:11434不需要额外路径。反正记住一个原则不同上游对api_base的接受程度不一样接之前先看一眼官方示例别凭感觉填。6.5 成本统计偏差必须显式配置单价如果你发现管理界面的成本数字和上游账单对不上大概率是模型单价配置的问题。公共云模型内置了官方单价表但新模型上线、价格调整、自建模型接入时litellm有可能还没有对应的计价信息。解决办法是在模型配置里显式加上计价参数model_list: - model_name: local-qwen litellm_params: model: openai/qwen2.5-7b-instruct api_base: http://localhost:8000/v1 api_key: dummy model_info: input_cost_per_token: 0.000001 output_cost_per_token: 0.000002 mode: chat这样网关统计成本时就会按你给的单价计算。自建模型按实际GPU成本估算就好云端模型按服务商官网价格换算成“每token美元”填进去。7. 我的最后一点建议用litellm做模型网关我自己最顺手的用法是把它当成公司内部的“模型接入层”。所有业务系统只认一个base_url、一个虚拟密钥模型选型、版本切换、成本统计、密钥治理全部收敛到网关配置层面。上线新模型时先跑通配置再小范围放量稳定后切流量全程不碰业务代码。如果你正在纠结多模型接入问题我的建议是先别急着写抽象层先把litellm这类网关部署起来用最小流量跑一两周看看稳定性和成本数据是否符合预期。实际用下来你会发现它解决的不只是“换模型少改代码”这一个问题连同密钥管理、预算控制、调用审计这些麻烦事也一并有了落脚点。
