企业官网建设流程全解析

Litellm这名字，第一次看到的时候，我还以为是个轻量级模型训练框架。真正用起来才发现，人家干的是网关的活——把几十家模型服务的API全部“翻译”成同一种格式，让团队接入大模型就像调用一个统一接口那样简单。这篇文章我就想把litellm从定位、核心功能到自托管部署，完整地拆一遍，尽量把那些踩过的坑和配置细节都写清楚。

今年几乎每个研发团队都在接大模型，但接的过程远比想象中痛苦。今天换一个模型服务商，明天换一套鉴权方式，后天又要给不同业务线配不同的权限和预算。明明只是调个API，硬生生搞成了中间件研发。litellm就是在这个时候出现的。它把常见的模型服务统一成同一套请求格式，提供代理转发、密钥管理、成本追踪、负载均衡这些能力，相当于在应用和模型之间加了一层标准化网关。这篇文章适合正在做模型接入的技术负责人、后端开发、算法工程和运维同学，尤其适合那些手上有多个模型服务、需要统一管理的团队。

1. 为什么需要统一网关：多模型混用场景下的真实痛点

1.1 各模型服务接口不统一的麻烦

先说说没有网关之前我遇到的实际问题。当时团队同时用了两个闭源模型服务商，还自建了一套开源的模型推理服务。三套接口，三种鉴权方式，三份SDK依赖，代码里到处是分支判断。有一次一个模型服务临时调整了返回格式，我们的解析逻辑直接崩了，排查了半天才发现是上游变更。

如果只是接口格式不统一，咬咬牙写个适配层也就算了。真正麻烦的是业务侧的诉求，不同业务线要用不同模型，有的看重效果、有的看重成本、有的对延迟敏感。我们没法简单地把某个模型服务商写死在代码里，因为模型效果和价格都在快速变化，今天效果最好的模型，下周可能就被另一个替代了。这意味着路由、切换、灰度这些逻辑都要在应用层实现，工作量非常大。

还有一个更痛的场景是成本控制。模型API都是按token收费的，但不同服务商的计费口径不一致，有的按输入输出分开计，有的直接给一个综合单价。月底对账的时候，财务给的账单和研发记录的对不上，光核对就花了好几天。密钥管理也做得稀烂：测试环境用的key和生产环境一样，部分同事离职后权限没有及时回收，造成很多安全隐患。

1.2 litellm的核心定位：解决“接口统一”和“治理统一”两层问题

litellm解决的其实是我上面说的所有问题。它的核心思路是做一个中间层代理，所有模型请求都发到litellm，由litellm负责转发到对应的模型服务商。对应用来说，永远只需要对接litellm一个地址，请求格式统一；对模型服务商来说，litellm就是一个普通客户端，密钥都保存在litellm这一层。

这个设计第一眼看上去很简单，但实际带来的收益非常大。首先，应用代码里不再需要耦合某个具体的模型服务商，切换模型只是改配置的事情。其次，密钥从应用侧收归到了网关侧，应用不再直接持有上游密钥，而是使用litellm生成的虚拟key，方便做权限控制和撤销。最后，所有请求都经过litellm，自然就能在上面做计费统计、速率限制、缓存、灰度路由这些统一治理。

我把litellm理解为“模型接入层的操作系统”。就像操作系统统一管理硬件资源一样，litellm统一管理所有模型服务的通信、权限、成本和稳定性。团队接入新模型的时间从几周缩短到几个小时，业务方只需要提需求说要用哪个模型，运维在litellm后台配置一下就能生效。

2. litellm核心能力拆解：路由、密钥、成本一个都不少

2.1 模型路由、重试与负载均衡的实现机制

litellm的路由能力很符合实际生产需要。它支持的模型服务商非常广泛，闭源的、开源的、自建的都有对应的接入方式。在litellm里，每个模型都有一个全局唯一的模型名，通常结构是“服务商/模型名”，但也可以自定义别名。应用调用时只认这个别名，完全不用关心背后是哪个服务商。

路由可以配策略。最简单的模式是固定路由，指定某个请求只走某个模型。更实用的模式是fallback，比如配置首选使用服务商A的模型，当A的调用失败、超时或者触发限流时，自动切换去调用服务商B的同级别模型。这功能在生产环境特别管用，因为模型服务商不可能做到100%可用，偶尔的限流和5xx错误很常见。以前需要应用自己做故障转移，现在直接在litellm配置里声明就行。

