SeetaFace6Onnx.model.fas_first 1.0.1

<div align="center">

SeetaFace6Onnx

基于 ONNX Runtime 的 SeetaFace6 .NET 人脸识别库

项目简介 · 快速开始 · 模型包 · 执行设备 · 示例项目 · 构建与测试

</div>

项目简介

SeetaFace6Onnx 将 SeetaFace6 的模型转换为 ONNX，使用OnnxRuntime进行推理。提供人脸检测、识别、关键点、属性、质量、活体和跟踪等功能。业务代码均在托管层实现，运行时不再依赖 SeetaFace、TenniS 或 C++ Bridge。

• 支持 .NET 6+
• 使用 SkiaSharp 读取和处理图像
• 支持 ONNX Runtime CPU、NVIDIA CUDA 和 Windows DirectML 执行后端
• 高性能，当前项目推理性能至少是SeetaFace6Sharp 5倍以上
• 跨平台，支持win(x64)、linux(x64/arm64/loongarch64)等

SeetaFace6Onnx 的业务层不依赖原生 SeetaFace 运行时，但 ONNX Runtime 和 SkiaSharp
仍包含与平台相关的原生组件。部署时必须为目标平台选择正确的 NuGet 运行时包。

功能

快速开始

1. 安装依赖

核心库不包含 ONNX 模型，也只引用 ONNX Runtime 的托管 API。一个可运行的应用需要同时安装：

1. SeetaFace6Onnx 核心包；
2. 一个 ONNX Runtime Provider 包；
3. 所需的模型包。

过下列命令安装 CPU 运行时和全部模型：

dotnet add package SeetaFace6Onnx
dotnet add package SeetaFace6Onnx.model.all
dotnet add package Microsoft.ML.OnnxRuntime

Linux 应用还需要部署 SkiaSharp 的 Linux 原生资源：

dotnet add package SkiaSharp.NativeAssets.Linux

生产项目可以只安装实际使用的模型包，以减小发布体积。参见模型包。

2. 检测并提取人脸特征

using System;
using System.IO;
using SeetaFace6Onnx.Models;
using SeetaFace6Onnx.Predictors;
using SkiaSharp;

using SKBitmap image = SKBitmap.Decode("face.jpg")
    ?? throw new IOException("无法读取 face.jpg");
using var detector = new FaceDetector();
using var landmarker = new FaceLandmarker();
using var recognizer = new FaceRecognizer();

FaceInfo[] faces = detector.Detect(image);
if (faces.Length == 0)
{
    Console.WriteLine("未检测到人脸");
    return;
}

FaceInfo face = faces[0];
FaceMarkPoint[] points = landmarker.Mark(image, face);
float[] feature = recognizer.Extract(image, points);

Console.WriteLine($"置信度：{face.Score:F4}");
Console.WriteLine($"位置：{face.Location}");
Console.WriteLine($"特征长度：{feature.Length}");

上述代码使用默认的 Light 5 点关键点模型、Normal 识别模型和 CPU Provider。比较两张人脸时， 分别提取特征后调用 recognizer.Compare(feature1, feature2) 或 recognizer.IsSelf(feature1, feature2)。

模型包

目前包含以下模型包（均可以通过nuget直接安装）：

安装对应的模型包后，会在构建和发布时将对应模型文件复制到：

runtimes/models/seetaface6

该路径也是 BaseConfig.ModelDirectory 的默认值。

如需从自定义位置加载模型，可为对应模块指定绝对目录：

var config = new FaceDetectConfig
{
    ModelDirectory = @"D:\models\seetaface6",
};
using var detector = new FaceDetector(config);

目录内的文件名必须与模型包中的名称一致，例如 face_detector.onnx。

推理后端

三个包都包含名为 onnxruntime 的原生库，同一个输出目录中只应选择一个。特别是 CUDA 和 DirectML 包不能混合部署。

默认执行设备为 CPU。使用加速设备时，既要安装对应 Provider 包，也要在每个模块的配置中明确选择：

var config = new FaceDetectConfig
{
    ExecutionProvider = ExecutionProvider.Cuda,
    GpuDeviceId = 0,
};
using var detector = new FaceDetector(config);

将 Cuda 替换为 DirectML 即可选择 DirectML。库不会在 Provider 不可用时静默回退，配置和部署
不匹配会抛出 NotSupportedException。CUDA 的驱动及依赖版本要求请参考 ONNX Runtime CUDA Execution Provider 文档。

