RetinaFace实战教程：如何将face_results结果导出为JSON格式供下游使用

RetinaFace实战教程：如何将face_results结果导出为JSON格式供下游使用

1. 引言：从可视化到结构化数据

当你使用RetinaFace镜像成功检测出人脸并绘制了关键点，看到face_results文件夹里一张张标注好的图片时，是不是觉得任务完成了？别急，这只是第一步。

在实际项目中，检测结果往往不是终点，而是起点。你的下游任务可能需要这些数据——可能是要统计人数、分析表情、进行人脸比对，或者集成到更大的业务系统中。这时候，图片格式的结果就显得有些“笨重”了。你需要的是结构化的、机器可读的数据。

这就是我们今天要解决的问题：如何将RetinaFace的检测结果，从图片里“提取”出来，转换成标准的JSON格式，让下游程序能直接使用。

简单来说，我们将实现一个功能：运行一次检测，不仅能得到标注好的图片，还能得到一个清晰的JSON文件。这个文件会告诉你：图片里有多少张脸，每张脸在哪里（坐标），以及五个关键点（双眼、鼻尖、嘴角）的精确位置。

整个过程就像把一份手写的报告，整理成一份标准的电子表格，方便后续的任何处理。接下来，我们就手把手教你实现它。

2. 理解RetinaFace的输出：数据在哪里？

在动手写代码之前，我们得先搞清楚RetinaFace的推理脚本到底输出了什么。这能帮助我们准确地找到需要导出的数据。

2.1 窥探推理脚本的内部

镜像提供的inference_retinaface.py脚本核心是调用ModelScope的模型进行预测。关键的一行代码类似于：

# 伪代码，示意模型调用 result = model(input_image)

这个result对象里就包含了我们想要的所有信息。为了看到它的真面目，一个最直接的方法是在脚本里临时添加几行打印代码。

操作步骤：

1. 进入工作目录：cd /root/RetinaFace
2. 备份原脚本：cp inference_retinaface.py inference_retinaface.py.backup
3. 用文本编辑器（如vim或nano）打开脚本，找到模型推理后、绘制结果图之前的代码位置。
4. 插入调试代码，例如：

   # 假设推理结果保存在变量 `detection_result` 中 print(f"结果类型: {type(detection_result)}") print(f"结果内容: {detection_result}") # 尝试查看其结构 if hasattr(detection_result, 'boxes'): print(f"检测框: {detection_result.boxes}") if hasattr(detection_result, 'keypoints'): print(f"关键点: {detection_result.keypoints}")

5. 运行脚本：python inference_retinaface.py -i ./your_test_image.jpg
6. 观察终端输出，你会看到类似下面的数据结构（具体字段名可能因ModelScope版本略有不同）：

通过这种方式，你会发现结果通常包含以下几个核心部分：

• boxes: 一个二维数组，每一行代表一个检测到的人脸框，格式通常是[x1, y1, x2, y2, score]，即左上角x、y坐标，右下角x、y坐标，以及检测置信度。
• keypoints: 一个三维数组，形状为[人脸数量, 5, 2]。对于每一张脸，它有5个关键点（左眼、右眼、鼻尖、左嘴角、右嘴角），每个点有x和y两个坐标。
• scores: 有时置信度会单独作为一个列表存放。

2.2 我们需要导出的核心数据

现在目标明确了。对于每一张输入图片，我们要导出的JSON需要包含：

1. 图片基本信息：如文件名、路径、处理时间。
2. 人脸数量：检测到的人脸总数。
3. 每个人脸的详细信息列表：
   • bbox: 人脸框坐标[x1, y1, x2, y2]。
   • score: 检测置信度。
   • landmarks: 5个关键点的坐标列表，每个点格式为[x, y]。顺序通常是：左眼、右眼、鼻尖、左嘴角、右嘴角。

有了这个清晰的目标，我们就可以开始动手编写导出工具了。

3. 实战：编写JSON结果导出脚本

我们不修改原有的可视化脚本，而是创建一个新的、专注数据导出的脚本。这样既能保持原有功能完整，又能获得干净的结构化数据。

3.1 创建新的Python脚本

在你的工作目录（/root/RetinaFace）下，创建一个新文件，例如叫做export_results_to_json.py。

