本项目基于 ai-engine-direct-helper (QAI_AppBuilder) https://github.com/quic/ai-engine-direct-helper.git

本指南为Genie 开发文档系列文章的第二篇，若需了解前文内容，请先阅读第一篇（附链接）。

2.1 简介

Genie API 服务是一款 Android 应用程序，旨在后台服务中运行一个高性能的 AI 模型。它提供了一个基于 Web 的界面用于模型的选择与交互，该界面会显示在应用的主活动（MainActivity）中。本文档为希望理解、构建和定制此应用的开发者提供了全面的指南。

2.2 项目架构

该应用由 Java/Kotlin 的 Android 前端和 C++ 的原生后端组成。这两层通过 Java 原生接口（JNI）进行通信。

• Android 前端: 负责管理用户界面、后台服务的生命周期以及系统交互。

• C++ 后端: 负责处理核心的 AI 模型推理，并提供一个用于模型选择的 Web 服务。

2.3 核心组件

2.3.1 MainActivity.java

这是应用的主入口点。其主要职责包括：

• 启动和停止 ForegroundService。

• 显示系统信息，如内存使用情况和 IP 地址。

• 内嵌一个 WebView，用于渲染由 C++ 后端提供的 Web 界面。

在 MainActivity 中，通过点击按钮来启动或停止服务是其关键交互逻辑。

java mStartService.setOnClickListener(new View.OnClickListener() {     @Override     public void onClick(View view) {         if (ForegroundService.ServiceIsRunning) {             // ... 停止服务 ...             stopForegroundService();         } else {             // ... 启动服务 ...             startForegroundService();         }     } });

2.3.2 ForegroundService.java

该服务是应用的核心。它在后台运行，并负责：

• 加载原生 C++ 库 (JNIGenieAPIService 和 GenieAPIService)。

• 使用一个硬编码的模型配置文件路径来启动 C++ 后端。

• 从 C++ Web 服务器获取 HTML 内容，并将其传递给 MainActivity 的 WebView 进行显示。

在 ForegroundService 的 onCreate 方法中，通过 JNI 调用原生代码来启动后端服务，并传入模型配置文件的路径。

java // ... nativeLib = new MyNativeLib(); String[] commandArgs = {     "main", "-c", "/sdcard/GenieModels/模型名称",     "-l", "-d", mLogLevelIndex != -1 ? String.valueOf(mLogLevelIndex) : "2",     "-f", logFileName }; nativeLib.runService(commandArgs); // ...

2.3.3 原生库 (C++)

C++ 层负责 AI 模型推理的繁重工作。它还运行一个 Web 服务器（地址为 http://127.0.0.1:8910），该服务器提供模型选择界面。

2.4 模型选择

模型的选择功能由 C++ 后端提供的 Web 界面处理。用户可以通过该界面选择需要加载和运行的 AI 模型。

模型选择界面截图

2.5 安装与运行

2.5.1 直接安装 (推荐)

如果您不想自己编译 APK，可以直接下载预编译好的版本进行安装和使用。

下载链接: GenieAPIService_v2.0.0_8750.apk

2.5.2 通过 Android Studio 构建

开发者可以通过源码构建和运行此应用。

1. 克隆或下载源码：点击访问源码仓库

1. 在 Android Studio 中打开项目文件 ai-engine-direct-helper\samples\genie\c++\Android。

1. 连接 Android 设备或启动一个模拟器。

1. 点击 Android Studio 中的 "Run" 按钮。

2.6 模型部署与使用

在应用中运行 AI 模型前，您需要先将下载好的模型文件部署到您的 Android 设备上。应用会从一个固定的路径加载模型。

1. 下载模型文件： 首先，从模型提供方获取完整的模型文件夹。

2. 将模型推送到设备： 使用 Android Debug Bridge (adb) 工具将整个模型文件夹推送到设备的 /sdcard/GenieModels/ 目录下。打开终端或命令行，执行以下命令：         

adb push <本地模型文件夹路径> /sdcard/GenieModels/例如，如果您的模型文件夹名为 Llama3-8B-Q4，则命令为：adb push C:\Downloads\Llama3-8B-Q4 /sdcard/GenieModels/

3. 验证路径： 确保文件结构正确。例如，您的 config.json 文件应该位于如下路径：/sdcard/GenieModels/Llama3-8B-Q4/config.json

提示: /sdcard/ 是 Android 设备内部存储的通用路径。您可以通过文件管理器在设备上找到 GenieModels 文件夹来确认模型是否上传成功。

2.7 配置自定义模型

如果您是开发者并希望在 Genie API 服务上运行自己的 AI 模型，您需要确保模型文件结构正确，并对 config.json 配置文件进行相应的修改。

2.7.1 模型文件结构

一个完整的模型文件夹通常需要包含以下文件：

• 模型文件.bin: 核心的模型权重文件。

• config.json: 模型的主要配置文件。

• tokenizer.json: 分词器配置文件。

• htp_backend_ext_config.json: 硬件加速后端扩展配置。

• prompt.json: 默认或示例提示词。

• prompt.prof: 性能分析相关的配置文件。

• (可选) kv-cache.primary.qnn-htp: SSD 类型模型所需的 KV 缓存文件。

2.7.2 修改 config.json

要让应用正确加载您的自定义模型，必须修改 config.json 文件中的路径，使其指向设备上的绝对路径。以下是需要修改的关键字段：

json {     "model": "/sdcard/GenieModels/<您的模型目录>/<您的模型名称>.bin",     "tokenizer_path": "/sdcard/GenieModels/<您的模型目录>/tokenizer.json",     "extensions": "/sdcard/GenieModels/<您的模型目录>/htp_backend_ext_config.json",     // ... 其他配置 ... }

修改说明：

• 将 <您的模型目录> 替换为您的模型文件夹名称（例如 MyCustomModel-v1）。

• 将 <您的模型名称>.bin 替换为您的模型二进制文件的实际名称。

2.8 日志

应用提供了日志记录机制以帮助调试。日志文件存储在应用内部存储的 Logs 目录中。您可以通过应用菜单访问这些日志。