Agnes Video Generator断点续传与任务管理:中断后自动恢复,不重复消耗API配额的完整机制
Agnes Video Generator断点续传与任务管理:中断后自动恢复,不重复消耗API配额的完整机制
Agnes Video Generator 是一款开源、可自托管的免费 AI 视频生成工具,支持文本生成多场景视频(含旁白、字幕与数字人口播)。它的核心卖点之一,是完整的断点续传与任务管理机制:服务中断、网络闪断或手动停止后,任务能从上次中断处精确恢复,已生成的场景、音频、字幕全部复用,不会重复调用 API 浪费配额。
🎯 为什么 AI 视频生成特别需要断点续传?
一次创意长视频任务要经过 10 多个步骤:故事生成 → 脚本编写 → 每个场景的视频生成 → 旁白配音 → 字幕 → 拼接。整个过程可能持续 30 分钟以上,期间随时可能发生:
- 网络闪断、DNS 解析失败或上游 API 限流(队列满);
- 服务器 Ctrl+C 停服、OOM 被杀、意外断电;
- 用户想中途停下检查,稍后再继续。
没有断点续传时,这一切都意味着"从头再来",既浪费时间也重复消耗 API 配额。Agnes Video Generator 的解决方案由三层机制组成,下面逐一拆解。
📁 机制一:task_state.json 全量落盘,状态永不丢失
每个任务都有独立的工作目录 .working_dir/{时间戳}_{task_id}/,其中最关键的是 task_state.json 文件——断点续传完全依赖它:
. working_dir/{时间戳}_{task_id}/
├── task_state.json # 任务状态(断点续传依赖此文件)
├── story.txt # AI 生成的故事
├── script.json # 场景脚本
├── narration.mp3 # 合并的 TTS 旁白音频
├── scene_0/
│ ├── video.mp4 # 场景 0 AI 视频
│ └── task.json # 视频生成任务 ID(video_id)
└── final_video.mp4 # 最终合成视频
状态管理的核心实现位于 core/task_manager.py,有两个工程细节值得新手了解:
1. 每一步完成后立即持久化
流水线每执行完一个步骤,就通过 update_step / update_state 把最新状态写入磁盘。这意味着哪怕进程下一秒就被杀掉,盘上状态也最多只损失"最后那一步"。
2. 原子写防止文件损坏
_save() 采用"唯一临时文件 + os.replace"的原子写入策略:先写临时文件,成功后才替换正式文件。这样即使写入中途进程被杀(二次 Ctrl+C、OOM、系统信号),也不会留下截断的损坏 JSON,任务依然可以被续传。
🧩 机制二:细粒度步骤检查点,恢复时自动跳过已完成步骤
多场景流水线的模板方法定义在 core/pipelines/multi_scene.py,标准流程为:
分镜 → 参考图 → 视频生成 → 配音 → 字幕 → 合成
统一步骤执行器 _execute_step 在恢复时执行一个简单判断:对应步骤字段已为 COMPLETED,整步跳过;否则执行并在完成后落盘 COMPLETED。以创意视频为例,各步骤内部还会做"读盘自跳过"(细粒度续传),例如:
- 音频步骤:
combined_narration.mp3已存在且非空 → 直接跳过 TTS,仅重采字幕时间轴; - 视频步骤:某场景的
scene_i/video.mp4已在磁盘上 → 该场景不重新生成。
这套机制让"续传"对用户完全透明——点一下,剩下的程序自己算。
💰 机制三:video_id 复用,真正省下 API 配额
这是最容易被人忽视、也最省钱的一层。视频 API 的生成任务是异步的:提交时返回一个 video_id,服务端在后台慢慢渲染。如果提交后进程崩了,视频其实可能已经生成好了。
Agnes Video Generator 的做法(见 core/pipelines/multi_scene.py 中的 _save_task_json / _load_task_json):
- 提交成功后立即把
video_id写入scene_i/task.json; - 续传时先读
task.json:文件已存在 → 直接复用video_id去查询/下载,不重新提交;视频文件已存在 → 连查询都跳过。
更精细的边界处理:等待视频时若发生超时、网络中断或用户取消,task.json 一律保留;只有确认是服务端渲染失败时才会删除并允许重新提交。因为 Agnes 平台的视频提交配额是每 Key 每分钟 1 次(见 core/api/rate_limiter.py),盲目重提会白白烧掉这 1 次配额。
🔄 手动操作指南:中断后如何一键续传
完整使用说明见 docs/public/usage.zh.md 第 4 节,步骤如下:
- 重启服务(重新运行
python server.py); - 进入前端页面上方的 Task List(任务列表);
- 找到未完成的任务(状态为 pending / 中断),点击 「续传」;
- 流水线从
task_state.json读取进度,自动跳过所有已完成步骤继续执行。
对应的后端接口是 web/routes/task_routes.py 中的 POST /api/tasks/{task_id}/resume,它对异常场景做了完善防护:
| 场景 | 行为 |
|---|---|
| 任务正在运行 | 返回 400 "Task is already running",拒绝重复启动 |
| 任务已完成 | 返回 400,不允许续传 |
| 任务不存在 | 返回 404 |
| 快速连续点击两次「续传」 | 通过 per-task 锁串行化,杜绝双流水线并发写同一状态文件 |
运行中的任务也可以随时点 「停止」(POST /api/tasks/{task_id}/stop):流水线在下一个安全检查点优雅落盘、状态回写为 pending,稍后随时可续传。
✋ 进阶:手动模式——在检查点暂停等你确认
v6.0 起,Agnes Video Generator 还提供手动执行模式(执行模式 Auto / Manual 切换,见上图顶部):
- 切到 Manual 后,流水线在每个有产物的检查点(如故事完成、脚本完成、视频生成完成、字幕完成)自动暂停,落盘
PENDING + current_checkpoint状态,等待你在页面上确认、修改产物后再继续; - 想随时切回自动:切回 Auto 即"切换即继续",暂停中的任务会立即恢复跑完。
实现上复用同一套状态落盘与 resume 链路(CheckpointPause 正常返回而非报错),源码入口同样是 web/routes/task_routes.py 中的 POST /api/tasks/{task_id}/mode。
🚀 服务重启后会发生什么?
服务启动时(lifespan 阶段),web/app_state.py 会做一次"残留任务重置":把上次异常退出时遗留在 running/queued 状态的任务统一改回 pending(日志前缀 [Startup]),使任务列表呈现真实可续传状态,避免前端误以为任务还在跑。
📌 一句话总结
| 你的担心 | 机制回应 |
|---|---|
| 中断后已生成的场景会重跑吗? | 不会。文件在磁盘 → 直接复用 |
| 提交过的视频任务会重复提交吗? | 不会。video_id 已落盘 → 只查不提交 |
| 状态文件会写坏吗? | 不会。原子写保证文件完整性 |
| 点两次「续传」会出乱子吗? | 不会。任务级锁 + 运行中拒绝 |
对自托管用户来说,这套"全量落盘 + 细粒度检查点 + video_id 复用"的组合,让 Agnes Video Generator 的中断成本趋近于零——恢复即继续,配额不浪费,这也是长任务型 AI 生成工具在工程上最该有的样子。
