企业官网建设流程全解析

litellm 这个项目，我第一次接触是在给团队做内部AI能力底座选型的时候。当时我们同时接了五六家大模型厂商的API，每家token计算方式不一样，鉴权方式不一样，请求格式更是各有各的脾气，联调阶段光是写适配层就写了将近一千行代码，后面维护起来真的头疼。后来在某次技术交流会上一哥们儿提到litellm，说它就是干这个的——统一封装、统一入口、统一计费口径，我回来花了半天时间把服务跑起来，之后那几百行适配代码全删了，所有业务方只需要面对一个OpenAI格式的接口。今天就把我从选型、部署到实际生产环境踩坑的完整经验整理出来。

1. litellm本质上解决了什么问题

1.1 多模型接入的“翻译层”思维

先说个最直观的类比。你公司要给几百个员工发通知，邮件、短信、IM各有各的发送协议，你不可能让每个业务系统自己去对接这三种通道，而是会做一个“消息中台”，统一收件口，再由中台去适配下游各家。litellm就是大模型世界的这个“消息中台”。

它对外暴露一个OpenAI风格兼容的接口，业务方的代码只需要按照这个统一格式来请求；至于后端到底调用的是哪家厂商、什么模型、走什么协议、怎么鉴权、计费规则是什么，全部由litellm来处理。也就是说，业务方不需要关心自己用的到底是A厂的大模型还是B厂的开源模型，只要会发OpenAI格式的POST请求，就能用上所有背后的模型生态。

实际项目里这一点价值非常大。我们当时后端用的是Python的openai官方SDK，前端页面配合一套简单的前端代理。引入litellm之后，前端和后端一行代码没改，只是把base_url从真实厂商地址换成litellm服务地址，就能在多个模型之间来回切换。业务侧完全没有感知，这对快速试错和模型选型太重要了。

1.2 核心能力全景：不只是代理转发

很多人以为litellm就是一个转发代理，那真是小看它了。完整的litellm具备下面几层能力：

• 协议统一层：把不同的厂商API格式全部转成OpenAI兼容格式，降低接入成本
• 密钥管理层：一个主密钥进，多个下游密钥出，业务方不直接接触各厂商密钥，密钥安全可控
• 路由策略层：支持模型级路由，同一模型背后可以配置多个上游提供商，自动做负载均衡和故障转移
• 预算控制层：按token、按项目、按API Key维度做配额限制和成本追踪
• 可观测性层：记录每一次请求的延迟、token消耗、成本花费，提供审计日志
• 缓存加速层：对相同请求做语义缓存，能显著降低重复请求的成本和延迟

这些能力不是堆功能玩票，而是真实生产环境里必然要面对的刚需。比如密钥管理，如果你有几十个业务方要接入模型，你不可能把厂商的API密钥直接给到每个团队，风险太大。litellm统一收口之后，每个业务方拿一个独立生成的key，权限、配额、成本都能独立控制，出问题也好追溯。

2. 环境搭建与核心配置拆解

2.1 部署方式选择

litellm的部署方式非常灵活，但不同方式的适用场景差别还是挺大的，我把自己实测过的几种方式整理在下面：

我个人的建议是：如果只是自己写脚本玩，pip安装完全够了；如果是给一个团队用，起步就用Docker Compose配合PostgreSQL方案。别等出问题了再迁移数据，litellm的很多统计数据都存在数据库里，换存储方案就得做数据迁移，比一开始就规划好麻烦得多。

2.2 最简配置：从零到能跑通第一遍请求

先聊最小可用配置。假设你现在只有一家厂商的API密钥，想快速让litellm跑起来，验证一下链路是否通畅。

安装这步没什么好说的，Python 3.9以上，直接：

pip install 'litellm[proxy]'

装完之后，建议先建一个工作目录，用一份最基本的配置文件起步：

model_list: - model_name: gpt-3.5-equivalent litellm_params: model: openai/gpt-3.5-turbo api_key: os.environ/OPENAI_KEY

注意这里的model_name是你对外暴露的名字，可以由你自己定义，而litellm_params里的model字段才是真正传给你上游厂商的模型名。这个设计意味着你可以在litellm这一层做模型映射，比如把市面上各种“XX-3.5同级别模型”统一映射成对外名称，下游换了实际厂商，你的业务方毫无感知。

