视觉 · 人脸识别

1. 模块概述

• 主要功能：基于 ArcFace（MobileFaceNet）的人脸特征提取与相似度比对。输入一张 112×112 的人脸图片，输出高维特征向量（embedding），通过计算两个特征向量的余弦相似度判断是否为同一人。通常与人脸检测（YOLOv5-Face）配合使用。
• 规格或特性：
  • 支持模型：ArcFace MobileFaceNet
  • 输入尺寸：[1, 3, 112, 112]
  • 量化类型：int8
  • 输出：人脸特征向量（embedding）
  • 相似度阈值：0.6（默认，可调）
  • 推理后端：ONNX Runtime + SpaceMITExecutionProvider
  • 接口形态：C++（vision_service.h）、Python（spacemit_vision wheel：VisionServiceNative）
• 相关目录结构：

examples/arcface/
├── config/arcface.yaml    # 配置文件
├── cpp/arcface.cpp        # C++ 示例
├── python/arcface.py      # Python 示例
└── scripts/               # 模型下载脚本
src/deploy/arcface/        # 部署实现（C++ / Python）

2. 环境准备

前置条件

SDK 源码获取和基础编译环境配置统一参考 2.3-构建编译。完成 SDK 初始化后，回到本文继续执行"构建编译"。

后续命令默认在 spacemit_robot SDK 根目录执行。

构建编译

系统缺少依赖时先安装：

sudo apt install python3-spacemit-ort opencv-spacemit libeigen3-dev spacemit-onnxruntime libyaml-cpp-dev

在 SDK 根目录加载构建环境后编译视觉组件：

source build/envsetup.sh
cd components/model_zoo/vision
mm

SDK 集成构建会把 arcface 等示例程序安装到 output/staging/bin，加载 build/envsetup.sh 后可直接运行。

运行 Python 示例前，需先安装 spacemit_vision wheel：

