企业官网建设流程全解析

做 AI 应用开发这两年，我最大的感受就是模型越来越多，接口却越来越乱。今天要聊的 litellm，就是一个专门把这种混乱封装掉的开源工具：通过一套统一接口，接入市面上主流的大模型服务，同时自带代理网关、故障转移、限流和成本统计。第一次接触它，是在给一个内部工具接入多模型的时候——某个上游服务响应变慢，业务不能停，模型还得继续用，当时的情况逼着我去找一个能“横跨多家服务商”的接入层。

这篇文章不打算写成官方文档的翻译，我会按自己实际落地的路径来讲：先说清楚 litellm 解决了什么、和框架类的工具区别在哪，再带你把 SDK 用法和代理模式跑通，最后把配置故障转移、预算限流、成本查询这些进阶操作拆开讲。适合这几类人：正在做 AI 应用开发、需要在多个模型服务间切换的工程师；要管模型网关、给团队分配访问权限的后端开发；还有对调用成本敏感、想拿到清晰账单的技术负责人。

1. 为什么我要在技术栈里加一层模型网关

很多第一次听说 litellm 的人会问：我直接用官方 API 不行吗？为什么要多包一层？我的回答是：如果你只需要对接一家模型服务、项目生命周期也只有两三个月，确实可以不折腾。但只要你开始做多模型对比、模型替换、团队共用一套模型资源，这层网关就变成刚需了。

1.1 多模型接入的三个真实痛点

第一个痛点是接口格式不统一。OpenAI 的 chat completions 接口和 Anthropic 的 messages 接口结构差异很大，从模型名到消息格式、返回字段都不一样。你给 A 模型写好的调用代码，搬到 B 模型上去，改的可不是一个参数名，而是整个请求体和解析逻辑。如果项目里同时在用 GPT 系列和 Claude 系列，你会发现自己一半的代码都在做“格式翻译”。

第二个痛点是切换成本高。业务代码里如果到处散落着针对某个特定服务商的调用，一旦要换模型，就得全局改代码。改完还得重新测试超时、重试、异常处理这些细节。每次模型一升级，或者服务商调价格、改限流策略，你都得跟着遭殃。

第三个痛点是稳定性与成本控制得自己造轮子。真实环境里，模型接口偶尔会慢、会限流、会返回 5xx 错误。你要么自己写重试逻辑，要么引入一堆第三方重试库。至于成本统计，更是麻烦——每个服务商的计费口径还不一样，token 数、缓存命中、图像输入，算得人头大。

1.2 litellm 与 LangChain 这类框架的本质区别

这里要特别说清楚一个容易混淆的点：litellm 不是 LangChain 那种应用编排框架，它做的是“请求入口封装”。LangChain 关心的是链路、Agent、记忆、文档加载这些高层抽象；而 litellm 只做一件事——把“发送一次模型请求、拿到一次响应”这个动作统一起来。它不绑死你的业务形态，也不会要求你必须按某种 Chain 的方式组织代码。

所以很多团队的落地方式是分层的：底层用 litellm 统一模型接入，上层再根据业务需要决定用不用 LangChain 或其他工具。如果你的项目本身不需要复杂的链式调用，直接就用 litellm 也完全够；如果你已经用了框架，也可以把它配置成底层客户端。这个定位差异决定了它非常轻，不会把你拖进某个框架的约束里。

2. 上手前必须搞清的三个核心概念

litellm 虽然用起来简单，但有几个核心概念最好在动手前就理解，否则后面配置代理、做故障转移时会一头雾水。

2.1 统一接口与 provider 前缀

litellm 的核心设计是：你仍然以熟悉的 OpenAI API 风格发请求，只是模型名里带上“服务商前缀”。比如anthropic/开头表示走 Anthropic 格式，openai/开头走 OpenAI，ollama/走本地模型，azure/走 Azure OpenAI 服务，gemini/走 Google 的模型接口。

