# 人脸特征提取API - 快速启动指南

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 启动API服务

```bash
python app.py
```

服务将在 `http://localhost:8000` 启动

### 3. 访问API文档

浏览器打开: http://localhost:8000/docs

---

## 📋 三个核心接口

### ✅ 接口1: 人脸特征提取
- **路径**: `POST /api/extract_feature`
- **功能**: 上传图像,提取1024维人脸特征向量
- **输入**: 人脸图像文件
- **输出**: 特征向量 + 质量评估结果

### ✅ 接口2: 特征向量对比
- **路径**: `POST /api/compare_features`
- **功能**: 计算两个特征向量的相似度
- **输入**: 两个1024维特征向量
- **输出**: 相似度分数 + 是否同一人判断

### ✅ 接口3: 图像特征对比 (组合接口)
- **路径**: `POST /api/compare_image_feature`
- **功能**: 上传图像和特征向量,自动提取并对比
- **输入**: 人脸图像 + 特征向量
- **输出**: 相似度分数 + 是否同一人判断

---

## 🔧 Python调用示例

```python
import requests

# 接口1: 提取特征
with open("face.jpg", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/extract_feature",
        files={"image": f}
    )
    result = response.json()
    feature = result["feature"]  # 获取特征向量

# 接口2: 对比特征
response = requests.post(
    "http://localhost:8000/api/compare_features",
    json={
        "feature1": feature1,
        "feature2": feature2
    }
)
result = response.json()
print(f"相似度: {result['similarity']}")

# 接口3: 图像特征对比
import json
with open("test.jpg", "rb") as f:
    response = requests.post(
        "http://localhost:8000/api/compare_image_feature",
        files={"image": f},
        data={"feature": json.dumps(known_feature)}
    )
    result = response.json()
    print(f"是否同一人: {result['is_same_person']}")
```

---

## 📚 详细文档

- **完整API文档**: [API_USAGE.md](API_USAGE.md)
- **客户端示例**: [examples/api_client_example.py](examples/api_client_example.py)
- **交互式文档**: http://localhost:8000/docs (启动服务后访问)

---

## 🎯 应用场景

1. **人脸注册**: 使用接口1提取特征并存储到数据库
2. **人脸验证 (1:1)**: 使用接口3验证用户身份
3. **人脸识别 (1:N)**: 使用接口1+接口2在数据库中搜索匹配
4. **人脸去重**: 使用接口2批量对比特征,找出重复人脸

---

## ⚙️ 启动参数

```bash
# 默认启动
python app.py

# 自定义端口
python app.py --port 8080

# 自定义地址和端口
python app.py --host 0.0.0.0 --port 8000

# 开发模式(热重载)
python app.py --reload
```

---

## 📊 相似度阈值

- **默认阈值**: 0.7
- **>= 0.7**: 判断为同一人
- **< 0.7**: 判断为不同人

根据实际需求调整:
- 安全优先: 提高阈值 (0.75-0.85)
- 体验优先: 降低阈值 (0.6-0.65)

---

## 🛠️ 技术栈

- **Web框架**: FastAPI
- **深度学习**: ONNX Runtime
- **图像处理**: OpenCV
- **特征维度**: 1024维 (固定,由模型决定)
- **相似度算法**: 余弦相似度

> 💡 **特征维度说明**: 查看 [FEATURE_DIMENSION.md](FEATURE_DIMENSION.md) 了解如何调整特征维度

---

## 📞 支持

遇到问题? 查看完整文档: [API_USAGE.md](API_USAGE.md)