# 人脸识别API服务器方案

## 一、方案概述

将人脸识别功能部署为独立的API服务，通过HTTP请求的方式提供给机器人调用，实现功能与业务逻辑的解耦。

## 二、技术架构

### 1. 服务端架构
- **框架**：Flask/FastAPI（轻量级Web框架）
- **人脸识别**：基于现有的FaceRecognitionAPI
- **部署**：Docker容器化部署
- **通信**：RESTful API

### 2. 客户端架构
- **机器人端**：通过HTTP请求调用API
- **认证**：API Key认证
- **响应处理**：JSON格式解析

## 三、API设计

### 1. 核心接口

| 接口 | 方法 | 功能 | 请求体 | 响应 |
|------|------|------|--------|------|
| `/api/recognize` | POST | 识别人脸 | `{"image": "base64编码的图像"}` | `{"detected": true, "faces": [...]}` |
| `/api/add-face` | POST | 添加人脸 | `{"name": "用户名", "image": "base64编码的图像"}` | `{"success": true, "message": "添加成功"}` |
| `/api/database` | GET | 获取数据库信息 | N/A | `{"face_count": 5, "faces": ["张三", "李四"]}` |
| `/api/health` | GET | 健康检查 | N/A | `{"status": "healthy"}` |

### 2. 接口详细设计

#### 识别接口 (`/api/recognize`)
- **请求**：
  ```json
  {
    "image": "base64编码的图像数据",
    "threshold": 0.6 (可选)
  }
  ```
- **响应**：
  ```json
  {
    "success": true,
    "detected": true,
    "faces": [
      {
        "name": "张三",
        "confidence": 0.98,
        "similarity": 0.85,
        "bbox": [100, 100, 200, 200]
      }
    ],
    "count": 1
  }
  ```

#### 添加人脸接口 (`/api/add-face`)
- **请求**：
  ```json
  {
    "name": "张三",
    "image": "base64编码的图像数据"
  }
  ```
- **响应**：
  ```json
  {
    "success": true,
    "message": "人脸添加成功",
    "name": "张三"
  }
  ```

## 四、服务端实现

### 1. 项目结构
```
face-recognition-api/
├── app/
│   ├── __init__.py
│   ├── api.py          # API路由
│   ├── face_service.py # 人脸识别服务
│   └── utils.py        # 工具函数
├── config.py           # 配置文件
├── Dockerfile          # Docker配置
├── requirements.txt    # 依赖管理
└── run.py              # 启动脚本
```

### 2. 核心代码示例

#### `app/face_service.py`
```python
from face_recognition_api import FaceRecognitionAPI

class FaceService:
    def __init__(self):
        self.face_api = FaceRecognitionAPI()
    
    def recognize(self, image):
        """识别人脸"""
        return self.face_api.detect_and_recognize(image)
    
    def add_face(self, name, image):
        """添加人脸"""
        # 实现添加人脸逻辑
        pass
    
    def get_database_info(self):
        """获取数据库信息"""
        return self.face_api.get_database_info()
```

#### `app/api.py`
```python
from flask import Flask, request, jsonify
from app.face_service import FaceService
import base64
import cv2
import numpy as np

app = Flask(__name__)
face_service = FaceService()

@app.route('/api/recognize', methods=['POST'])
def recognize():
    data = request.json
    image_data = data.get('image')
    
    # 解码base64图像
    image = base64_to_cv2(image_data)
    
    # 识别人脸
    results = face_service.recognize(image)
    
    return jsonify({
        "success": True,
        **results
    })

@app.route('/api/add-face', methods=['POST'])
def add_face():
    data = request.json
    name = data.get('name')
    image_data = data.get('image')
    
    # 解码base64图像
    image = base64_to_cv2(image_data)
    
    # 添加人脸
    success = face_service.add_face(name, image)
    
    return jsonify({
        "success": success,
        "message": "添加成功" if success else "添加失败"
    })

def base64_to_cv2(base64_string):
    """将base64字符串转换为cv2图像"""
    import base64
    import numpy as np
    import cv2
    
    # 移除base64头部
    if ',' in base64_string:
        base64_string = base64_string.split(',')[1]
    
    # 解码
    image_data = base64.b64decode(base64_string)
    image_array = np.frombuffer(image_data, dtype=np.uint8)
    image = cv2.imdecode(image_array, cv2.IMREAD_COLOR)
    
    return image
```

## 五、部署方案

### 1. Docker容器化

#### `Dockerfile`
```dockerfile
FROM python:3.8-slim

WORKDIR /app

# 安装依赖
RUN apt-get update && apt-get install -y \
    libgl1-mesa-glx \
    libglib2.0-0 \
    fonts-wqy-microhei \
    fonts-wqy-zenhei \
    && rm -rf /var/lib/apt/lists/*

# 复制文件
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# 暴露端口
EXPOSE 5000

# 启动服务
CMD ["python", "run.py"]
```

#### `requirements.txt`
```
Flask==2.0.1
numpy==1.24.3
opencv-python==4.5.5.64
insightface==0.7.3
freetype-py==2.3.0
Pillow==8.4.0
```

### 2. 启动脚本 (`run.py`)
```python
from app.api import app

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)
```

## 六、客户端调用示例

### Python客户端
```python
import requests
import base64
import cv2

def recognize_face(image_path):
    # 读取图像并编码为base64
    with open(image_path, 'rb') as f:
        image_data = f.read()
    base64_image = base64.b64encode(image_data).decode('utf-8')
    
    # 发送请求
    response = requests.post(
        'http://localhost:5000/api/recognize',
        json={'image': base64_image},
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    )
    
    return response.json()

# 使用示例
result = recognize_face('test.jpg')
print(result)
```

### 机器人端调用
```python
def handle_face_recognition():
    # 拍照
    image = capture_image()
    
    # 调用API
    result = recognize_face(image)
    
    if result['detected']:
        for face in result['faces']:
            if face['name'] != 'Unknown':
                return f"你好，{face['name']}！"
    return "你好，陌生人！"
```

## 七、安全性考虑

1. **API认证**：使用API Key或JWT Token进行认证
2. **请求限流**：防止恶意请求攻击
3. **输入验证**：验证图像格式和大小
4. **HTTPS**：生产环境使用HTTPS加密传输
5. **错误处理**：避免暴露敏感错误信息

## 八、性能优化

1. **模型缓存**：预加载模型，避免每次请求重新加载
2. **异步处理**：使用异步框架处理并发请求
3. **批处理**：支持批量人脸识别
4. **图像压缩**：限制上传图像大小
5. **硬件加速**：如果服务器支持，使用GPU加速

## 九、监控与维护

1. **日志记录**：记录API调用和错误信息
2. **健康检查**：定期检查服务状态
3. **数据库备份**：定期备份人脸数据库
4. **版本管理**：API版本控制

## 十、迁移步骤

1. **提取人脸识别核心代码**：将FaceRecognitionAPI从现有代码中提取
2. **创建API服务**：实现Flask/FastAPI服务
3. **容器化部署**：构建Docker镜像并部署
4. **客户端适配**：修改机器人代码调用API
5. **测试验证**：确保功能正常运行

## 十一、优势分析

1. **解耦**：人脸识别功能与业务逻辑分离
2. **可扩展性**：独立部署，易于横向扩展
3. **维护性**：单独升级和维护
4. **复用性**：可被多个客户端同时使用
5. **安全性**：集中管理认证和授权

此方案既保留了现有人脸识别功能的完整性，又提供了灵活的API调用方式