InspireFaceInspireFace1.2.4.d10
首页
快速开始
获取和编译
完整示例
  • English
  • 简体中文
GitHub
首页
快速开始
获取和编译
完整示例
  • English
  • 简体中文
GitHub
  • 介绍
  • 快速开始
  • 功能概览
  • 使用指南

    • 架构与生命周期
    • 模型资源包
    • 图像输入与坐标
    • 会话与跟踪
    • 人脸分析
    • 识别与特征库
    • 人脸关键点
    • 活体检测
    • 人脸抓拍
    • 补充 API 示例
  • 语言与平台

    • C API
    • C++
    • Python
    • Java
    • Windows
    • Android
    • Apple
    • iOS
    • macOS
    • HarmonyOS
  • 获取和编译

    • 概述与下载
    • 源码准备与通用选项
    • Linux
    • Windows
    • macOS
    • Android
    • iOS
    • HarmonyOS
    • NVIDIA TensorRT
    • Rockchip NPU
    • Python 打包
    • Java 打包
  • 硬件部署

    • x86 CPU
    • ARM
    • NVIDIA TensorRT
    • Rockchip NPU
    • Rockchip 上的 Python
  • InspireCV
  • 完整示例
  • API 功能索引
  • 性能测量
  • 图像处理性能
  • 常见问题

构建 Android SDK

Android 应用可以直接添加 1.2.4.post1 AAR。C/C++ 或可移植 Java 接入可以下载下面的 1.2.4 原生 SDK。需要修改原生实现或制作自己的 SDK 包时,再从源码构建。Rockchip Android 的构建方法见 RKNN 章节。

标准脚本现在会一起生成 C/C++ SDK 和可移植 Java JAR。每个 ABI 只有一份 libInspireFace.so,包含原生核心、Android JNI 和可移植 JNI 接口。

下载预编译 SDK

Android 1.2.4 ZIP 的目录与下方源码构建产物一致,只是不带开头的 build/。直接使用时无需再通过 NDK 编译:

curl -fL -o inspireface-android-1.2.4.zip \
  https://github.com/HyperInspire/InspireFace/releases/download/v1.2.4/inspireface-android-1.2.4.zip
unzip inspireface-android-1.2.4.zip

原生接入使用 include/ 和 lib/<abi>/libInspireFace.so。可移植 Java 还需要 java/inspireface.jar 和 java/consumer-rules.pro,具体配置见应用打包。模型包需要单独下载。ZIP 不包含 AAR 或完整的 Android 便捷接口;Android 指南中的 InspireFace、Session 和 Bitmap 示例使用 AAR。

准备工具链

先完成源码准备,再安装 CMake 3.20 或更新版本、Make、Python 3、JDK(8 或更新版本)及 Android NDK。以下命令均从 SDK 目录运行。JDK 用于编译兼容 Java 8 的 JAR,Python 用于生成和检查接口绑定。

ANDROID_NDK 应指向包含 build/cmake/android.toolchain.cmake 的 NDK 目录,而不是 Android SDK 或 Android Studio 的安装目录。如果 CMake 找不到 JDK,可通过 JAVA_HOME 指定其安装路径。

export ANDROID_NDK=/absolute/path/to/android-ndk
test -f "$ANDROID_NDK/build/cmake/android.toolchain.cmake"
cmake --version
javac -version
python3 --version

SDK 发布流程目前使用 NDK r18b。直接依赖预编译 AAR 的应用无需安装这一 NDK,包里的 Java 与原生库已经编译好。示例应用使用 JDK 17 运行 Gradle,并使用 Android SDK 35。

构建标准 SDK

VERSION=1.2.4 bash command/build_android.sh

VERSION 只给输出目录添加后缀,原生 SDK 版本取决于源码。未设置这个变量时,输出目录为 build/inspireface-android。Android 发布包的 .post1 后缀与原生版本分别管理。

SettingScript value
ABIarm64-v8a、armeabi-v7a、x86_64
Native API level三种 ABI 均为 21;发布的 AAR 要求 API 24
Build typeRelease
C++ runtimec++_static
Library每个 ABI 一份动态库 libInspireFace.so
Java bindingsISF_BUILD_JAVA=ON,生成兼容 Java 8 的 inspireface.jar
Binding checks检查 C 声明、生成的 Java/JNI 签名与原生导出符号
Samples, native tests and host JVM tests关闭

脚本逐个编译 ABI,安装 SDK,再将文件收集到同一目录:

build/inspireface-android-1.2.4/
  include/
    inspireface.h
    intypedef.h
    herror.h
  lib/
    arm64-v8a/libInspireFace.so
    armeabi-v7a/libInspireFace.so
    x86_64/libInspireFace.so
  java/
    inspireface.jar
    api-manifest.json
    consumer-rules.pro
    sources/com/insightface/sdk/inspireface/jni/
    examples/DetectFaces.java
    com/insightface/sdk/inspireface/
  version.txt

java/sources/ 是与 JAR 对应的源码。单独的 java/com/... 目录保存 Android 抓拍和快照的补充源码,并不是完整的 Android 便捷接口。需要一起使用 InspireFace、Session 和 Bitmap 辅助方法时,使用 AAR 即可。

最后的整理步骤会删除中间 CMake 构建目录。需要保留缓存和目标文件以便增量编译时,可以使用下面的直接构建方式。

只构建一个 ABI

下面的 arm64 配置会保留构建目录,安装文件单独放置。构建 armeabi-v7a 时,修改 ANDROID_ABI,并加入 -DANDROID_ARM_NEON=TRUE。

