做 AI 应用两年多，真正让我烦躁的往往不是模型效果，而是接入方式。今天从一个叫 LiteLLM 的开源网关项目说起——它不是某一家大模型厂商的官方 SDK，而是一个把各家模型服务的调用方式拉平的库，也能单独跑成代理服务。简单说，你只需要学会一种写法，就能接上主流大模型服务商，包括普通 API、云厂商托管的模型、本地部署的开源模型等。这篇文章我不做泛泛介绍，直接讲它解决什么问题、核心机制怎么运作、生产环境怎么用，以及我踩过的几个坑。

1. LiteLLM 是什么：它把多家大模型的接入方式拉成了一条线

1.1 我为什么会去找这么一层"中间层"

最开始做 AI 功能时，我属于典型的"哪个模型好用就用哪个"的做法，项目里同时塞了好几个 SDK。这种做法的代价，短期内看不出来，等业务逻辑跑起来以后就非常难受。

首先是接口风格不统一。有的 SDK 用prompt作为输入字段，有的用messages，还有的需要把对话上下文拆成system、user、assistant三段结构。参数名也一样，有的叫max_tokens，有的叫max_output_tokens，有的叫temperature但语义还略有差异。返回结果更乱，有的直接返回纯文本，有的套一层choices[0].message.content，有的把内容放在一个叫output的字段里。

其次是切换成本高。某一天我发现供应商 A 的模型效果不够好，想换成供应商 B，或者想加一个备用模型作为降级方案，结果光是 SDK 替换、超时处理、错误码转换就花了一个下午。改完接口还要重新测一遍不同场景，因为两家服务对同样错误的表达方式都不一样。痛定思痛，我决定在业务代码和模型服务之间加一个抽象层。这个抽象层要能统一接受我的请求、统一返回结果、统一处理异常，并且能随时增加新厂商的模型进来，而不动业务代码。LiteLLM 基本就是按这个思路设计的。

1.2 从项目视角看，它的核心能力可以归纳成一块表

我看一个开源项目，习惯先列能力再动手。LiteLLM 最常见的几个能力点如下：

这张表要说明的很关键的一点是：LiteLLM 不是一个转发器那么简单。它以"统一"为切入点，把重试、回退、成本、密钥管控这些工程问题也一并归到了接入层。尤其适合两类团队：一类是产品还在快速试错，今天可能换一个模型；另一类是多业务线共用模型资源，需要一个集中管控的入口。

2. 核心机制拆解：一次适配，处处调用

2.1 统一输入输出约定的价值

LiteLLM 的调用方式长这样：你给它一个model参数，格式是"厂商前缀/模型名称"，比如supplier_a/model-7b，再给它一组messages，它就会自动把参数翻译成目标厂商需要的格式，然后把返回结果标准化成统一结构再交给你。

用户侧看到的永远是：

{ "choices": [ { "message": { "role": "assistant", "content": "..." } } ] }

这意味着业务代码里不需要写"如果调用 A 厂商就取这个字段，调用 B 厂商就取那个字段"这种分支。之前我的代码里有七八种字段解析逻辑，后来全部删掉，只剩一种。

这里有个容易忽略的好处：因为输入输出统一了，你可以把一次模型调用封装成一个函数，整个公司不同项目都能复用。新人接手时也不需要先搞清楚各家 SDK 的差异，只要知道messages怎么组织就行。

2.2 厂商适配器在工作时到底做了什么

如果只是简单转发，LiteLLM 做不了这么多厂商的适配。它内部像插件一样给每家服务商做了一层适配器，负责三件事：

第一，参数翻译。你传max_tokens，有的服务商管这个叫max_output_tokens，适配器会把它转成目标服务的参数名。你传temperature，有的服务商不支持或者取值范围不同，适配器也负责转换或者降级处理。

第二，请求鉴权。不同服务商的鉴权方式不一样，有的用请求头，有的要求把密钥放在特定字段里，有的还要求附带额外的项目 ID 或区域信息。这些细节全部被适配器消化掉了，你在业务代码里只需要在环境变量里配好密钥。

第三，错误码归一化。这是最容易被低估的部分。服务商报错时有的返回 429 表示限流，有的返回 503，有的返回一段很长的 JSON，里面藏着真正的错误原因。LiteLLM 会把它们翻译成相对统一的异常类型和错误信息。我做排障时，先看错误码属于哪一类，再去对应厂商文档里查细节，比之前直接在几十种返回格式里捞原因效率高得多。

2.3 模型名、密钥与额外参数的处理逻辑

很多人第一次用 LiteLLM 时会好奇：它怎么知道model-a到底该走哪家厂商？答案就是靠model参数里的前缀，也就是"斜杠左边那一段"。举个例子：

• supplier_a/model-7b，前缀supplier_a，走供应商 A 的适配器；
• supplier_b/model-tiny，前缀supplier_b，走供应商 B 的适配器。

密钥也不是混在一起的。传统做法是每个 SDK 用自己的环境变量，比如A_PROVIDER_KEY、B_PROVIDER_KEY分开存。LiteLLM 兼容这种思路，你只要把对应的密钥放在环境变量里，它会在调用时自动按前缀去取。

