Face_reg_app/FaceFeatureExtractorAPI/API_USAGE.md

# 人脸特征提取API使用文档

## 快速开始

### 1. 安装依赖

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

### 2. 启动服务

```bash
# 基础启动
python app.py

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

# 开发模式（支持热重载）
python app.py --reload
```

服务启动后访问:
- API服务: http://localhost:8000
- 交互式文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

---

## API接口说明

### 接口1: 人脸特征提取

**接口地址**: `POST /api/extract_feature`

**功能**: 上传一张人脸图像,提取并返回1024维特征向量

**请求参数**:
- `image` (File): 人脸图像文件 (支持 jpg, png, jpeg 格式)

**响应示例**:
```json
{
  "success": true,
  "message": "特征提取成功",
  "feature": [0.123, -0.456, 0.789, ...],  // 1024维特征向量
  "feature_dim": 1024,
  "quality_passed": true,
  "processing_time": 0.235
}
```

**Python调用示例**:
```python
import requests

url = "http://localhost:8000/api/extract_feature"

with open("face.jpg", "rb") as f:
    files = {"image": f}
    response = requests.post(url, files=files)
    result = response.json()

if result["success"]:
    feature = result["feature"]  # 获取特征向量
    print(f"特征维度: {result['feature_dim']}")
else:
    print(f"失败: {result['message']}")
```

**cURL示例**:
```bash
curl -X POST "http://localhost:8000/api/extract_feature" \
  -F "image=@face.jpg"
```

---

### 接口2: 两个特征值对比

**接口地址**: `POST /api/compare_features`

**功能**: 输入两个特征向量,计算相似度并判断是否为同一人

**请求体** (JSON):
```json
{
  "feature1": [0.123, -0.456, ...],  // 1024维特征向量
  "feature2": [0.789, 0.234, ...]    // 1024维特征向量
}
```

**响应示例**:
```json
{
  "success": true,
  "message": "对比成功",
  "similarity": 0.8523,
  "is_same_person": true,
  "threshold": 0.7
}
```

**Python调用示例**:
```python
import requests
import json

url = "http://localhost:8000/api/compare_features"

data = {
    "feature1": feature_vector_1,  # 从接口1获取的特征
    "feature2": feature_vector_2   # 从接口1获取的特征
}

response = requests.post(url, json=data)
result = response.json()

if result["success"]:
    print(f"相似度: {result['similarity']:.4f}")
    print(f"是否同一人: {result['is_same_person']}")
```

**cURL示例**:
```bash
curl -X POST "http://localhost:8000/api/compare_features" \
  -H "Content-Type: application/json" \
  -d '{
    "feature1": [0.1, 0.2, ...],
    "feature2": [0.3, 0.4, ...]
  }'
```

---

### 接口3: 人脸图像和特征值对比 (组合接口)

**接口地址**: `POST /api/compare_image_feature`

**功能**: 上传一张图像和一个特征向量,自动提取图像特征后进行对比

**请求参数**:
- `image` (File): 人脸图像文件
- `feature` (Form): 特征向量的JSON字符串

**响应示例**:
```json
{
  "success": true,
  "message": "对比成功",
  "similarity": 0.8234,
  "is_same_person": true,
  "threshold": 0.7,
  "processing_time": 0.245
}
```

**Python调用示例**:
```python
import requests
import json

url = "http://localhost:8000/api/compare_image_feature"

# 已有的特征向量
known_feature = [0.123, -0.456, ...]  # 1024维

with open("test_face.jpg", "rb") as f:
    files = {"image": f}
    data = {"feature": json.dumps(known_feature)}
    response = requests.post(url, files=files, data=data)
    result = response.json()

if result["success"]:
    print(f"相似度: {result['similarity']:.4f}")
    print(f"是否同一人: {result['is_same_person']}")
else:
    print(f"失败: {result['message']}")
```

**cURL示例**:
```bash
curl -X POST "http://localhost:8000/api/compare_image_feature" \
  -F "image=@face.jpg" \
  -F 'feature=[0.1, 0.2, 0.3, ...]'
```

---

## 完整工作流程示例

### 场景: 人脸识别系统

