企业官网建设流程全解析

LiteLLM 是我在给内部 AI 工具做多模型接入时，目前觉得最顺手的一个开源网关。它本身不训练模型，也不帮你写 prompt，而是把各家模型服务收敛到一个统一接口后面：业务代码只管调/v1/chat/completions，至于背后是哪个厂商、哪个模型、有没有限流和故障，全在网关这一层处理。下面这篇内容，就从我实际配置和使用 LiteLLM 的经验出发，讲讲它解决了什么问题、怎么从零跑起来，以及哪些配置值得生产环境直接用。

如果你现在也处在“同一个产品要接两三家模型服务、每个 SDK 都有自己的脾气”的状态，这篇应该能帮你省掉不少折腾时间。

1. 为什么我最终把 LiteLLM 放进了模型接入链路

1.1 多模型接入的真实混乱，往往是从 SDK 开始的

先说一个我经手过的内部工具。最开始只接了一个模型服务，业务代码里直接用了那个厂商的 SDK，prompt 拼接、流式输出、错误处理都写在一个模块里。后来为了对比效果，又接进入第二家，问题就来了：两家 SDK 的初始化方式不一样，返回对象的结构不一样，错误码含义也不一样，甚至流式输出的解析逻辑都要单独写。

再往后，产品经理希望同一套对话逻辑能根据用户等级自动切换到不同规格的模型，也就是说同一个接口，有时走快速小模型，有时走深度推理大模型。这时候如果继续在每个业务服务里各自维护“厂商 SDK + 模型切换规则”，代码会迅速熵增。最后大家聊下来，决定在业务服务和模型厂商之间加一层统一网关，LiteLLM 就是在这个背景下进入视野的。

这种混乱其实非常典型。很多人刚开始觉得“就调几个 API 而已”，但等模型数量超过三个、调用方超过两个团队，统一入口就不再是锦上添花，而是必需品。LiteLLM 的核心价值不是帮你选模型，而是把“调用模型”这件事标准化：你只面对一套 OpenAI 风格的接口，所有供应商差异被挡在网关后面。

1.2 LiteLLM 的定位：统一入口，而不是模型本身

LiteLLM 经常被叫做“LLM 代理层”，但我更愿意叫它“模型网关”。它本身不托管模型权重，也不做训练和微调。它做的事，是接收业务方的请求，然后按照你配置的规则转发给真正的模型服务，并把模型返回的结果按统一格式回给业务方。

用生活化的方式理解，LiteLLM 就像一个公司前台。访客不需要知道公司里哪个部门负责什么、谁今天请假了，只需要告诉前台“我要找财务”，前台会自己判断该引到哪个工位。对应到模型调用场景里，业务方只需要说“我要一个通用对话模型”，网关去路由到具体供应商、处理超时重试、记录 token 消耗。

它兼容的模型来源很多，既有通过标准 OpenAI 协议暴露的服务，也有其他几家主流厂商的专用接口。只要你把密钥和模型名配进它的配置文件，业务方就不用感知这些差异。

1.3 适用场景与不适用场景

我列过一个简单的判断表，帮团队决定要不要引入它：

这中间的权衡在于“多一跳”。LiteLLM 转发请求会有毫秒级的额外开销，但对绝大多数对话应用来说完全无感。真正需要注意的是，引入网关意味着多了一个需要维护的组件，配置、日志、密钥管理都要跟上，不能配完就丢在服务器上不管。

2. 从零起步：安装配置与第一个可用的统一接口

2.1 安装方式与基础环境变量

LiteLLM 的安装很简单，就是一个 Python 包。官方推荐安装带代理能力的版本，因为光装核心包没有启动网关服务的命令：

pip install 'litellm[proxy]'

装完以后，先准备好密钥。LiteLLM 的配置习惯是从环境变量里读密钥，而不是直接把密钥写进 YAML 文件提交到仓库。比如要接入常见的 OpenAI 风格服务，就设置：

export OPENAI_API_KEY="你的密钥"

然后可以用命令直接验证一下能不能启动：

litellm --model openai/gpt-4o-mini --port 4000

这个命令的作用是：用命令行参数临时启动一个模型入口，openai/gpt-4o-mini表示走 OpenAI 协议、模型名是gpt-4o-mini，端口监听在 4000。第一次跑通这个，说明环境和密钥都没问题。

不过命令行临时方式不适合长期使用，很快就要切换到配置文件方式。

2.2 config.yaml 里的模型声明规则

LiteLLM 的核心配置是 YAML 文件。初次使用时，至少要有model_list这一段，它定义了这个网关对外暴露哪些模型入口。

model_list: - model_name: chat-small litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY

这里有两个概念很容易混淆：

• model_name是你自己起的名字，也是业务方调用时看到的模型名。
• litellm_params.model是真正请求上游时用的模型标识。

