%20(1).png)
ComfyUI-HunyuanPortrait 插件超详细新手教程
1. 插件简介
ComfyUI-HunyuanPortrait 是一个让你的照片变成会动的人像动画的神奇插件！
插件原地址： https://github.com/Yuan-ManX/ComfyUI-HunyuanPortrait
这个插件能干什么？
- 把静态人像照片变成会动的视频
- 让照片里的人做出各种表情和动作
- 控制人物的头部姿势和表情变化
- 生成逼真的人像动画效果
就像给照片里的人装上了"遥控器"，你可以控制他们眨眼、转头、微笑，就像哈利波特里面的魔法照片一样！
2. 如何安装
步骤一：确保你有ComfyUI
首先确保你的电脑上已经安装了ComfyUI（就像要玩游戏先装游戏平台一样）
步骤二：下载插件
- 打开你的ComfyUI文件夹
- 找到
custom_nodes文件夹（就像软件的"插件库"） - 在这个文件夹里打开终端（命令行）
- 输入下面的命令：
git clone https://github.com/Yuan-ManX/ComfyUI-HunyuanPortrait.git
步骤三：安装依赖包
就像做菜要准备食材一样，这个插件需要一些"配料"：
- 进入插件文件夹：
cd ComfyUI-HunyuanPortrait - 安装基础工具：
pip install torch torchvision torchaudio - 安装专用工具：
pip install -r requirements.txt
步骤四：下载模型文件
这些是让插件工作的"大脑"文件，需要放在 ComfyUI/models/HunyuanPortrait/pretrained_weights 文件夹里：
# 创建文件夹
mkdir -p ComfyUI/models/HunyuanPortrait/pretrained_weights
cd ComfyUI/models/HunyuanPortrait/pretrained_weights
# 下载各种"大脑"文件
pip install "huggingface_hub[cli]"
huggingface-cli download --resume-download stabilityai/stable-video-diffusion-img2vid-xt --local-dir . --include "*.json"
wget -c https://huggingface.co/LeonJoe13/Sonic/resolve/main/yoloface_v5m.pt
wget -c https://huggingface.co/stabilityai/stable-video-diffusion-img2vid-xt/resolve/main/vae/diffusion_pytorch_model.fp16.safetensors -P vae
wget -c https://huggingface.co/FoivosPar/Arc2Face/resolve/da2f1e9aa3954dad093213acfc9ae75a68da6ffd/arcface.onnx
huggingface-cli download --resume-download tencent/HunyuanPortrait --local-dir hyportrait
硬件要求
- 显卡：至少需要NVIDIA 3090或同等级别（24GB显存）
- 操作系统：推荐Linux，Windows可能需要额外配置
3. 节点详细解析
3.1 HunyuanPortrait_Loader 节点 - 模型加载器
这个节点就像是"启动器"，负责把所有的AI模型加载到内存里，让后面的节点能够使用。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 模型路径 | model_path | 文件路径 | 默认路径 | 告诉插件AI模型文件放在哪里 | 指定预训练模型的存储路径 | 选择你下载的模型文件夹 |
| 设备类型 | device | auto/cpu/cuda | auto | 选择用CPU还是显卡来运行 | 指定计算设备类型 | 有好显卡选cuda，没有选cpu |
| 精度模式 | precision | fp16/fp32 | fp16 | 选择计算精度，影响速度和质量 | 浮点数精度设置 | fp16更快但质量稍低，fp32更慢但质量更高 |
| 内存优化 | low_mem | True/False | False | 是否启用省内存模式 | 内存使用优化开关 | 显存不够时开启True |
3.2 HunyuanPortrait_Sampler 节点 - 生成采样器
这个节点是"画家"，负责根据你的输入生成动态人像。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 输入图片 | input_image | 图片文件 | - | 你想让它动起来的照片 | 输入的静态人像图像 | 上传一张清晰的人脸照片 |
| 驱动视频 | drive_video | 视频文件 | - | 参考动作的视频（可选） | 提供动作参考的视频文件 | 上传一段说话或表情变化的视频 |
| 生成步数 | steps | 1-100 | 20 | 生成质量高低的旋钮 | 扩散模型的采样步数 | 越高质量越好但越慢，20步够用 |
| 引导强度 | guidance_scale | 1.0-20.0 | 7.5 | 控制生成结果有多听话 | 分类器自由引导强度 | 太低会偏离输入，太高会过度拟合 |
| 视频长度 | video_length | 1-300 | 25 | 生成多少帧的视频 | 输出视频的总帧数 | 25帧约1秒视频（25fps） |
| 宽度 | width | 256-1024 | 512 | 输出视频的宽度 | 输出视频分辨率宽度 | 512适合大多数情况 |
| 高度 | height | 256-1024 | 512 | 输出视频的高度 | 输出视频分辨率高度 | 512适合大多数情况 |
| 种子值 | seed | 整数 | -1 | 随机数种子，控制生成结果 | 随机种子值 | -1为随机，固定数字可重复生成 |
3.3 HunyuanPortrait_FaceDetector 节点 - 人脸检测器
这个节点就像"扫描仪"，负责在图片中找到人脸的位置和关键点。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 输入图片 | input_image | 图片文件 | - | 需要检测人脸的图片 | 待检测的图像数据 | 上传包含人脸的图片 |
| 检测阈值 | detection_threshold | 0.1-1.0 | 0.5 | 检测敏感度调节器 | 人脸检测的置信度阈值 | 越低越敏感，能检测更模糊的脸 |
| 人脸数量 | max_faces | 1-10 | 1 | 最多检测几张脸 | 最大检测人脸数量 | 多人照片时可以调高 |
| 返回关键点 | return_landmarks | True/False | True | 是否返回面部关键点 | 是否输出面部特征点坐标 | True可以做更精确的控制 |
3.4 HunyuanPortrait_ExpressionExtractor 节点 - 表情提取器
这个节点像"表情分析师"，从视频中提取表情信息。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 输入视频 | input_video | 视频文件 | - | 要提取表情的视频 | 输入的视频数据 | 上传一段表情丰富的视频 |
| 帧率 | fps | 1-60 | 25 | 每秒处理多少帧 | 视频帧率设置 | 25fps适合大多数情况 |
| 起始帧 | start_frame | 0-N | 0 | 从第几帧开始提取 | 提取的起始帧位置 | 0表示从头开始 |
| 结束帧 | end_frame | 0-N | -1 | 到第几帧结束 | 提取的结束帧位置 | -1表示到视频末尾 |
| 平滑强度 | smooth_strength | 0.0-1.0 | 0.5 | 表情变化的平滑程度 | 时间序列平滑系数 | 越高变化越自然，越低越跟原视频 |
3.5 HunyuanPortrait_HeadPoseEstimator 节点 - 头部姿态估计器
这个节点像"姿态分析师"，专门分析头部的转动和倾斜。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 输入图片 | input_image | 图片文件 | - | 需要分析头部姿态的图片 | 输入的人像图像 | 上传人脸清晰的照片 |
| 算法类型 | algorithm | hopenet/6dof | hopenet | 选择姿态估计算法 | 头部姿态估计方法 | hopenet适合大多数情况 |
| 置信度阈值 | confidence_threshold | 0.1-1.0 | 0.3 | 估计结果的可信度门槛 | 姿态估计置信度阈值 | 越高结果越准确但可能检测不到 |
| 输出格式 | output_format | euler/matrix | euler | 输出角度还是矩阵 | 姿态数据的输出格式 | euler角度更直观，matrix更精确 |
3.6 HunyuanPortrait_VideoProcessor 节点 - 视频处理器
这个节点像"视频工厂"，负责把生成的结果组装成最终的视频。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 输入帧序列 | input_frames | 图片序列 | - | 一系列连续的图片帧 | 输入的视频帧序列 | 从采样器获得的图片序列 |
| 输出帧率 | output_fps | 1-60 | 25 | 输出视频的播放速度 | 输出视频的帧率 | 25fps标准电影帧率 |
| 视频格式 | video_format | mp4/avi/gif | mp4 | 保存什么格式的视频 | 输出视频的编码格式 | mp4兼容性最好 |
| 质量设置 | quality | 1-10 | 8 | 视频压缩质量 | 视频编码质量等级 | 越高文件越大质量越好 |
| 循环播放 | loop | True/False | False | 是否制作循环播放的视频 | 是否生成循环视频 | True制作无缝循环效果 |
3.7 HunyuanPortrait_PreviewImage 节点 - 图片预览器
这个节点像"展示框"，让你能看到处理过程中的图片。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 输入图片 | input_image | 图片文件 | - | 要预览的图片 | 输入的图像数据 | 连接其他节点的图片输出 |
| 显示标题 | title | 文字 | "Preview" | 预览窗口的标题 | 预览界面显示的标题 | 自定义名称方便区分 |
| 显示尺寸 | display_size | 像素值 | 256 | 预览图片的显示大小 | 预览图片的像素尺寸 | 256够看清楚又不占地方 |
| 自动刷新 | auto_refresh | True/False | True | 是否自动更新预览 | 是否实时更新预览图 | True方便看到实时效果 |
4. 使用技巧和建议
4.1 选择合适的输入图片
- 清晰度要求： 选择清晰、光线充足的人像照片
- 角度建议： 正面或微侧面的照片效果最好
- 分辨率： 建议至少512x512像素
- 背景简单： 避免复杂背景干扰人脸检测
4.2 参数调节心得
- 新手起步： 先用默认参数，熟悉后再调节
- 质量优先： 如果显存够用，优先提高steps和分辨率
- 速度优先： 显存不足时降低分辨率和steps
- 种子固定： 满意的效果记住seed值，可以重复生成
4.3 工作流程建议
- 先用FaceDetector检测人脸是否正确
- 再用Loader加载模型
- 最后用Sampler生成动画
- 用VideoProcessor输出最终视频
4.4 常见组合搭配
- 基础动画： Loader → Sampler → VideoProcessor
- 表情控制： + ExpressionExtractor → Sampler
- 姿态控制： + HeadPoseEstimator → Sampler
- 实时预览： + PreviewImage 查看中间结果
5. 常见问题解答
Q1: 安装后找不到节点？
答： 重启ComfyUI，确保插件文件夹在custom_nodes目录下。
Q2: 提示显存不足？
答： 降低分辨率到256x256，或者启用low_mem模式。
Q3: 生成的动画不自然？
答： 调低guidance_scale（比如5.0），增加平滑强度。
Q4: 处理速度太慢？
答： 减少steps到10-15，使用fp16精度模式。
Q5: 人脸检测失败？
答： 检查照片清晰度，调低detection_threshold到0.3。
Q6: 生成结果不稳定？
答： 固定seed值，确保每次生成相同结果。
Q7: 视频质量不好？
答： 提高输出质量设置，增加生成步数。
Q8: 支持哪些视频格式？
答： 推荐使用mp4格式，兼容性最好。
6. 高级技巧
6.1 批量处理
- 可以连接多个相同节点并行处理多张图片
- 使用不同的seed值生成多个版本
- 结合其他ComfyUI节点做后处理
6.2 风格化处理
- 可以在VideoProcessor后添加风格化节点
- 结合ControlNet做更精细的控制
- 配合其他AI插件做混合效果
6.3 性能优化
- 合理设置显存使用
- 根据硬件调整并行度
- 使用适当的精度模式
6.4 创意应用
- 制作表情包动画
- 创建虚拟主播效果
- 做影视特效预览
- 制作教学演示视频
7. 更新和维护
7.1 插件更新
定期检查GitHub仓库的更新，获取新功能和bug修复。
7.2 模型更新
关注官方发布的新模型，可能会有更好的效果。
7.3 社区资源
- 加入ComfyUI社区讨论
- 分享你的工作流程
- 学习其他用户的创意用法
总结： ComfyUI-HunyuanPortrait 是一个强大的人像动画生成工具，虽然安装配置稍显复杂，但效果非常出色。按照本教程一步步操作，你就能让静态照片变成生动的动画了！记住，熟练掌握需要多练习，不要害怕尝试不同的参数组合。