Personal AI Infra

LLM Gateway：所有调用收口到一个端点

背景与原理

Gateway 是整套 infra 的单一入口。所有 app 不再认识「Anthropic」「OpenAI」「Gemini」，只认识一个本地端点 http://localhost:4000/v1，统一说 OpenAI ChatCompletions 方言。Gateway 在背后负责真正的 provider 适配、鉴权、记账、缓存、日志。LiteLLM Proxy 是个体最省事的选择：一个 config.yaml 把 100+ provider 映射成统一模型名，跑起来就是一个 OpenAI 兼容服务器。

关键收益是解耦：换底层模型只改 gateway 一处配置，所有下游 app 零改动；想给某个 app 限额、换 key、加 fallback，全在中枢做。这正是下面这张图想表达的——四层都挂在 gateway 后面，app 侧只看见一个端点。

实战示例

# config.yaml —— 统一模型名映射到真实 provider
model_list:
  - model_name: smart            # app 只说 "smart"
    litellm_params:
      model: anthropic/claude-opus-4-8
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: cheap
    litellm_params:
      model: anthropic/claude-haiku-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

# 启动：litellm --config config.yaml   →  localhost:4000
# app 侧零感知 provider：
from openai import OpenAI
client = OpenAI(base_url="http://localhost:4000/v1", api_key="sk-my-virtual-key")
client.chat.completions.create(model="smart", messages=[...])  # 用 OpenAI SDK 调 Claude

跨模型路由与 Fallback：按任务选模型，按可用性兜底

背景与原理

第一维度（成本路由）：不是所有调用都值得 frontier 模型。分类、抽取、格式化、路由判断本身——这些用 Haiku 档够了，价格差一个数量级。把「贵模型默认」改成「便宜模型默认、贵模型按需」，是个体 token 账单立刻砍半的最快动作。

第二维度（可用性 fallback）：provider 会限流、会 5xx、会偶发拒答。Fallback 是一条有序模型链：主模型报错就自动试下一个。OpenRouter 把这个做成了一个 models 数组参数——按优先级排，前一个出错自动落到下一个，最终按真正用上的那个模型计费。LiteLLM 也有等价的 router fallback。

关键纪律：两个维度不要纠缠。成本路由是「我主动选便宜的」，fallback 是「被动兜底别让我挂」。把降级模型误当成本优化，会在 provider 抖动时悄悄把质量也降了还不自知。

实战示例

# 成本路由：先用一句话分类，再决定派哪档模型
tier = classify(task)                       # 用 cheap 模型判断难度
model = "smart" if tier == "hard" else "cheap"

# 可用性 fallback：OpenRouter models 数组，按序兜底
client.chat.completions.create(
    model="anthropic/claude-opus-4-8",
    extra_body={"models": [          # 主模型出错自动顺延
        "anthropic/claude-sonnet-4-6",
        "openai/gpt-latest",
    ]},
    messages=[...],
)
# 响应里 model 字段会告诉你最终实际用了哪个 → 一定要 log 它

Cache 两层：Provider 端 Prompt Cache + 语义缓存

背景与原理

第一层 · Provider prompt caching：缓存的是prefix（前缀）。把稳定不变的部分（system prompt、工具定义、长文档）标上 cache_control，provider 端缓存这段 KV 计算，后续命中只按极低费率收 read。Anthropic 文档明确：cache read 约为基础 input 价的 0.1×，5 分钟 cache write 约 1.25×、1 小时约 2×。这一层是同一个长 prefix 反复调时的省钱利器（agent loop、多轮对话尤其明显），但它只复用计算、不跳过推理——每次还是真调了模型。

第二层 · 语义缓存（GPTCache 这类）：缓存的是整个问答对。新 query 先做 embedding，和历史 query 比相似度，足够像就直接返回旧答案，完全不调模型——延迟和成本都→0。代价是「相似」的判定有风险：阈值松了会返回不该返回的旧答案。

两层正交、可叠加：prefix cache 降每次调用的成本，语义 cache 降调用次数。前者几乎零风险，后者省得多但要管阈值。

实战示例

# 第一层：Anthropic prompt caching —— 给稳定 prefix 打标
client.messages.create(
  model="claude-opus-4-8",
  system=[{
    "type": "text",
    "text": LONG_STABLE_INSTRUCTIONS,          # 长且每次都一样
    "cache_control": {"type": "ephemeral"}  # ← 这段被缓存，read≈0.1×
  }],
  messages=[{"role":"user","content": today_query}],  # 变化部分放后面
)

# 第二层：语义缓存 —— 命中就不调模型（GPTCache 思路）
emb = embed(query)
hit = vec_store.search(emb, threshold=0.95)   # 阈值是关键旋钮
if hit: return hit.cached_answer            # 0 token, 0 延迟
ans = call_llm(query); vec_store.add(emb, ans)

纪律一条：把易变内容放 prefix 末尾。prompt cache 命中的前提是前缀逐字节一致，一个动态时间戳塞在 system 开头就能让整段 cache 全部失效。

Observability 与 Key 治理：看得见花了多少，管得住谁在花

背景与原理

Observability：LLM 调用的可观测和普通 API 不同，你要看的是 prompt/completion 对、token 用量、每次调用成本、延迟、以及（agent 场景）整条调用链。Langfuse 是个体首选的开源方案：可自托管，原生理解 LLM 概念（token、cost、trace、嵌套 span），接 OpenTelemetry 和各家 SDK。装上之后，「这个月哪个 side project 偷偷烧了 $40」从猜测变成一张图。

Key 治理——三条铁律：(1) 真 key 永远不进代码、不进 git，只存环境变量或 secret manager，且只存在 gateway 这一层。(2) 给每个 app 发 virtual key 而非共用真 key：LiteLLM 的 virtual key 支持 per-key 预算、限流、模型白名单、过期时间——某个 app 失控烧钱，只伤它自己的额度，且能单独吊销不影响别人。(3) 预算从小开始（$5–50），按真实用量上调，每把 key 设硬上限——这是个体防「凌晨死循环烧爆账单」的唯一兜底。

实战示例

# Langfuse：装饰器自动 trace，零侵入
from langfuse.openai import OpenAI   # drop-in 替换，自动记 token/cost/latency
client = OpenAI(base_url="http://localhost:4000/v1", api_key="sk-my-virtual-key")

# LiteLLM virtual key：per-app 限额 + 模型白名单 + 过期
# POST /key/generate
{
  "key_alias": "side-project-blog",
  "max_budget": 20,            # 这把 key 这辈子最多花 $20
  "budget_duration": "30d",     # 每 30 天重置
  "models": ["cheap"],          # 只许用便宜档，防误用 opus
  "duration": "90d"             # key 本身 90 天后失效
}