```python
import requests
import json

API_BASE = "http://localhost:8000"

# 步骤1: 注册用户 - 提取并存储特征
def register_user(user_id, image_path):
    """注册用户人脸"""
    url = f"{API_BASE}/api/extract_feature"

    with open(image_path, "rb") as f:
        files = {"image": f}
        response = requests.post(url, files=files)
        result = response.json()

    if result["success"]:
        # 将特征向量存储到数据库
        feature = result["feature"]
        save_to_database(user_id, feature)
        print(f"✓ 用户 {user_id} 注册成功")
        return feature
    else:
        print(f"✗ 注册失败: {result['message']}")
        return None

# 步骤2: 验证用户 - 使用组合接口
def verify_user(user_id, image_path):
    """验证用户身份"""
    # 从数据库获取已存储的特征
    stored_feature = get_from_database(user_id)

    if not stored_feature:
        print(f"✗ 用户 {user_id} 不存在")
        return False

    # 使用组合接口进行对比
    url = f"{API_BASE}/api/compare_image_feature"

    with open(image_path, "rb") as f:
        files = {"image": f}
        data = {"feature": json.dumps(stored_feature)}
        response = requests.post(url, files=files, data=data)
        result = response.json()

    if result["success"]:
        is_verified = result["is_same_person"]
        similarity = result["similarity"]
        print(f"{'✓' if is_verified else '✗'} 验证结果: {similarity:.4f}")
        return is_verified
    else:
        print(f"✗ 验证失败: {result['message']}")
        return False

# 步骤3: 1对N识别 - 在数据库中搜索最相似的人脸
def identify_user(image_path):
    """识别用户（1:N匹配）"""
    # 先提取待识别图像的特征
    url = f"{API_BASE}/api/extract_feature"

    with open(image_path, "rb") as f:
        files = {"image": f}
        response = requests.post(url, files=files)
        result = response.json()

    if not result["success"]:
        print(f"✗ 特征提取失败: {result['message']}")
        return None

    query_feature = result["feature"]

    # 与数据库中所有用户特征进行对比
    all_users = get_all_users_from_database()

    best_match = None
    best_similarity = 0.0

    for user_id, stored_feature in all_users.items():
        # 使用接口2对比特征
        url = f"{API_BASE}/api/compare_features"
        data = {
            "feature1": query_feature,
            "feature2": stored_feature
        }
        response = requests.post(url, json=data)
        result = response.json()

        if result["success"]:
            similarity = result["similarity"]
            if similarity > best_similarity:
                best_similarity = similarity
                best_match = user_id

    # 判断是否超过阈值
    if best_similarity >= 0.7:
        print(f"✓ 识别为: {best_match} (相似度: {best_similarity:.4f})")
        return best_match
    else:
        print(f"✗ 未识别到已注册用户 (最高相似度: {best_similarity:.4f})")
        return None

# 使用示例
if __name__ == "__main__":
    # 注册用户
    register_user("user001", "photos/user001.jpg")
    register_user("user002", "photos/user002.jpg")

    # 验证用户
    verify_user("user001", "photos/user001_verify.jpg")

    # 识别用户
    identify_user("photos/unknown.jpg")
```

---

## 错误处理

### 常见错误码

- `400`: 请求参数错误 (图像无法解析、特征维度不匹配等)
- `500`: 服务器内部错误 (模型加载失败、处理异常等)
- `503`: 服务不可用 (健康检查失败)

### 错误响应示例

```json
{
  "success": false,
  "message": "未检测到合格的人脸",
  "processing_time": 0.123
}
```

---

## 性能优化建议

1. **批量处理**: 对于大量图像,建议使用异步并发请求
2. **特征缓存**: 已提取的特征应缓存到数据库,避免重复计算
3. **负载均衡**: 高并发场景下可部署多个实例
4. **GPU加速**: 如有GPU,可安装 `onnxruntime-gpu` 加速推理

---

## 相似度阈值说明

默认阈值: **0.7**

- `>= 0.7`: 认为是同一人
- `< 0.7`: 认为不是同一人

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

---

## 技术支持

- 查看交互式API文档: http://localhost:8000/docs
- 查看示例代码: `examples/api_client_example.py`