负载均衡也内置了，支持按权重分发和按优先级分发。比如你有多个不同规格的实例，或者同时买了几家服务，可以通过权重控制流量分配比例。litellm还支持健康检查，它会记录每个模型最近的错误率和延迟情况，自动把流量切到更健康的实例上。这些能力单独做出来都要写不少代码，litellm用配置就能完成。

2.2 虚拟密钥、多租户隔离与权限控制

密钥管理是litellm让人越用越舒服的功能。上游模型服务的密钥统一配置在litellm环境变量或者配置文件中，不对业务方暴露。业务方需要接入时，在litellm后台生成一个虚拟key，这个key对应特定的模型权限、速率限制和预算上限。

一个典型的场景是这样的：A部门要使用某个模型做客服机器人，B部门要使用同一个模型做内容分析。两个部门的虚拟key是独立的，可以分别限制每日调用量、每分钟请求数、每月预算，还能设置过期时间。如果B部门某个同学离职了，直接在后台把对应的key禁用掉，而不会再影响其他部门。相比以前大家共用一把key，这个管控粒度是一个质的提升。

多租户隔离在litellm里做得很自然。你可以在配置里定义不同的团队或用户，每个虚拟key都归属于某个团队。所有请求日志、token消耗、成本数据都会自动打上团队的标签。这样月底出成本报表时，按团队、按项目、按key一拉就出来了，再也不用拿Excel对着账单手工整理了。

提示：虚拟key的生成依赖master key。部署时一定要保管好master key和salt key，丢失了会导致已有虚拟key无法解析，所有客户端都要重新生成。

2.3 成本追踪、速率限制与预算控制怎么做

成本追踪是litellm被很多团队选中的直接原因。它会对每一次请求记录三样东西：输入token数、输出token数、使用的模型单价。把这两个数字乘起来，就得到了单次请求的成本。litellm支持为每个模型配置单价，每个服务商的价格不一样，就在模型配置里逐个登记。

预算控制可以做到用户级和key级。可以给一个虚拟key设置每月1000元的预算上限，当消耗达到这个额度时，litellm会直接拒绝新的请求，返回预算超限的错误。这个能力对内部工具型应用尤其重要，之前经常出现某个人写了个脚本，不小心死循环调用模型，一天跑掉几千块。有了预算限制之后，这类事故最多损失的就是单个key的限额。

速率限制支持每分钟请求数（RPM）和每分钟token数（TPM）两个维度。限制可以作用在全局、用户、key三个层面。设置的时候建议先看模型服务商本身的限流规格，把litellm的限流值配得比上游略低一点，这样litellm就能在应用侧提前拦掉超限请求，避免打到上游触发服务商的限流惩罚。

litellm还有一个缓存功能值得单独说。它可以缓存请求的响应结果，支持按prompt的精确匹配，也支持语义相似度匹配。对于客服问答、知识库检索这类请求重复度高的场景，命中缓存能省掉大量token成本。缓存可以放在内存里，也可以放在Redis里，生产环境建议用Redis，一方面多实例共享缓存，另一方面重启不丢数据。

3. 自托管部署实操：从零搭建一套可用的代理网关

3.1 组件准备：选择一个最稳的部署方式

litellm最推荐的部署方式是用Docker Compose拉起一套服务。一个最小的生产部署需要四个组件：litellm主服务、PostgreSQL数据库、Redis缓存、以及一个用于存放配置文件的目录。如果只是在本地跑着玩，可以不接Redis，但连接数据库是必须的，因为虚拟key、预算、日志这些数据都存在数据库里。

我在选择组件时花了一些时间对比。PostgreSQL是必须的吗？litellm也支持SQLite，但只适合单机测试，生产环境多个实例并发写SQLite会出问题，所以直接上PostgreSQL更省心。Redis也不是可选项，生产环境强烈建议接上。除了缓存之外，限流计数、请求追踪也需要用到Redis，如果缺失，部分功能会退化成不好用的形态。

数据库连接串的格式大概是postgresql://用户名:密码@地址:5432/数据库名，这里要注意密码里有特殊字符的话，需要做URL编码。Redis连接串格式则是redis://地址:6379，如果Redis设置了密码，同样需要体现在连接串里。

