> ## 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 얼굴 감지를 사용하여 이미지에서 얼굴을 감지하고 얼굴 랜드마크, 경계 상자 및 영역 마스크를 추출하는 방법을 알아보세요

<Tip>
  <Tabs>
    <Tab title="휴대용 또는 자체 배포 사용자">
      ComfyUI가 최신 버전으로 업데이트되었는지 확인하세요.

      * [ComfyUI 다운로드](https://www.comfy.org/download)
      * [업데이트 가이드](/ko/installation/update_comfyui)

      이 가이드의 워크플로우는 [워크플로우 템플릿](/ko/interface/features/template)에서 확인할 수 있습니다.
      템플릿에서 찾을 수 없다면, 귀하의 ComfyUI가 오래된 버전일 수 있습니다. (데스크톱 버전의 업데이트는 다소 지연될 수 있습니다)

      워크플로우를 로드할 때 노드가 누락되는 경우, 가능한 원인:

      1. 최신 ComfyUI 버전(야간 빌드)을 사용하고 있지 않음
      2. 일부 노드가 시작 시 가져오기에 실패함
    </Tab>

    <Tab title="데스크톱 또는 클라우드 사용자">
      * 데스크톱 버전은 ComfyUI 안정판 기반으로, 새로운 데스크톱 안정판이 출시되면 자동으로 업데이트됩니다.
      * [클라우드](https://cloud.comfy.org)는 ComfyUI 안정판 출시 후 업데이트됩니다.

      따라서 이 문서에서 핵심 노드가 누락된 것을 발견했다면, 그 이유는 새로운 핵심 노드가 아직 최신 안정판에 공개되지 않았기 때문일 수 있습니다. 다음 안정판 출시를 기다려 주세요.
    </Tab>
  </Tabs>
</Tip>

[MediaPipe](https://github.com/google-ai-edge/mediapipe)는 실시간 인식을 위한 구글의 오픈소스 머신러닝 솔루션입니다. ComfyUI에서 MediaPipe 얼굴 감지는 **BlazeFace** 감지, **FaceMesh v2** 랜드마크 추정, 그리고 **ARKit-52 블렌드셰이프**를 하나의 통합된 워크플로우로 제공합니다.

MediaPipe 얼굴 감지는 ComfyUI에서 기본적으로 지원되며([PR #14009](https://github.com/Comfy-Org/ComfyUI/pull/14009)), 모델 가중치는 [Apache 2.0 라이선스](https://github.com/google-ai-edge/mediapipe/blob/master/LICENSE) 하에 이용 가능합니다.

[MediaPipe GitHub](https://github.com/google-ai-edge/mediapipe) | [Comfy-Org 모델 저장소](https://huggingface.co/Comfy-Org/mediapipe)

### 주요 기능

* **빠른 얼굴 감지** — BlazeFace 기반 감지기로 짧은(\~2m) 및 전체(\~5m) 범위 변형 제공
* **478개의 얼굴 랜드마크** — 감지된 각 얼굴마다 밀도 높은 FaceMesh v2 키포인트 제공
* **ARKit-52 블렌드셰이프** — 실시간 얼굴 표정 계수
* **얼굴 영역 마스크** — 얼굴 타원, 입술, 눈, 홍채별로 영역별 마스크 제공
* **얼굴 경계 상자** — 경계 상자 시각화를 위한 `DrawBBoxes`와 호환되는 출력 제공

> **범위:** 얼굴 감지만 제공 — BlazeFace + FaceMesh v2 + ARKit 블렌드셰이프. 이는 손, 자세 또는 전신 감지를 포함하지 않습니다.

## MediaPipe 얼굴 감지 워크플로우

### 1. 워크플로우 다운로드하기

ComfyUI를 최신 버전으로 업데이트한 후, `워크플로우` → `템플릿 둘러보기`로 이동해 유틸리티 카테고리에서 "Mediapipe: 이미지 얼굴 감지"를 찾으세요.

<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 얼굴 감지 미리보기](https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/templates/utility_face_detection_mediapipe-1.webp)

### 2. 모델 다운로드하기

MediaPipe 얼굴 감지 모델은 [Comfy-Org MediaPipe 모델 저장소](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. 워크플로우 사용하기

이 워크플로우는 얼굴 감지, 시각화 및 마스크 생성을 조율하는 **서브그래프** 노드를 사용합니다. 서브그래프는 다음과 같은 컨트롤을 노출합니다:

<Card title="서브그래프 알아보기" icon="book-open" href="/ko/interface/features/subgraph">
  이 워크플로우는 서브그래프 노드를 사용해 모듈식 처리를 수행합니다. 서브그래프 문서를 확인해 워크플로우를 맞춤화하고 확장하는 방법을 알아보세요.
</Card>

**서브그래프 입력:**

| 입력                   | 설명                                                                  |
| -------------------- | ------------------------------------------------------------------- |
| **image**            | 분석할 입력 이미지 배치                                                       |
| **face\_landmarker** | 선택적. 내장 모델 로더를 사용하려면 비워두세요. 외부 `FACE_DETECTION_MODEL` 출력을 연결해 덮어쓰세요 |

**서브그래프 매개변수:**

| 매개변수                   |                기본값                | 설명                                                                                                                              |
| ---------------------- | :-------------------------------: | ------------------------------------------------------------------------------------------------------------------------------- |
| **model\_name**        | `mediapipe_face_fp32.safetensors` | `ComfyUI/models/detection/`에 있는 체크포인트. 없으면 위에서 모델을 다운로드하세요                                                                      |
| **detector\_variant**  |              `short`              | **short** — 가까운/큰 얼굴용으로 조정됨(\~2m 범위). **full** — 더 작고 먼 얼굴까지 포괄하며 느림. **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`              | 마스크에 홍채 영역 포함                                                                                                                   |

마스크 토글은 내부적으로 커스텀 모드를 사용합니다: 체크된 영역만 채워지고, 여러 ON 영역은 프레임당 하나의 마스크로 **합집합**됩니다.

**서브그래프 출력:**

| 출력                  | 유형               | 설명                                                                         |
| ------------------- | ---------------- | -------------------------------------------------------------------------- |
| **face\_landmarks** | `FACE_LANDMARKS` | 프레임별 얼굴과 478개의 2D/3D 랜드마크, ARKit-52 블렌드셰이프, 메쉬 토폴로지 데이터 — 시각화 및 마스크 노드에 공급 |
| **bboxes**          | `BOUNDING_BOX`   | 얼굴 경계 상자 — `DrawBBoxes` 노드와 호환                                             |
| **mask**            | `MASK`           | 활성화된 영역 토글에 따른 이진 마스크                                                      |

### 4. 워크플로우 실행하기

1. 모델 파일이 `ComfyUI/models/detection/`에 배치되었는지 확인하세요.
2. `이미지 로드` 노드에서 이미지를 불러오세요.
3. 필요에 따라 감지 매개변수를 조정하세요.
4. `큐`를 클릭하거나 `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 서브그래프 가이드](https://docs.comfy.org/interface/features/subgraph) — 서브그래프 작동 방식 알아보기