4.6.2. 样例运行

开发样例包可在运行时开发工具包提供的环境中运行。

4.6.2.1. Linux环境下示例运行

执行下面步骤完成样例运行：

完成 Linux环境准备。
下载开发样例包。
解压缩 houmo-examples_<release>.zip。
在 houmo-examples_<release>/houmo-examples-xh2 目录下，配置运行环境：
```
cd houmo-examples_<release>/houmo-examples-xh2
source env.sh
```

安装相关依赖:

python3 -m pip install -r requirements.txt
cd hmatc
python setup.py install

进入要运行的样例目录下，如要运行 qwen3 样例，则进入 houmo-examples_<release>/houmo-examples-xh2/apis/inferences/qwen3 目录下。
运行样例目录下 run.sh 或 run.bat 脚本推理样例模型。

样例运行详细步骤，可参看样例目录下 houmo-examples_<release>/houmo-examples-xh2/apis/README.md。

4.6.2.2. Windows环境下示例运行

执行下面步骤完成样例运行：

完成 Windows环境准备。
下载开发样例包。
解压缩 houmo-examples_<release>.zip。
在 houmo-examples_<release>/houmo-examples-xh2 目录下，配置运行环境：
```
cd houmo-examples_<release>\houmo-examples-xh2
env.bat --set
```

安装相关依赖:

python3 -m pip install -r requirements.txt
cd hmatc
python setup.py install

进入要运行的样例目录下，如要运行 qwen3 样例，则进入 houmo-examples_<release>/houmo-examples-xh2/apis/inferences/qwen3 目录下。
运行样例目录下 run.sh 或 run.bat 脚本推理样例模型。

样例运行详细步骤，可参看样例目录下 houmo-examples_<release>/houmo-examples-xh2/apis/README.md。

4.6.2.3. Android环境下示例运行

示例需在Linux主机端Docker环境中完成构建与模型准备；由于Android设备与主机在架构及运行环境上存在差异，无法直接本地编译运行，因此需通过Android NDK进行交叉编译生成设备可执行程序，并依赖驱动SDK与Runtime提供运行支持。

本章以 qwen3 模型示例为例，介绍如何在Android上完成模型推理。

该示例位于开发样例包中 houmo-examples_<release>/houmo-examples-xh2/apis/inferences/qwen3 目录下。

整体流程如下：

在主机端安装Docker镜像。
配置主机端Docker镜像环境。
Docker镜像中编译示例程序并准备模型。
推送模型文件到Android设备。
推理模型。

在执行本章节前，请确保已完成Android端Runtime推理环境部署。

4.6.2.3.1. 主机端安装Docker镜像

执行下面步骤，在主机端安装部署Docker镜像：

下载Docker镜像，用于模型量化、编译和推理。
1. 登录后摩开发者社区。
2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为部署镜像的下载资源，选中该资源左边复选框。
4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
加载并启动Docker镜像。
1. 在Docker镜像存放路径下，运行下面命令导入镜像：
```
docker load -i <docker_file>
```
  其中 docker_file 为下载的Docker镜像文件名。如果导入成功，则会显示导入后Docker镜像名，示例如下：
```
Loaded image: harbor.houmo.ai/toolchain/release:Dadao-deploy-xh2-v1.4.0-ubuntu24.04-x86.64
```
2. 运行下面命令启动Docker镜像：
```
docker run -it --pid=host --privileged -w /hmdd -v $PWD:/hmdd --shm-size 64g --name <container_name> <docker_image_name> /bin/bash
```
  其中 container_name 需替换为自定义容器命名；docker_image_name 需替换为Docker镜像名，如上一步示例镜像名为 harbor.houmo.ai/toolchain/release:Dadao-deploy-xh2-v1.4.0-ubuntu24.04-x86.64；$PWD 所指定的目录为Docker容器关联目录，后续用于存放示例包和模型示例。

4.6.2.3.2. 配置主机端Docker镜像环境

执行下面步骤，在主机端Docker镜像中完成配置：

