FDE W7D5 学习手册 · LiteLLM 集成与 Build vs Buy ADR

W7 Day5 · B/C 级（企业平台与架构决策核心）· 4h · 学完能讲清"企业级模型网关选型 + 自研 vs 购买决策 + ADR 写作"

一、LiteLLM 是什么与定位

1.1 一句话定位

LiteLLM 是一个轻量级 LLM 网关 / 统一调用层，核心解决两件事：① 用统一的 OpenAI 格式 API 调用 100+ 家模型（OpenAI / Anthropic / Gemini / 本地 vLLM 等）；② 提供企业级治理能力——虚拟 Key、预算、配额、多租户、项目级成本、管理界面。

1.2 两个最常用的形态

• Python SDK（litellm）：代码里直接 litellm.completion(model=..., messages=...)，统一各家调用格式，适合把"调不同厂商"这件事收口。
• Proxy Server（litellm-proxy）：起一个 HTTP 网关服务，对外暴露 /v1/chat/completions，背后接各家模型；治理（Key/预算/租户）主要在这里做。

二、虚拟 Key（Virtual Key）机制

2.1 原理

LiteLLM 对外给用户/应用发的是虚拟 Key（也叫 Consumer Key / Token），用户用这个 Key 调 Proxy；Proxy 内部再拿真正的"厂商 Master Key"去调模型。真实厂商 Key 不暴露在业务侧。

2.2 虚拟 Key 能做什么

三、预算（Budget）与配额（Quota / Rate Limit）

3.1 预算

预算是钱/Token 的上限，可设在不同粒度：

• Key 预算：单个虚拟 Key 的总额度（如每月 $50）。
• 用户/团队预算：某团队一个月能花多少。
• 项目预算：某项目周期内额度（见 3.4）。

预算超限后，请求被拒（返回 429 / budget exceeded），避免"一个失控的调用把整月额度刷爆"。

3.2 速率配额（Rate Limit / RPM-TPM）

• RPM（Requests Per Minute）：每分钟请求数上限。
• TPM（Tokens Per Minute）：每分钟 Token 数上限。
• 可防止单一 Key 把厂商限速打满，影响其他业务。

3.3 模型级白名单

每个虚拟 Key 可限制只能用哪些模型（如只准用便宜的 gpt-4o-mini，不准用贵的 o1）。这是"成本护栏"的控制点。

四、多租户（Multi-tenant）与项目级成本

4.1 多租户模型

LiteLLM 用 team / organization 维度组织租户。不同团队是不同租户，各自有 Key、预算、模型权限；平台方在后台统一看总成本和各租户分布。

4.2 项目级成本（Project / Tag）

• 每次请求可带 metadata={"project":"claims-extract"} 等标签。
• Proxy 按标签聚合成项目级成本报表：哪个项目花了多少、调了哪些模型。
• 这是"AI 成本内部结算/Chargeback"的基础——IT 部门能跟业务线算账。

4.3 成本数据从哪里来

Proxy 把每次调用的 token 用量、模型、耗时、Key/团队/项目写到数据库（Postgres/MySQL）或日志/BI。LiteLLM 提供 /spend 接口和 Daily Spend 报表做查询。

五、管理界面（Proxy UI / Spend Dashboard）

5.1 提供什么

• Key 管理 UI：可视创建/吊销虚拟 Key、设预算。
• Daily Spend 报表：按天、按 Key、按模型看花费。
• 请求日志：看每次调用谁、用什么模型、花多少、成功失败。
• User / Team 管理：在多租户场景分配角色。

5.2 工程价值

没有 UI 时，运营/财务查成本得登数据库跑 SQL；有 UI 后，非技术人员也能自助看。交付企业平台时，这直接关系到"甲方能不能自己用起来"。

六、LiteLLM Proxy 的部署形态

6.1 部署方式

6.2 配置要点

• config.yaml：配置模型列表、路由、默认参数。
• 环境变量 / Secret：厂商 Master Key、数据库密码放 Secret，不放明文。
• 数据库：用 Postgres 存 Key、预算、Spend（生产建议独立、有备）。
• 回调（Callbacks）：把日志/成本推到 Kafka / Datadog / 自研平台。

七、与 Spring AI 的集成方式

7.1 集成思路

Spring AI 的 OpenAiChatModel（或兼容 OpenAI 的客户端）只要把 base-url 指向 LiteLLM Proxy 地址、把 api-key 填成虚拟 Key，就能无缝调用。对 Java 业务代码而言，背后是 LiteLLM 还是真 OpenAI 完全透明。