这个前缀机制非常关键。它既是路由规则，也是自动转换开关。litellm 会读取前缀，把统一的请求格式转换成对应服务商要求的格式，再把响应转回统一结构。如果你不写前缀，默认按 OpenAI 兼容格式处理。这个设计让我后来接入新模型时，几乎只需要在配置里加一行，而不是重新写一个客户端。

2.2 SDK 模式与 Proxy 模式

litellm 有两种运行方式，理解它们的不同能帮你少走弯路。

SDK 模式：在你的 Python 项目里直接 import litellm，调用它提供的 completion 方法。这种方式适合单个应用、单个进程内部使用，代码侵入最小。

Proxy 模式：litellm 启动一个独立的网关服务，对外暴露一个 OpenAI 兼容的 HTTP 接口。所有团队成员把自己的代码指向这个网关就行，网关负责转发、鉴权、限流、计费。这种方式适合多团队、多应用共享一套模型资源，也是企业落地最常见的形态。

2.3 为什么它能做到“无感替换”

litellm 把输出结构也统一成了 OpenAI 风格，所以很多场景下你可以直接把它当作官方 SDK 的平替。原来写OpenAI().chat.completions.create(...)的地方，改成litellm.completion(...)，业务代码几乎不用动。这种“无感替换”能力，是它能在很多项目里快速落地的重要原因。

3. SDK 接入实操：从第一行代码到流式输出

理解了概念，下面进入实操。这部分我会从一个最小例子开始，逐步加复杂度，你跟着敲一遍就能跑通。

3.1 安装与配置环境变量

安装非常简单，一行命令：

pip install litellm

它能从环境变量里自动读取各家服务的密钥：设置OPENAI_API_KEY就能调用 OpenAI 的模型，设置ANTHROPIC_API_KEY就能调用 Claude 系列，设置GOOGLE_API_KEY就能调用 Gemini 系列。Azure OpenAI 需要设置AZURE_API_KEY和AZURE_API_BASE，本地模型如 Ollama 则不需要密钥。如果你不想用环境变量，也可以在调用时显式传入api_key参数，但我不建议把密钥写死在代码里，环境变量或密钥管理服务会稳妥得多。

3.2 用一个函数切换多家模型

这是 litellm 最让我舒服的一点：写一个通用的补全函数，切换模型时只需要换model参数。

import litellm def ask(model_name: str, user_content: str) -> str: response = litellm.completion( model=model_name, messages=[{"role": "user", "content": user_content}], max_tokens=256, ) return response.choices[0].message.content # 调用 OpenAI 模型 print(ask("gpt-4o", "用一句话介绍你自己")) # 切换 Anthropic 模型 print(ask("anthropic/claude-3-5-sonnet-20241022", "用一句话介绍你自己")) # 调用本地 Ollama 模型 print(ask("ollama/llama3", "用一句话介绍你自己"))

注意几个细节：max_tokens、temperature、top_p这类参数可以直接透传，litellm 会按目标服务商支持的字段做映射。某些服务商不支持某些参数时，它会自动忽略或报错，这个行为可以在文档里查到。返回对象的结构是统一的，所以你只需要写一次响应解析逻辑。

3.3 流式输出与多轮对话

流式输出在聊天类应用里几乎是标配。litellm 的流式和普通调用差别不大，加个stream=True，然后遍历 chunk 就行：

response = litellm.completion( model="gpt-4o", messages=[{"role": "user", "content": "写一段关于秋天的散文"}], stream=True, ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True)

多轮对话也很直接，把历史消息一起传进去：

messages = [ {"role": "system", "content": "你是一个严谨的代码评审专家"}, {"role": "user", "content": "帮我 review 下面这段代码"}, {"role": "assistant", "content": "请贴出代码"}, {"role": "user", "content": "def foo(): pass"}, ] response = litellm.completion(model="gpt-4o", messages=messages)