所以model_name: chat-small的意思是“我对外叫 chat-small，但背后对应的是 openai/gpt-4o-mini”。业务方不需要知道上游真实模型名，以后你想换更强的模型，只需改网关配置，业务代码一行不用动。

如果还想加一个更贵的深度模型，就在model_list里追加一条：

model_list: - model_name: chat-small litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY - model_name: chat-large litellm_params: model: openai/gpt-4 api_key: os.environ/OPENAI_API_KEY

启动时指定配置文件：

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

看到监听地址之后，网关就算跑起来了。

2.3 用标准 SDK 完成第一个请求

因为 LiteLLM 对外暴露的是 OpenAI 风格接口，所以任何支持 OpenAI 协议的客户端都能直接连它。我用 Python 的 openai 包验证过，代码里只需要改base_url和api_key：

from openai import OpenAI client = OpenAI( base_url="http://localhost:4000/v1", api_key="sk-anything", ) resp = client.chat.completions.create( model="chat-small", messages=[ {"role": "user", "content": "你好，简单介绍一下你自己"} ], ) print(resp.choices[0].message.content)

注意这里的api_key只要随便填一个非空字符串就行，网关默认不校验，除非你额外开启了虚拟 key 功能。model填的是我们配置里的chat-small，不是上游真实模型名。

这个请求能通，说明核心链路已经没问题：业务请求进网关，网关转发给上游，上游结果再原路返回。很多刚接触 LiteLLM 的人会在这里卡住，多数不是配置问题，而是忘了在配置里写model_name对应的litellm_params.model，导致网关不知道转发给谁。

3. 路由、负载均衡、故障转移：配置上的实战理解

3.1 模型别名是业务与上游之间的解耦点

在 LiteLLM 里，我最看重的一个设计就是模型别名机制。它让业务方看到的模型列表和真实上游完全解耦。

举个例子：你可以在网关里定义model_name: main-chat，同时给它配上多个上游来源，比如一个便宜的小模型和一个贵一些的大模型。策略上可以让普通请求走小模型，复杂请求走大模型。对业务方来说，它们始终只认main-chat这一个名字。

这种解耦在模型版本升级时特别有用。上游某个模型可能隔几个月就换新版本，旧版本下架。如果你直接让业务代码写死上游模型名，升级就要改代码重新发版。但有了网关这一层，只改配置文件里的litellm_params.model，业务侧无感知。

另外，如果业务方传了一个网关里不存在的model_name，LiteLLM 默认会报模型不存在。我建议在配置阶段就把团队约定的模型名固定下来，并写一份简短的接入文档，避免各业务方各自起名字。

3.2 多密钥负载均衡与 fallback 配置

当同一个上游模型你有多个密钥、或者同一语义模型你有多个不同规格时，LiteLLM 可以按配置自动分配请求。下面这段配置，是我在一个模拟项目中验证过的方式：

model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY model_info: mode: chat - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4 api_key: os.environ/OPENAI_API_KEY

同一个model_name出现两条记录，网关会把它当成同一个逻辑模型的多个部署。正常情况下请求会在这些部署之间轮询，起到负载分散的作用。

更实用的是 fallback。假设main-chat指向某个常用模型，但上游偶尔不稳定，网关就可以配置一个备用模型，在主模型返回错误或超时时自动切过去：

model_list: - model_name: main-chat litellm_params: model: openai/gpt-4o-mini api_key: os.environ/OPENAI_API_KEY fallbacks: ["backup-chat"] - model_name: backup-chat litellm_params: model: openai/gpt-4 api_key: os.environ/OPENAI_API_KEY

这样配置之后，调用main-chat时如果上游异常，网关会尝试转向backup-chat。我在压测时故意关掉主模型服务，请求确实能自动切到备用模型，业务方只会感到一次轻微延迟，不会直接看到报错。

不过也要提醒一句：fallback 不是银弹。如果上游是业务强依赖的，建议把备用模型设成同一个厂商的另一个规格，跨厂商 fallback 虽然可行，但模型行为差异可能导致返回风格不一致，最好评估后再用。

3.3 超时重试参数怎么给

模型接口和普通 HTTP 接口不一样，特别是深度推理模型，响应时间波动很大。重试和超时参数不能照搬普通服务的配置。

我现在的习惯是在litellm_settings里统一设置：

litellm_settings: request_timeout: 60 max_retries: 2

request_timeout控制网关等待上游响应的上限。如果设置太短，长一点的推理任务会被误杀；设置太长，上游如果真的挂了，业务方也要等很久才能收到失败。对于普通对话模型，30 到 60 秒是比较稳妥的范围；如果要跑深度推理任务，可以放宽到 120 秒甚至更长。

max_retries是请求失败后的重试次数。我的建议是重试 1 到 2 次就好，不要把重试次数设成 5 次以上。重试太激进，上游一旦出问题，反而会因为大量重试请求造成更严重的拥堵。

