cutlab — AI 视频区域编辑
使用 Wan2.1-VACE-1.3B 扩散模型编辑视频每一帧的遮罩区域。通过文本提示描述期望的结果;模型将修复遮罩区域,同时保持其余部分不变。音频得以保留。
技能目录(该 SKILL.md 所在位置)在下文中称为 $SKILL_DIR。
需要 GPU。 需要 CUDA GPU,且空闲显存不低于 8 GB。 运行前请暂停 LLM 上下文以释放显存。
何时使用
当用户希望执行以下操作时使用此技能:
- 替换讲话者视频的背景为不同场景
- 编辑视频的矩形区域(天空、标志、屏幕等)
- 改变环境细节同时保留主体
环境设置(仅在首次运行时)
cd "$SKILL_DIR" && uv sync
Wan2.1-VACE-1.3B 模型权重将在首次运行时从 HuggingFace 下载(约 3 GB)。rembg 模型权重也会在首次使用背景模式时下载。
代理工作流程
1. 询问用户
在编辑视频之前,我需要了解以下信息:
💬 提示词(必填)
描述编辑后的区域应呈现的效果,例如:
"现代办公室,落地窗,可看到城市景观"
🎭 遮罩模式
- background — 自动检测并替换背景 [默认]
- region — 编辑一个矩形区域(x1,y1,x2,y2 为 0.0–1.0 之间的分数)
📐 如果 mode=region:mask_region
格式:"x1,y1,x2,y2" 例如 "0.0,0.0,1.0,0.3" 表示帧的上 30%
⚙️ 强度(0.0–1.0,默认 0.85)
编辑的应用强度。值越低越忠实于原图。
📁 输入/输出目录(默认:./input 和 ./output)
等待用户回复后再继续。
2. 编辑 config.json
根据用户的选择写入或更新 $SKILL_DIR/config.json。
3. 运行
cd "$SKILL_DIR" && uv run python scripts/vace.py --config config.json
4. 报告结果
告知用户输出文件路径、使用的遮罩模式以及应用的提示词。
配置参考
| 键 | 值 | 默认值 | 描述 |
|---|---|---|---|
input_dir | 路径 | ./input | 包含输入视频的文件夹 |
output_dir | 路径 | ./output | 输出文件夹 |
prompt | 字符串 | (必填) | 期望编辑区域的描述 |
negative_prompt | 字符串 | "worst quality, blurry, distorted" | 要避免的内容 |
mask | background, region | background | 遮罩策略 |
mask_region | "x1,y1,x2,y2" | (如果为 region 则必填) | 以分数表示的矩形 |
strength | 浮点数 (0, 1] | 0.85 | 修复强度 |
num_inference_steps | 整数 | 30 | 扩散步数 |
guidance_scale | 浮点数 | 5.0 | 提示词遵循程度 |
batch_size | 整数 | 8 | 每次推理批次处理的帧数(降低可减少显存占用) |
max_proc_dim | 整数 | 384 | 修复前的最大帧尺寸(降低可减少显存占用) |
model | HuggingFace ID | Wan-AI/Wan2.1-VACE-1.3B-diffusers | 使用的模型 |
常见用法
# 自动替换背景
cd "$SKILL_DIR" && uv run python scripts/vace.py \
--prompt "日落时分的宁静山湖"
# 编辑矩形区域(帧的上三分之一 = 替换天空)
cd "$SKILL_DIR" && uv run python scripts/vace.py \
--mask region --mask-region "0.0,0.0,1.0,0.33" \
--prompt "晴朗蓝天,点缀着几朵云"
# 更轻量的编辑(保留更多原始细节)
cd "$SKILL_DIR" && uv run python scripts/vace.py \
--prompt "舒适的家庭办公室" --strength 0.6
# 自定义目录
cd "$SKILL_DIR" && uv run python scripts/vace.py \
--input /path/to/videos --output /path/to/edited \
--prompt "未来都市景观"
输出
每个输入视频在 output_dir 中生成一个同名的 .mp4 文件。原始音频会重新合成进去。
错误处理
- 显存不足 → 打印所需 vs 可用 GB,提供释放显存的建议,退出
- 无 CUDA GPU → 清晰错误信息,退出
- input_dir 中无视频 → 清晰提示,退出
- mask_region 格式无效 → 显示预期格式的清晰错误,退出
- 单个视频错误 → 记录日志;其他视频继续处理