启动服务：

litellm --config ./config.yaml --port 4000

然后你用任意支持OpenAI接口的SDK，把base_url指向http://localhost:4000，请求你自定义的模型名，就能拿到真实模型返回的结果了。这一步能通，整个架构的骨架就有了。

2.3 环境变量与密钥注入的讲究

配置里我写了os.environ/OPENAI_KEY这种写法，这是litellm官方推荐的一种变量占位方式，意思是这个key从环境变量里读取。这样做的好处是配置文件和密钥分离，你完全可以把config.yaml提交到Git仓库，而密钥只在部署服务器的环境变量里配置，避免通过配置文件把密钥散播出去。

实际操作中，我习惯把下游所有厂商的密钥放在一个.env文件里统一管理：

OPENAI_API_KEY=sk-xxxx ANTHROPIC_API_KEY=sk-ant-xxxx AZURE_OPENAI_KEY=xxxx AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com/

然后在启动命令前通过dotenv加载：

export $(cat .env | xargs) && litellm --config ./config.yaml

有一点要特别提醒：os.environ/这个语法只适用于配置文件里的api_key字段，它的机制是服务启动时去读取环境变量的值。如果你改了环境变量，需要重启litellm才能生效，不是热加载的。很多第一次用的人在这里踩坑，改完环境变量不重启，半天排查不到问题。

3. 多模型接入与路由策略实战

3.1 多厂家模型如何统一接入

到了真正需要接多个厂家模型的时候，配置文件就复杂起来了。下面我给出一个比较典型的配置片段，包含三家厂商的不同模型，这是我在生产环境里实际跑过的结构：

model_list: - model_name: chat-main litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY rpm: 300 - model_name: chat-main litellm_params: model: anthropic/claude-3.5-sonnet api_key: os.environ/ANTHROPIC_API_KEY rpm: 200 - model_name: embed-zh litellm_params: model: openai/text-embedding-3-small api_key: os.environ/OPENAI_API_KEY - model_name: llama-local litellm_params: model: ollama_chat/llama3 api_base: http://localhost:11434

注意模型名的前缀规则。openai/、anthropic/、ollama_chat/这些都是litellm的provider前缀，告诉litellm应该用哪套适配协议去请求上游。前缀和api_base的组合非常灵活，比如你可以用openai/前缀配一个任意兼容OpenAI协议的私有化部署地址，这样任何一套兼容OpenAI格式的推理服务都能直接接入。

这里有个容易踩的坑：model_name重名不是错误，反而是实现故障转移和负载均衡的关键。上面配置里chat-main被定义了两个条目，分别指向不同厂商，litellm收到对chat-main的请求时，会根据自己的负载均衡策略在这两个条目之间分发。如果其中一家超时或者返回错误，litellm还能尝试用另一个条目做容灾。这一点在业务高峰期的可靠性保障上非常管用。

3.2 基于权重的负载均衡配置

litellm支持在同名模型下设置权重，控制请求分发的比例。这个机制在做灰度的时候很好用。比如你已经跑了半年A厂模型，现在想逐步把流量切给B厂的新模型，你不需要改业务代码，只需要调整配置权重：

model_list: - model_name: chat-main litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY weight: 30 - model_name: chat-main litellm_params: model: anthropic/claude-3.5-sonnet api_key: os.environ/ANTHROPIC_API_KEY weight: 70

weight字段表示相对权重，litellm内部是按权重比例做随机分发。如果A厂质量不稳定，你想快速切回老路，把weight改小甚至改成0即可，改完配置后发送一个/reload接口请求就能让配置在运行中生效，不需要重启进程。

需要注意的是，权重均衡主要关注的是“请求次数”的分配比例，不保证“token量”的比例。有些模型上下文窗口大，一次调用消耗的token可能是另一个模型的五倍，如果你的场景对成本很敏感，建议配合后面的预算控制功能一起用。

3.3 自定义路由策略与预算控制

除了简单的负载均衡，litellm还有一个比较强大的能力：基于用户、团队、项目维度的路由和配额控制。它在底层维护了一份key的体系，你可以为不同的业务方创建不同功能的虚拟key：

• 有的key只能调用chat模型，不允许调用embedding模型
• 有的key每月最多消耗100美元，超出后直接拒绝请求
• 有的key只能从固定IP段访问