有一点容易忽略：流式输出场景下的超时和普通请求不一样。代码里接收流式响应时，如果长时间没有新的数据块，客户端往往已经断了，但网关这边的超时设置还没触发。这类问题排查起来比较隐蔽，我会在监控里专门看“长时间无数据块”的连接数。

4. 成本、用量与访问控制：把网关当成运营工具

4.1 请求日志里的 token 数据

LiteLLM 让我觉得“这钱花得值”的地方，是它默认会记录每次请求的 token 消耗。

如果你用了带代理功能的安装包，网关启动后会在本地记录请求日志，包括请求时间、模型名、输入 token 数、输出 token 数、请求是否成功等。这些数据是成本分析的基础。

很多人以为“token 统计”只是简单地把prompt_tokens和completion_tokens加起来，实际操作里还要注意上下文缓存命中、输入缓存读取、输出 token 计费差异等问题。LiteLLM 的日志字段会保留上游原始计费信息，你可以基于这些字段做更精细的账单拆分。

比如，内部想按小组核算月度成本，就可以定期从日志里按“项目标识”聚合 token 消耗。怎么把项目标识传进来？简单做法是在请求里带上自定义参数，LiteLLM 会把它们记录到日志，之后按字段分组统计就行。

4.2 虚拟 key、预算上限与限流

如果网关只是放在内网里给一两个服务用，密钥管理可以随便一点。但只要接入方变多，就要开启虚拟 key 功能。

虚拟 key 的意思是，业务方拿到的是一把 LiteLLM 生成的 key，而不是上游厂商的真实密钥。这把 key 可以在网关里单独设置预算、限流和过期时间。即使某个业务方的 key 泄露，也不会暴露上游厂商密钥。

用命令行创建虚拟 key 大致这样：

curl -X POST http://localhost:4000/key/generate \ -H "Authorization: Bearer sk-your-master-key" \ -H "Content-Type: application/json" \ -d '{"models": ["chat-small", "chat-large"], "max_budget": 50}'

返回结果里会有一个新的key，这个 key 之后就能用来调网关接口。

预算上限可以用max_budget控制，单位通常是美元。还可以配合budget_duration设置周期，比如按天、按月。实际运营里，我会给每个业务线开一个独立 key，并设置月度预算。某条业务线预算快用完时，网关会直接拒绝新增请求，比事后看账单再追责要干脆得多。

限流方面，虚拟 key 上可以配置 RPM（每分钟请求数）和 TPM（每分钟 token 数）。比如一个轻量级对话应用，可以设置rpm: 100, tpm: 100000。这样做的好处是，单个接入方即使写了个死循环也不会打爆上游配额。

4.3 一个最小可用的用量监控闭环

只看日志不够，生产环境最好有监控。LiteLLM 提供了 Prometheus 指标暴露，开启方式是在litellm_settings里挂一个回调：

litellm_settings: success_callback: ["prometheus"]

开启后，网关会在/metrics路径暴露指标，包括请求总数、失败数、请求延迟分布、token 消耗等。配合 Prometheus 和面板工具，就能看到一张实时变化的模型调用大盘。

我实际搭的最小监控闭环包含三块：

1. Prometheus 定时抓取/metrics。
2. 一个简单的面板展示总体请求量、错误率、平均延迟。
3. 在面板里按模型名拆分 token 消耗趋势。

有了这三块，模型是不是该降级、哪个业务线异常增长、上游是不是开始频繁限流，基本都能提前发现。

5. 缓存、内容安全与并发控制：生产化必配的开关

5.1 语义缓存与 TTL 选择

模型调用是有成本的。业务里如果存在大量重复问题，比如常见的产品 FAQ、固定话术生成，就可以考虑打开缓存。

LiteLLM 支持响应缓存，简单配置可以这样：

litellm_settings: cache: true

缓存的 key 会基于请求内容生成。下一个完全相同的请求来时，网关直接返回缓存结果，不再调用上游模型。

不过缓存不是越多越好。我建议只对“高命中率、低变化度”的场景开缓存，而且必须设置 TTL。比如 FAQ 类接口可以缓存 10 到 30 分钟，个性化生成的接口尽量不要缓存。对包含用户隐私信息的请求开缓存，还要先确认数据合规边界。

还有一种更聪明的缓存类型是语义缓存，它不只是要求字符串完全一样，而是语义相近就命中。这类缓存对底层向量检索和相似度阈值都很敏感，配置不当会得到“答非所问”的缓存结果。我个人的建议是：先跑一段完全匹配缓存，等日志里看到大量重复问题，再决定要不要上语义缓存。

5.2 内容安全策略接入点

模型网关是所有模型请求的必经之路，所以内容安全策略放在这里做，覆盖面最广。