# Spring AI 配置示例（application.yml）
spring:
  ai:
    openai:
      base-url: http://litellm-proxy:4000/v1   # 指向 LiteLLM 代理
      api-key: sk-virtual-xxxx                 # 虚拟 Key
      chat:
        options:
          model: gpt-4o-mini

7.2 分层职责

八、Build vs Buy 决策框架总览

8.1 本质问题

"自研 Gateway（D4 讲的那种）还是直接用 LiteLLM（买/用开源）？"这是一个经典的 Build vs Buy 决策。框架不是二选一，而是用一组维度打分。

8.2 评估维度

九、何时选择自研 Gateway（D4 场景）

9.1 适合自研的信号

• 深度定制路由：需要按业务语义做复杂路由（如"理赔类走私有模型、营销类走公有模型"的自定义策略），LiteLLM 的路由规则表达不了。
• 已有统一治理底座：公司已有 Java 微服务治理体系（Spring Cloud 网关、自研鉴权），再塞个 Python Proxy 反而割裂。
• 特殊合规/审计：监管要求调用链路、留痕格式完全自定义，开源产品改不动。
• 团队能力差补：核心能力（如私有模型调度）是竞争力，不愿依赖外部。

9.2 自研的成本（要诚实说）

自研意味着你要自己实现：虚拟 Key、预算扣减、配额、多租户、成本落库、UI、高可用——这些 LiteLLM 白送的，你都得造。D4 讲的"自研 Gateway 最小集"就是这部分。

十、何时选择直接用 LiteLLM

10.1 适合直接用的信号

• 要快速拿到企业治理能力：虚拟 Key、预算、多租户、成本报表开箱即用，正是 D5 讲的能力。
• 模型厂商多、切换频繁：LiteLLM 统一格式，换厂商不改业务代码（Spring AI 只认一个地址）。
• 团队小/交付急：没有余力养一套自研网关。
• 需求在 LiteLLM 能力边界内：路由/预算/租户都用标准功能即可满足。

10.2 什么情况会"卡脖子"

若需要 LiteLLM 没有的扩展（如特定内部鉴权协议、私有模型特殊调度），要么用它的 callback/hook 扩展点，要么在它外面再包一层薄适配——而不是推翻重造。

十一、ADR（架构决策记录）怎么写

11.1 ADR 是什么

ADR（Architecture Decision Record）是记录"为什么做这个架构决策"的轻文档。它不描述系统怎么搭，而是记录"在 X 背景下，我们决定做 Y，权衡了 Z，后果是 W"。目的是让后人（包括 6 个月后的自己）理解"当时为什么这么选"。

11.2 标准四段结构

十二、示例 ADR：是否引入 LiteLLM 作为模型网关

12.1 模板示例

ADR-007  引入 LiteLLM 作为企业模型网关

【背景】
W7 要落地企业 Agent 平台，需统一调用多家模型，并具备虚拟 Key、
预算、多租户与成本结算能力。团队以 Java 为主，交付窗口 2 个月。

【决策】
采用 LiteLLM Proxy 作为模型网关层；Spring AI 通过 OpenAI 兼容
接口对接；厂商 Master Key 存 Secret，业务侧只持虚拟 Key。

【权衡】
- 自研 Gateway：可控性高，但要 1-2 人月并实现全套治理能力，超限。
- 直接用 LiteLLM：开箱治理能力，私有部署满足数据不出网；不足处
  用 callback 扩展，不推翻重造。 → 选此项。
- 直连厂商不使用网关：最简单，但无预算/租户/成本，否决。

【后果】
+ 2 周内具备企业治理能力，Spring AI 零改造接多模型。
+ 成本可按团队/项目结算，支撑内部 Chargeback。
- 引入 Python 组件，需建立运维与版本跟进能力。
- 后续若遇标准能力外的定制，需评估 hook 扩展或薄适配层。

十三、面试达标线①：讲清 LiteLLM 的企业能力

十四、面试达标线②：Build vs Buy 框架 + ADR 结构

1. Build vs Buy：不是站队，是按维度评估；金融场景重点看数据不出网、合规审计、团队能否运维 Python。
2. 自研信号：深度定制路由、已有 Java 治理底座、特殊合规、核心能力不愿外包。
3. 直接用信号：要快速拿治理能力、厂商多切换勤、团队小、需求在能力边界内。
4. ADR 背景：写清业务/合规/团队/时间约束，让决策有根。
5. ADR 决策：一句话结论 + 范围，可验证。
6. ADR 权衡：列出备选方案及否决理由，证明比较过。
7. ADR 后果：正面 + 负面 + 后续动作，诚实列技术债。

十五、W7D5 自测清单

十六、高频面试题速记卡