# export_results_to_json.py import argparse import json import os from datetime import datetime from modelscope.pipelines import pipeline from modelscope.utils.constant import Tasks from PIL import Image import numpy as np def main(): # 1. 解析命令行参数 parser = argparse.ArgumentParser(description='使用RetinaFace检测人脸并导出JSON结果。') parser.add_argument('--input', '-i', type=str, required=True, help='输入图片路径（支持本地文件或URL）') parser.add_argument('--output_json', '-j', type=str, default='./detection_results.json', help='JSON结果输出路径（默认：./detection_results.json）') parser.add_argument('--threshold', '-t', type=float, default=0.5, help='人脸检测置信度阈值（默认：0.5）') args = parser.parse_args() # 2. 准备结果数据结构 result_data = { "image_info": { "file_path": args.input, "processed_time": datetime.now().isoformat() }, "detection_results": { "face_count": 0, "faces": [] } } # 3. 加载模型并执行推理 print(f"[INFO] 正在处理图片: {args.input}") face_detection = pipeline(Tasks.face_detection, 'damo/cv_resnet50_face-detection_retinaface') try: # 执行检测 detection_result = face_detection(args.input) # 4. 解析并过滤检测结果 # 注意：ModelScope返回的结果结构可能需要根据实际打印的调试信息调整键名 # 这里假设结果有 'boxes' 和 'keypoints' if detection_result and 'boxes' in detection_result: boxes = detection_result['boxes'] keypoints = detection_result.get('keypoints', []) face_list = [] valid_face_count = 0 # 假设 boxes 是 [N, 5] 的数组，最后一列是score for i, box in enumerate(boxes): # box: [x1, y1, x2, y2, score] if len(box) >= 5: score = float(box[4]) # 根据阈值过滤 if score >= args.threshold: valid_face_count += 1 face_info = { "face_id": i, "bbox": { "x1": float(box[0]), "y1": float(box[1]), "x2": float(box[2]), "y2": float(box[3]) }, "score": score, "landmarks": [] } # 提取对应的人脸关键点 if i < len(keypoints): # keypoints[i] 形状应为 [5, 2] for kp in keypoints[i]: if len(kp) >= 2: face_info["landmarks"].append({ "x": float(kp[0]), "y": float(kp[1]) }) else: face_info["landmarks"].append({"x": 0.0, "y": 0.0}) else: # 如果没有关键点数据，用空列表填充 face_info["landmarks"] = [] face_list.append(face_info) # 更新结果数据 result_data["detection_results"]["face_count"] = valid_face_count result_data["detection_results"]["faces"] = face_list print(f"[INFO] 检测到 {valid_face_count} 张人脸（阈值={args.threshold}）") else: print("[WARNING] 未检测到人脸或结果格式异常。") except Exception as e: print(f"[ERROR] 推理过程发生错误: {e}") result_data["error"] = str(e) # 5. 将结果保存为JSON文件 output_path = args.output_json try: with open(output_path, 'w', encoding='utf-8') as f: # indent参数让JSON文件更易读 json.dump(result_data, f, ensure_ascii=False, indent=2) print(f"[SUCCESS] 结果已成功导出至: {output_path}") except Exception as e: print(f"[ERROR] 写入JSON文件失败: {e}") if __name__ == '__main__': main()

3.2 脚本使用说明

保存上面的代码后，你就可以在终端里使用它了。

基本命令：

# 激活环境（如果尚未激活） conda activate torch25 # 进入工作目录 cd /root/RetinaFace # 运行脚本，检测图片并导出JSON python export_results_to_json.py -i ./your_photo.jpg

运行后，会在当前目录生成一个detection_results.json文件。

更多参数示例：

# 指定输入图片和自定义JSON输出路径 python export_results_to_json.py -i ./group_photo.jpg -j ./output/faces.json # 使用更高的置信度阈值（只输出更确定的人脸） python export_results_to_json.py -i ./crowd.jpg -t 0.8 # 检测网络图片 python export_results_to_json.py -i https://example.com/test.jpg

3.3 生成的JSON文件示例

运行脚本后，打开生成的JSON文件，你会看到结构清晰的数据：