cd components/model_zoo/vision
python3 -m pip install -U pybind11 build setuptools wheel
cmake -S . -B build && cmake --build build -j
python3 -m pip install --force-reinstall src/python/dist/*.whl
python3 -c "from spacemit_vision import VisionServiceNative; print('ok')"

模型权重默认存放路径为 ~/.cache/models/vision/arcface/。须先手动执行下载脚本；缺失时程序会直接报错（Model file not found）。

3. 示例使用（从 0 跑通）

3.1 ArcFace 人脸识别（Python）

前置：见 §2。

步骤 1：下载模型

cd components/model_zoo/vision
bash examples/arcface/scripts/download_models.sh

预期现象：模型文件下载至 ~/.cache/models/vision/arcface/arcface_mobilefacenet_cut.q.onnx。

步骤 2：下载测试素材

bash scripts/download_assets.sh

预期现象：测试人脸图片下载至 ~/.cache/assets/image/003_face0.png 和 ~/.cache/assets/image/004_face1.png。

步骤 3：运行人脸比对

python3 examples/arcface/python/arcface.py --config examples/arcface/config/arcface.yaml

3.2 ArcFace 人脸识别（C++）

前置：见 §2，C++ 编译完成。

步骤 1：下载模型（同 §3.1 步骤 1）

步骤 2：运行人脸比对

arcface examples/arcface/config/arcface.yaml

3.3 运行结果示例

终端输出示例：

相似度: 0.1931
判断: 非同一人

4. 应用开发

本章面向应用开发者，说明如何在自己的 C++ 或 Python 应用中集成人脸识别组件。完整接口定义以 include/vision_service.h 和 src/python/spacemit_vision/vision_service_native.py 为准；本节介绍常用公开接口和典型调用方式。

4.1 接口说明

人脸识别组件基于 ArcFace 模型，通过提取人脸特征向量（embedding）并计算相似度来判断是否为同一人。应用侧需要先使用人脸检测模型定位人脸区域，裁剪对齐后再送入 ArcFace 提取特征。

4.1.1 常用数据结构

类型	说明
vision::Embedding	人脸特征向量结果，字段 std::vector<float> embedding（通常 128 维或 512 维）与 float score。
VisionServiceResponse	统一推理响应，包含 results（vision::ResultList，即 std::variant 列表）、ok、error_message。
VisionServiceStatus	接口返回的状态码枚举，VISION_SERVICE_OK 表示成功。

4.1.2 服务初始化

C++ 接口

接口	说明	参数	返回值
VisionService::Create	从 YAML 配置文件创建人脸识别服务实例	config_path：YAML 配置文件路径	VisionService 智能指针
VisionService::LastCreateError	获取最近一次创建失败的错误信息	无	错误描述字符串

Python 接口

接口	说明	参数	返回值
VisionServiceNative.create	从 YAML 配置文件创建人脸识别服务	config_path：YAML 路径；model_path_override：可选覆盖模型路径	VisionServiceNative 实例
VisionServiceNative.last_create_error	获取最近一次创建失败的错误信息	无	错误描述字符串

4.1.3 人脸识别

C++ 接口

接口	说明	参数	返回值
Infer	统一推理入口，对人脸图像提取特征（结果以 vision::Embedding 变体写入 response）	image_path：人脸图像文件路径；response：输出 VisionServiceResponse	VisionServiceStatus（VISION_SERVICE_OK 表示成功）
Infer	统一推理入口，对 cv::Mat 图像提取特征	image：OpenCV Mat 对象；response：输出 VisionServiceResponse	VisionServiceStatus（VISION_SERVICE_OK 表示成功）
EmbeddingSimilarity	计算两个特征向量的余弦相似度（静态方法）	embedding_a：特征向量 A；embedding_b：特征向量 B	float（相似度，范围 -1 到 1）
LastError	获取最近一次推理的错误信息	无	错误描述字符串

Python 接口

接口	说明	参数	返回值
infer_embedding	提取人脸特征向量	image_or_path：BGR numpy 数组或图像路径	(VisionServiceStatus, embedding 列表)
VisionServiceNative.embedding_similarity	计算两个特征向量的余弦相似度（静态方法）	embedding_a、embedding_b：特征向量	float（-1 到 1）
last_error	获取最近一次推理错误	无	错误描述字符串

4.1.4 性能监控

C++ 接口

接口	说明	参数	返回值
SetTimingOptions	启用/禁用性能计时	options：VisionServiceTimingOptions（设置 enabled 字段）	void
GetLastTiming	获取最近一次推理的各阶段耗时	无	VisionServiceTiming 结构体（包含 model_infer_ms、infer_ms 等字段）

4.2 典型调用流程

4.2.1 C++ 人脸比对（1:1）

#include "vision_service.h"
#include <opencv2/opencv.hpp>
#include <variant>
#include <vector>
#include <iostream>

int main() {
    // 1. 创建服务
    auto service = VisionService::Create("examples/arcface/config/arcface.yaml");
    if (!service) {
        std::cerr << "Failed to create service: "
                  << VisionService::LastCreateError() << std::endl;
        return -1;
    }

    // 2. 启用性能计时（可选）
    VisionServiceTimingOptions timing_options;
    timing_options.enabled = true;
    service->SetTimingOptions(timing_options);

    // 3. 提取人脸特征：统一 Infer 接口，结果以 vision::Embedding 变体返回
    auto extract_embedding = [&](const std::string& path,
                                 std::vector<float>* out) -> bool {
        VisionServiceResponse response;
        if (service->Infer(path, &response) != VISION_SERVICE_OK) {
            std::cerr << "Infer failed: " << service->LastError() << std::endl;
            return false;
        }
        if (response.results.empty()) return false;
        const vision::Embedding* emb =
            std::get_if<vision::Embedding>(&response.results[0]);
        if (emb == nullptr) return false;
        *out = emb->embedding;
        return true;
    };

    std::vector<float> embedding_a, embedding_b;
    if (!extract_embedding("face_a.jpg", &embedding_a)) return -1;
    if (!extract_embedding("face_b.jpg", &embedding_b)) return -1;

    // 4. 计算相似度（静态方法）
    float similarity = VisionService::EmbeddingSimilarity(embedding_a, embedding_b);

    std::cout << "Similarity: " << similarity << std::endl;

    // 5. 判断是否为同一人（阈值 0.6）
    if (similarity > 0.6) {
        std::cout << "Same person" << std::endl;
    } else {
        std::cout << "Different person" << std::endl;
    }

    // 6. 查看性能指标（可选）
    auto timing = service->GetLastTiming();
    std::cout << "Inference: " << timing.infer_ms << " ms" << std::endl;

    return 0;
}

4.2.2 C++ 人脸搜索（1:N）

#include "vision_service.h"
#include <opencv2/opencv.hpp>
#include <variant>
#include <vector>
#include <string>

// 提取单张人脸的特征向量
static bool ExtractEmbedding(VisionService* service,
                             const std::string& path,
                             std::vector<float>* out) {
    VisionServiceResponse response;
    if (service->Infer(path, &response) != VISION_SERVICE_OK) return false;
    if (response.results.empty()) return false;
    const vision::Embedding* emb =
        std::get_if<vision::Embedding>(&response.results[0]);
    if (emb == nullptr) return false;
    *out = emb->embedding;
    return true;
}

int main() {
    auto service = VisionService::Create("examples/arcface/config/arcface.yaml");

    // 1. 构建人脸库（提取所有注册人脸的特征）
    std::vector<std::string> names = {"Alice", "Bob", "Charlie"};
    std::vector<std::vector<float>> face_database;

    for (const auto& name : names) {
        std::vector<float> embedding;
        ExtractEmbedding(service.get(), "database/" + name + ".jpg", &embedding);
        face_database.push_back(embedding);
    }

    // 2. 提取待识别人脸的特征
    std::vector<float> query_embedding;
    ExtractEmbedding(service.get(), "query.jpg", &query_embedding);

    // 3. 在人脸库中搜索最相似的人脸
    float max_similarity = -1.0f;
    int best_match_idx = -1;

    for (size_t i = 0; i < face_database.size(); ++i) {
        float similarity = VisionService::EmbeddingSimilarity(
            query_embedding, face_database[i]);

        if (similarity > max_similarity) {
            max_similarity = similarity;
            best_match_idx = i;
        }
    }

    // 4. 输出结果
    if (max_similarity > 0.6) {
        std::cout << "Matched: " << names[best_match_idx]
                  << " (similarity: " << max_similarity << ")" << std::endl;
    } else {
        std::cout << "No match found (max similarity: "
                  << max_similarity << ")" << std::endl;
    }

    return 0;
}

4.2.3 Python 人脸比对（1:1）

import cv2
from spacemit_vision import VisionServiceNative, VisionServiceStatus

recognizer = VisionServiceNative.create("examples/arcface/config/arcface.yaml")

st1, embedding_a = recognizer.infer_embedding(cv2.imread("face_a.jpg"))
st2, embedding_b = recognizer.infer_embedding(cv2.imread("face_b.jpg"))
if st1 != VisionServiceStatus.OK or st2 != VisionServiceStatus.OK:
    raise RuntimeError(recognizer.last_error())

similarity = VisionServiceNative.embedding_similarity(embedding_a, embedding_b)
print(f"Similarity: {similarity:.4f}")
print("Same person" if similarity > 0.6 else "Different person")

4.2.4 Python 人脸搜索（1:N）

import cv2
import numpy as np
from spacemit_vision import VisionServiceNative, VisionServiceStatus

recognizer = VisionServiceNative.create("examples/arcface/config/arcface.yaml")
names = ["Alice", "Bob", "Charlie"]
face_database = []

for name in names:
    st, emb = recognizer.infer_embedding(cv2.imread(f"database/{name}.jpg"))
    if st != VisionServiceStatus.OK:
        raise RuntimeError(recognizer.last_error())
    face_database.append(emb)

st, query = recognizer.infer_embedding(cv2.imread("query.jpg"))
if st != VisionServiceStatus.OK:
    raise RuntimeError(recognizer.last_error())

similarities = [VisionServiceNative.embedding_similarity(query, db) for db in face_database]
best = int(np.argmax(similarities))
print(f"Matched: {names[best]} ({similarities[best]:.4f})" if similarities[best] > 0.6 else "No match")

4.3 配置说明

YAML 配置文件是模型加载和推理参数的核心，以下是完整配置项说明：

# 模型文件路径（ArcFace MobileFaceNet 模型）
model_path: ~/.cache/models/vision/arcface/arcface_mobilefacenet_cut.q.onnx

# 测试图像路径（用于示例程序）
test_image1: ~/.cache/assets/image/003_face0.png
test_image2: ~/.cache/assets/image/004_face1.png

# 模型输入尺寸 [height, width]（ArcFace 标准输入为 112×112）
image_size: [112, 112]

# 部署类名（C++ 模型工厂注册名，Python 通过 yaml 路径间接使用）
class: deploy.arcface.ArcFaceRecognizer

# 推理参数
default_params:
  # 推理线程数（示例默认 8；K3 平台 intra-op 最大建议 8，可按场景调低）
  num_threads: 8
  
  # 推理后端（优先使用 SpaceMITExecutionProvider）
  providers:
    - SpaceMITExecutionProvider
    - CPUExecutionProvider  # 备用后端

参数调优建议：

• image_size：ArcFace 标准输入为 [112, 112]，不建议修改。
• num_threads：示例 yaml 默认为 8，K3 平台 intra-op 线程数最大建议 8。若 CPU 竞争或延迟不稳定，可尝试降至 4 观察效果，不建议超过 8。
• providers：优先使用 SpaceMITExecutionProvider 以获得最佳性能。
• 相似度阈值：0.6 为经验值，可根据实际场景调整（提高阈值减少误识，降低阈值增加召回）。
• 输入要求：输入必须为裁剪对齐后的人脸图像（112×112），建议先用人脸检测模型定位人脸区域。

4.4 性能监控

通过启用性能计时，可以分析推理各阶段的耗时，用于性能优化和瓶颈定位。

C++ 示例：

VisionServiceTimingOptions timing_options;
timing_options.enabled = true;
service->SetTimingOptions(timing_options);

VisionServiceResponse response;
service->Infer("face.jpg", &response);

auto timing = service->GetLastTiming();
std::cout << "Model inference: " << timing.model_infer_ms << " ms" << std::endl;
std::cout << "Total inference: " << timing.infer_ms << " ms" << std::endl;

性能优化建议：

• ArcFace 模型非常轻量（MobileFaceNet），单次推理耗时极低（< 3ms）。
• 整体流水线性能主要受前端人脸检测影响。
• 对于 1:N 搜索，特征向量相似度计算是 CPU 操作，N 较大时可考虑使用向量检索库（如 Faiss）加速。

参考 demo 路径：examples/arcface/

注意事项：

• 输入图片应为裁剪对齐后的人脸图片（112×112），建议先用人脸检测模型（见 4.2.4-人脸检测）定位人脸区域后裁剪
• 相似度阈值 0.6 为经验值，可根据实际场景调整
• 人脸识别与检测、分类等任务共用统一的 Infer 接口，区别在于人脸识别的结果以 vision::Embedding 变体写入 response.results

5. 调试指南

• 启用计时：通过 SetTimingOptions 启用后用 GetLastTiming 查看 model_infer_ms、infer_ms 字段
• 相似度异常低：确认输入为裁剪对齐的人脸图片，非全身照
• 确认模型文件为 ArcFace 专用模型（arcface_mobilefacenet_cut.q.onnx）

6. 常见问题

现象	可能原因	处理
Model file not found	模型未下载	执行 bash examples/arcface/scripts/download_models.sh
No module named 'spacemit_vision'	wheel 未安装	按 §2 编译并 pip install src/python/dist/*.whl
相似度始终很低	输入非人脸图片或未裁剪对齐	先用人脸检测裁剪人脸区域，缩放至 112×112
同一人相似度低于 0.6	光照、角度差异大	正常现象，可适当降低阈值

附录：性能与测试数据

以下数据摘自 Vision 组件 README.md 附录「不包含前后处理」（纯 ONNX 模型推理，不含图像预处理与后处理）。为 K3 平台阶段性实测结果，完整表见 README。

K3 平台

具体模型	输入大小	数据类型	帧率 (4核)	帧率 (8核)
arcface_mobilefacenet	[1,3,112,112]	int8	373.7	531.7

复现方法：使用 onnxruntime_perf_test 工具（4 线程）：

onnxruntime_perf_test ~/.cache/models/vision/arcface/arcface_mobilefacenet_cut.q.onnx -e spacemit -r 20 -x 1 -S 1 -s -I -c 1 -i "SPACEMIT_EP_INTRA_THREAD_NUM|4"