快速上手Openjutsu:本地GPU一键部署AI视频换人工具完整教程
快速上手Openjutsu:本地GPU一键部署AI视频换人工具完整教程
Openjutsu 是一款开源、完全本地运行的 AI 视频换人工具:上传一段视频和一张人物照片,点击 Generate,视频里的主角就会被替换成你的角色,同时完整保留原始的运动、镜头、剪辑和音轨。它基于 ComfyUI + MiniMax H3 开放权重模型,在你的 NVIDIA GPU 上运行,数据不出本机。本文带你走一遍从硬件检查到一键启动的完整部署流程。
Openjutsu 能做什么?5 种核心玩法
| 模式 | 说明 |
|---|---|
| 🎬 简单换人(Simple) | 一张照片替换视频中的主要人物,一条工作流一键完成 |
| 👥 高级换人(Advanced) | 1–4 个角色,每人可选角色设定,逐镜头匹配"谁变成谁" |
| 🕶️ 物体替换(Object swap) | 改发型、换外套、删掉某物,或重绘背景,只重生成所选区域 |
| 🖼️ 图片生成(From picture) | 一张人物照片 + 视频帧摆姿,FLUX.3 Klein 直接生成新场景视频 |
| ✨ 后处理 | Fix faces 修复小脸,Fix colours 柔化 H3 偏硬的色调 |
简单换人模式下,Openjutsu 用 SAM 3.1 追踪视频中占画面最大的人物,把该区域替换成你的角色,其余人、背景、声音全部原样保留。
高级模式支持最多 4 张照片,每个人都可以设定角色(如"the singer"),没有角色的路人保持不动。
部署前检查清单:硬件、软件与模型
硬件要求 ⚙️
- 一块 NVIDIA GPU:官方在 RTX 4060 Ti 16 GB + 64 GB 内存上测试,H3 int8 模型从内存流式加载,内存不能太小
- 显存按模型自行预留,视频生成耗时与分辨率成正比
软件要求
- ComfyUI 0.41.2 或更新版本(核心提供 MiniMax H3、SAM 3.1 与 TextGenerate 节点)
- Node.js 22.6+ 与 Python(用于
comfy-api-proxy)
自定义节点
需要安装到 ComfyUI/custom_nodes,主要包括:SolarRenderer(From picture 四步采样)、ComfyUI-MiniMaxH3-Context-Loop(片段循环与拼装)、comfyui-h3-oneclick-swap(换人/物体计划、角色遮罩、镜头切分)、ComfyUI-H3-FaceRefine 与 ComfyUI-Impact-Pack(Fix faces)、Orion4D_FXMax 等。完整清单见 CUSTOM_NODES_REPORT.md,大部分可用 ComfyUI Manager 按名称自动安装,装完重启 ComfyUI。
模型文件 📦
按目录放入 ComfyUI/models(核心 6 项):
| 目录 | 文件 |
|---|---|
diffusion_models |
minimax_h3_ref2va_pruned_int8_convrot.safetensors |
loras |
minimax_h3_DMAD_4step_full_lora_avg_rank_39_bf16.safetensors |
text_encoders |
qwen3vl_32b_minimax_h3_int4_convrot.safetensors(H3 文本编码器) |
text_encoders |
qwen3vl_8b_int8_convrot.safetensors(视觉描述模型) |
vae |
minimax_h3_video_vae_int8_convrot.safetensors、minimax_h3_audio_vae_fp32.safetensors |
checkpoints |
sam3.1_multiplex_fp16.safetensors |
提交任务前,Openjutsu 会自动核对所选工作流的节点与模型是否齐全,缺失的包和文件会直接列出,省去翻找时间。
最快方式:Windows 一键启动 🚀
Windows 用户只需双击 start_openjutsu.bat:
- 首次运行自动在
.venv-proxy虚拟环境中安装comfy-api-proxy 0.1.6,并用仓库自带的 patch_proxy.py 修复任务实时进度 - 自动执行
npm ci与npm run build - 检测 ComfyUI 是否在
127.0.0.1:8188运行,没启动会等待提示 - 最后打开代理(8189 端口)、启动应用,并自动在浏览器打开
http://127.0.0.1:3000
停止使用:关闭 "Openjutsu proxy" 和 "Openjutsu app" 两个窗口即可。
手动部署:跨平台 5 步指南
如果需要 Linux/macOS 或想理解每一步,按下面流程操作:
第 1 步:启动 ComfyUI(监听 127.0.0.1:8188)。Windows 下建议先设置环境变量 AIOHTTP_NOSENDFILE=1,否则拖动视频进度条时可能卡死 ComfyUI 的文件接口。
第 2 步:安装并启动 API 代理
pip install comfy-api-proxy==0.1.6
python openjutsu/patch_proxy.py
comfy-api-proxy run --max-upload-mb 500
代理把 Comfy 的 API v2 暴露在 127.0.0.1:8189,--max-upload-mb 可上调长视频上传上限(默认 100 MB)。
第 3 步:克隆仓库并安装依赖
git clone https://gitcode.com/gh_mirrors/op/openjutsu
cd openjutsu
cp .env.example .env.local
npm ci
npm run build
第 4 步:启动应用
npm start
第 5 步:打开页面 → 访问 http://127.0.0.1:3000。
关键配置:.env.local 三个参数 🔧
模板见 .env.example,本地部署只需关心三项:
| 变量 | 说明 |
|---|---|
COMFY_BASE_URL |
指向代理,本地默认 http://127.0.0.1:8189 |
COMFYUI_URL |
指向 ComfyUI 本体(默认 http://127.0.0.1:8188),用于读取基础模型与 LoRA 下拉列表 |
OPENJUTSU_PASSWORD |
本地留空;如需对外提供服务必填(≥12 位,用户名固定为 openjutsu)。无密码时应用只允许监听回环地址,该逻辑在 instrumentation.ts 中强制执行 |
上传限制为每次请求共 512 MB,任务结束后上传缓存会被清理,但文件保留在 ComfyUI 的 input/ 目录。
第一次打开页面:选择视觉描述模型 👀
欢迎页会让你选择"视觉描述模型"——它负责描述图片、撰写生成提示词并驱动"Find people"人物追踪匹配:
- 默认 Qwen3-VL 8B INT8(推荐)
- 显存紧张可选更小的 Qwen3-VL 4B FP8 或 Gemma 4 E2B INT8
- 模型放入
ComfyUI/models/text_encoders后点击 Refresh models 即可识别
选择不影响 H3 文本编码器,只影响提示词质量与人物匹配准确度,可随时在"Welcome & models"里更改。
开始第一次 AI 视频换人 🎬
- 进入编辑器,选择 Simple 模式,上传源视频和人物照片
- 用 Part to use 可只取视频的一段(Start/Middle/End),片段越短出片越快
- 建议先点 Check mask(约 3 秒视频 1 分钟):青色遮罩是将被重绘的区域,右侧灰色人偶是 H3 参考的动作骨架,可逐帧拖拽检查
- 点击 Generate,页面通过 SSE 实时转发 ComfyUI 的节点进度
性能参考(RTX 4060 Ti 16 GB): 480p 6 秒片段约 6–13 分钟,大部分时间花在 H3 采样;默认 736p;1080p 约为 736p 的 2.5 倍耗时且更吃内存。简单模式跑的是 workflows/simple.api.json,前端参数拼装逻辑在 lib/simple.ts,想深入工作流可看 workflows/ 目录。
Object swap 模式下,只需给 SAM 一个词(hair、jacket),Change 替换、Remove 删除、Background 重绘背景,还可以画笔扩展编辑区域。
From picture 是"从一张照片到一段视频"的玩法:FLUX.3 Klein 把人物摆进视频帧的姿势,再由 H3 + SolarRenderer(Metric3D 法线图引导)渲染出带原声的视频,最长 15 秒。工作流细节见 workflows/picture/README.md。
Relight(默认关闭)在同一次 FLUX 通道里换光:17 种预设灯光效果各带示例图,也可自定义描述光线,甚至直接重打光视频里原有的主角。
后处理的 Fix faces 专治 H3 画小脸的短板:用照片中的人脸特写重绘并贴回,可选择"Match the photo"(更像照片)或"Follow the mouth"(保留原口型)。
实用技巧与常见问题 💡
- 镜子与倒影暂不支持:倒影里的原人物会被 H3"抄"走,选没有镜面反射的视频
- 换人对象提示词用角色名(
the singer)而非服装描述,避免服装词泄漏进结果 - 换 seed 可获得新的一次演绎;相同输入再次运行会从上次完成的片段断点续跑
- No lip-sync(默认关):视频中人物不唱歌/说话时开启,避免新角色乱对口型
- 高级模式的 Motion reference 从 512px 提到 768px 质量略升,采样时间约 +1/3
- 上传失败/进度卡住时,先确认代理窗口还活着且 ComfyUI 未崩溃
总结
Openjutsu 把"AI 视频换人"从云端服务搬到了你自己的显卡上:ComfyUI 负责模型调度,MiniMax H3 负责生成,SAM 3.1 负责追踪,Qwen3-VL 负责理解画面。Windows 用户双击一个脚本,其他平台五条命令,即可拥有一个数据完全本地、玩法覆盖换人/换物/换景/重打光的一体化工作台。更多细节可查阅仓库根目录的 README.md。





