Windows-SDK-常见问题

更新时间：2023-07-21

1. 激活说明

1.1 获取硬件指纹

LicenseTool工具获取：在SDK解压目录~\tools\license_tool\ 双击LicenseTool.exe，可以看到设备的硬件指纹
运行SDK获取：使用vs打开工程，选择Relase x64运行，同样可以得到指纹信息，如下 device_id即为指纹信息

1.2 获取序列号

申请授权：

申请链接：https://console.bce.baidu.com/ai/?fromai=1#/ai/face/offline/index
查看剩余：
申请更多测试授权：依次选择：离线识别SDK ->申请更多测试授权 -> 填写申请理由即可 -> 确定，预计24小时通过

单台设备授权序列号：

依次点击：单设备授权 -> 添加序列号 -> 测试版 -> 添加个数填写1 -> 确定

页面稍后自动刷新，即可看到生成的16位序列号，以及激活状态和状态类型

批量授权应用：

依次点击 : 批量授权 -> 新建应用 -> 填写应用名称（自定义）-> 填写License ID （自定义，需要英文）-> 选择操作系统（Linux/Windows）-> 试用版 -> 添加个数填写2 -> 创建应用

页面稍后自动刷新，即可看到自定义的license id，如下截图

1.3 激活

在线激活

单设备激活

方法1：在SDK解压目录~\tools\license_tool\ 双击LicenseTool.exe，填写单台设备授权的16位序列号，点击激活，会提示激活成功，同时会自动生成license.key 和 license.ini文件，在控制台的单台设备授权中的序列号状态为已激活。
方法2：在SDK解压目录~\license\打开license.key文件，删除里面内容，填写16位序列号，然后运行工程即可。运行工程时会自动拉取license.ini文件。

批量激活
在SDK解压目录~\license\打开license.key文件，删除里面内容，填写在批量授权应用中自定义的license id
在设备运行sdk时，可以自动拉取license.ini文件，对应的授权应用中的数量减1，直到用完为止

注意：license文件内容（license.key和license.ini）需要放置~\license\目录下

离线激活

在获取硬件指纹后，可在控制台中的序列号列表右侧点击离线激活，按照操作，输入硬件指纹（尽可能复制粘贴，手动输入容易出错），绑定之后，可下载授权文件

将授权文件解压后替换sdk 中的license文件夹即可

注意：license文件内容（license.key和license.ini）需要放置~\license\目录下

2. 授权失败相关问题

2.1 常见错误码

错误码	错误描述	错误中文描述	处理办法
-4	MODEL_IS_EMPTY	模型内容为空	1、在二次开发过程中，models文件夹和license文件夹与程序运行目录的相对路径需要跟SDK demo保持同样的相对路径 2、如果自行调整路径，则models文件夹和license文件夹要在同一级目录，如均在 D://face目录下；②sdk_init函数传参应该为D://face
-13	NOT_AUTHORIZED	未授权	1、可以使用licensetool.exe进行激活（需要联网） 2、可以登录控制台控制台进行激活 3、可以直接修改license.key文件，将内容替换成要激活的序列号（需要联网）
-1015	LICENSE_FILE_NOT_EXIST	授权文件不存在	sdk_init传入的路径下没有license文件夹
-1016	LICENSE_KEY_EMPTY	授权序列号为空	检查license.key文件是否为空
-1017	LICENSE_KEY_INVALID	授权序列号无效	检查license.key文件是否与控制台的序列号格式一致
-1018	LICENSE_KEY_EXPIRE	授权序序列号过期	检查控制台授权序列号是否是测试序列号，测试序列号的授权是有时效的，可以在控制台查看序列号的失效时间，也有可能已被其他设备使用
-1019	LICENSE_ALREADY_USED	授权序列号已被使用	该序列号已在其它设备上激活，检查当前设备的device_id是否与控制台对应序列号的硬件指纹信息一致，也有可能出现序列号过期
-1020	DEVICE_ID_EMPTY	设备指纹为空	远程激活时，输入指纹ID为空，一般不会出现该错误
-1021	NETWORK_TIMEOUT	网络超时	远程激活时，网络超时，可稍后再试，一般不会出现该错误
-1022	NETWORK_ERROR	网络错误	远程激活时，设备没有网络，联网后进行激活，如果仍然失败，可在控制台进行离线激活，下载对应的license文件

2.2 通用排查方法

检查模型文件和license文件是否在同一级目录下，如果自行调整位置，sdk_init需要修改路径，例：均在D://face目录下，则sdk_init函数传参应该为D://face
检查license文件夹下的文件是否被替换成已激活的license文件，如果已经替换，查看控制台输出的license.key是否与激活的序列号一致
检查设备的指纹信息与控制台激活的序列号中的指纹信息是否一致
网络超时或者网络错误，需要检查网络问题
设备重启之后，时间可能被修改，需要调整为当前时间（当前北京时间）

2.3 指纹信息变更原因

