ReelPilot

English · 参与改进 · 英文技术案例

面向文娱素材的多模态检索与可恢复剪辑 Agent

从「找出城市、机器人、人物交流的画面」到带来源时间戳的候选剪辑：模型拆解检索目标，程序编译和校验剪辑计划，FFmpeg 执行，SQLite 记录每一步以支持失败恢复。

适用于探索内容平台、影视宣发、游戏宣传素材的检索与粗剪工作流。当前是本地运行的工程原型，使用公开素材验证完整链路；没有企业上线或真实业务收益数据。

项目重点

v0.5 新增本地 MCP v2 工具接入：默认只读检索与状态查询；显式开启后复用原任务队列提交/取消剪辑。真实 stdio 子进程断开后可通过原任务 ID 找回结果，同请求重放复用已验证产物。接入与协议证据

v0.4 深化模型资源管理：取消感知的 FIFO 入口、有界查询缓存与同请求计算合并、可选规划器驻留、生成步控制，以及服务退出后恢复。模型资源设计与证据 · 运行控制 · 代码追问入口

• 时间对齐的多模态索引：Whisper 词级时间戳、六秒窗口、中点帧；Qwen3-VL-Embedding-2B 构建画面、对白、联合内容三种索引，保留素材哈希、时间区间和授权来源。

• 有约束的 Agent 工具链：Qwen3-0.6B + LM Format Enforcer 生成 Schema 约束目标；Beam Search 在时长上限、片段数和不重叠约束下编译 EditPlan，独立校验后才执行固定参数的 FFmpeg 工具。

• 可恢复执行：SQLite 幂等请求、所有权租约、心跳与阶段日志；owner 校验和原子文件发布阻止过期 worker 覆盖结果，重试复用哈希验证后的产物。

• 可终止的任务运行：取消意图持久化，排队等待纳入尝试 deadline；独立 worker 采用启动门、受控进程树、双路有界日志，终止确认与最终提交均有明确状态规则。线程模式保留模型复用，进程模式提供本地终止边界。

• 受控的模型资源：关键词检索和向量缓存命中绕过模型入口；未命中查询按 FIFO 申请资源，同键请求共用一次计算。缓存限制条目与计费字节，等待者各自响应取消。可选驻留规划权重，每次重新创建解码状态。

• 有对照的方案选择：比较 BM25、三种向量视图和 RRF，保留逐条排名和错误案例。模型加载严格检查 checkpoint keys，索引 fingerprint 不匹配时拒绝使用。

• 完整交互：FastAPI 工作台支持画面/对白检索、原片定位、生成进度、结果播放与剪辑计划 JSON 导出。

Related MCP server: ffmpeg-mcp-video-editor

看实际结果

上图来自实际检索到的城市与大脑画面；12 秒剪辑结果来自故障恢复实验。素材为 (CC) Blender Foundation | mango.blender.org，CC BY 3.0，此处做了截帧、缩放和片段重组。来源与授权。

五分钟运行：不需要模型或 GPU

Python 3.11+；推荐先在独立虚拟环境安装。此模式生成原创的四场景测试视频，使用明确目标和关键词检索，不调用大模型。

安装后可先运行 reelpilot selfcheck：生成原创视频，验证中断后恢复、相同请求重放与损坏产物修复，打印结果目录和 JSON。每次使用新的独立目录，保留已有文件；不下载模型。这个命令检查安装和执行链路，使用 Python 控制性异常，不替代后面的真实进程强杀实验。实际自检报告示例

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e '.[dev]'
reelpilot demo --collection data/demo
reelpilot serve --collection data/demo

打开 http://127.0.0.1:8765，保持「明确目标」与「字幕关键词」，输入 forest; robot。也可直接执行：

reelpilot edit --collection data/demo --jobs data/jobs --budget 8 'forest; robot'
pytest

FFmpeg 可执行文件由 imageio-ffmpeg 依赖提供，无需写入系统目录。应用默认只绑定本机地址。

需要逐任务进程隔离时，运行 reelpilot serve --collection data/demo --execution-backend process --request-timeout 60。界面支持取消当前任务；POST /api/jobs/{job_id}/cancel 返回的是取消意图接收结果，需轮询到终态。线程中的阻塞模型调用不能立即抢占；进程模式则每次冷加载模型。接口语义与平台差异

运行真实模型与公开素材

本次验证环境：Windows、Python 3.13.9、PyTorch 2.11.0、Transformers 4.57.1、RTX 5070 Ti Laptop 12 GB。ASR 使用 CPU int8；嵌入与规划分阶段运行。检查点共约 6 GB，视频约 380 MB，处理缓存需额外空间。

先按你的硬件安装 PyTorch，然后：