LiteLLM 可以配置 guardrail 类的回调，在请求转发前或响应返回前执行校验。你可以把它理解为“网关的保安”：请求进来先在门口检查一遍，发现不合规直接拦下；响应出去前再查一遍，避免不好的内容流到业务方。

配置时可以挂外部的安全审核服务，而不是自己写模型判断逻辑。这样好处是规则统一：不管哪个业务线用哪个模型，都经过同一套审核策略。坏处是多一次外部调用会增加延迟，所以建议只在风险较高的接口上开启，并且看一下审核服务的 P99 延迟。

5.3 并发与排队控制

网关默认会尽可能快地转发请求，但如果上游模型服务的并发配额很有限，不加控制就会频繁触发上游 429 限流。

我的做法是，在虚拟 key 上先做一层 RPM/TPM 限制，再在业务侧控制并发。如果某些任务真的允许排队，业务代码里塞一个简单的信号量就行，不必把排队逻辑做进网关。

这里有个容易踩的误区：大量请求触发上游 429 时，如果网关配置了重试，这些请求可能在短时间内再次全部打向上游，形成“重试风暴”。所以在做故障复盘时，要格外关注 429 之后的客户端实际重试情况，建议对重试请求也做退避，而不是立即重试。

6. 部署和排错：我实际踩过的坑

6.1 进程托管与 Docker 部署

LiteLLM 作为独立服务运行，最常见的部署方式有两种：直接用 Python 进程跑，或者用容器跑。

如果只在服务器上简单跑，systemd 是个省心选项。服务文件里写清楚启动命令、环境变量和日志路径，崩溃后能自动拉起，比裸nohup靠谱：

[Unit] Description=LiteLLM Proxy After=network.target [Service] EnvironmentFile=/etc/litellm/litellm.env ExecStart=/usr/local/bin/litellm --config /etc/litellm/config.yaml --port 4000 Restart=always RestartSec=5 [Install] WantedBy=multi-user.target

容器部署更便携。项目官方有镜像，配置文件和密钥建议通过挂载和环境变量注入，不要把密钥打进镜像层。一个最小的容器启动命令大概是这样：

docker run -d \ -p 4000:4000 \ -e OPENAI_API_KEY="你的密钥" \ -v /etc/litellm/config.yaml:/app/config.yaml \ 官方镜像地址 \ --config /app/config.yaml --port 4000

我倾向于在服务器上用 systemd，在开发测试环境用容器。原因是生产环境里 systemd 的服务发现和日志采集都比较直接，容器在本地快速搭建多个不同配置的网关实例则很方便。

6.2 三个常见故障及排查链路

我整理过三个自己踩过、也在其他团队里见过的故障，排查链路很有参考价值。

第一个是模型名不存在的报错。现象是客户端调一个看似合法的模型名，网关返回模型不存在。排查顺序是先看配置文件是否真的包含这个model_name，再看是不是大小写或前后空格问题，最后看litellm_params.model的提供商前缀是否写错。

第二个是密钥未加载。现象是启动时一切正常，但第一个真实请求就报鉴权失败。这个大多是环境变量没配置对。LiteLLM 的配置文件里通常用os.environ/变量名这种写法，而不会直接解析${变量名}。如果直接用${OPENAI_API_KEY}，可能不会被正确解析。

第三个是上游限流导致的连锁失败。现象是某个时间点开始大量请求报错，而且 fallback 似乎也没生效。排查时先看上游返回的限流状态码，再看网关日志里的 fallback 记录。很多时候是 fallback 配置里也指向同一个上游，上游本身已经限流，所以备用模型也跟着失败。这种情况需要对不同的上游来源分别配置 fallback 策略。

6.3 安全边界与密钥管理

把 LiteLLM 暴露在公网之前，一定要想清楚安全边界。

我建议至少做这几件事：

• 网关只监听内网或经过防火墙控制的端口，不要直接暴露到公网。
• 外部访问务必开启虚拟 key，且主 key 不要分发给业务方。
• 定期轮换上游密钥和虚拟 key。
• 给不同业务线分配不同 key，方便隔离和撤销。

密钥管理上，很多团队犯的错是把密钥写进 YAML 文件并且提交到代码仓库。正确的做法是把密钥放在环境变量或密钥管理服务里，配置文件只写os.environ/变量名。即使配置文件泄露，别人也拿不到真实密钥。

还有一点，虽然网关替业务方屏蔽了上游密钥，但虚拟 key 一旦泄露，别人就能以你的名义消耗模型配额。所以虚拟 key 一样要设置预算和限流，不能因为它是“虚拟的”就放松管理。

最后补一个我自己的习惯：配完网关先不要直接上业务流量，先用脚本模拟几十个并发请求，观察错误日志、fallback 情况和延迟曲线，确认无误后再切换线上流量。这样即使配置有问题，影响范围也控制在自己手里。