# 模型调用与动态 Fallback 完成说明

> 状态：已完成
>
> 最后核对：2026-07-21
>
> 用途：说明当前模型调用、重试、动态切换、计费和日志流程。

## 1. 当前调用流程

```text
用户选择模型 / 系统默认模型
→ 创建一个 AITask
→ 预留一次积分
→ 调用主模型
→ 明确失败：按配置重试主模型，仍失败且允许时动态 Fallback
→ 远端结果不确定：停止自动重试和 Fallback
→ 成功：保存结果并结算一次
→ 最终失败或结果不确定：释放一次预留
```

主模型始终是用户本次选择的模型；Fallback 不修改用户选择、默认模型或下次调用。

## 2. Retry 与 Fallback

- `Retry`：再次调用当前模型。
- `Fallback`：切换到其他兼容模型。
- `调用审计`：记录每次真实调用，不参与模型评分或自动学习。

当前默认值：

| 能力 | 主模型重试 | 单次超时 | 总时限 |
|---|---:|---:|---:|
| 文本 | 2 次，等待 1 / 3 秒 | 120 秒；流式 300 秒 | 480 秒 |
| 图片 | 1 次，等待 3 秒 | 300 秒 | 900 秒 |
| 配音 | 1 次，等待 2 秒 | 60 秒 | 180 秒 |
| 视频提交 | 1 次，等待 3 秒 | 120 秒 | 300 秒 |
| 视频成片 | 不重新提交 | 单次轮询 60 秒 | 以供应商终态为准，无本地硬总时限 |

单个逻辑任务最多尝试 3 个模型、发出 5 次真实请求。

### 2.1 远端结果确定性保护

统一执行器先判断本次失败是否能确认供应商没有成功处理：

- 明确失败：保留现有 Retry 与动态 Fallback。
- 结果不确定：记录当前一次失败后立即停止，不查询候选、不等待退避、不再次调用 Provider。
- `ReadTimeout`、请求发送后连接中断、HTTP `502/504`、响应缺失且无法确认结果，按结果不确定处理。
- DNS、连接拒绝、建立连接超时和明确 `429` 仍按现有策略重试或 Fallback。
- 结果不确定记录在 `AIModelAttempt.response_summary.outcome_unknown=true`，不新增表字段。
- 该保护不改变超时数值、普通用户提示、模型选择、动态排序或视频长轮询规则。

## 3. 配置位置

全局策略在：

```text
core/backend/.env
core/backend/airshelf/settings/base.py → MODEL_ROUTING_POLICY
```

控制重试、提交超时、最多模型数、最多调用数和后处理退避。视频取得远端任务 ID 后不设本地成片硬总时限。修改后必须同时重启 API 与 Celery Worker。

每个模型的开关保存在数据库 `ModelConfig.metadata.routing`：

```json
{
  "fallback_on_failure": false,
  "fallback_candidate": true
}
```

- `fallback_on_failure`：当前模型失败后是否允许切到其他模型。
- `fallback_candidate`：当前模型是否允许被其他失败模型选中。
- 开关按模型独立配置，不在代码中写死供应商或模型名单。

## 4. 火山 / 豆包直连现状

文本、配音、视频都已接入统一 Fallback 代码，但当前直连模型统一配置为：

```text
fallback_on_failure = false
fallback_candidate = true
```

当前行为：

- 允许原模型重试。
- 不允许从直连模型主动切出。
- 已启用且能力匹配时，可以作为其他模型的候选。
- 以后只改模型 metadata 即可开启，无需重新开发路由代码。

## 5. 动态候选规则

候选每次失败后实时读取数据库，必须同时满足：

- 供应商已启用。
- 模型已启用。
- `fallback_candidate=true`。
- 能力一致：`text`、`image`、`audio` 或 `video`。
- 操作要求一致：流式、结构化、图片编辑、参考素材数量、比例、分辨率、时长、音色映射等。
- 本任务尚未尝试过。

排序规则：

```text
火山 / 豆包直连
→ YunQi
→ 其他 OpenAI API 兼容供应商
→ 同层级按 ModelConfig.updated_at 从新到旧
```