python -m pip install -e '.[models,dev]'
python scripts/bootstrap_assets.py movie
python scripts/bootstrap_assets.py asr
python scripts/bootstrap_assets.py embedding
python scripts/bootstrap_assets.py planner
python scripts/prepare_open_movies.py --embed
python scripts/evaluate_pilot.py
python scripts/run_real_experiments.py
reelpilot serve --collection data/index --jobs data/jobs --embedding-model .runtime/models/qwen3-vl-embedding-2b --planner-model .runtime/models/qwen3-0.6b

下载脚本固定模型 revision 并校验下载大小与可用的 LFS SHA256。模型默认来自 Hugging Face；如需镜像，可通过 REELPILOT_MODEL_ENDPOINT 指定兼容端点。权重、完整影片、索引缓存和本地任务目录均不进入 Git。

自己的素材可用 reelpilot ingest --help 登记，必须提供来源与授权信息，再运行 reelpilot embed 构建三种索引。当前界面使用服务器已登记的素材库，不提供任意文件上传。

实验概况

2 份公开素材、约 13.1 分钟、132 个时间窗口；15 个场景意图对应 30 条中英文查询。标签由代理检查时间戳联系表后辅助编写，属于开发性小样本，不是独立人工测试集。

这组问题以画面需求为主，无法据此判断对白路由的收益。默认采用按目标通道选视图的规则；不宣称统计显著或可泛化的提升。查询编码耗时中位数约 30.5 ms，不含模型加载，不是完整问答或剪辑延迟。

完成三次真实媒体运行，包括一次渲染后主动中断再恢复；该次日志记录渲染只执行一次，恢复命中缓存。v0.2 在原有 CPU 测试上补充请求容量、规划失败持久化、跨实例竞争和最终清单发布的恢复测试。测试结果见 Actions 与 本地日志。详见实验报告、原始排名、真实运行日志。

v0.3 运行机制实验

真实强杀分别发生在渲染提交后、最终清单替换后但 SQL 提交前；两次恢复都复用已验证的渲染，render 提交次数保持 1。另验证真实 FFmpeg 运行中的取消/超时、监督进程自身死亡后的子进程退出，以及每路 5 MiB 输出只保留 64 KiB 的管道控制。取消与完成另做 20 组事务竞争测试。实验使用原创合成视频，无模型效果或生产故障率声明。

python scripts/validate_runtime.py
python scripts/measure_runtime.py --samples 5

测试摘要 · 逐项故障证据 · 线程/进程开销原始样本。CPU 开销对照不加载模型，不能替代 GPU 推理或生产吞吐测试；具体注入方法、测试替身和限制见实验说明。

v0.4 模型资源与退出实验

本地完整验证为 103 项通过，含旧故障回归及真实 FFmpeg 退出后用原请求重启恢复。随机初始化的 6384 参数 CPU Transformer 另验证实际生成循环：第 4 个 forward 触发取消，部分输出不接受；同键并发向量探针将 8 次基线 forward 合并为 1 次。它只证明调用与控制机制接通，不代表 Qwen 模型质量或 GPU 加速。

受控回调对照与 500 查询容量抖动另存原始数据，清楚标注注入延迟；默认缓存上限 256 条、16 MiB 计费字节，并非显存或 RSS 上限。规划器驻留默认关闭，开启需要额外内存。详细方法、失败定位与边界见资源实验说明。

python scripts/validate_resources.py
python scripts/measure_model_resources.py
# 已安装 models 依赖时，下面的探针不下载权重
python scripts/validate_generation_control.py

最新测试摘要 · 资源验证与进程恢复 · 真实微型模型探针 · 受控对照

实现边界

固定窗口与单帧可能漏掉短动作或截断台词；当前不做镜头边界检测。小模型仍会扩写需求，真实预告片实验中城市目标召回了室内全息场景。结构验证保证来源和执行约束，不证明画面语义、审美或叙事质量。最终选片需要审片。

可恢复执行不是 exactly-once；进程崩溃可能重跑工具。当前是单实例本地服务，没有多租户、鉴权或公网部署加固。Ollama 后端已实现，但本次未进行服务实测。Docker 示例未在本机完成构建验证。

进程隔离用于可信工具的生命周期控制，不是安全沙箱。Windows Job Object 与 POSIX 进程组/父进程轮询的保证不同；取消本地 worker 也不保证远端服务停止计算。文件改名与 SQLite 提交之间的恢复测试不等于断电一致性验证。

进一步阅读

• MCP 接入、幂等调用与跨会话恢复

• 技术架构与模块

• 实验设计、消融与失败分析

• 产品目标与验收范围

• 面试讲解 · 简历条目草稿

• 第三方来源 · 代码许可

代码由 AI 编程工具辅助实现；实验由本地真实运行产生，保留原始记录和明确边界。基础模型来自公开检查点，本项目没有训练或微调这些模型。