ComfyUI Sonic 安装教程
本文面向已安装 ComfyUI 的用户，详细介绍了安装对口型视频生成节点 ComfyUI_Sonic 的两种方式：手动克隆仓库与通过 ComfyUI Manager 安装。同时说明了模型下载路径、前置条件（NVIDIA GPU ≥12GB 显存）及常见问题处理，帮助用户快速搭建人像+音频生成短视频的工作流。
面向 已安装好 ComfyUI 环境（GPU、Python、能浏览器或 API 访问）的机器。Sonic 用于 人像 + 音频 → 对口型短视频（Portrait Animation），适合歌曲片段、口播等场景。
下文路径均相对于 ComfyUI 根目录（记为 ComfyUI/）。请把命令里的路径换成你的实际安装位置（Linux 常见 /root/ComfyUI，Windows 本机如 D:\ComfyUI）。
| 项目 | 路径 |
|---|---|
| ComfyUI 根目录 | ComfyUI/ |
| Sonic 自定义节点 | ComfyUI/custom_nodes/ComfyUI_Sonic |
| Sonic 专用模型 | ComfyUI/models/sonic/ |
| SVD 检查点 | ComfyUI/models/checkpoints/ |
| 输出视频 | ComfyUI/output/ |
0. 前置条件
- 已安装 ComfyUI，并能用浏览器或 API 正常访问
- NVIDIA GPU，建议 ≥ 12GB 显存（首次加载易 OOM，见下文）
- Python 3.10+，CUDA 与 PyTorch 版本与 ComfyUI 一致
- 若从其他机器访问 ComfyUI，需放行对应端口（防火墙 / 安全组）
1. 安装 ComfyUI_Sonic 自定义节点
在 ComfyUI/custom_nodes/ 下克隆（任选其一仓库，工作流节点名需与所装版本一致）。
1.1 常用仓库（smthemex）
cd ComfyUI/custom_nodes
git clone https://github.com/smthemex/ComfyUI_Sonic.git
cd ComfyUI_Sonic
pip3 install -r requirements.txt
GitHub 较慢可用镜像：
```bash
cd ComfyUI/custom_nodes
git clone https://ghproxy.net/https://github.com/smthemex/ComfyUI_Sonic.git ComfyUI_Sonic
cd ComfyUI_Sonic && pip3 install -r requirements.txt
1.2 使用 ComfyUI Manager 安装（推荐）
ComfyUI-Manager 可在网页里搜索、安装自定义节点，并自动执行 git clone 与 pip install -r requirements.txt。模型权重仍需按第 2 节手动下载（Manager 不会替你下 GB 级 Sonic/SVD 文件）。
1.2.1 安装 ComfyUI-Manager（若尚未安装）
插件目录必须是 ComfyUI/custom_nodes/ComfyUI-Manager（不要解压到 custom_nodes 根目录下一层乱套）。
cd ComfyUI/custom_nodes
git clone https://github.com/ltdrdata/ComfyUI-Manager.git
GitHub 较慢可用镜像：
cd ComfyUI/custom_nodes
git clone https://ghproxy.net/https://github.com/ltdrdata/ComfyUI-Manager.git ComfyUI-Manager
安装后 重启 ComfyUI（见第 3 节）。浏览器打开工作流页，菜单栏或侧边应出现 Manager 按钮；若无，查看启动日志里是否有 ComfyUI-Manager 的 import 报错。
1.2.2 在 Manager 中安装 ComfyUI_Sonic
- 浏览器访问 ComfyUI（本机常见
http://127.0.0.1:8188；远程则为http://<主机>:<端口>）。若已配置 ComfyUI-Login，先完成登录。 - 点击 Manager（新版界面可能在右上角 ⋮ 或 Manager 菜单里）。
- 打开 Custom Nodes Manager / Install Custom Nodes（文案因 Manager 版本略有不同）。
- 在搜索框输入
Sonic、ComfyUI_Sonic或smthemex。 - 在结果列表中找到 ComfyUI_Sonic（作者 smthemex，仓库 smthemex/ComfyUI_Sonic），点击 Install。
- 等待底部日志显示 clone /
pip install完成（首次可能需数分钟，取决于网络）。 - 若提示 Restart required，在 Manager 里点 Restart，或结束 ComfyUI 进程后重新启动（见 §3）。
安装成功后，目录应类似：
ComfyUI/custom_nodes/ComfyUI_Sonic/
不要 同时用 Manager 再装 Sean-Bradley/ComfyUI-Sonic 等不同 fork，节点名与工作流不通用，易冲突。
1.2.3 搜索不到或安装失败时
| 情况 | 处理 |
|---|---|
| 列表里没有 Sonic | 在 Manager 的Install via Git URL（或「通过 Git 安装」）中粘贴：https://github.com/smthemex/ComfyUI_Sonic.git，再 Install |
pip 超时 / 失败 |
进入节点目录手动安装：cd ComfyUI/custom_nodes/ComfyUI_Sonic && pip3 install -r requirements.txt |
| 权限 / git 报错 | 确认 custom_nodes 可写（按需 chown）；或改用 §1.1 手动 git clone |
| 安装后仍无 Sonic 节点 | 必须完整重启 ComfyUI 进程，不要只刷新浏览器 |
Manager 安装与 §1.1 手动 clone 二选一即可，不必重复安装同一仓库。
1.2.4 安装节点后的必做步骤
- 重启 ComfyUI（见 §3）。
- 按 §2 下载
models/sonic/与 SVD 检查点（否则 Queue 会报缺模型）。 - 在界面 Add Node 搜索 SONIC，确认出现
SONIC_PreData、SONICSampler等节点后再保存 API 工作流。
安装或更新节点后 必须重启 ComfyUI；仅刷新网页不会加载新节点。
2. 下载模型
国内怎么下（直连不行就用 ModelScope）
| 方式 | 适用 | 说明 |
|---|---|---|
ModelScope modelscope download |
国内服务器首选 | 魔搭镜像，大文件稳；先 pip install -U modelscope |
huggingface-cli / hf download + HF_ENDPOINT=https://hf-mirror.com |
备选 | ModelScope 无对应仓库时用 |
wget + hf-mirror.com / huggingface.co |
小文件或海外 | GB 级 safetensors 常 403/超时，不推荐当首选 |
通用安装 CLI：
pip install -U modelscope
下载命令格式（Sonic 两套模型见下表，把 --model 换成对应 ID）：
modelscope download \
--model <作者>/<仓库名> \
<文件名或子目录> \
--local_dir <保存目录>
在 https://www.modelscope.cn 搜索模型名（如 ComfyUI_Sonic、stable-video-diffusion），打开模型页可复制 模型 ID。
Sonic 要下 两套 权重，不要混：
| 目录 | 用途 | ModelScope 示例 |
|---|---|---|
models/checkpoints/ |
SVD 图生视频底模 | cjc1887415157/stable-video-diffusion-img2vid-xt-1-1 |
models/sonic/ |
Sonic 对口型专用 | zhuzhukeji/ComfyUI_Sonic_Models |
2.1 Sonic 权重（models/sonic/）
目标目录结构：
ComfyUI/models/sonic/
├── audio2bucket.pth
├── audio2token.pth
├── unet.pth
├── yoloface_v5m.pt
├── whisper-tiny/
│ ├── config.json
│ ├── model.safetensors
│ └── preprocessor_config.json
└── RIFE/
└── flownet.pkl
国内推荐：ModelScope 一键下整包
pip install -U modelscope
mkdir -p ComfyUI/models/sonic
modelscope download \
--model zhuzhukeji/ComfyUI_Sonic_Models \
--local_dir ComfyUI/models/sonic
模型页：https://www.modelscope.cn/models/zhuzhukeji/ComfyUI_Sonic_Models
下完后确认 unet.pth 约 6GB+（不是空目录）：
ls -lh ComfyUI/models/sonic/
ls -lh ComfyUI/models/sonic/whisper-tiny/
ls -lh ComfyUI/models/sonic/RIFE/flownet.pkl
若文件落在 models/sonic/sonic/ 子目录，挪到上一层：
mv ComfyUI/models/sonic/sonic/* ComfyUI/models/sonic/
备选： 官方 Google Drive 解压上传；或 HuggingFace 镜像：
pip3 install -U huggingface_hub
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download ApacheOne/ComfyUI-Sonic-models \
--include "sonic/*" \
--local-dir ComfyUI/models \
--local-dir-use-symlinks False
2.2 SVD 检查点（models/checkpoints/）
Sonic 工作流里的 ImageOnlyCheckpointLoader 需要其一：svd_xt.safetensors 或 svd_xt_1_1.safetensors（约 4～5GB）。
国内推荐：ModelScope（SVD 常用这条）
pip install -U modelscope
mkdir -p ComfyUI/models/checkpoints
modelscope download \
--model cjc1887415157/stable-video-diffusion-img2vid-xt-1-1 \
svd_xt_1_1.safetensors \
--local_dir ComfyUI/models/checkpoints
若要用 svd_xt（非 1.1），在 ModelScope 搜索 stable-video-diffusion-img2vid-xt 换对应模型 ID。
下完后检查（须在 checkpoints 根目录，且为 GB 级）：
ls -lh ComfyUI/models/checkpoints/svd_xt_1_1.safetensors
# 若在子目录：
find ComfyUI/models/checkpoints -name "svd_xt*.safetensors"
备选：huggingface-cli + HF 镜像（wget 对大文件常 403 时用）
pip3 install -U huggingface_hub
export HF_ENDPOINT=https://hf-mirror.com
cd ComfyUI/models/checkpoints
huggingface-cli download stabilityai/stable-video-diffusion-img2vid-xt-1-1 \
svd_xt_1_1.safetensors \
--local-dir . \
--local-dir-use-symlinks False
新版 CLI 也可写成：
hf download stabilityai/stable-video-diffusion-img2vid-xt-1-1 svd_xt_1_1.safetensors \
--local-dir ComfyUI/models/checkpoints
（同样先 export HF_ENDPOINT=https://hf-mirror.com。）
3. 重启并验证节点
本机示例：
cd ComfyUI
python3 main.py --listen 127.0.0.1 --port 8188
需局域网 / 公网访问时（将 0.0.0.0 换为实际需求，并注意端口安全）：
cd ComfyUI
python3 main.py --listen 0.0.0.0 --port 8188
浏览器打开后：
- 右键空白处 → Add Node，搜索 Sonic / SONIC
- 应能看到如
SONIC_PreData、SONICSampler等节点（名称因 fork 略有差异） - 打开仓库自带的 example_workflows 示例 JSON，在界面 Load 后点 Queue Prompt 试跑
首次运行会加载大模型，耗时较长，属正常现象。
4. 工作流要点
4.1 基本连线逻辑
典型流程（概念上）：
参考人像 (LoadImage) ──┐
├──► Sonic 预处理 / 采样 ──► 解码 ──► SaveVideo
音频 (LoadAudio) ──┘
- LoadImage：正面或半侧面人像，清晰、光线稳定，避免遮挡嘴部
- LoadAudio：与要对口型的 mp3/wav 片段，时长与生成段一致
- duration（秒）：控制本段生成时长，与音频长度匹配；不要用整曲时长跑长音频（易 OOM）
4.2 duration 与显存
- 插件用 duration（秒） 控制输出长度，不是「整首歌一次生成」
- T4（16GB） 等卡：建议单段 10～15 秒，过长易
CUDA out of memory - 长音频应 切段 → 多次生成 → 再拼接（可用 ffmpeg concat）；常见做法为每段用同一张原图，生成时长可比字幕段多 0.5～2 秒（本软件在「视频 → 模型配置」可调），拼接前裁掉尾秒
4.3 工作流 JSON 里的 duration
若在 API 或脚本中自动改 duration：
- JSON 里可写占位数值，运行时按当前音频切片覆盖
- 不要写整曲 200+ 秒，否则提交即可能爆显存
API 自动化时，工作流须包含：
LoadImage、LoadAudio- 带
duration（或video_duration/audio_duration）输入的 Sonic 相关节点 - 输出端 SaveVideo（或等价保存节点）
5. 导出 API 工作流
与通用 ComfyUI 一致：
- 在界面把 Sonic 工作流 跑通
- 菜单 Save (API Format)（不是普通 Save）
- 保存为如
ComfyUI/workflows/sonic_api.json
正确 API JSON： 顶层为 "3"、"7" 等节点 ID，含 class_type、inputs
错误： 含 nodes、links 的界面版 JSON
5.1 API 调用流程
POST /prompt提交 API JSON（鉴权用启动日志里的 token，或浏览器 CookieAIOHTTP_SESSION）- 上传参考图、音频到 ComfyUI
input（或工作流里已写死的文件名） GET /history/{prompt_id}轮询直至outputs出现（视频任务较慢，建议间隔 60 秒 以上）GET /view下载videos中的 mp4
单段视频生成可能需 数分钟到数十分钟，超时建议按 ≥ 3600 秒（1 小时）/ 段 配置客户端。
6. 常见问题
| 现象 | 处理建议 |
|---|---|
| 找不到 Sonic 节点 | 确认装在 custom_nodes/ComfyUI_Sonic，完整重启 ComfyUI；看启动日志 import 报错；勿混装多个 Sonic fork |
| Manager 里 Install 一直转圈 | 看 Manager 日志 / 手动 pip3 install -r requirements.txt；网络差时改 §1.1 手动 clone |
| Manager 按钮不存在 | 先按 §1.2.1 安装 ComfyUI-Manager 并重启；检查 custom_nodes/ComfyUI-Manager 路径是否正确 |
| 首次运行 OOM | 减小 image_size（见仓库 README）；缩短 duration；换更大显存卡 |
必须用 cuda:0 |
部分环境需指定 GPU 0，在启动参数加 --cuda-device 0 |
| bf16 / MPS 报错 | Linux + CUDA 一般无 MPS 问题；macOS 按仓库说明关闭 bf16 或换 fork |
| batch 与帧率 | 非 25fps 时历史版本曾有 batch 问题，以当前仓库 README 为准 |
| API 提交后一直无输出 | 看 ComfyUI 网页Queue 是否排队；查启动日志；确认模型路径完整 |
| 对口型与音频对不齐 | 检查音频是否被剪短；duration 是否与音频秒数一致 |
wget hf-mirror 返回 403 |
大文件改用**modelscope download** 或 huggingface-cli + HF_ENDPOINT=https://hf-mirror.com |
SONICTLoader 里 sonic_unet 为 none |
models/sonic/ 未下齐，用 §2.1 ModelScope 补 unet.pth 后重启 |
7. 参考链接
- Sonic 论文与原始项目：jixiaozhong/Sonic
- ComfyUI 节点（常用）：smthemex/ComfyUI_Sonic
- ComfyUI-Manager：ltdrdata/ComfyUI-Manager
- 另一实现：Sean-Bradley/ComfyUI-Sonic（节点命名可能不同，工作流不通用）
- 大模型国内下载：优先 ModelScope
modelscope download（见本文 §2）
附：长视频制作思路（通用）
完整音频 + 字幕时间轴 (.srt)
→ 按句/按秒切成多段 [t0, t1)，记每段时长 seg_len
→ 每段：始终用同一张原图；音频 [t0, t1+pad)（如 [0,16)、[15,31)）→ ComfyUI duration = seg_len+pad
→ 下载 mp4 后裁掉尾部 pad 秒，得到成片 [t0,t1)，拼接后总长不变
→ ffmpeg 拼接各段视频轨 + 混入完整原曲音频
这样每段显存可控，且每段人脸来自同一参考图。具体脚本或业务软件自行对接 API 即可。