除现有火山 / 豆包专用适配器外，新增供应商只支持 OpenAI API 兼容协议。

## 6. 任务与计费

一次用户操作始终只有：

- 一个 `AITask`。
- 一次积分预留。
- 一次最终扣费或释放。

每次真实模型调用只新增一条 `AIModelAttempt`，不会单独预留或扣费。

- Fallback 成功：按原逻辑任务结算一次。
- 全部失败：释放原预留，用户扣费为 0。
- 多次尝试产生的上游费用累计为平台成本，不转换成多笔用户扣费。

## 7. 调用日志

`AIModelAttempt` 记录：

- 调用顺序。
- 供应商与真实模型快照。
- 首次调用、重试或 Fallback。
- 成功 / 失败、耗时和错误分类。
- Provider 任务 ID、用量和平台成本。
- 脱敏请求 / 响应摘要。

管理员在 `/admin/tasks` 的任务详情查看完整调用链。普通用户端保持静默，不显示内部供应商、真实候选、失败原因或尝试次数。

公开别名保持不变：

- Gemini 3.1 Pro → `AirShelf Script`
- `gpt-image-2` → `AirShelf Image`
- 火山 / 豆包直连继续显示原公开名称。

## 8. 视频特殊规则

- 只有尚未取得远端任务 ID，且明确提交失败时，才允许重试或 Fallback。
- 提交读取超时或响应缺少任务 ID 视为“远端状态未知”，禁止重复提交。
- 获得远端任务 ID 后固定使用真正提交成功的模型轮询和结算。
- 普通轮询超时只继续轮询，不切模型、不重新提交。
- 本地等待时长不产生失败终态；只有供应商明确返回 `failed`、`expired` 或 `cancelled` 才失败并释放预留。
- Worker 有限轮询用尽后只停止本轮兜底，业务任务仍保持生成中；用户重新打开页面可继续查询。
- 供应商最终成功时正常转存资产并结算一次，即使成片超过 30 分钟。
- 下载、上传、TOS 或资产保存失败只重试后处理，不重新调用模型。

旧版 30 分钟硬终止误判任务可使用以下管理命令核对：

```text
python manage.py reconcile_video_timeouts --task-id <AITask UUID>
python manage.py reconcile_video_timeouts --task-id <AITask UUID> --apply
```

默认只读；`--apply` 仅恢复远端已成功结果，不重新提交模型、不追扣用户积分，并保证重复执行不会重复创建版本或资产。

## 9. 已接入入口

- 脚本生成、脚本优化、单镜优化。
- 显式实体提取、脚本实体同步兼容入口。
- 独立图片生成 / 编辑、模特上身图、平台套图。
- 商品 / 人物 / 场景基础资产、项目与模特三视图。
- 故事板分镜生成。
- 配音生成。
- 视频片段生成。
- 自由创作 / 免费视频生成。

## 10. 发布要求

- 数据库迁移：`0028_seed_model_routing_metadata`、`0029_aimodelattempt`。
- API 与 Celery Worker 必须使用同一版后端镜像。
- API 与 Worker 必须读取同一份路由配置。
- 发布后至少冒烟验证文本、图片、配音、视频和 `/admin/tasks` 调用链。
- 回滚代码时不要直接反向执行 `0028`，避免删除已维护的模型路由 metadata。

## 11. 关键代码

```text
core/backend/apps/ai/routing_policy.py    全局策略读取与校验
core/backend/apps/ai/generation_errors.py 错误分类与远端结果确定性判断
core/backend/apps/ai/model_routing.py     能力匹配与动态候选排序
core/backend/apps/ai/routing_executor.py  重试、Fallback 与调用审计
core/backend/apps/ai/models.py            AITask / AIModelAttempt
core/backend/apps/ai/services.py          各业务入口编排
core/backend/apps/ai/free_video.py        自由视频提交与轮询
core/backend/apps/ai/script_agent.py       脚本流式调用
```

## 12. 非本次范围

- 未修改 `/admin/providers` 页面。
- 未实现用户反馈学习、模型评分或自动调权。
- 未写死备用模型链。
- 未支持新增非 OpenAI API 私有协议供应商。