ai/docs/system_b/12_任务队列_错误重试_稳定性设计.md

12_任务队列_错误重试_稳定性设计

1. 文档目标

本文档定义系统 B 的任务队列、状态机、幂等、重试、错误码、恢复机制和并发控制。

2. 为什么必须队列化

系统 B 的生成链路长且耗时：

照片检测
人物档案
方案生成
预览图
正式图
图片质检
TTS
字幕
视频合成
最终质检
人工审核

如果同步执行，容易导致：

• 请求超时
• 用户重复点击
• 服务阻塞
• 失败无法恢复
• 成本无法追踪

3. 队列划分

photo_check_queue：照片检测
text_queue：方案、文案、Prompt
image_queue：预览图、正式图
video_queue：AI 图生视频
voice_queue：TTS
audio_queue：BGM 处理
ffmpeg_queue：视频合成
qc_queue：质量检测
cleanup_queue：文件清理
notification_queue：通知

4. 任务状态

pending：等待执行
running：执行中
success：成功
failed：失败
retrying：重试中
cancelled：取消
manual_required：需要人工处理

5. 任务字段

每个任务必须有：

task_id
project_id
task_type
provider_id
status
input_json
input_hash
output_asset_id
provider_request_id
retry_count
max_retry
cost_estimate
cost_actual
error_code
error_message
created_at
started_at
finished_at

6. 幂等设计

幂等 key：

project_id + task_type + input_hash

规则：

• 如果已有成功任务，直接返回成功结果。
• 如果已有运行任务，返回当前任务状态。
• 如果已有失败任务，按重试规则处理。
• 同一请求不能重复创建多个高成本任务。

7. 项目级锁

某些任务必须串行：

• 创作方案生成
• 视频合成
• 最终交付

使用 Redis lock：

lock:project:{project_id}:workflow

避免并发触发导致状态混乱。

8. 重试策略

默认：

max_retry = 3
backoff = exponential

例如：

第 1 次失败：30 秒后重试
第 2 次失败：2 分钟后重试
第 3 次失败：5 分钟后重试

不可重试错误：

• 用户照片不合格
• 余额不足
• 授权未确认
• 内容审核不通过
• 套餐限制冲突

可重试错误：

• Provider 超时
• 网络错误
• 速率限制
• 临时服务异常
• FFmpeg 临时失败

9. 失败转人工

满足任一条件转人工：

• 同一任务连续失败超过 max_retry
• 图片质检连续失败
• 人像一致性评分过低
• 视频合成失败
• 审核 warning
• 高端定制项目

状态：

manual_required

10. 并发限制

用户级

每个用户最多同时 1 个正式生成项目

项目级

每个项目最多同时 N 个图片任务
视频合成任务只能 1 个

Provider 级

按 Provider 设置 QPS 和并发数

11. 队列优先级

优先级建议：

1. 高端定制项目
2. 已支付正式生成
3. 预览生成
4. 免费预览
5. 清理任务

12. 错误码设计

错误码	含义
TASK_TIMEOUT	任务超时
PROVIDER_TIMEOUT	Provider 超时
PROVIDER_RATE_LIMIT	Provider 限流
PROVIDER_ERROR	Provider 错误
INPUT_INVALID	输入参数错误
PHOTO_QUALITY_FAIL	照片质量不合格
PAYMENT_REQUIRED	需要支付
QUOTA_NOT_ENOUGH	额度不足
MODERATION_REJECTED	审核不通过
FFMPEG_FAILED	视频合成失败
STORAGE_FAILED	存储失败
UNKNOWN_ERROR	未知错误

13. 任务恢复

服务重启后：

1. 扫描 running 超时任务。
2. 判断是否有 Provider request_id。
3. 查询 Provider 状态，能恢复则恢复。
4. 无法恢复则标记 failed 并按规则重试。

14. 状态一致性

项目状态由 WorkflowService 统一更新。不要让 Worker 随意改最终状态。

Worker 只上报：

task success/failed
output asset
progress
error

WorkflowService 根据任务完成情况推进项目状态。

15. 防重复点击

前端：按钮 loading，防抖。
后端：幂等 key + 状态校验。

例如：

• 已在 preview_generating，不允许再次 generate-preview。
• 已 payment_paid，不允许重复创建同一套餐订单。

16. 任务超时设置

建议：

photo_check：2 分钟
text_generate：3 分钟
image_generate：10 分钟
video_generate：30 分钟
voice_generate：5 分钟
ffmpeg_render：30 分钟
final_qc：10 分钟

17. 告警

触发告警：

• 失败任务数超过阈值
• 某 Provider 连续失败
• 队列积压过多
• 视频合成失败率过高
• 单项目成本异常
• 磁盘/MinIO 容量不足

18. 日志要求

每个任务记录：

• 输入摘要
• 输出摘要
• Provider
• 成本
• 耗时
• 错误
• 重试次数

敏感数据脱敏保存。

19. V3 真人动态视频队列增量

新增队列：

identity_anchor_queue：身份锚点生成
face_consistency_queue：本人相似度检查
motion_portrait_queue：动态写真轻动效
real_video_clip_queue：真人动态视频片段
video_clip_qc_queue：视频片段质检
lipsync_queue：口型同步

隔离原则：

• real_video_clip_queue 必须独立限流，避免高成本视频任务堵住图片和普通合成。
• lipsync_queue 独立限流，失败不影响基础旁白字幕交付。
• face_consistency_queue 可优先级较高，因为它决定是否能继续生成。

V3 超时建议：

identity_anchor_generate：10 分钟
face_consistency_check：3 分钟
motion_portrait_generate：20 分钟
real_video_clip_generate：60 分钟
video_clip_qc：10 分钟
lipsync_generate：45 分钟

V3 错误码：

IDENTITY_ANCHOR_NOT_CONFIRMED
FACE_CONSISTENCY_LOW
REAL_VIDEO_PROVIDER_DISABLED
REAL_VIDEO_CONFIRMATION_REQUIRED
REAL_VIDEO_COST_LIMIT_EXCEEDED
REAL_VIDEO_CLIP_FAILED
VIDEO_CLIP_QC_FAILED
LIPSYNC_FAILED
MINOR_MANUAL_REVIEW_REQUIRED

真实视频任务失败时：

1. 记录 Provider 错误。
2. 标记片段 failed 或 needs_retry。
3. 不回落 mock 假成功。
4. 不重复扣用户额度。
5. 用户端显示失败原因和重试入口。