这里我吃过一次亏：不同服务商对 system 消息的支持程度不同，有的模型对 system 和 user 的边界很敏感。如果你发现同一套 messages 在不同模型上表现差异很大，可以先检查是不是消息角色设置的问题，而不是急着怀疑 litellm 转换逻辑。

4. Proxy 模式：让一个接口服务整个团队

SDK 模式适合单人开发，但到了团队阶段，你不可能让每个成员都配置一套自己的密钥，更不可能为每个人的代码单独做计费。这时候就需要起一个代理服务，这也是 litellm 在企业场景里最常用的形态。

4.1 写一个 config.yaml 就够了

代理的核心是一个 YAML 配置文件，把你想开放给团队的模型都声明在里面。下面是一个最小可用的例子：

model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-3-5 litellm_params: model: anthropic/claude-3-5-sonnet-20241022 api_key: os.environ/ANTHROPIC_API_KEY - model_name: llama3 litellm_params: model: ollama/llama3 - model_name: my-azure-model litellm_params: model: azure/azure-gpt-4o api_key: os.environ/AZURE_API_KEY api_base: os.environ/AZURE_API_BASE

注意model_name和litellm_params.model的区别：前者是暴露给团队的外部名字，后者是真正去调用的服务商模型名。外部名字可以随便起，比如你们内部统一叫claude-3-5，后面想换底层版本，只需要改配置，团队侧代码完全不用变。

4.2 启动代理并用 curl 验证

配置文件写好后，启动命令很直接：

litellm --config config.yaml --port 4000

启动后，它会对外暴露一个 OpenAI 兼容的地址：http://localhost:4000/v1/chat/completions。你可以用 curl 验证：

curl http://localhost:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5", "messages": [{"role": "user", "content": "你好"}] }'

团队里的应用只需要把原来的 API Base 改成这个地址，模型名改成你配置的model_name，就能立刻切到代理上。这个兼容性设计极大降低了迁移成本，我们当时把好几个应用切过去，花了不到半天。

4.3 虚拟 Key 与访问控制

代理模式天然支持多团队隔离。启动时设置一个主密钥（Master Key），然后通过管理接口为不同团队生成虚拟 Key，每个虚拟 Key 可以绑定不同的模型列表、预算和速率限制。

生成新 Key 的调用大致是这样的：

curl http://localhost:4000/key/generate \ -H "Authorization: Bearer $LITELLM_MASTER_KEY" \ -H "Content-Type: application/json" \ -d '{ "models": ["gpt-4o", "claude-3-5"], "max_budget": 50 }'

返回的 Key 给团队成员用，他们调用代理时带上这个 Key。这样你就能清楚地知道每个团队用了多少额度、调了哪些模型。对于要给老板交差、要给客户分摊成本的场景，这一步基本是必做的。

5. 进阶实战：故障转移、限流与成本追踪

跑通基础调用后，接下来这些才是生产环境真正需要的功能。litellm 之所以能让我放心把它放在业务和模型之间，靠的就是这几个硬实力。

5.1 配置 fallback，让调用在故障时自动切换

我们遇到过最尴尬的场景：正在线上跑的模型突然开始频繁报错，如果业务代码里没有兜底逻辑，用户直接看到失败。litellm 的 fallback 配置可以在主模型失败时自动切换到备用模型。

在代理配置里，大概这样写：

router_settings: fallbacks: [ {"claude-3-5": ["gpt-4o", "ollama/llama3"]} ]

意思是：当claude-3-5出现 5xx 或超时类错误时，依次尝试gpt-4o，再不行就尝试本地模型ollama/llama3。这个配置对于追求稳定的业务来说太重要了。之前我们为了这个功能自己写重试和切换逻辑，代码又丑又难维护，换成配置项之后，责任边界清晰多了。

有个细节要提醒：fallback 之后要留意返回结果到底来自哪个模型，因为业务可能对模型身份敏感。litellm 会在返回信息里带上实际使用的模型，你在解析时不要写死模型名，最好从响应里读取。

5.2 用预算和限流把花费关进笼子里

