# 人脸特征提取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`