源码中的示例项目通过 OnnxRuntimeFlavor 选择原生包，默认值为 Cpu：

dotnet build src\examples\SeetaFace6Onnx.Example.ConsoleApp -c Release -p:OnnxRuntimeFlavor=Cpu
dotnet build src\examples\SeetaFace6Onnx.Example.ConsoleApp -c Release -p:OnnxRuntimeFlavor=Cuda
dotnet build src\examples\SeetaFace6Onnx.Example.ConsoleApp -c Release -p:OnnxRuntimeFlavor=DirectML

OnnxRuntimeFlavor 只决定部署哪个原生 Provider；应用仍需通过各模块的 ExecutionProvider 配置 决定实际使用的设备。

性能与并发

• 相同模型、Provider、设备编号和线程配置会共享 ONNX Runtime Session。
• ThreadNumber 控制 ORT 的 intra-op 线程数；默认值已按模块分档，但仍应在目标硬件上实测。
• FaceTracker 和 FaceAntiSpoofing.PredictVideo 保存视频状态，每路视频应使用独立实例。
• 高频调用可使用接收 Span<T> 的重载复用结果缓冲，减少托管分配。

var faces = new FaceInfo[30];
var points = new FaceMarkPoint[landmarker.PointCount];
var feature = new float[recognizer.FeatureSize];

int faceCount = detector.Detect(image, faces);
if (faceCount > 0)
{
    landmarker.Mark(image, faces[0], points);
    recognizer.Extract(image, points, feature);
}

CPU 线程测试方法和 Ryzen 9 9950X 基线见 docs/cpu-thread-benchmark.md。运行端到端基准：

dotnet run --project src\benchmarks\SeetaFace6Onnx.Benchmarks -c Release -- `
  scripts\onnx\fp32 `
  src\benchmarks\SeetaFace6Onnx.Benchmarks\images\Jay_3.jpg `
  50

示例项目

仓库中的示例面向 .NET 10 SDK：

dotnet run --project src\examples\SeetaFace6Onnx.Example.ConsoleApp -c Release
dotnet run --project src\examples\SeetaFace6Onnx.Example.WebApp -c Release
dotnet run --project src\examples\SeetaFace6Onnx.Example.Camera -c Release
dotnet run --project src\examples\SeetaFace6Onnx.Example.VideoForm -c Release

Camera 和 VideoForm 使用 FlashCap 获取摄像头帧。VideoForm 仅支持 Windows。

构建与测试

构建核心库：

dotnet restore src\SeetaFace6Onnx\SeetaFace6Onnx.csproj
dotnet build src\SeetaFace6Onnx\SeetaFace6Onnx.csproj -c Release --no-restore

运行兼容性和推理测试：

dotnet test src\tests\SeetaFace6Onnx.Tests\SeetaFace6Onnx.Tests.csproj -c Release

测试项目会同时引用 SeetaFace6Sharp 1.0.10 作为差分基准，因此完整兼容性测试当前面向 Windows x64。

模型导出

原始 CSTA 模型位于 scripts/weights，导出的 FP32、FP16 和 INT8 文件分别位于 scripts/onnx/fp32、scripts/onnx/fp16 和 scripts/onnx/int8。安装 Python 依赖后可重新导出：

python -m pip install -r scripts\requirements.txt
python scripts\export_all.py --dtype float32
python scripts\verify_precision.py --dtype float32

--dtype 还接受 float16 和 int8。当前 NuGet 模型项目只打包 FP32 文件；FP16 和 INT8 属于实验产物，部署前应在目标 Provider、真实数据和业务阈值上重新验证精度与性能。

项目结构

src/SeetaFace6Onnx/   核心库
src/models/           ONNX 模型 NuGet 打包项目
src/examples/         Console、Web、Avalonia 和 WinForms 示例
src/tests/            API、推理和兼容性测试
src/benchmarks/       .NET 端到端基准
scripts/              CSTA 解析、ONNX 导出、验证和 Python 基准
docs/                 设计与性能记录

参考与许可

• SeetaFace6Open
• SeetaFace6 文档
• ONNX Runtime

本项目使用的 SeetaFace 模型来源于 SeetaFace6Open。使用、修改或分发代码及模型时，请同时遵守 SeetaFace6Open、ONNX Runtime、SkiaSharp 和其他第三方依赖的许可条款。