模型费用是不可预测的，尤其当某个线上服务出现异常循环调用时，账单会在几个小时内飙升。litellm 的预算配置可以给整体设置一个硬上限：

litellm_settings: max_budget: 100 budget_duration: 30d

含义是：30 天内总花费不能超过 100 美元（按你配置的计价口径统计），超过后代理会直接拒绝新请求。另外，你还可以在模型级别配置速率限制，比如每分钟请求数（rpm）和每分钟 token 数（tpm）：

model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: os.environ/OPENAI_API_KEY rpm: 100 tpm: 50000

这种限制对防止单个应用把共享资源打爆非常有用。我的建议是预算值不要只设一个“理论安全值”，要根据你们一个月真实用量再留出 20%-30% 的缓冲，避免误伤正常业务。

5.3 成本统计：给每一次调用记账

litellm 会在代理模式下记录每次调用的 token 数和估算费用，并提供统计接口。常见的查询有总花费、按模型维度的花费、按团队或 Key 维度的花费。这些数据用管理密钥访问，格式也很直接，你可以拉到自己的监控系统里做可视化。

我个人的做法是：每天早上拉一次昨天的花费数据，生成一张简单报表。出现异常时，先按 Key 维度找哪个团队在猛调，再按模型维度确认是哪个模型单价贵。这套链路让我们控制模型成本时不再是瞎子摸象。

6. 高频报错与排查实录

真实使用过程中，我踩过不少坑，这里整理成一份速查表，再讲两个印象最深的排查过程。

6.1 按错误信息定位问题的速查表

6.2 我排查过的两个典型问题

第一次出问题是在代理刚跑起来的时候，某个应用调用时报密钥错误。我第一反应是环境变量没配对，后来发现是启动代理的进程没有继承配置文件中os.environ/XXX对应的环境变量。也就是说，config.yaml里的os.environ/OPENAI_API_KEY只是告诉 litellm“去环境变量里拿”，但运行代理的 shell 里本身没有这个变量。后来我在启动脚本里显式 export 了所有需要的密钥，问题立刻消失。这一点很多人容易忽略，尤其是用 systemd 或容器部署时。

第二次是流式调用偶发中断。现象是大部分请求正常，偶尔第二个 chunk 开始就断了。排查下来发现是我们在代理前面又挂了一层定时任务做超时回收，它对长请求不太友好，误杀了连接。把超时阈值调大，并让 litellm 的 fallback 处理上游异常后，问题就不再出现了。这类“代理前面还有一层”的架构，排查时一定要把每层都看一遍，别只盯着模型服务商。

7. 一些落地建议与个人体会

上面把 litellm 的主要能力都过了一遍，最后分享几条我实际项目里的建议。

第一，从第一天就用 provider 前缀的写法，哪怕你当前只有一个服务商。因为前缀写法和普通写法在 litellm 里行为一致，但之后加新模型时，你的代码风格不需要迁移。第二，密钥管理要规范。代理模式下，把密钥集中在配置和环境的注入层，团队成员拿到的是虚拟 Key，出了问题可以单独吊销，不会影响所有人。第三，先跑 SDK 模式验证模型效果，确认没问题后再上代理。代理解决的是治理问题，不是模型效果问题，别把顺序搞反。

我个人最深的体会是：litellm 让我把精力从“怎么对接模型”切换到了“业务到底需要模型做什么”。以前每次模型升级或者切换服务商，都要重新写一遍适配代码，现在这只是配置上一个字符串的事。这种看似不起眼的简化，在长期维护的项目里价值会越来越大。

最后再分享一个小技巧：如果你打算在生产长期用代理模式，建议把配置文件和启动脚本纳入版本管理，同时把花费统计定期导出。这样无论是排查线上问题、核算项目成本，还是将来扩展新的模型接入，你都有一个清晰的基线。litellm 不是那种需要你花很多时间学习才能入手的工具，但把它用对、用到位，绝对能让你的模型接入层少操很多心。