# AI 流水线与 Provider 设计 V1

> 文档状态：当前有效  
> 基线日期：2026-07-15  
> 目的：说明当前 AI 请求如何选择、执行、记录、回退和进入业务资产。

## 1. 设计目标

- 业务不直接绑定单一厂商 SDK。
- 每次调用可解释、可审计、可计费、可重试。
- 同步和异步 Provider 使用统一日志与业务结果。
- 用户指定的模型和参数不被静默替换。
- Prompt 模板、实验请求和原样透传有明确边界。
- AI 失败不会破坏已经确认的业务资产。

## 2. Provider 类型

当前目录覆盖：

- `TextProvider`
- `NovelProvider`
- `ImageProvider`
- `VideoProvider`
- `VoiceProvider`
- `MusicProvider`
- `EmbeddingProvider`
- `ModerationProvider`
- `LipSyncProvider`（抽象存在，真实配置当前关闭）

数据库当前有 112 个 Provider 配置，其中真实配置 101 个、启用 64 个；Mock 配置 11 个、启用 10 个。全局 `AI_PROVIDER_MODE` 当前仍为 `mock`，但业务显式选择真实 Provider 时会产生真实调用。

## 3. 调用选择

一次调用可能同时受到以下输入影响：

1. 用户明确选择的 `provider_code`。
2. 项目级模型偏好。
3. 用户级模型偏好。
4. 业务模块默认 Provider。
5. Provider 启停、优先级、能力和成本限制。
6. AI Router 的业务评分与回退规则。

当前 AI Router 主要用于真人视频，不是全平台统一路由。后续必须固定一套明确优先级，并在调用详情展示：请求选择、路由原因、实际 Provider、实际模型和回退链。

## 4. 请求生命周期

```mermaid
flowchart LR
  Input[业务输入] --> Build[构建请求]
  Build --> Preflight[参数/能力/素材 URL/成本预检]
  Preflight --> Config[解析 ProviderConfig]
  Config --> Submit[同步执行或异步提交]
  Submit --> Log[ProviderLog]
  Log --> Poll[异步轮询/回调]
  Poll --> Normalize[结果归一]
  Normalize --> Asset[Asset / VideoClip / 文本版本]
  Normalize --> QC[质量评估]
  QC --> Pass{通过?}
  Pass -- 否 --> Retry[同模型重试/回退/人工介入]
  Pass -- 是 --> Done[业务确认]
```

### 4.1 请求构建

请求快照至少保存：

- 业务类型和关联项目/分镜/角色。
- 原始输入与最终 Prompt。
- 公共模板版本和是否旁路模板。
- 模型、比例、时长、分辨率、种子等参数。
- 参考素材的资产 ID、顺序和用途。
- 预估成本和用户确认条件。

### 4.2 Preflight

提交前检查：

- Provider 是否启用且类型匹配。
- 参数是否在模型能力范围。
- 参考图数量、格式、大小和顺序。
- 外部 Provider 能否访问临时素材 URL。
- 账户额度和项目成本上限。
- 原生音频、首尾帧、多图参考等能力是否真实支持。
- 实验请求是否要求禁止模板注入。
- 新生产任务的画幅是否为唯一允许值16:9。
- S+ Kling Omni 镜头的每个出场角色是否绑定质检分不低于90的已审批视频角色元素。
- Omni 的图片、视频与元素组合是否满足数量和互斥限制；无参考视频时图片与元素合计不超过7。

### 4.3 结果归一

不同 Provider 的任务 ID、状态、URL、用量和错误格式必须转换为平台统一结构，再写入业务资产。临时 URL 不是最终资产，需下载到私有存储并保存来源信息。

## 5. Prompt 管理

Prompt 分为四层：

1. 业务事实：剧本、角色、场景、动作和台词。
2. 公共质量模板：画质、一致性、可用性和负向约束。
3. Provider 适配：模型特有参数与表达。
4. 本次覆盖：用户人工修改或严格原样提交。

优先级为“本次明确覆盖 > 已确认业务事实 > 公共模板 > Provider 默认”。公共模板不得改变台词、人物、镜头时长或参考图集合。

人物三视图已具备“主锚点参考”和“本次唯一角色描述覆盖”两种模式，并将视觉质检问题沉淀为后续优化经验。经验只能以版本化、可审阅方式进入公共模板，避免单个角色的专用词污染全局。

Kling 正式镜头不再重复大段描述已锁定角色五官。平台从不可变 Generation Plan 读取 `CharacterProviderBinding` 快照，把真实 `element_id` 写入 `element_list`，再在 Prompt 中使用与数组顺序一致的 `<<<element_n>>>` 标记。角色元素控制身份和绑定声线，镜头 Prompt 控制本次动作、表演、空间、台词与摄影。