{ "image_info": { "file_path": "./test_group.jpg", "processed_time": "2024-05-27T10:30:15.123456" }, "detection_results": { "face_count": 3, "faces": [ { "face_id": 0, "bbox": { "x1": 120.5, "y1": 85.2, "x2": 185.7, "y2": 170.8 }, "score": 0.996, "landmarks": [ {"x": 135.3, "y": 110.5}, {"x": 165.1, "y": 112.8}, {"x": 150.2, "y": 135.7}, {"x": 138.9, "y": 155.2}, {"x": 161.5, "y": 156.8} ] }, { "face_id": 1, "bbox": { "x1": 300.1, "y1": 90.5, "x2": 365.3, "y2": 176.1 }, "score": 0.987, "landmarks": [ {"x": 315.0, "y": 115.8}, {"x": 345.2, "y": 117.3}, {"x": 330.5, "y": 140.1}, {"x": 318.8, "y": 160.5}, {"x": 341.9, "y": 162.1} ] } // ... 可能还有第三张脸的数据 ] } }

这个结构非常直观，任何下游程序（Python、Java、JavaScript等）都可以轻松解析和使用。

4. 进阶：批量处理与结果整合

单张图片处理很好，但实际项目往往是批量处理。我们可以轻松扩展脚本功能。

4.1 批量处理多张图片

创建一个新脚本batch_export_json.py，核心思路是遍历一个文件夹内的所有图片，为每张图片生成一个独立的JSON文件，或者汇总到一个大的JSON中。

示例代码片段（汇总模式）：

import os import glob import json def process_batch(input_folder, output_json='batch_results.json', threshold=0.5): all_results = [] image_extensions = ['*.jpg', '*.jpeg', '*.png', '*.bmp'] for ext in image_extensions: image_paths = glob.glob(os.path.join(input_folder, ext)) for img_path in image_paths: print(f"处理: {img_path}") # 调用单张图片的处理函数（需稍作修改使其返回字典） result = process_single_image(img_path, threshold) all_results.append(result) # 保存所有结果 with open(output_json, 'w') as f: json.dump({"batch_results": all_results}, f, indent=2) print(f"批量处理完成，共处理 {len(all_results)} 张图片。")

4.2 与可视化脚本结合使用

你可能既需要可视化的图片用于人工检查，又需要结构化的JSON用于程序分析。一个高效的工作流是：

1. 并行运行：同时运行可视化脚本和JSON导出脚本。

   # 终端1：生成标注图片 python inference_retinaface.py -i ./photos/ -d ./visual_results/ # 终端2：生成JSON数据 python batch_export_json.py -i ./photos/ -j ./data_results/

2. 结果关联：在JSON数据中，可以加入生成的可视化结果图片路径，方便对应查看。

   { "image_info": { "source": "./photos/group1.jpg", "visualization": "./visual_results/group1_retinaface.jpg" } // ... 其他人脸数据 }

5. 下游应用场景示例

有了标准化的JSON输出，这些数据能怎么用？想象空间很大。

5.1 人脸计数与基础统计

用Python几行代码就能实现：

import json with open('detection_results.json', 'r') as f: data = json.load(f) face_count = data['detection_results']['face_count'] print(f"图片中共有 {face_count} 张人脸") # 计算平均置信度 scores = [face['score'] for face in data['detection_results']['faces']] avg_score = sum(scores) / len(scores) if scores else 0 print(f"平均检测置信度: {avg_score:.3f}")

5.2 生成人脸位置报告

将坐标数据转换成更易读的报告格式，或标记在原始图片上（使用PIL或OpenCV）。

from PIL import Image, ImageDraw # 加载JSON数据 # 加载原始图片 img = Image.open('your_photo.jpg') draw = ImageDraw.Draw(img) for face in faces_data: bbox = face['bbox'] # 在图片上绘制矩形框 draw.rectangle([bbox['x1'], bbox['y1'], bbox['x2'], bbox['y2']], outline='red', width=2) # 标注人脸ID和分数 draw.text((bbox['x1'], bbox['y1']-10), f"ID:{face['face_id']}({face['score']:.2f})", fill='green') img.save('annotated_faces.jpg')

5.3 集成到Web服务或应用程序

JSON是Web API的通用语言。你可以快速搭建一个简单的Flask服务：

from flask import Flask, request, jsonify import tempfile import os app = Flask(__name__) @app.route('/detect-faces', methods=['POST']) def detect_faces(): # 接收上传的图片 image_file = request.files['image'] # 保存临时文件 # 调用我们的JSON导出函数 result = process_image_and_export_to_dict(temp_image_path) # 返回JSON结果 return jsonify(result) if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)

这样，任何前端或移动端应用都可以通过调用这个API，直接获取结构化的人脸检测结果。

6. 总结与最佳实践

通过本教程，你已经掌握了将RetinaFace检测结果从“可视化图片”转换为“结构化JSON数据”的完整方法。让我们回顾一下关键点，并分享一些让流程更顺畅的建议。

6.1 核心步骤回顾

1. 理解数据源：首先通过调试，弄明白inference_retinaface.py脚本内部result对象的具体数据结构（boxes,keypoints等）。
2. 设计数据结构：规划好JSON的格式，明确要包含图片信息、人脸数量、每个人脸的框、分数和关键点。
3. 编写导出脚本：创建独立的export_results_to_json.py脚本，解析模型输出，过滤数据，并序列化为JSON文件。
4. 扩展与集成：可以进一步开发批量处理功能，并将JSON数据轻松应用于统计分析、Web服务或与其他系统集成。

6.2 实践建议与技巧

• 先调试，后编码：在写导出脚本前，务必先用print语句查看模型返回值的具体格式，因为ModelScope的接口可能随版本更新略有变化。
• 保持脚本独立：新建脚本而不是修改原可视化脚本，这样两者功能清晰，互不干扰。
• 处理异常情况：在你的脚本中加入健壮的错误处理（如try...except），应对图片读取失败、网络URL无效、模型加载错误等情况。
• 数据序列化：使用json.dump()的indent参数让输出的JSON文件拥有缩进，便于人工阅读和调试。
• 性能考虑：批量处理大量图片时，可以考虑复用已加载的模型管道，而不是每次处理都重新加载，以提升速度。

将结果导出为JSON，看似是一个简单的格式转换，实则是将AI能力从“演示阶段”推向“工程应用阶段”的关键一步。结构化的数据是自动化的基石，它让RetinaFace强大的人脸检测能力，能够无缝嵌入到你工作流的任何一个环节中。

现在，你的face_results不再只是一堆图片，而是一个随时待命的数据宝库。去构建你的下一个有趣的应用吧。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。