3.2 配置文件逐行讲解：模型、路由与密钥参数

litellm的配置核心是一个YAML文件，官方通常叫config.yaml。下面是一份我在测试环境常用配置的结构说明，每类配置的关键字段我都标注了含义：

model_list: - model_name: gpt-entry # 统一对外暴露的模型名，应用侧只认这个 litellm_params: model: provider-a/llm-v1 # 实际的服务商模型标识 api_key: os.environ/PROVIDER_A_API_KEY # 从环境变量读取上游密钥 model_info: cost_per_token: 0.00001 # 每token的成本，用于费用统计 - model_name: chat-alt litellm_params: model: provider-b/chat-large api_key: os.environ/PROVIDER_B_API_KEY router_settings: routing_strategy: usage-based-routing # 基于用量的路由策略 model_group_alias: # 定义模型组，方便做fallback chat-all: models: - gpt-entry - chat-alt

这份配置要解释几个关键点。model_name是应用直接感受的模型名，它是整个配置体系的入口。model字段指定的是litellm翻译后实际请求的目标模型。cost_per_token是成本统计的基础数据，一定要和上游报价对得上，不然成本报表就是错的。

router_settings这段是生产环境里的重头戏。model_group_alias可以定义一个模型组，组内按顺序排列多个模型。当组内第一个模型失败或超时时，litellm会自动用下一个模型重试，这就是最基础也最有效的fallback机制。我建议所有重要模型都配上fallback，成本可以接受，稳定性提升非常明显。

3.3 用Docker Compose启动服务并完成初始化

准备好config.yaml和docker-compose.yml之后，启动流程很简单。先创建需要挂载的目录，然后通过环境变量文件传入master key、salt key和数据库连接串。这里有一份docker-compose.yml的关键结构可以参考：

services: litellm: image: ghcr.io/litellm/litellm:main-latest ports: - "4000:4000" volumes: - ./config.yaml:/app/config.yaml environment: - LITELLM_MASTER_KEY=sk-master-xxxxx - LITELLM_SALT_KEY=sk-salt-xxxxx - DATABASE_URL=postgresql://user:pass@postgres:5432/litellm - REDIS_URL=redis://redis:6379/0 depends_on: - postgres - redis postgres: image: postgres:16 environment: POSTGRES_USER: user POSTGRES_PASSWORD: pass POSTGRES_DB: litellm volumes: - pgdata:/var/lib/postgresql/data redis: image: redis:7 volumes: - redisdata:/data

启动命令就是常规的docker compose up -d。第一次启动litellm会自动建表并初始化数据库。初始化完成后，访问主机的4000端口就能看到管理后台，用master key登录，进入后台创建一个虚拟key，然后就可以开始测试了。

有个细节要注意：默认的master key和salt key绝不能在生产环境使用。master key相当于整个网关的root权限，salt key用于加密虚拟key，这两个key必须改成足够随机的长字符串，建议至少32位。如果生成虚拟key之后修改了salt key，之前生成的所有虚拟key都会失效，所以要提前规划好密钥管理方案。

3.4 把现有代码切换到litellm的两种方式

接入litellm有两种常见方式，按需选择。第一种方式是更换base_url，适用于已经使用兼容行业通用接口协议格式的客户端的情况。只需要把代码里设置API地址的地方改成litellm服务的地址，把API key改成在litellm后台生成的虚拟key即可。这种方式改动最小，应用代码几乎不需要动。

第二种方式是使用litellm的官方SDK。对于新项目或者需要更灵活控制的场景，建议直接用litellm封装好的客户端。它提供了与通用聊天接口一致的调用方法，但内部会自动处理路由、重试、fallback这些逻辑。用Python写一个简单调用长这样：

from litellm import completion response = completion( model="gpt-entry", messages=[{"role": "user", "content": "你好"}], ) print(response.choices[0].message.content)

这个简单调用的背后，litellm做了很多事情：解析模型名、查询路由策略、读取对应的上游配置、发起真实请求、处理重试和fallback、记录token和成本数据。应用层只需要关心传入了哪些消息、拿到了什么回复，这就是网关该有的样子。

