模型资源包

部署 InspireFace 需要三部分配套：原生 SDK、模型资源包，以及后端所需的运行库。先确认它们能够配合工作，再调整检测参数。

选择模型资源包

Pack	Backend	使用建议
`Pikachu`	CPU / MNN	适合首次接入和较小规模部署。
`Megatron`	CPU / MNN	可作为另一种通用模型选择，在目标设备上比较大小与性能。
`Megatron_TRT`	NVIDIA TensorRT	搭配启用 TensorRT 的 SDK 和兼容的 GPU 运行环境。
`Gundam_RV1109`	Rockchip RV1109/RV1126	匹配 RKNPU 代际与板端运行环境。
`Gundam_RV1106`	Rockchip RV1103/RV1106	匹配板端工具链与运行环境。
`Gundam_RK356X`, `Gundam_RK3588`	Rockchip RK356x / RK3588	按实际 SoC 选择。

可通过模型发布页或仓库中的 command/download_models_general.sh 下载模型包。在仓库根目录执行：

bash command/download_models_general.sh Pikachu

文件会保存为 test_res/pack/Pikachu，首次运行 CPU 示例使用这个包即可。需要下载脚本列出的全部模型包时，不传参数运行脚本。

iOS 和 macOS 的 CPU Framework 同样可以从 Pikachu 开始。CoreML 构建需配套兼容的 CoreML 模型包；修改编译选项或重命名通用包都不会转换模型格式。上面的通用下载脚本不提供 CoreML 包。

模型包是一个文件，有时没有扩展名。如果下载的是 ZIP 压缩包，先解压，再将模型包文件传给 HFLaunchInspireFace 或 launch(resource_path=...)。

创建会话前验证模型包

1.2.4 源码接口提供模型包验证和元信息读取：

import inspireface as isf

info = isf.validate_resource_pack("/path/to/Pikachu")
print(info)
isf.launch(resource_path="/path/to/Pikachu")

C 中使用 HFValidateResourcePack 和配套头文件声明的 HFResourcePackInfo 检查资源格式。后端所需的运行库按下方对应平台指南安装。

在 Apple 平台传入模型包的本地文件路径，例如应用 bundle 中资源的路径。创建会话前可以这样验证并加载：

Objective-C

#import <InspireFace/InspireFaceApple.h>

BOOL LaunchValidatedPack(NSString *path, NSError **error) {
    HFResourcePackInfo info = {0};
    if (![IFRuntime validateResourcePackAtPath:path info:&info error:error]) {
        return NO;
    }
    return [IFRuntime launchAtPath:path error:error];
}

Swift

import InspireFaceSwift

func launchValidatedPack(path: String) throws {
    var info = HFResourcePackInfo()
    try InspireFaceRuntime.validateResourcePack(path: path, info: &info)
    try InspireFaceRuntime.launch(path: path)
}

发布应用时，记录 SDK 版本、模型包文件及其校验值。更换识别模型后，重新生成特征库中的向量，并重新评估比对阈值。

切换已加载的模型包

已经初始化的进程需要更换模型包时，使用 reload 接口：

API	Entry point	成功条件
C API	`HFReloadInspireFace(pack_path)`	返回 `HSUCCEED`。
C++	`inspire::Launch::GetInstance()->Reload(pack_path)`	返回 `0`。
Objective-C	`[IFRuntime reloadAtPath:path error:&error]`	返回 `YES`；失败时返回 `NO` 并提供 `NSError`。
Swift	`try InspireFaceRuntime.reload(path: path)`	正常返回；失败时抛出错误。
Python	`isf.reload(resource_path=pack_path)`	返回 `True`；失败时抛出异常。

1.2.4 中，已有 Session 会继续持有创建时的资源。整个应用切换时，先停止提交帧，释放旧 Session，验证并重新加载模型包，成功后再创建新 Session。加载失败时先处理错误，再恢复图像处理。识别模型发生变化后，还需要重建特征库。

使用 Android Java SDK 1.2.0 时，在初始化前选定模型包，更换时重新启动应用进程。

桌面、移动设备、服务器和边缘硬件的部署示意 — 应用可以部署到不同设备，但 SDK、模型包与后端运行库必须配套。下面按目标平台选择接入路径。

Android：NDK、ABI、JNI 与 AAR 打包。
iOS：真机与模拟器切片、XCFramework 和 CoreML。
macOS：Intel / Apple Silicon Framework、Swift 模块和原生库。
HarmonyOS：原生 SDK 和 ArkTS HAR 工程。
NVIDIA TensorRT：CUDA / TensorRT 依赖和构建环境。
Rockchip NPU：板端工具链、RKNN 与 RGA。
Python 打包：替换原生库、制作 wheel 和安装验证。

启动失败时，先检查文件路径，以及模型包与 SDK 构建是否配套。后续步骤见模型加载排查。

模型资源包

选择模型资源包

创建会话前验证模型包

切换已加载的模型包

下载 SDK

构建 CPU SDK

影响接入的构建选项

各平台的构建方式