这套能力相当实用。我们当时有个数据团队，需要一个key批量处理历史数据，我们就把key的预算设成50美元每自然月，同时把这个key的并发上限调低，防止数据任务把在线业务的算力全占了。litellm在请求到达时会先做预算检查，超了就返回明确的错误码，业务方能快速感知并处理。

具体创建一个受控key，可以通过管理接口完成，也可以直接在数据库里开一个用户然后生成虚拟key。生产环境建议不要用默认的master key对外发请求，而是每个人或每个业务组一把独立的key，审计和限流都清晰很多。

4. 代理服务进阶：缓存、重试与成本观测

4.1 语义缓存要不要开？怎么调参

litellm的缓存是我特别喜欢的一个功能，但也建议理性使用。它的缓存不是简单的文本匹配，而是把请求做向量化之后做语义相似度比较。具体原理是：第一次拿到用户问题，算出一个embedding向量，存储起来；后续进来的问题也算一个向量，如果和之前的问题相似度超过阈值，就直接返回之前的answer，而不再去调用大模型厂商。

这个功能对很多客服问答场景特别有价值。我们有个内部知识库问答机器人，用户问的问题高度相似，大约三成请求都是重复的。开缓存之后，平均响应时间下降了60%左右，成本也省了将近两成。

配置缓存有两步，第一步在config.yaml里指定缓存类型：

litellm_settings: cache: true cache_params: type: redis host: localhost port: 6379 namespace: litellm_cache ttl: 86400

第二步在请求时带上缓存开关参数。如果你用的SDK是OpenAI风格，可以在extra_body里传：

from openai import OpenAI client = OpenAI(base_url="http://localhost:4000", api_key="sk-litellm-master-key") resp = client.chat.completions.create( model="chat-main", messages=[{"role": "user", "content": "什么是负载均衡"}], extra_body={"caching": True} )

不建议无脑全开缓存，特别是对实时性要求极高的场景，或者用户问题明确标注了私有化、定制化等字眼的场景。语义缓存是按向量相似度匹配的，意味着“相似的”也可能是“不相同的”，开缓存会带来答非所问的风险。我一般只在知识库类、FAQ类场景开，代码生成、实时分析类场景全部走实时请求。

4.2 重试与超时参数的血泪教训

litellm默认的重试次数可能不够你生产环境的稳定性要求。大模型厂商的服务经常因为高并发返回429限流或者500内部错误，如果litellm不做重试，错误就直接穿透给业务方了。

配置重试需要理解它的分层设计。litellm支持每次请求级的重试参数，也支持在litellm_settings里设置全局默认值。我实测下来比较稳的配置是：

litellm_settings: retry: true num_retries: 3 retry_after: 1 request_timeout: 120 fallbacks: [{"gpt-4o": ["claude-3.5-sonnet"]}]

num_retries: 3表示重试3次，重试间隔初始值1秒，按退避策略递增。request_timeout: 120表示单次请求最长等待120秒，超过就判定为超时。对于长文本生成任务，这个超时时间建议别设太短，有些模型思考链路长，输出很慢，60秒根本不够用。

fallbacks配置表示：如果模型A连续失败，自动降级到模型B。我踩过一个坑，就是重试次数设太大会导致整体响应时间被拉得很长。一个请求如果全部打满重试，最坏情况要等接近10分钟才返回失败，这个延迟对在线业务来说是不可接受的。所以现在的经验是：在线场景重试次数控制在2-3次，宁可快速失败，也不要无限重试拖垮体验。

4.3 成本追踪：别让你的账单失控

成本追踪是litellm在生产环境里绝对不能省的一块配置。它的底层机制是对每次请求做token统计，结合每一家的计费模型算出成本，然后按虚拟key、用户、团队等维度汇总。你可以通过管理后台看实时数据，也可以把数据同步到Prometheus做监控告警。

我倾向于在任务级别就对成本做控制。比如某个数据分析任务，我可以在请求里加上max_tokens和预算限制参数，超出就立刻中断生成，宁可结果不完整也不能让费用失控。

litellm的日志表里，每次请求都有prompt_tokens、completion_tokens、total_cost这几个关键字段，配合查询面板可以按小时聚合成本。我习惯每条线上请求都打印一个带有请求ID的日志，出了成本问题直接按请求ID反查明细，定位很快。