如果应用已经用别的SDK封装好的对话逻辑，我建议先用第一种方式快速切换，验证功能正常后，再决定要不要逐步重构到新SDK上。迁移这件事，步子迈得小一点反而稳。

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

4.1 请求超时与重试策略的常见坑

使用litellm一段时间后，我遇到过几次问题，整理下来最有代表性的是以下几类。

第一个是请求超时时间设置过短。模型推理本身就是高延迟操作，遇到高峰时段或者模型负载高时，单次请求耗时可能超过30秒。如果应用侧或litellm侧的超时设置小于模型实际耗时，就会造成局部成功但整体报错的现象。排查这类问题，先看litellm日志里的具体错误信息，确认是超时还是没有响应，然后针对性调整timeout配置。我习惯把超时时间设为60秒以上，给慢请求留出余量。

第二个是重试导致的重复扣费。litellm默认会在请求失败或超时时自动重试，重试是好事，但如果不改配置，在“请求已经发送、响应超时”的情况下重试，可能造成用户实际只发起一次请求，上游却被扣了两次费用。解决办法是把重试策略和幂等机制配合好，在业务代码里生成请求唯一标识，模型侧支持幂等参数时尽量带上，减少重复扣费的可能性。

4.2 模型配置不生效与权限认证失败

第二个常见问题：改了config.yaml发现不生效。这个问题多半是没重启服务。litellm的部分配置支持热加载，但新增模型列表这种核心配置，建议在修改后重启容器，或者确认配置热加载的机制是否已开启。有一次我改了模型别名，以为已经生效，结果线上调用还是走的旧配置，浪费了不少排查时间。

第三种问题是权限认证失败。表现是请求被拒绝，返回认证相关的错误。排查步骤很固定：先确认请求用的key是虚拟key还是在后台创建的测试key；再确认该虚拟key是否绑定了对应的模型权限；最后检查master key是否被误用。master key是管理后台用的，不能当作正常业务key放在应用里，严格区分这两种key能减少很多认知混乱。

有时认证失败的时间点也很关键。如果是一次性生成的一批key突然全部失效，大概率是salt key变了或者数据库被重置了。这种情况没有快捷恢复方式，只能重新生成key并下发，所以生产环境的密钥保存和备份策略要提前设计好。

4.3 成本统计偏差与缓存误伤的应对思路

成本统计偏差也值得单独讲一下。多数情况是模型单价配置得不对，或者模型版本更新后计费规则变化了而litellm配置没同步更新。建议定期核对自己使用的每个模型的实际计费价格，更新到config.yaml里。另外，如果使用了缓存功能，命中缓存的请求不会计费，成本报表会显示聚合成本偏低，这是正常现象，但要在做成本分析时把缓存命中率一起纳入参考，才不会误判。

缓存的副作用还有“误伤”。语义缓存如果相似度阈值设置过低，可能把两个语义相近但内容不同的请求当成同一个请求来处理，返回了旧结果。解决方式很简单：对需要高准确率、不允许内容偏差的场景，不要开启语义缓存，只开精确匹配缓存，或者干脆全关掉；对百科问答、标准流程查询这类允许近似回答的场景，再考虑语义缓存。

4.4 运维安全：日志、端口与数据库备份

最后是一些运维层面的建议。litellm的日志里包含完整请求和响应内容，这些数据可能涉及用户隐私和业务敏感信息，生产环境部署时一定要做好日志存储和访问权限控制，不能开着默认配置就把服务暴露在公网。管理后台端口建议只对内网开放，需要远程访问时走带身份认证的跳板方案，不要直接把4000端口裸奔到公网。

数据库和Redis同样需要注意安全。虚拟key、预算数据、请求记录都存里面，一定要设置强密码，定期备份。我自己的经验是每周做一次全量备份，每天做一次增量备份，并且定期演练恢复流程。备份不是光把数据导出来就行，还要确认恢复后服务能正常起来，否则真出事时才发现备份是个空壳，就太晚了。

最后再说一点实际经验：litellm引入团队后，真正有价值的并不是它省了多少接入代码，而是它把模型接入变成了一个可治理的过程。以前模型变更动一发牵全身，现在只是改配置、切流量、观察数据。这种架构上的灵活性，在模型快速迭代的当下比省几行代码重要得多。如果你团队也面临多模型接入的混乱期，花一两天把litellm部署起来，后面会省下非常多功夫。