Genie API 服务 - 开发者文档

发布时间：2025-10-29 10:16:52

134 阅读

0 评论

1. 简介

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

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

2. 项目架构

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

Android 前端: 负责管理用户界面、后台服务的生命周期以及系统交互。
C++ 后端: 负责处理核心的 AI 模型推理，并提供一个用于模型选择的 Web 服务。

3. 核心组件

3.1 MainActivity.java

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

启动和停止 ForegroundService。
显示系统信息，如内存使用情况和 IP 地址。
内嵌一个 WebView，用于渲染由 C++ 后端提供的 Web 界面。

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

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

3.2 ForegroundService.java

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

加载原生 C++ 库 (JNIGenieAPIService 和 GenieAPIService)。
使用一个硬编码的模型配置文件路径来启动 C++ 后端。
从 C++ Web 服务器获取 HTML 内容，并将其传递给 MainActivity 的 WebView 进行显示。

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

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

3.3 原生库 (C++)

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

4. 模型选择

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

5. 安装与运行

5.1 直接安装 (推荐)

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

下载链接: GenieAPIService_v2.0.0_8750.apk

5.2 通过 Android Studio 构建

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

克隆或下载源码：点击访问源码仓库
在 Android Studio 中打开项目文件 ai-engine-direct-helper\samples\genie\c++\Android。
连接 Android 设备或启动一个模拟器。
点击 Android Studio 中的 "Run" 按钮。

6. 模型部署与使用

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

下载模型文件： 首先，从模型提供方获取完整的模型文件夹。
将模型推送到设备： 使用 Android Debug Bridge (adb) 工具将整个模型文件夹推送到设备的 /sdcard/GenieModels/ 目录下。打开终端或命令行，执行以下命令：
```
adb push <本地模型文件夹路径> /sdcard/GenieModels/
```
例如，如果您的模型文件夹名为 Llama3-8B-Q4，则命令为：
```
adb push C:\Downloads\Llama3-8B-Q4 /sdcard/GenieModels/
```
验证路径： 确保文件结构正确。例如，您的 config.json 文件应该位于如下路径：/sdcard/GenieModels/Llama3-8B-Q4/config.json

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

7. 配置自定义模型

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

7.1 模型文件结构

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

模型文件.bin: 核心的模型权重文件。
config.json: 模型的主要配置文件。
tokenizer.json: 分词器配置文件。
htp_backend_ext_config.json: 硬件加速后端扩展配置。
prompt.json: 默认或示例提示词。
prompt.prof: 性能分析相关的配置文件。
(可选) kv-cache.primary.qnn-htp: SSD 类型模型所需的 KV 缓存文件。

7.2 修改 config.json

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

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

修改说明：

将 <您的模型目录> 替换为您的模型文件夹名称（例如 MyCustomModel-v1）。
将 <您的模型名称>.bin 替换为您的模型二进制文件的实际名称。

8. 日志

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