本页目录
要在人脸检测和比对之外，再加上“离线运行”和“成本可控”两个条件，选择一下就少了。我给不方便接公网的客户用过虹软 ArcFace 3.0，也把它封装成了 ArcFace.Net，方便 .NET 项目调用。
这篇从获取 SDK 到跑通 Sample，重点讲授权、Linux 动态库路径，以及人脸检测、特征比对和人脸库检索。原生 SDK 的功能与封装已经实现的功能要分开看，不能只看一张功能清单就直接上线。
1. 为什么选离线 SDK
有些场景不能把人脸图像发送到公网服务，或者希望减少上传与网络等待。离线 SDK 把推理放在本机，更容易控制数据流向。
它不等于天然安全：原图、特征向量、日志和备份仍可能留在本机。这里介绍接入方法，真实部署还需要确认采集目的、授权、访问权限、保留期限和人工复核方式。
2. 获取 SDK：平台、版本和授权必须配套
从 虹软开发者中心注册并登录，创建应用，再在应用中添加 SDK。我演示选择的是 Linux x64、ArcFace 3.0、C++ 包；是否仍提供免费方案、有效期和商用范围，以当前后台及许可为准。
| 准备项 | 用途 |
|---|---|
| 对应平台的原生 SDK | Linux 使用 .so，Windows 使用 .dll |
| AppId 与平台 SDKKey | 激活和初始化；须与所选 SDK 配套 |
| SDK 文档 | 核对数据结构、接口顺序和错误码 |
| .NET 项目或 Sample | 调用封装并检查结果 |
| 获准使用的测试图片 | 验证检测与比对，不使用真实客户资料做公开演示 |
下载并解压后，lib 保存原生动态库，doc 提供接入说明。只安装 NuGet 包不能替代原生 SDK，也不能替代合法授权。授权值留在本地受保护配置中，不进入仓库或截图。
3. .NET 封装：先选图像处理实现
ArcFace.Net 的核心库调用原生 SDK，图像处理另分实现，Sample 用于调试和走读。
| 实现 | 选择时注意 |
|---|---|
| Core | 核心接口，需要配合图像处理实现 |
| 4.x／SystemDrawing | 基于 System.Drawing.Common；核对运行平台 |
| 5.x／ImageSharp | 项目说明要求 .NET 8+；同时核对依赖许可 |
自定义 IImageProcessor | 可以替换图像处理库，接口实现参考现有代码 |
微软说明 .NET 6 起 System.Drawing.Common 只支持 Windows，不是整个库停止维护。Linux 项目不能照搬 Windows 的图像处理依赖。
4. 跑 Sample：授权之后，通常还差动态库路径
克隆仓库，打开 ColinChang.ArcFace.Sample。先阅读示例配置和 Program.cs，在自己的本地配置中填写对应平台 AppId／SDKKey，再确认测试图片路径。
广告
我的 Linux 调试在第一次运行时提示找不到原生库。原因不是 NuGet 包没装，而是进程找不到 SDK 的 .so。
- 找到合法 SDK 的
lib目录，确认是 Linux x64 文件。 - 在 Rider 对应运行／调试配置的环境变量中设置
LD_LIBRARY_PATH，指向该目录。 - 重新运行 Sample，检查库加载及激活结果。
- 如仍失败，按报错核对架构、原生依赖、授权与读写权限，不把所有目录都塞进查找路径。
LD_LIBRARY_PATH 只是动态链接器的查找路径之一；应限制在需要的进程环境，不随意全局设置。已有值时按需要追加并保留原配置。
5. 按接口顺序检查检测、特征和人脸库
先看激活及 SDK 版本，再测试单项功能，更容易定位失败环节。
| 阶段 | 应观察的结果 | 不应推断 |
|---|---|---|
| 激活／版本 | 授权状态、有效期和平台信息 | 一次激活成功就永久可用 |
| 人脸检测 | 检测数量、位置矩形等 | 能检测到就一定能正确识别身份 |
| 属性接口 | 所选版本实际返回的属性 | 年龄、性别预测可直接用于决策 |
| 特征提取与比对 | 两个特征的匹配得分 | 得分就是同一人的概率 |
| 人脸库检索 | 返回匹配候选及得分 | 任意最高分都应自动放行 |
测试比对时可以选两张相近但身份不同的授权样本，再与同一人的不同照片对照。得分用于该算法的比较，不直接等于概率；阈值必须在实际人群、光照和误识代价下评估，不照搬示例输出。
Sample 涉及活体接口，也不代表封装已经交付完整活体防伪。项目 README仍列出视频模式追踪、活体检测未开发，以及角度结果的限制。需要这些能力时，逐项看当前版本源码和测试，不以原生产品“支持”代替封装“实现”。
6. 部署与激活：离线推理不等于从不联网
Rider 配置只影响调试进程，部署服务后还要在服务或容器环境中配置动态库位置。仓库提供 Dockerfile，可作为目录与依赖配置的参考，但生产镜像要使用自己的合法 SDK，不把授权文件和客户照片烘焙进公开镜像。
我使用的免费 3.0 方案需要初次联网激活，到期后更新 SDK 并重新激活。这是该方案的条件；其他版本是否支持不同激活方式、费用如何，都按当前合同和后台核对，不能把“离线”理解为没有授权期限。
接得上之后，还要用自己的样本验收
按 SDK 与授权配套 → 原生库加载 → Sample 单项验证 → 部署环境复测走，常见的路径和激活问题就有了检查顺序。真正上线还要管好人脸数据，特征向量同样属于需要保护的信息，不是天然匿名的普通数字。
欢迎带着平台、.NET 版本、SDK 版本和脱敏错误码交流，也可以在 ArcFace.Net 仓库提交问题。别上传授权值或真实人脸库。感谢阅读，希望这套接入顺序能帮你把“包已经装了，为什么还跑不起来”拆解清楚。
广告