单个 ABI 的 CMake 构建命令
cmake -S . -B build/android-arm64-local \
  -G "Unix Makefiles" \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK/build/cmake/android.toolchain.cmake" \
  -DANDROID_TOOLCHAIN=clang \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_NATIVE_API_LEVEL=21 \
  -DANDROID_STL=c++_static \
  -DMNN_BUILD_FOR_ANDROID_COMMAND=ON \
  -DISF_BUILD_SHARED_LIBS=ON \
  -DISF_BUILD_JAVA=ON \
  -DISF_BUILD_JAVA_TESTS=OFF \
  -DISF_BUILD_WITH_SAMPLE=OFF \
  -DISF_BUILD_WITH_TEST=OFF \
  -DISF_ENABLE_BENCHMARK=OFF \
  -DISF_ENABLE_USE_LFW_DATA=OFF \
  -DISF_ENABLE_TEST_EVALUATION=OFF
cmake --build build/android-arm64-local --parallel 4
cmake --install build/android-arm64-local

C/C++ SDK 安装在 build/android-arm64-local/install/InspireFace/,JAR、manifest、可移植接口源码和 consumer rules 位于 build/android-arm64-local/install/Java/。Android 上的可移植 JNI 直接链接到 libInspireFace.so,不再生成 libInspireFaceJNI.so。交叉编译时不启用宿主 JVM 接口测试。

将 native 库打包进应用

根据使用的接口选择一种方式:

Integration需要打包的内容
Android 便捷接口完整的 Android AAR,其中已包含模型和 consumer rules。
可移植 Java APIjava/inspireface.jar、lib/<abi>/libInspireFace.so、模型资源和随包提供的 consumer rules。
自己的 JNI / C++lib/<abi>/libInspireFace.so,编译时使用安装后的头文件。

使用可移植 Java API 时,将 JAR 和各 ABI 的库放入应用模块,再把 java/consumer-rules.pro 复制为 app/proguard-inspireface.pro:

app/
  libs/inspireface.jar
  proguard-inspireface.pro
  src/main/jniLibs/
    arm64-v8a/libInspireFace.so
    armeabi-v7a/libInspireFace.so
    x86_64/libInspireFace.so

应用模块对应配置如下:

android {
    defaultConfig {
        minSdk 24
        // Optional: package only the ABIs your application supports.
        ndk { abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86_64' }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'),
                    'proguard-rules.pro', 'proguard-inspireface.pro'
        }
    }
}

dependencies {
    implementation files('libs/inspireface.jar')
}

接口调用参考 Java 指南中的 com.insightface.sdk.inspireface.jni.Native。Android 上会自动从打包的原生库中加载 InspireFace。调用 HFLaunchInspireFace 前,先将模型包复制到可读取的文件路径;Android assets 不是普通文件路径。JAR 本身不包含模型或 Android Bitmap 辅助方法。

混淆时保留 JNI 名称

普通 JAR 不会自动应用旁边的 Android consumer rules,需要在应用的 release 配置中引入。JNI 会按名称查找类、字段和构造方法,不能只保留 native 方法名。AAR 中的 consumer rules 则会自动合并。

可移植 Java JNI 保留规则
-keep class com.insightface.sdk.inspireface.jni.Native { *; }
-keep class com.insightface.sdk.inspireface.jni.CPUEngine { native <methods>; }
-keep class com.insightface.sdk.inspireface.jni.NativeTypes$* { *; }

不要同时引入完整 AAR 和另一份 inspireface.jar,也不要重复打包它的原生库。从早先的双库源码包升级时,移除 libInspireFaceJNI.so。每个 ABI 的 Java 类和 libInspireFace.so 应来自同一次构建;用 Gradle pickFirst 压过重复文件,可能会留下旧实现。

检查构建结果

可以用 NDK 自带的 llvm-readelf 查看库文件。将 HOST_TAG 替换为本机 NDK 的 toolchains/llvm/prebuilt/ 下实际存在的目录名:

export NDK_HOST_TAG=HOST_TAG
"$ANDROID_NDK/toolchains/llvm/prebuilt/$NDK_HOST_TAG/bin/llvm-readelf" \
  -h -d -l build/inspireface-android-1.2.4/lib/arm64-v8a/libInspireFace.so

arm64-v8a 的 machine 应为 AArch64。再用 Android Studio 的 APK Analyzer 确认最终 APK 中,每个选定 ABI 的目录只有一份 libInspireFace.so。1.2.4 Release ZIP 的三种 ABI 均使用 16 KB ELF 加载段对齐,源码构建目标也设置了这一对齐值;应用的页面大小验证还应覆盖其他 native 依赖和最终 APK 的对齐情况。

SymptomCheck
CMake 找不到 Java 或 Python确认 JDK 开发工具和 Python 3 可用,并检查 JAVA_HOME。
找不到 NDK toolchain 文件ANDROID_NDK 应指向一个具体 NDK 版本的目录。
加载时出现 UnsatisfiedLinkError检查设备 ABI、APK 内容和动态库依赖。
只有 release 包找不到 JNI 方法或类检查 JAR 与原生库版本是否一致,以及 consumer keep rules 是否生效。
打包时出现重复类或 .so检查是否同时引入了 AAR 和手动复制的 SDK 文件。
换了 ABI 或编译器,CMake 仍用旧配置为新的工具链使用独立构建目录。

在目标设备上先验证模型加载和单张图像检测,再接相机。Android 指南介绍初始化、CPU 策略、帧数据生命周期与版本诊断。

源码:Android 构建脚本、Java/JNI 构建规则。

编辑此页
最近更新: 2026/9/29 17:08
贡献者: Jingyu
上一页
macOS
下一页
iOS