设置Android NDK。
1. 在 hmdd 目录下，下载官方Android NDK 软件包。该工具仅在 android-ndk-r28c 版本上验证通过。如使用其他版本，请根据实际环境进行适配。示例如下：
```
https://dl.google.com/android/repository/android-ndk-r28c-linux.zip
```
2. 设置 NDK_PATH 环境变量，指向 Android NDK 软件包的解压路径。
```
unzip android-ndk-r28c-linux.zip
export NDK_PATH=/hmdd/android-ndk-r28c
```
配置Android驱动：
1. 将驱动安装时下载的驱动安装包解压缩：
```
tar -xzf houmo-drv-xh2_<release>_androidmicron_aarch64.tar.gz
```
  解压后为 houmo-drv-xh2。
2. 设置 HOUMO_SDK_PATH 环境变量，指向驱动安装包的解压路径，示例如下：
```
export HOUMO_SDK_PATH=/hmdd/houmo-drv-xh2
```
配置Android运行时开发工具包：
1. 执行下面指令解压之前下载的运行时开发工具包。
```
tar -xzf houmo-tcim-runtime-xh2_<release>_android_aarch64h.tar.gz
```
  解压后为 houmo-tcim-runtime-xh2。
2. 设置 TCIM_RUNTIME_PATH 环境变量，指向运行时开发工具包的解压路径，示例如下：
```
export TCIM_RUNTIME_PATH=/hmdd/houmo-tcim-runtime-xh2
```
下载应用开发示例包到 /hmdd 目录。
1. 登录后摩开发者社区。
2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为示例代码的下载资源，选中该资源左边复选框。
4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮，下载应用开发示例包。
设置模型示例下载环境，并下载模型：
1. 执行下面指令解压应用开发示例包。
```
unzip houmo-examples-xh2_<release>.zip
```
  解压后为 houmo-examples-xh2。
2. 设置环境变量：
```
cd houmo-examples-xh2
source env.sh
```

完成上述步骤后，保持Docker环境，不退出，继续下一步。

4.6.2.3.3. 编译示例程序与模型准备

配置主机端Docker镜像环境完成后，在主机端Docker镜像中，继续执行下面步骤，编译示例程序并准备模型：

进入模型示例目录，如 houmo-examples-xh2/apis/inferences/qwen3，执行下面指令编译示例程序：
```
./build_ndk.sh
```
指令生成 android/example_cxx_qwen3 可执行文件，并下载了模型文件。

执行下面指令将下载的模型文件拷贝到 models 文件夹中：

mkdir models
cp qwen3_prefill.hmm models
cp qwen3_decode.hmm models
cp qwen3-8b/tokenizer.json models
cp hmquant/quant_embedding.bin models

退出Docker镜像：
```
exit
```

4.6.2.3.4. 推送模型文件

执行下面步骤，在主机端，推送模型文件到Android设备。

将下载的模型文件 $PWD/houmo-examples-xh2/apis/inferences/qwen3/models 传输到Android设备的 /data/houmo 目录：
```
cd $PWD/houmo-examples-xh2/apis/inferences/qwen3
adb push models /data/houmo
```
$PWD 所指定的目录为Docker容器创建时关联目录。
将可执行文件 $PWD/houmo-examples-xh2/apis/inferences/qwen3/android/example_cxx_qwen3 传输到Android设备的 /data/houmo 目录：
```
cd $PWD/houmo-examples-xh2/apis/inferences/qwen3/android
adb push example_cxx_qwen3 /data/houmo/models
```

4.6.2.3.5. 推理模型

通过adb进入Android设备开发板命令行，并获取root权限：
```
adb shell
su
```
在Android设备端，确保下面环境变量已设置：
```
export TCIM_BACKEND=Xh2HalBackend
export TCIM_RUNTIME_PATH=$TCIM_RUNTIME
export LD_LIBRARY_PATH=$DRV_HAL:${TCIM_RUNTIME_PATH}/lib
```
其中 $DRV_HAL 应替换为驱动安装后系统软件动态库 hal 目录，如 /data/houmo/houmo-drv-xh2/hal；$TCIM_RUNTIME 为TCIM运行时开发工具的路径，如 /data/houmo/houmo-tcim-runtime-xh2。

在Android设备端，执行下面指令推理模型：

 cd /data/houmo/models
./example_cxx_qwen3 ./qwen3_prefill.hmm ./qwen3_decode.hmm ./tokenizer.json ./quant_embedding.bin