如果需要传递厂商专属参数，比如某个云厂商的部署名称、区域 ID，LiteLLM 也留了api_base、api_version这类通用参数位。我的经验是：先看默认适配器能不能满足需求，如果某个厂商有特殊要求，再这些参数传给适配器，不要让这些细节渗入业务代码。

3. 从零开始：先用 Python 库打通一次真实模型调用

3.1 安装和最小可运行示例

最快的上手方式，是直接装 Python 包，在本地脚本里完成第一次调用。

pip install "litellm[proxy]"

我推荐把proxy扩展一起装上，因为后面大概率会用到代理模式。装完之后，先配置一个密钥环境变量，比如要接供应商 A，就设置：

export SUPPLIER_A_API_KEY="你的密钥"

然后写一个最小例子：

from litellm import completion response = completion( model="supplier_a/model-7b", messages=[ {"role": "system", "content": "你是一个简洁的助手。"}, {"role": "user", "content": "用一句话解释什么是 API 网关。"}, ], ) print(response.choices[0].message.content)

只要密钥有效、模型名前缀对应得上，就能跑通。第一次跑通后，你会发现response对象的结构很接近那些主流 Chat 类接口，连usage里的输入 token、输出 token 数量都能直接拿到。

3.2 流式输出、异步调用与函数调用

对话类应用里，流式输出基本是标配。LiteLLM 把流式也做了统一处理：

from litellm import stream resp = stream( model="supplier_a/model-7b", messages=[{"role": "user", "content": "写一段 100 字的产品介绍"}], ) for chunk in resp: delta = chunk.choices[0].delta.content if delta: print(delta, end="")

如果你的业务是异步框架，比如 FastAPI，那就用acompletion：

import asyncio from litellm import acompletion async def main(): response = await acompletion( model="supplier_a/model-7b", messages=[{"role": "user", "content": "你好"}], ) print(response.choices[0].message.content) asyncio.run(main())

这段代码有两个细节值得注意。第一，异步和同步的返回结构一致，代码迁移成本很低。第二，流式调用时别直接把整个chunk打日志，因为每个 chunk 都包含完整字段，日志量会非常大；我习惯只记录增量内容，或者只记录首末 chunk 的时间。

关于函数调用，也就是tools能力，各家的实现差异其实不小。LiteLLM 的做法是让你按熟悉的方式组织tools，适配器负责转成目标厂商要求的格式。我的建议是：先在小流量场景验证一次，确认工具调用参数能正常往返，再全面铺开。

3.3 密钥管理：环境变量比硬编码靠谱得多

有人图省事，直接把密钥写在代码里，然后提交到仓库。这种事一旦发生，基本等于把模型预算的钥匙交了出去。我在项目里都是环境变量加上本地配置文件，代码里不出现任何真实的密钥。

export SUPPLIER_A_API_KEY="sk-xxx" export SUPPLIER_B_API_KEY="sk-yyy"

如果用的是代理模式，还可以在服务端统一管理密钥，客户端调用时无需知道任何厂商密钥。这个细节后面展开。

4. 进阶：把 LiteLLM 跑成团队网关服务

4.1 为什么要用代理模式而不是各自引用

Python 库模式适合单个服务内部使用，但一旦你服务多了，问题就来了：每个服务都要配密钥，每个服务都要单独设置重试和超时。万一供应商临时要换一个模型名，你得把所有服务的配置都改一遍。

代理模式就是解决这个问题的。LiteLLM 可以启动一个本地服务，对外暴露一个统一的 HTTP 接口，团队内部所有服务都通过这个接口访问模型。业务服务不需要再关心接的是哪家服务商，也不需要持有任何厂商密钥。

我用下来最大的感受是，这层代理把"模型路由"和"业务代码"彻底拆开了。模型怎么切、怎么降级、怎么限流，是网关层面的事；业务服务只需要知道网关地址和虚拟密钥。

4.2 一份可以上手的配置示例

代理模式的管理核心是配置文件。我用的是 YAML，大致长这样：

model_list: - model_name: chat-main litellm_params: model: supplier_a/model-7b api_key: os.environ/SUPPLIER_A_API_KEY - model_name: chat-fast litellm_params: model: supplier_b/model-tiny api_key: os.environ/SUPPLIER_B_API_KEY

启动方式：

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

启动后，内部请求地址是http://localhost:4000/v1/chat/completions，请求体沿用统一的 Chat 格式。调用方只需要把 base_url 指向这个地址，model 参数填chat-main或chat-fast这样的别名就可以。

这里有一个我很推荐的用法：给模型起别名时，不要直接用真实模型名，而是按用途命名。比如chat-main表示主线对话模型，chat-cheap表示低价备选模型。哪天你想换供应商，只要在配置文件里改映射关系，业务方完全无感。

4.3 团队接入方式与统一管控

代理模式下，团队内部可以给每个业务方发一个虚拟密钥，用来区分调用来源和权限。比如 A 服务用自己的虚拟密钥，B 服务用自己的，每一笔请求量、花销、错误率都能归到对应密钥上。

