README.md

---
license: mit
tags:
- face-recognition
- face-embedding
- face-similarity
- insightface
- computer-vision
pipeline_tag: feature-extraction
---

# InsightFace Endpoint Model

InsightFace를 사용한 얼굴 임베딩 추출 및 유사도 계산 모델입니다.

## 모델 설명

이 모델은 다음 두 가지 주요 기능을 제공합니다:

1. **얼굴 감지 및 임베딩 추출 (Face Detection & Embedding)**: `buffalo_l` 모델을 사용하여 이미지에서 얼굴을 감지하고 특징 벡터(임베딩)를 추출합니다.
2. **얼굴 유사도 계산 (Face Similarity)**: 두 얼굴의 임베딩 벡터 간 코사인 유사도를 계산하여 얼굴이 같은 사람인지 판단합니다.

## 모델 파일

- `buffalo_l/`: 얼굴 감지 및 임베딩 추출 모델 폴더
  - `det_10g.onnx`: 얼굴 감지 모델
  - `genderage.onnx`: 성별/나이 추정 모델
  - `w600k_r50.onnx`: 얼굴 랜드마크 및 임베딩 추출 모델

## 사용 방법

### Inference Endpoint API

이 모델은 HuggingFace Inference Endpoint로 배포되어 사용됩니다.

#### 얼굴 감지 및 임베딩 추출

```python
import requests

response = requests.post(
    "https://your-endpoint-url.hf.space",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "task": "face-detect",
        "image": "data:image/png;base64,..."
    }
)

# 응답 형식:
# {
#   "faces": [
#     {
#       "bbox": [x1, y1, x2, y2],
#       "embedding": [0.123, 0.456, ...],  # 512차원 벡터
#       "det_score": 0.99,
#       "gender": 0,  # 0: 여성, 1: 남성
#       "age": 25
#     }
#   ]
# }
```

#### 얼굴 유사도 계산

```python
response = requests.post(
    "https://your-endpoint-url.hf.space",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "task": "face-similarity",
        "image1": "data:image/png;base64,...",
        "image2": "data:image/png;base64,...",
        "face_index1": 0,
        "face_index2": 0
    }
)

# 응답 형식:
# {
#   "similarity": 0.85,  # 0.0 ~ 1.0 (1.0이 가장 유사)
#   "embedding1": [0.123, 0.456, ...],
#   "embedding2": [0.234, 0.567, ...],
#   "face1_info": {"bbox": [...], "det_score": 0.99, ...},
#   "face2_info": {"bbox": [...], "det_score": 0.98, ...}
# }
```

## 요구사항

- Python 3.8+
- ONNX Runtime
- InsightFace 라이브러리

## 라이선스

이 모델은 원본 InsightFace 모델의 라이선스를 따릅니다.

## 사용 사례

- 얼굴 인증 및 검증
- 동일인 판별
- 얼굴 기반 검색
- 출입 통제 시스템

## 참고 자료

- [InsightFace 공식 사이트](https://www.insightface.ai/)
- [InsightFace GitHub](https://github.com/deepinsight/insightface)