S+ 结构化写路径新增阶段 Prompt Builder。Source Analyst、Adaptation Showrunner、Episode Planner 的公共模板与项目数据分离，运行时只注入不可变来源快照、已确认父合同和上一集状态。Writer 输出完整合同；Reviewer 只输出问题与结构化修复差异，不静默重写正文。用户可以在调用 Provider 前预览最终阶段 Prompt；Phase 2 默认不提供一键付费生成入口。

## 6. 任务与队列

### 6.1 队列

```text
novel_queue / parse_queue / story_queue / character_queue
episode_queue / script_queue / storyboard_queue / image_queue
audio_queue / subtitle_queue / video_queue / qc_queue
review_queue / analytics_queue
```

### 6.2 平台任务状态

```text
pending / running / success / failed / retrying
cancelled / manual_required / skipped
```

数据库中仍有历史 `completed`，需要迁移或兼容，不应继续产生新值。

### 6.3 执行模式

Worker 消费 BullMQ 后，通过受密钥保护的内部 API 委托 backend 执行。这样可复用业务逻辑，但也意味着 backend 必须能承受 Worker 回调并保持幂等。

### 6.4 已知覆盖缺口

以下任务在通用 Worker 映射中没有 Provider 执行器，可能被标记为 `skipped`：

- `long_memory_generate`
- `subtitle_generate`
- `live_action_keyframe_generate`
- `live_action_video_render`
- `analytics_event`

部分能力目前由同步 Service 完成，因此应选择：补齐 Worker 执行器，或从异步任务目录移除并明确同步语义。`video_render` 当前映射到 VideoProvider，与 FFmpeg 成片合成的命名也需要拆分。

## 7. 重试与回退

重试策略按错误性质区分：

| 错误 | 处理 |
| --- | --- |
| 参数/素材不可用 | 不盲目重试，返回可修复原因 |
| 限流/临时网络故障 | 指数退避重试 |
| 异步任务超时 | 先核对外部任务，避免重复扣费 |
| 质量不达标 | 同模型定向重试，必要时回退其他模型 |
| 多次失败 | `manual_required`，保留全部候选和日志 |

回退不可静默发生。UI 应展示实际使用模型和回退原因。

## 8. 成本与额度

- `ProviderConfig` 保存成本规则和能力配置。
- `ProviderLog` 保存本次调用的估算/实际成本、耗时和状态。
- `QuotaAccount`、`QuotaLog` 支持冻结、释放和扣减。
- 数据库历史 `cost_actual` 可能混有不同币种/规则，只能技术对账，不能直接作为财务总额。
- 真实支付仍为 mock，不能把订单模型描述成生产支付闭环。

提交付费任务建议采用：

```text
预估 -> 冻结额度 -> 执行 -> 按实际结算 -> 释放差额
```

异步任务重试必须复用或核验外部任务 ID，避免重复扣费。

## 9. 日志与审计

每次 AI 调用应能回答：

- 谁、在哪个项目、为了哪个业务对象调用？
- 用户请求了什么 Provider/模型？
- 系统为何选择实际 Provider/模型？
- 最终提交了什么参数和参考素材？
- 是否注入模板、是否回退、重试了几次？
- 外部任务 ID、耗时、状态和错误是什么？
- 产生了哪些资产，哪一个被选择？
- 估算成本、实际成本和额度变化是什么？

API Key、JWT、数据库密码和临时签名参数不能进入可下载日志或 Work 文档。

## 10. 新 Provider 接入清单

1. 明确能力类型、模型和区域。
2. 定义请求 DTO、参数范围和默认值。
3. 实现鉴权、提交、轮询/回调、取消和结果归一。
4. 处理文本、二进制和临时 URL 输入。
5. 定义成本规则和币种。
6. 增加 preflight 与错误分类。
7. 增加 mock、单元测试和至少一次真实小额冒烟。
8. 在 Provider Lab 验证参数透传。
9. 验证日志不泄露密钥。
10. 更新本文件、CHANGELOG 和项目状态文档。

## 11. 当前优先级

### P0

- 修复 Provider/Seedance 相关测试与真实策略不一致。
- 对齐运行进程与最新构建。

### P1

- 固化模型选择优先级和路由解释。
- 补齐素材 URL preflight。
- 清理历史 running/failed 日志和任务积压。
- 补齐队列执行映射与任务命名。

### P2

- 将 AI Router 扩展为可选的平台统一入口。
- 建立 Provider 契约测试和录制回放测试。
- 统一成本币种和财务口径。