64 lines
3.1 KiB
Markdown
64 lines
3.1 KiB
Markdown
# Provider Routing 技术说明
|
||
|
||
本说明用于支撑求职版 DreamWeaver 的 Provider 分层表达。当前目标不是做复杂平台化，而是把 AI 能力供应链讲清楚、跑稳定、便于后续演进。
|
||
|
||
## 核心概念
|
||
|
||
| 概念 | 含义 | 当前代码位置 |
|
||
| --- | --- | --- |
|
||
| Capability | 产品需要的 AI 能力类型，例如文本、图片、语音、绘本结构 | `backend/app/services/provider_policy.py` |
|
||
| Provider | 某个能力下的可调用供应商配置，例如 Gemini、OpenAI、CQTAI、MiniMax | `providers` 表与 `provider_cache.py` |
|
||
| Adapter | 供应商调用实现，负责把统一入参翻译成具体 API 调用 | `backend/app/services/adapters/` |
|
||
| Routing Policy | 调用前如何排序与选择 Provider，例如优先级、成本、延迟、轮询 | `provider_policy.py` + `provider_router.py` |
|
||
| Failover | 当前 Provider 调用失败后自动尝试下一 Provider | `provider_router.py` |
|
||
|
||
## 当前 Capability
|
||
|
||
| Capability | 用途 | 默认 Provider | Demo Provider |
|
||
| --- | --- | --- | --- |
|
||
| `text` | 生成/润色儿童故事文本 | `gemini`, `openai` | `demo` |
|
||
| `image` | 生成封面和绘本插图 | `cqtai` | `demo` |
|
||
| `tts` | 故事语音合成 | `minimax`, `elevenlabs`, `edge_tts` | 无 |
|
||
| `storybook` | 生成多页绘本结构和插图提示词 | `storybook_primary` | `demo` |
|
||
|
||
`ENABLE_DEMO_PROVIDERS=true` 时，只会给具备 demo adapter 的能力前置 `demo` provider。TTS 暂无 demo adapter，因此不会插入不存在的 `tts:demo`。
|
||
|
||
## 代码边界
|
||
|
||
`provider_policy.py` 负责定义“产品级策略”：
|
||
|
||
- Capability 清单
|
||
- 默认 Provider 顺序
|
||
- `.env` 中对应的 provider 列表字段
|
||
- 默认 routing strategy
|
||
- API key ref 到 settings 字段的映射
|
||
- 哪些能力支持本地 demo provider
|
||
|
||
`provider_router.py` 负责执行“运行时路由”：
|
||
|
||
- 从 DB cache 或 `.env` 读取 Provider 配置
|
||
- 构建 `AdapterConfig`
|
||
- 按 Routing Policy 排序
|
||
- 熔断过滤
|
||
- 调用 adapter
|
||
- 记录 metrics、health、cost
|
||
- failover 并聚合错误
|
||
|
||
`adapters/` 负责具体供应商 API：
|
||
|
||
- 不决定业务工作流
|
||
- 不读取用户故事上下文
|
||
- 不负责 Provider 排序或熔断
|
||
|
||
## 演进原则
|
||
|
||
- 新增 AI 能力时，先在 `provider_policy.py` 增加 Capability，再注册 adapter。
|
||
- 新增供应商时，先实现 adapter，再把默认顺序或 DB 配置接入对应 Capability。
|
||
- 路由策略只影响调用顺序，不应该改变故事/绘本/音频的产品工作流。
|
||
- 本轮求职版不做多租户供应商市场，也不做复杂负载均衡；优先保证能力分层清楚、失败可恢复、演示稳定。
|
||
- 后台 `config_ref` 可以使用 adapter 别名，也可以直接使用 settings 字段名，例如 `text_api_key`、`antigravity_api_key`。
|
||
|
||
## 面试表达口径
|
||
|
||
DreamWeaver 的 Provider 体系不是把供应商暴露给用户，而是把多模型能力整理成稳定的产品能力。用户看到的是“生成故事、生成封面、播放语音”，系统内部才把它映射到 `text`、`image`、`tts`、`storybook` 这些 Capability，再通过 Routing Policy 选择具体 Provider 和 Adapter。
|