> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MediaPipe：ComfyUI 人脸检测

> 了解如何在 ComfyUI 中使用 MediaPipe Face Detection 检测人脸，提取面部关键点、边界框和区域遮罩

<Tip>
  <Tabs>
    <Tab title="便携版或手动安装用户">
      请确保你的 ComfyUI 已经更新。

      * [ComfyUI 下载](https://www.comfy.org/download)
      * [ComfyUI 更新教程](/zh/installation/update_comfyui)

      本指南里的工作流可以在 ComfyUI 的[工作流模板](/zh/interface/features/template)中找到。如果找不到，可能是 ComfyUI 没有更新。

      如果加载工作流时有节点缺失，可能原因有：

      1. 你用的不是最新开发版（nightly）。
      2. 你用的是稳定版或桌面版（没有包含最新的更新）。
      3. 启动时有些节点导入失败。
    </Tab>

    <Tab title="桌面版或云端用户">
      * 桌面版是基于 ComfyUI 稳定版本构建的，它会在有新的桌面稳定版本发布时自动更新。
      * [Cloud](https://cloud.comfy.org) 会在 ComfyUI 稳定版本发布后更新，我们会同步更新 Cloud。

      所以，如果你发现本教程中有任何核心节点缺失，那是因为对应的节点支持还在开发中没有发布正式的稳定版，请等待下一个稳定版本发布。
    </Tab>
  </Tabs>
</Tip>

[MediaPipe](https://github.com/google-ai-edge/mediapipe) 是 Google 开源的实时感知机器学习解决方案。在 ComfyUI 中，MediaPipe Face Detection 集成了 **BlazeFace** 检测、**FaceMesh v2** 关键点估计和 **ARKit-52 blendshape**，全部在一个统一的工作流中完成。

MediaPipe Face Detection 已原生集成到 ComfyUI（PR [#14009](https://github.com/Comfy-Org/ComfyUI/pull/14009)），模型权重基于 [Apache 2.0 License](https://github.com/google-ai-edge/mediapipe/blob/master/LICENSE) 提供。

[MediaPipe GitHub](https://github.com/google-ai-edge/mediapipe) | [Comfy-Org Model Repository](https://huggingface.co/Comfy-Org/mediapipe)

### 主要功能

* **快速人脸检测** — 基于 BlazeFace 的检测器，支持近距离（约 2 米）和远距离（约 5 米）检测
* **478 个面部关键点** — 每张人脸密集的 FaceMesh v2 关键点
* **ARKit-52 blendshape** — 实时面部表情系数
* **面部区域遮罩** — 面部轮廓、嘴唇、眼睛和虹膜的逐区域遮罩
* **人脸边界框** — 输出兼容 `DrawBBoxes` 节点用于边界框可视化

> **范围说明：** 仅人脸检测 — BlazeFace + FaceMesh v2 + ARKit blendshape。不包括手部、姿态或整体检测。

## MediaPipe Face Detection 工作流

### 1. 下载工作流

将 ComfyUI 更新到最新版本，然后进入 `Workflow` → `Browse Templates`，在 Utility 分类下找到 "Mediapipe: Image Face Detection"。

<Card title="下载工作流 JSON 文件" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_face_detection_mediapipe.json">
  下载工作流
</Card>

<Card title="在 Comfy Cloud 中运行" icon="cloud" href="https://cloud.comfy.org/?template=utility_face_detection_mediapipe&utm_source=docs&utm_medium=referral&utm_campaign=mediapipe">
  在云端打开
</Card>

<Card title="下载示例图片" icon="image" href="https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/soft_neon_girl.png">
  获取此工作流的示例输入图片
</Card>

![MediaPipe Face Detection 预览](https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/templates/utility_face_detection_mediapipe-1.webp)

### 2. 下载模型

MediaPipe Face Detection 模型托管在 [Comfy-Org MediaPipe model repository](https://huggingface.co/Comfy-Org/mediapipe) 上。

* [mediapipe\_face\_fp32.safetensors](https://huggingface.co/Comfy-Org/mediapipe/resolve/main/detection/mediapipe_face_fp32.safetensors)

将其放置在以下目录结构中：

```
📂 ComfyUI/
└── 📂 models/
    └── 📂 detection/
        └── mediapipe_face_fp32.safetensors
```

### 3. 使用工作流

本工作流使用一个 **subgraph**（子图）节点来协调人脸检测、可视化和遮罩生成。子图暴露了以下控制参数：

<Card title="了解 Subgraph" icon="book-open" href="/zh/interface/features/subgraph">
  本工作流使用 Subgraph 节点进行模块化处理。查看 Subgraph 文档了解如何自定义和扩展工作流。
</Card>

**子图输入：**

| 输入                   | 描述                                                |
| -------------------- | ------------------------------------------------- |
| **image**            | 要分析的输入图片批次                                        |
| **face\_landmarker** | 可选。留空则使用内置模型加载器。连接外部 `FACE_DETECTION_MODEL` 输出可覆盖 |

**子图参数：**

| 参数                     |                默认值                | 描述                                                                                                             |
| ---------------------- | :-------------------------------: | -------------------------------------------------------------------------------------------------------------- |
| **model\_name**        | `mediapipe_face_fp32.safetensors` | `ComfyUI/models/detection/` 目录下的模型文件。如缺失则下载上述模型                                                                |
| **detector\_variant**  |              `short`              | **short** — 针对近距离/大脸优化（约 2 米范围）。**full** — 覆盖更小/更远的人脸（约 5 米），速度较慢。**both** — 同时运行两个检测器，保留每帧检测到更多人脸的结果（约 2 倍开销） |
| **num\_faces**         |                `1`                | 每帧最多返回的人脸数。`0` = 不限制（返回所有检测结果）。范围：0–16                                                                         |
| **custom\_face\_oval** |              `false`              | 在遮罩输出中包含面部轮廓区域                                                                                                 |
| **custom\_lips**       |              `false`              | 在遮罩中包含嘴唇（与其他启用的区域合并）                                                                                           |
| **custom\_left\_eye**  |              `false`              | 在遮罩中包含左眼区域                                                                                                     |
| **custom\_right\_eye** |              `false`              | 在遮罩中包含右眼区域                                                                                                     |
| **custom\_irises**     |              `false`              | 在遮罩中包含虹膜区域                                                                                                     |

遮罩切换在内部使用自定义模式：仅填充勾选的区域；多个开启的区域会合并为每帧一个遮罩。

**子图输出：**

| 输出                  | 类型               | 描述                                                                |
| ------------------- | ---------------- | ----------------------------------------------------------------- |
| **face\_landmarks** | `FACE_LANDMARKS` | 每帧人脸数据，包含 478 个 2D/3D 关键点、ARKit-52 blendshape、网格拓扑数据——输入到可视化和遮罩节点 |
| **bboxes**          | `BOUNDING_BOX`   | 人脸边界框——兼容 `DrawBBoxes` 节点                                         |
| **mask**            | `MASK`           | 基于启用的区域切换生成的二值遮罩                                                  |

### 4. 运行工作流

1. 确保模型文件已放置在 `ComfyUI/models/detection/` 目录
2. 在 `Load Image` 节点加载一张图片
3. 根据需要调整检测参数
4. 点击 `Queue` 或使用 `Ctrl(Cmd) + Enter` 运行
5. 工作流输出网格覆盖图、边界框和遮罩预览

## 社区资源

* [MediaPipe GitHub](https://github.com/google-ai-edge/mediapipe) — MediaPipe 上游框架
* [Comfy-Org/mediapipe](https://huggingface.co/Comfy-Org/mediapipe) — 官方 ComfyUI 模型权重
* [ComfyUI Subgraph 指南](https://docs.comfy.org/zh/interface/features/subgraph) — 了解子图的工作原理