%20(1).png)
ComfyUI Sapiens 插件完全教程
1. 插件简介
插件地址： https://github.com/smthemex/ComfyUI_Sapiens
这个插件就像是给 ComfyUI 装了一个"人体透视仪"和"人体分析师"！它能让你的图片变成各种神奇的效果，比如看透人体的深度、分析人体姿态、分离人体各个部位，甚至能生成人体的法线贴图。
想象一下，你有一张人物照片，这个插件就能帮你：
- 把人体的各个部位（头、手、脚、衣服等）分别提取出来，就像给人体做"解剖"
- 分析人体的深度信息，告诉你哪里近哪里远
- 检测人体的姿态和关节点，就像给人体画骨架
- 生成法线贴图，用于3D建模和游戏开发
主要功能：
- 人体分割：把人体分成28个不同部位，可以单独提取任意部位
- 深度检测：分析图片中人体的远近深度信息
- 姿态检测：识别人体的关节点和姿态
- 法线生成：生成用于3D渲染的法线贴图
- 遮罩生成：自动生成人体区域的遮罩
2. 如何安装
方法一：通过 ComfyUI Manager 安装（推荐）
- 打开 ComfyUI
- 点击右下角的 "Manager" 按钮
- 在搜索框输入 "Sapiens"
- 找到插件后点击 "Install" 安装
- 重启 ComfyUI
方法二：手动安装
- 打开终端或命令提示符
- 进入你的 ComfyUI 安装目录下的
custom_nodes文件夹 - 运行命令：
git clone https://github.com/smthemex/ComfyUI_Sapiens.git - 运行命令：
pip install -r requirements.txt - 重启 ComfyUI
重要提醒
- 需要下载多个模型文件到
models/sapiens文件夹 - 模型文件较大，建议使用稳定的网络环境
- 支持多种模型规格：0.3B、0.6B、1B、2B（数字越大质量越好但速度越慢）
- 如果使用姿态检测功能，还需要下载 YOLOv8 模型
模型下载说明
插件会自动创建以下文件夹结构：
ComfyUI/models/sapiens/
├── seg/ (人体分割模型)
├── depth/ (深度检测模型)
├── normal/ (法线生成模型)
├── pose/ (姿态检测模型)
└── yolov8m.pt (YOLO检测模型，用于姿态检测)
3. 节点详细解析
3.1 SapiensLoader 节点
这个节点就像是"模型管理员"，负责加载和配置所有需要的人体分析模型，就像给电脑装上各种专业的"人体分析软件"。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| Seg Ckpt | seg_ckpt | 下拉选择 | 选择分割模型 | 选择哪个"人体切割刀"来分离身体部位 | 人体分割模型文件选择 | 选择 sapiens_1b_seg 获得最佳质量 |
| Depth Ckpt | depth_ckpt | 下拉选择 | 选择深度模型 | 选择哪个"深度探测器"来分析远近 | 深度估计模型文件选择 | 选择 sapiens_1b_depth 获得准确深度 |
| Normal Ckpt | normal_ckpt | 下拉选择 | 选择法线模型 | 选择哪个"表面分析器"来生成法线贴图 | 法线估计模型文件选择 | 选择对应的 normal 模型文件 |
| Pose Ckpt | pose_ckpt | 下拉选择 | 选择姿态模型 | 选择哪个"骨架检测器"来分析人体姿态 | 姿态估计模型文件选择 | 选择 sapiens_1b_pose 检测关节点 |
| Dtype | dtype | 下拉选择 | float32_torch | 选择计算精度，就像选择计算器的精确度 | 模型推理时的数据类型 | float32 最准确，bfloat16 更快但略粗糙 |
| Minimum Person Height | minimum_person_height | 小数 | 0.5 | 设置能检测到的最小人体高度比例 | 人体检测的最小高度阈值 | 0.5 表示图片中人体至少占一半高度才检测 |
| Remove Background | remove_background | 开关 | True | 是否自动去除背景，只保留人体 | 是否移除背景保留人体区域 | 开启后背景变透明，只显示人体部分 |
| Use YOLO | use_yolo | 开关 | False | 是否使用YOLO来辅助检测人体 | 是否启用YOLO目标检测 | 姿态检测时建议开启，提高检测准确性 |
| Show Pose Object | show_pose_object | 开关 | False | 是否在姿态图上显示检测框 | 是否在姿态结果中显示目标框 | 开启后能看到检测到的人体边界框 |
| Seg Pellete | seg_pellete | 开关 | True | 是否使用彩色调色板显示分割结果 | 是否使用调色板渲染分割结果 | 开启后不同身体部位显示不同颜色 |
| Convert Torchscript to BF16 | convert_torchscript_to_bf16 | 开关 | False | 是否将模型转换为更小的格式 | 是否转换模型为半精度格式 | 开启后模型文件更小，速度更快 |
3.2 SapiensSampler 节点
这个节点是真正的"人体分析师"，它接收图片和配置，然后输出各种分析结果，就像一个全能的人体检测实验室。
参数详解
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| Model | model | 连接线 | 来自 SapiensLoader | 这是从模型加载器传来的"分析工具箱" | 从加载器节点传递的模型对象 | 用线连接到 SapiensLoader 的输出 |
| Image | image | 图片输入 | 连接图片 | 这是你要分析的人体照片 | 输入的图像数据 | 连接图片加载节点或其他图片输出 |
| Seg Select | seg_select | 下拉选择 | none | 选择要提取的特定身体部位 | 选择特定的分割类别 | 选择 "5.Left_Hand" 只提取左手部分 |
| Add Seg Index | add_seg_index | 文本输入 | 空白 | 用数字指定额外要提取的身体部位 | 额外的分割索引，用逗号分隔 | 输入 "2,5,21" 提取脸部、左手、躯干 |
| Save Pose | save_pose | 开关 | False | 是否保存姿态数据为文件 | 是否将姿态关键点保存为npy文件 | 开启后在输出文件夹生成姿态数据文件 |
| BG_R | BG_R | 滑块 | 255 | 设置背景的红色分量，就像调色板的红色 | 背景颜色的红色通道值 | 255 是纯红，0 是无红色，128 是中等红色 |
| BG_G | BG_G | 滑块 | 255 | 设置背景的绿色分量，就像调色板的绿色 | 背景颜色的绿色通道值 | 255 是纯绿，0 是无绿色，128 是中等绿色 |
| BG_B | BG_B | 滑块 | 255 | 设置背景的蓝色分量，就像调色板的蓝色 | 背景颜色的蓝色通道值 | 255 是纯蓝，0 是无蓝色，128 是中等蓝色 |
4. 使用技巧和建议
4.1 模型选择建议
- 质量优先：选择 1B 或 2B 模型获得最佳效果
- 速度优先：选择 0.3B 或 0.6B 模型获得更快处理速度
- 内存有限：开启 convert_torchscript_to_bf16 减少内存占用
- 精确分割：使用 seg 模型配合具体的 seg_select 参数
4.2 身体部位编号对照表
0.Background - 背景
1.Apparel - 服装
2.Face_Neck - 脸部和脖子
3.Hair - 头发
4.Left_Foot - 左脚
5.Left_Hand - 左手
6.Left_Lower_Arm - 左前臂
7.Left_Lower_Leg - 左小腿
8.Left_Shoe - 左鞋
9.Left_Sock - 左袜子
10.Left_Upper_Arm - 左上臂
11.Left_Upper_Leg - 左大腿
12.Lower_Clothing - 下装
13.Right_Foot - 右脚
14.Right_Hand - 右手
15.Right_Lower_Arm - 右前臂
16.Right_Lower_Leg - 右小腿
17.Right_Shoe - 右鞋
18.Right_Sock - 右袜子
19.Right_Upper_Arm - 右上臂
20.Right_Upper_Leg - 右大腿
21.Torso - 躯干
22.Upper_Clothing - 上装
23.Lower_Lip - 下唇
24.Upper_Lip - 上唇
25.Lower_Teeth - 下牙
26.Upper_Teeth - 上牙
27.Tongue - 舌头
4.3 参数组合建议
- 完整人体分析：所有模型都选择，seg_select 选择 "none"
- 手部特写：只选择 seg 模型，seg_select 选择 "5.Left_Hand" 或 "14.Right_Hand"
- 姿态分析：选择 pose 模型，开启 use_yolo 和 show_pose_object
- 深度分析：选择 depth 模型，用于后续的景深效果
- 服装分离：选择 seg 模型，add_seg_index 输入 "1,12,22"
4.4 性能优化技巧
- 显存不足：开启 convert_torchscript_to_bf16，选择较小的模型
- 处理速度慢：选择 0.3B 模型，关闭不需要的功能
- 批量处理：一次处理多张图片时注意显存使用
- 结果质量：使用高分辨率输入图片获得更好效果
5. 常见问题解答
Q1：为什么模型加载失败？
A：
- 检查网络连接，模型需要从网上下载
- 确保
models/sapiens文件夹有写入权限 - 检查磁盘空间是否足够（模型文件较大）
- 尝试手动下载模型文件到对应文件夹
Q2：分割效果不理想怎么办？
A：
- 使用更大的模型（1B 或 2B）
- 确保输入图片中人体清晰可见
- 调整 minimum_person_height 参数
- 尝试不同的 seg_select 组合
Q3：姿态检测检测不到人体？
A：
- 开启 use_yolo 选项
- 确保下载了 yolov8m.pt 模型
- 检查图片中人体是否完整
- 调整 minimum_person_height 参数
Q4：处理速度很慢怎么办？
A：
- 选择较小的模型（0.3B 或 0.6B）
- 开启 convert_torchscript_to_bf16
- 降低输入图片分辨率
- 只加载需要的模型，其他设为 "none"
Q5：输出结果是黑色的？
A：
- 检查对应的模型是否正确加载
- 确认输入图片中有人体
- 尝试调整背景颜色参数
- 检查 remove_background 设置
6. 进阶使用技巧
6.1 创意应用场景
- 服装设计：分离上装、下装进行服装替换
- 人体建模：使用法线贴图进行3D建模
- 动作分析：提取姿态关键点分析运动
- 医学应用：分析人体各部位的比例和位置
- 游戏开发：生成角色的各种贴图资源
6.2 工作流搭建建议
- 基础分析流程：图片加载 → SapiensLoader → SapiensSampler → 结果保存
- 部位提取流程：设置特定 seg_select → 提取特定部位 → 后续处理
- 深度合成流程：深度检测 → 结合其他节点制作景深效果
- 姿态追踪流程：姿态检测 → 保存关键点数据 → 动画制作
6.3 输出结果说明
- seg_img：人体分割结果，不同部位显示不同颜色
- depth_img：深度图，近处亮远处暗
- normal_img：法线贴图，用于3D渲染
- pose_img：姿态检测结果，显示关键点和连线
- mask：人体区域遮罩，白色是人体黑色是背景
6.4 模型管理技巧
- 定期清理：删除不需要的模型文件释放空间
- 版本管理：保留效果好的模型版本
- 备份重要模型：避免重新下载
- 监控显存使用：根据硬件选择合适的模型大小
7. 注意事项和最佳实践
7.1 使用注意事项
- 硬件要求：建议使用支持CUDA的显卡
- 内存需求：大模型需要较多显存和内存
- 网络环境：首次使用需要稳定网络下载模型
- 版本兼容：注意 ultralytics 库的版本安全问题
7.2 输入图片要求
- 人体清晰：确保人体在图片中清晰可见
- 完整性：人体尽量完整，避免严重遮挡
- 分辨率：适中的分辨率，太小影响效果太大影响速度
- 光线条件：良好的光线有助于提高检测准确性
7.3 最佳实践
- 渐进测试：从简单功能开始，逐步尝试复杂应用
- 参数记录：记录好用的参数组合
- 结果对比：对比不同模型和参数的效果
- 合理规划：根据需求选择合适的功能组合
总结： ComfyUI Sapiens 是一个功能强大的人体分析插件，包含了人体分割、深度检测、姿态估计、法线生成等多种功能。虽然模型文件较大，对硬件有一定要求，但能够产生专业级的人体分析结果。掌握好各种参数和技巧，你就能创造出各种有趣的人体分析和处理效果！
记住：好的分析效果需要清晰的输入图片和合适的模型选择。多尝试不同的参数组合，找到最适合你需求的设置。这个插件特别适合需要精确人体分析的专业应用场景！