实际运营时，我还会在代理层做三个事：给不同业务方设置调用频率上限；给每个密钥设置月度消费上限；把厂商原始密钥统一锁在网关环境变量里，开发机不需要也不应该接触厂商密钥。

这个模式对安全也有好处。厂商密钥一旦分发出去，很难追踪谁在用；而虚拟密钥可以随时吊销，权限回收的成本低很多。

5. 生产环境踩坑记录：限流、超时和格式不一致

5.1 限流和自动重试：默认行为没那么可靠

第一次上生产时，我以为代理层自动重试就够了，结果高峰期还是出现了大量超时。后来看日志，原因是限流触发后，上游服务还没缓过来，请求又在同一时间被重试，把原本已经拥堵的通道顶得更满。

后来我在配置里做了两件事：限制单实例并发请求数，设置冷却时间。比如某个厂商账号并发上限是 10，我就把单实例并发控制在 8 左右，留出余量；一旦上游返回限流错误，短时间内不再把新请求发给这个实例，而是直接走备用模型或返回降级结果。这个"先保护上游，再谈重试"的思路，比盲目重试稳妥得多。

5.2 超时与慢请求：网关也需要止损

模型服务有个特点：正常情况下 1 到 3 秒返回，但偶尔会拖到十几秒甚至更久。如果不设超时，调用方会一直占着连接池，最终把整个服务拖垮。

我的做法非常朴素：在网关层给每次调用设置一个总超时，比如 30 秒；内部再做细分，连接超时短一些，读取超时长一些。用户侧对慢响应一般能容忍 3 到 5 秒，超过这个时间就可以直接提示"系统繁忙"。关键是，超时之后还要记住一点：上游可能已经生成了结果，只是响应没回来。所以涉及扣费、状态变更的操作，要设计成幂等，避免超时重试导致重复扣费。

5.3 token 和上下文相关报错的几个常见现场

生产上最常遇到的错误不是密钥失效，而是上下文长度超限。不同厂商的上下文窗口不一样，有的返回非常详细的错误说明，有的只给一个泛泛的失败信息。

我的排查惯例是：先看是不是消息数量太多，把系统提示词、示例对话、历史消息都清点一遍；再用 token 估算工具确认实际占用；最后看厂商文档给的上限值。切模型时尤其要小心，同一个对话在供应商 A 能跑，换到供应商 B 可能就超限，因为两者的上下文策略不同。

还有一个细节：有些模型服务对messages里的角色有严格限制，比如某类角色不能连续出现，或者最后一条必须是用户消息。这类错误报错信息不一定明确，如果你遇到"请求格式错误"但看不出原因，优先检查消息序列是否符合目标厂商的规则。

6. 成本治理与可观测性：让每笔模型调用都有账可查

6.1 单次调用的成本怎么算

模型调用成本往往不是按次收费，而是按输入、输出 token 分别计价。不同厂商的计价规则差异很大，靠人肉估算容易算错。

LiteLLM 自带成本计算能力，你可以在一次调用结束后直接算出参考费用：

from litellm import completion_cost cost = completion_cost(response) print(cost)

这个值可以随日志一起落库，也可以作为监控指标上报。我的习惯是给每个业务场景打上标签，比如"客服问答""内容总结""代码生成"，这样月底能一眼看出哪条业务线消耗最大。

需要提醒的是，成本计算依赖模型名称和厂商的价目表。如果你的模型不在内置列表里，或者用的是私有化部署的服务，价格需要单独配置。不要拿一个未知模型的估算成本去做财务决策，先核实计费口径再上线。

6.2 自定义日志与线上追踪

很多人把日志系统搭得很重，但模型调用的日志往往被忽略。实际上，模型调用的日志价值极高：它能告诉你每次请求发了什么、返回了什么、用了多少 token、耗时多久、成本多少。

我一直保持一个习惯：每条日志至少记录请求 ID、模型名称、业务标签、输入 token、输出 token、耗时、成本、返回状态。请求 ID 还可以关联到上游链路，排查问题时能从头追到尾。

LiteLLM 支持注册自定义回调，把调用详情推送到已有的日志或监控平台。比如每次调用完成时，把response.usage和cost写进数据表。这样即使模型调用分散在不同服务里，只要都走统一网关，日志格式还能保持一致。

6.3 我的日常监控习惯

落到实操上，我日常会盯三类指标：请求成功率、P95 耗时、单日成本。成功率低于阈值就报警；P95 耗时过高说明某个模型服务变慢，需要考虑切流量到备用模型；单日成本异常飙升，通常对应某条业务线流量上涨或者某个模型价格调整。

还有一个习惯建议也给到大家：线上切模型，不要一次性全部切过去。我会先在网关配置里把新模型的流量比例调到 10%，观察两天，看成功率和耗时没问题，再逐步提高比例。这个过程完全不需要业务方参与，对用户也没有感知，但能避免很多事故。

我现在的日常流程基本固定了：凡是需要新接入的模型，先本地脚本试通，再放到网关里小流量验证，稳定后全量切换，最后把成本监控同步接上。模型更新速度那么快，真正决定工程质量和工作效率的，往往不是模型本身，而是接入层能不能干脆利落地更换。