硬件指纹是指通过算法，提取到设备的CPU，GPU，硬盘，内存条，网卡等信息，加密成唯一字符串，因此在使用过程中不要更换CPU，GPU，硬盘，内存条，网卡等硬件设备，更换会导致指纹变更，重装系统也会导致指纹变更。常见的指纹变更原因如下：

扩容硬盘后，出现指纹变化
使用虚拟机，重启之后发生了指纹变化
重装系统后，导致指纹信息变化
系统时间变更，导致授权失败
个别工控机设备重启之后，或者外接硬件插拔（如继电器），导致指纹信息发生变化
个别网络环境切换时，导致指纹发生变化
个别设备外接U盘，指纹信息发生变化
个别设备存在多个网卡，可能会导致指纹信息发生变化

3. 运行问题

3.1 运行环境

支持Win7，Win10系统，其他系统可能存在兼容性问题，推荐使用x64运行
Windows Server系统上可能缺失一些动态库，不建议使用
不建议使用虚拟机，虚拟机重启可能会导致指纹发生变化

3.2 DLLNotFound异常

此DllNotFound异常可能是系统环境必要的DLL缺失导致，也可能是此设备的CPU没有AVX指令集所导致(编译运行离线SDK需要AVX指令进行协助的，可以下载CPU-Z工具查询是否有AVX指令集)，需要从这两方面排查一下:

安装依赖

可以先安装一下基础环境的动态链接库DLL包，下载链接：https://ai-test-data.bj.bcebos.com/MSVisualC.rar
离线SDK中~/tools/vc_redist，根据开发设备的选择安装vc_redist
安装vc2013和vc2015

安装CPU-Z

下载链接：https://www.cpuid.com/softwares/cpu-z.html
检查是否缺少AVX指令集，如果没有AVX指令集，则可以在控制台下载NOAVX版本的SDK

3.3 内存占用较高

SDK demo在运行时，加载全部模型，大约会占用800M左右的内存

SDK在使用过程中（如持续循环调用人脸检测）会出现短暂的内存增加，随后内存会保持稳定，不再增加

4. 二次开发

4.1 必要文件

db文件无需复制，sdk初始化时会自动生成，license、models、conf文件夹要放到同一级目录中，dll文件放到根目录或者编译生成的exe目录

授权文件：license文件夹
模型文件：models文件夹
配置文件：conf文件夹
dll库文件：SDK运行目录下所有的dll文件
以c++ SDK为例，如下图

4.2 输出日志配置

在exe运行目录下创建配置文件 face_conf.json，且其中写入 json 字段 {“log_open”: 1}为console 日志输出模式，若字段值为 2，则可输出日志文件 face_sdk.log（同 exe 所在目录）。通过日志输出可更详细判断各接口返回的错误码及问题所在。若该 conf 配置文件不存在或字段值为 1 或 2 之外的其他字段，则不输出日志。

4.3 模型缩减

sdk 支持按需配置模型和加载能力，若 sdk 有某部分功能不需要使用，可尝试删除一些模型，删除后模型既不会加载也不会占用内存。sdk 中 models 文件夹里的模型及是否可删减说明如下表:

模型文件夹名称	说明	是否可删减	删减说明
detect	人脸检测模型	是	若不使用nir近红外功能，可删除detect_nir开头的模型文件
align	人脸关键点模型	是	若不使用nir近红外功能，可删除align_nir开头的模型文件
attribute	人脸属性	是	若不使用人脸属性检测功能，该文件夹可删除
best_image	最佳人脸	是	若不使用最佳人脸检测功能，该文件夹可删除
blur	人脸质量模糊度检测	是	若不使用该功能，该文件夹可删除
dark_enhance	暗光恢复	是	若不使用该功能，该文件夹可删除
eye_close	眼睛闭合	是	若不使用眼睛闭合及动作活体功能，该文件夹可删除
feature	人脸特征值	是	若仅使用rgb可见光人脸特征值，feature_nir文件可删除（nir特征值）
gaze	人脸注意力检测	是	若不使用该功能，该文件夹可删除
mouth_close	嘴巴闭合检测	是	若不使用嘴巴闭合及动作活体功能，该文件夹可删除
mouth_mask	口罩佩戴检测	是	若不使用该功能，该文件夹可删除
occlusion	人脸遮挡检测	是	若不使用该功能，该文件夹可删除
silent_live	静默活体检测	是	若只使用rgb可见光单目静默活体，则liveniss_nir和live_depth文件可删除

4.4 阈值配置

sdk 支持能力自定义、通过读取配置文件的方式进行能力定制化。sdk 默认能力加载无需定制化，若需要定制化，请把 sdk 根目录里面的 conf 文件夹重命名为 config 文件夹。并且在 sdk 中，把里面的 json 配置按如下说明做修改，可起到定制化能力加载的效果，配置文件简要说明如下（若需定制化修改，请参考示例 json，修改 json 字段的值来达到定制化的目的）