设想一个客服团队:机器人只查帮助中心,后端拿一个 Key 调模型。接入运营摘要和工单分析后,不同部门开始争用额度:慢请求拖住连接,429 的来源说不清,账单只能按供应商看,无法分到业务。这是用于讨论架构的示例团队,不是某家企业的生产复盘。
下面把问题放进一个能运行的实验:LiteLLM Proxy 前面接客户端,后面接两个 FastAPI 模拟模型。所有故障、Token 和费用都是本地测试数据,没有调用收费模型。核验日为 2026 年 11 月 11 日;当日最新非预发布版为 1.109.0,工程选用 1.108.5 LTS,镜像同时锁定 digest。版本依据
一次调用,怎样长成一套治理系统
单上游调用只需这些代码。本地 Primary 实现了 Chat Completions,所以示例可以直接执行:
from openai import OpenAI
client = OpenAI(
api_key="mock-only",
base_url="http://127.0.0.1:18081/v1",
max_retries=0,
)
answer = client.chat.completions.create(
model="demo-primary",
messages=[{
"role": "user", "content": "local hello"}],
max_tokens=32,
)
print(answer.choices[0].message.content)
当客服与运营共用它,调用前要识别部门、检查模型权限与预算、占用并发额度;调用中要选择部署、处理限流和超时;返回后还要结算并记录归因。如果把这些逻辑分别塞进两个后端,同一条预算规则就有两套实现,换供应商也可能要求一起发版。
我们把公共治理收进网关,业务只持有受限的虚拟 Key,并调用 support 这个模型别名。普通 API 网关已有认证、流控等能力;LLM 治理还要理解 Token 用量、模型能力、价格和流式终止状态,按请求数限流不够。
flowchart LR
C[客服与运营后端] --> G
subgraph G[LiteLLM 数据面]
A[虚拟 Key 与授权] --> L[RPM / TPM / 并发]
L --> B[预算预留与检查]
B --> R[部署选择 / 重试 / Fallback]
end
R --> P[Primary 模拟模型]
R --> Q[Backup 模拟模型]
M[管理 API 与配置] -.策略与密钥.-> G
G <--> D[(PostgreSQL)]
G <--> S[(Redis)]
G --> O[Prometheus]
图中控制面管理 Key、价格和策略,数据面执行请求;这是职责划分,演示没有把两者拆成独立服务。PostgreSQL 保存身份与消费记录,Redis 共享治理状态;本次只启一个 Proxy,未验证多副本一致性。回答缓存关闭,避免缓存命中掩盖故障。请求生命周期
便宜模型能不能接这次请求,必须先回答
对退款 Agent,能否正确续接工具结果,比单价更重要。一个合理顺序是:按授权、地域、协议、模态、工具和上下文筛硬约束,排除不健康部署,再按软目标评分,选定执行模型。上下文放不下、缺少工具能力的模型,即使免费也不应入选。
阿里云智能路由文章把能力门槛与成本、速度等优化偏好分开,也把选主模型与失败兜底分开。这是可借鉴的决策方式,不代表 LiteLLM 的一个 YAML 开关自动实现了相同任务识别。阿里云路由说明
LiteLLM 同一 model_name 下可挂多个部署;不同组之间另配 Fallback。工程的关键配置如下,完整文件还包含备用组和每 Token 的模拟价格:
model_list:
- model_name: support
litellm_params:
model: openai/demo-primary
api_base: http://primary:8000/v1
api_key: mock-only
max_retries: 0
router_settings:
routing_strategy: simple-shuffle
num_retries: 1
timeout: 2
stream_timeout: 2
allowed_fails: 2
cooldown_time: 5
fallbacks:
- support: [support-backup]
simple-shuffle 配权重是加权随机,并非严格加权轮询。补充实验在真实 Router 选择器上设 9:1、固定随机种子,10,000 次选择得到 9009:991;它验证概率偏向,不能保证每十次恰好九次主部署。
同一组还可选 least-busy、latency-based-routing 或 cost-based-routing。通过注入在途计数和历史样本,选择器分别选中了较空闲、较低延迟的候选;流式选择使用 TTFT 样本。值得注意:该版成本策略按输入、输出单价之和比较,不能宣传成按本次输入输出比例计算的最省总价。这些是选择器级验证,不是上游性能压测。固定版成本实现
冷却用于暂时排除故障部署,不等于已配置主动健康探测。探测也应覆盖实际协议和必要能力,不能仅凭端口连通就放回候选。Agent 的一次任务应保留实际模型绑定;工具结果续接时不能只因价格波动重选。明确新任务,或原模型失效且完成上下文与工具状态兼容性检查后,才考虑重新绑定。本文未验证自动会话亲和。
降级还需要约定业务结果:备用模型若只会普通问答,就不能接管正在执行工具链的任务。可以退回人工客服、暂存工单或明确提示稍后重试。把请求交给一个会返回200的模型,只解决了传输可用性,不能证明它完成了原任务。
限流通过了,为什么预算仍可能越线
RPM 管每分钟请求数,TPM 管每分钟 Token,并发限制管在途请求;Budget 管一个周期的金额。四者不能互相替代。下面是可组合的 Key 配置示例;本次实验分别设置各项,实际管理 API 调用见工程脚本:
{
"models": ["support", "support-backup"],
"rpm_limit": 2,
"tpm_limit": 1000,
"max_parallel_requests": 1,
"max_budget": 0.01,
"budget_duration": "1h"
}
限流、预算实验分别建新 Key,避免多个限制一起触发而误判。RPM=2 连发三次得到 200、200、429;TPM=10 的长输入得到 429;并发上限为1时,三个并行请求只放行一个。
Token 准入需要估算输入,并为输出预留额度;响应后用真实 usage 调整。多实例必须共享计数,预留不能用各进程独立的“读取后加一”。LiteLLM 此版已默认尝试金额预算预留,通过 Redis 原子增量协调,再按实际成本调整;跨 Key、团队等多个计数并不构成一笔完整事务,DB 汇总仍在后台持久化。预算文档
实验给 mock 固定声明输入20、输出10 Token,模拟单价分别为每 Token 0.000001、0.000002美元,单次成本为 0.00004美元。它们是测试夹具,不是真模型的分词或报价。
预算设0.00006美元,默认配置连续放行两次,合计0.00008美元,后续请求返回 422。原因不只是异步记账:源码允许在仍有余额、但放不下完整估算时缩额预留。复跑中首笔 /key/info 在最初数秒仍显示0;持久化另外通过SQL轮询核对,不拿这次查询作为实时余额。默认缩额分支
对照打开 general_settings.fail_closed_budget_enforcement: true,预算0.0001美元,第一笔成功;第二笔已有消费0.00004美元,再加预估0.000073美元放不下,返回422。另一次8并发默认实验放行2笔、拒绝6笔,DB最终记录0.00008美元;不能从这一次未超额推导所有并发都零误差。
严格设置也要核查价格是否齐全、输出上限是否有效和共享后端故障策略。部分无法定价的路由会退化为按已记录消费检查;预算告警更只是通知,不能当作硬准入承诺。
预留金额也不等于最终账单。失败重试可能已经消耗上游资源,连接中断又可能拿不到最终usage;缓存输入、推理Token及特殊模态还有不同计价规则。需要将网关已捕获费用与供应商账单对账,对缺失用量单独标记,不能把“没有记录”直接算成零元。本文验证的是人为单价与固定usage的计算链路。
不同产品计量时点也不同:Azure 策略可请求前估算,流式还有特定估算规则;Kong 对应插件按上游返回用量更新,后续请求才体现已发生费用。两者都要看并发与同步边界,不能把任意 Token 限制写成精确财务账本。Azure策略、Kong插件
返回200之前与之后,是两种故障
负载均衡是在同组部署间分流;Retry 是同组重新尝试,可能选到其他部署;Cooldown 暂时移除故障部署;Fallback 才跨到另一个模型组。配置一次重试并不保证所有错误都重试一次,异常类别与健康状态会影响执行。可靠性说明
工程启动后,在虚拟环境中运行:
python tests/run_experiments.py --case all
Primary 分别返回503和带 Retry-After: 1 的429,两次实验均观察到主部署尝试2次、备用1次,最终200。最终复跑的单次端到端耗时分别约2.62秒、2.34秒;每次尝试2秒的 timeout 显然不等于整个调用链2秒截止。
| 错误 | 业务应制定的处理原则 |
|---|---|
| 上游429 | 尊重Retry-After,限制总尝试次数;先区分网关自身限流 |
| 500/502/503 | 判断临时故障及备用兼容性,再重试或切换 |
| 连接超时 | 确认是否已提交;未收到结果不代表上游未执行 |
| 400 | 检查参数,避免盲目重复 |
| 401/403 | 检查凭据与授权,不当作普通拥塞 |
| 上下文超限 | 缩减上下文,或选有足够容量且兼容的组 |
这些是工程原则,并非对 LiteLLM 默认错误策略逐项复述。退避加抖动可以缓解同步重试,但仍要给业务、网关和SDK分配统一的总次数与截止时间。本例关闭客户端SDK重试;退款、发券等有副作用操作必须用业务幂等键去重,不能指望切模型解决。AWS退避模式
SSE 更容易误判。模拟首内容前超时,备用最终完成,最终复跑的客户端首内容等待约6.65秒;模拟已输出 primary: loc 后断开,则收到 HTTP 200 内的error事件,没有 [DONE],Backup 调用为0。流已开始后不能把另一个模型的新答案直接接在旧内容后面。应用应保留部分内容、标明中断,并由用户或明确的恢复协议决定重新生成。
监控要能把“慢”拆开,把“成功”说清楚
配置 callbacks: [prometheus] 后,本次实际读到了请求数、总延迟、输入与输出Token指标,Prometheus target为up。HTTP客户端访问 /metrics 时遇到307,需要跟随重定向。
histogram_quantile(0.95,
sum by (le) (rate(litellm_request_total_latency_metric_bucket[5m]))
)
同一个延迟直方图可取P50/P99;请求数增长率换算RPM,输入、输出Token增长率换算TPM。成功率必须把流中错误计入失败;429和5xx按错误来源拆开,不能只看最终HTTP状态。还应记录TTFT、每输出Token耗时、实际用量定价、Fallback次数,以及按受控租户身份归因的预算消耗。LiteLLM指标
Fallback率的分母应固定为入口逻辑请求数,不能把内部每次重试也算作新用户请求。报警至少区分“备用成功但变慢”和“备用也失败”;否则最终成功率尚可时,主供应商的持续故障会被掩盖。租户维度也不宜直接展开到每个终端用户标签,以免监控序列数量失控。
TTFT应明确是客户端首内容还是网关观察到的首Token。SSE chunk可能含多个Token,不能把chunk间隔直接命名为每Token耗时。OTel当前GenAI规范仍为Development,指标名在演进;本工程导出的是LiteLLM指标,没有宣称已实现最新OTel映射。固定快照
一份请求日志应建立这样的关联;下面是字段示意,完整实测ID见 results/trace.json:
{
"request_id":"trace-local-correlation-001","gateway_call_id":"…",
"model_group":"support","provider":"primary","status":200,
"input_tokens":20,"output_tokens":10,"cost_usd":0.00004}
应用记录request_id与返回的网关call ID;本地实验通过单独的 extra_headers 透传同一非敏感ID,在上游事件中核对。真实部署应由可信入口生成并限制可转发字段,不转发业务Bearer Key。默认不收集完整Prompt、响应正文与密钥;脱敏、访问控制和保存期限同样要覆盖错误日志与指标标签。
收口到网关的权限,止步于业务执行之前
虚拟Key表示业务身份及调用范围,真实供应商Key留在服务端密钥系统,按环境隔离、定期轮换。租户身份由认证结果确定,不能相信请求随手填的tenant字段。网关还要防止日志泄露、限制异常消费,对结构化输出进行schema校验。
Prompt Injection无法用几个关键词正则解决。检索文档、用户文本和工具返回值都可能含恶意指令;模型提出退款工具调用后,执行层仍须校验用户身份、订单归属、金额、状态与幂等键,高风险动作进入人工审批。JSON格式正确也不代表操作被授权。OWASP LLM风险
接入层可以组合使用。
例如灵眸AI定位为多模型API聚合接入服务,可作为统一上游接入与协议适配的一种选择;企业内部的租户预算、审计和业务授权须单独落实。这里引用公开协议文档,其国内备案、并发稳定、可开票等方面契合企业需求。
从现有基础设施出发选方案
| 方案 | 适合评估的起点与代价 |
|---|---|
| LiteLLM | 需要多模型适配、希望控制部署;承担升级与数据库运维,区分MIT主体与商业目录 |
| Kong AI Gateway | 已有Kong治理体系;核对AI许可,2.0架构与旧Gateway插件不可混配 |
| Azure API Management | 已使用Azure API治理;逐项确认服务层级、协议和策略适用范围 |
| Google Apigee | 已有企业API生命周期体系;按参考方案配置模型代理和关联安全服务 |
| 阿里云AI网关 | 希望托管治理并对接现有云环境;以当期产品文档和可用实例验证能力 |
表中比较的是部署与集成条件,不是性能排名。托管与商业产品也不等于同一种交付模式。Kong架构、Azure总览、Apigee参考方案
只有少量固定上游时,可先复用成熟反向代理与密钥服务做轻量入口;若开始自己实现分布式Token预留、跨模型恢复和审计后台,就应重新评估维护成本。
网关也进入了客服的关键链路。上线前应验证配置回滚、数据库连接池、共享计数后端不可用时的拒绝或放行策略,以及一次请求的总截止时间。演示里的单进程和本地持久卷足以观察行为,无法替代这些可用性演练;增加一个入口服务后,运维责任也会随之增加。
这个客服系统可以按入口、密钥、限流预算、路由兜底、可观测、安全审计逐步接入。做完这些,部门额度和供应商故障有了统一处理位置;至于检索是否命中、回答是否可靠、订单能否退款,仍要回到业务系统验证。