FDE W1D4 学习手册 · 多模型统一接入

W1 Day4 · A 级（必须掌握，面试核心）· 4h · 学完能画出统一接入层架构，并讲清超时/重试/Fallback/Trace/成本记录的全链路设计

一、为什么需要统一接入层

裸调各家 API 的痛点：每个厂商的请求格式、鉴权、响应结构、错误码、流式格式都不同。业务代码若直接耦合 Qwen/DeepSeek/Claude/Ollama，会带来：

• 厂商锁定：换模型要改业务代码，无法快速 A/B 或迁移。
• 容错缺失：某家宕机就全链路挂，无 Fallback。
• 不可观测：成本、延迟、错误率散落各家，无法统一分析。
• 重复造轮子：超时、重试、Token 统计每个调用点各写一遍。

统一接入层（Unified Model Gateway）把这些横切关注点收口到一层，业务只面对"一个统一接口"。

二、统一请求结构（Model Adapter）

2.1 原理

定义一个与厂商无关的内部请求/响应结构，所有业务都用它。Adapter 负责把它翻译成具体厂商格式，再把厂商响应翻译回统一结构。

2.2 统一请求字段（建议）

2.3 统一响应结构

{
  "content": "模型文本输出",
  "finish_reason": "stop",
  "usage": { "prompt_tokens": 120, "completion_tokens": 30, "total_tokens": 150 },
  "model": "qwen-max",         // 实际命中的底层模型
  "provider": "qwen",
  "trace_id": "tr-abc-123",
  "latency_ms": 820
}

三、Provider Adapter（Qwen / DeepSeek / Claude / Ollama）

每个厂商一个 Adapter，实现统一接口 chat(req) → UnifiedResponse。差异点：

3.1 关键差异处理

• Claude 的 system 是顶层字段，不是 messages 里的 role=system；Adapter 要拆分。
• Claude 错误码与限流：429 限流、529 过载，需单独映射。
• OpenAI 兼容族（Qwen/DeepSeek/Ollama 多数）可共用一个基类 Adapter，仅改 base_url 和 key。
• 工具调用：Claude 走 tool_use，OpenAI 系走 tool_calls，统一层要抽象成一套中间表示。

四、模型路由（Routing）

4.1 原理

路由决定"这次请求走哪个逻辑模型"。可按多维度决策：

• 静态路由：配置写死（如"抽取类走 qwen，推理类走 claude"）。
• 基于能力/成本：简单任务→小模型，复杂→大模型（级联）。
• 基于可用性：主模型健康度下降→切备模型（与 Fallback 配合）。
• 基于 A/B / 灰度：按 user_id 哈希分流做实验。
• 基于语义分类：先分类问题类型再路由（如"政策问答→RAG+某模型"）。

五、超时与重试

5.1 超时设计

• 连接超时（如 3s）：建连慢说明网络/服务异常，早失败。
• 读取超时（如 30~60s）：生成慢，按场景设上限（流式可更长）。
• 整体超时预算：业务侧有 SLA，留给模型调用的时间有限，超时即降级。

5.2 重试策略

六、Fallback（降级）策略

6.1 原理

当主模型失败（超时/限流/5xx/内容违规）且重试耗尽，自动切换到备用模型/方案，保证业务不中断。

6.2 Fallback 层级

1. 同厂商换模型：qwen-max 挂 → qwen-plus。
2. 换厂商：qwen 挂 → deepseek / claude（需语义等价，注意风格差异）。
3. 换小模型/规则：复杂模型都挂 → 退简单模型或规则兜底。
4. 缓存/默认/转人工：都不可用 → 返回缓存答案、兜底文案或转人工。

6.3 Fallback 设计要点

• 等价性：Fallback 模型要在该任务上"够用"，不能降级成答非所问。
• 避免连环失败：Fallback 本身也要有超时，否则卡在备选。
• 快速失败标记：记录本次是否走了 Fallback，供监控与计费。
• 熔断：某模型连续失败，暂时从路由摘掉（circuit breaker），恢复后再放。

七、Token 统计与成本记录

7.1 为什么记

• 成本核算：按业务线/用户/功能分摊模型费用。
• 异常监控：某调用突然 token 暴涨，可能是 prompt 注入或死循环。
• 容量规划：预测预算、识别高成本路径。

7.2 记录维度

八、Trace ID 与全链路追踪

8.1 原理

每个请求生成唯一 trace_id，在网关、路由、各 provider 调用、重试、Fallback、业务处理间全程透传。所有日志/指标都打上它，可回放一次请求的完整链路。

8.2 要记录的字段

• trace_id、parent/span 关系（一次请求可能调多次模型）。
• 每次模型调用：model_key、实际 provider、latency_ms、usage、finish_reason。
• retry_count、is_fallback、fallback_to、error_type。
• 业务上下文：user_id、功能模块、输入/输出摘要（脱敏）。

九、流式输出（Streaming）

9.1 原理

流式让模型"边生成边返回"，首字延迟（TTFT）大幅降低，用户体验更好。底层多为 SSE（Server-Sent Events）增量 chunk。

9.2 统一层要做的事

• 归一 chunk 格式：各厂商增量结构不同，统一成 {delta, finish_reason, usage?}。
• TTFT / TPOT 指标：首字延迟、每 token 间隔，是衡量体验的关键指标。
• 中断与取消：用户关闭连接要能取消后端调用（节省算力）。
• 流式下的超时/重试：已开始流式又中断，重试策略要谨慎（可能重复内容）。

十、统一接入层架构图（达标线核心）

十一、LiteLLM 等开源方案

不必从零造轮子，社区已有成熟统一接入层：

十二、医疗保险实战：多模型冗余接入

医保理赔系统对可用性和合规都极敏感。设计统一接入层：

• 主备冗余：主用本地 Qwen/Ollama（数据不出域），备用地端 DeepSeek/Claude（仅脱敏后复杂 case）。
• Fallback 链：本地模型超时 → 地端大模型（脱敏数据）→ 规则兜底/转人工。
• 合规脱敏：出域前 Adapter 层做 PII 脱敏（姓名/身份证/病历摘要打码），Trace 日志不落明文。
• 成本分摊：按"理赔单号/机构"记录 token，内部结算。
• Trace 串联：从用户提交到最终判定，trace_id 贯穿所有模型调用与人工环节。

十三、面试达标线①：画出统一接入架构

面试官："画一下你们的多模型统一接入层。"标准回答要包含 5 段：业务 → 网关（路由/超时/重试/Fallback/流式）→ Provider Adapter → 厂商 → 横切（成本+Trace）。

1. 业务侧：只发统一请求（带 trace_id、model_key）。
2. 网关：路由选模型 → 超时控制 → 重试（退避限次）→ Fallback（熔断）→ 流式归一。
3. Adapter 层：每个厂商一个，翻译请求/响应、归一错误码与 usage。
4. 厂商/本地：Qwen/DeepSeek/Claude/Ollama。
5. 横切：Token 成本记录 + Trace 全链路 + 监控告警。

十四、面试达标线②：Fallback + 成本/Trace 记录

14.1 Fallback 怎么设计

• 层级：换模型 → 换厂商 → 小模型/规则 → 缓存/转人工。
• 备选要任务等价；要有超时防连环；要熔断（连续失败临时摘除）。
• 记录 is_fallback、fallback_to，供监控。

14.2 成本与 Trace 怎么记录

十五、Day 4 自测清单

十六、高频面试题速记卡