5. 常见问题与排查技巧实录

5.1 模型名称带前缀报错的排查

很多初次用litellm的人，在配置的时候容易犯一个低级错误，把模型名写成本来不带前缀的格式。比如上游是OpenAI的模型，配置里写成gpt-4o而没有openai/前缀。这个问题看起来小，但报错时很有迷惑性，错误提示会告诉你“model not found”，让你误以为是模型不存在，实际上只是缺少provider前缀。

另外要检查你用的模型名到底支不支持这个前缀对应的协议。有些模型已经下架或者改名了，比如某个老版本模型已经退役，你配置里还写着它，请求就会一直报错。这种问题需要在litellm的/model/info接口查看当前所有可用的模型列表，确认模型是否在你使用的版本和配置中真实存在。

5.2 环境变量不生效的几种可能

这个是我最有感触的一块，之前调试了一个下午都搞不定，后来发现是启动方式的问题。如果你用export的方式设置环境变量，但启动litellm的终端和设置环境变量的终端不是同一个，环境变量根本不会传递过去。用systemd或Docker启动服务的话，环境变量的作用域就更是有讲究。

再一个容易忽略的问题是：litellm读取环境变量的时机是启动时，如果你在config.yaml里写了os.environ/XX，但XX环境变量在启动那一刻还没设置好，litellm会在配置校验阶段直接报错或跳过这个key。我建议在启动命令前做一次环境变量检查，用printenv看看关键变量是否都在，再启动服务。

最后注意：某些部署方式下，进程守护工具会把无效的环境变量给清理掉。比如systemd的EnvironmentFile语法如果文件里有个别行格式不对，整个文件都会解析失败，坑得很。

5.3 请求超时与限流的定向排查

遇到请求超时，先别急着调大timeout参数，要分清楚是哪个环节慢。litellm的/spend/logs接口记录了每一次请求的耗时明细，包括连接建立时间、模型响应时间、token处理时间。如果连接时间很长，多半是网络链路问题；如果模型响应时间很长，大概率是上游本身处理慢。

对于限流问题，你要分清是litellm对业务方的限流，还是上游对litellm的限流。前者通常是在业务方key上配置了rpm、tpm限制，返回的错误码会带着rate_limit_exceeded字样；后者是上游厂商因为并发过高拒绝服务，litellm会在日志里记录上游返回的状态码。搞清楚是哪个方向在限流，才能对症下药。

5.4 一个小技巧：定期清理历史日志

litellm的日志表如果长期不清理会非常大。我们生产环境一天大概产生几十万条日志，两三个月下来数据库表就能涨到几十GB，查询和统计明显变慢。建议写一个定时任务，定期归档三个月前的日志到冷存储，线上只保留最近三个月的热数据。

数据库连接池参数也要注意。默认的连接数不一定够你高并发场景使用，建议在配置里显式调大连接池上限，并设置空闲连接回收时间，不然高峰期数据库连接容易被耗尽。

6. 我从实际项目中总结的几个心得

顺着前面这些细节，再说点我自己的体会。

litellm这个项目，最漂亮的不是它“能接多少家模型”，而是它把“接入多家模型”这件事从混乱的适配工作变成了一张可配置的表。正因为这样，团队的技术选型空间变得非常大。以前你要绑定一家厂商做深度适配，现在你只是在litellm配置里加一段yaml，新模型就能以同样的接口方式上线。这种松耦合的架构，对于快速试错、模型选型、成本控制都有很实际的意义。

第二个体会是，litellm虽然降低了接入门槛，但生产化的问题还是要靠团队自己做好运维基建。比如密钥管理，不是部署了litellm就万事大吉，你仍然需要建立密钥申请审批流程；成本控制也一样，litellm只是提供了工具，你还是需要设好每一条业务链路的预算阈值并持续观察。

最后再讲一个小经验。建议你在litellm前面再加一层自己的业务网关，做一些业务级参数校验、用户身份识别、上下文组装之类的事情。litellm本身是通用LLM网关，不该塞太多业务逻辑进去，保持它的轻薄，后续升级和维护都会省心很多。我现在维护的这套架构，litellm只管模型统一接入和成本控制，所有业务规则基本都是上层处理，已经稳定跑了大半年，基本没在这层出过幺蛾子。