跳到主要内容

Linux主机端安装与部署

在Linux主机端，软件平台提供包含完整开发环境的Docker镜像，其内部预置HMQuantool、TCIM等软件组件。用户可以在Docker容器中快速构建、运行和测试软件平台。

此外，用户也可使用 运行时开发工具包安装与部署，通过后摩芯片部署和推理模型，并执行推理示例。

3.1.1. Docker镜像安装与部署​

3.1.1.1. 使用依赖​

Docker 容器运行依赖如下：

  • Docker Engine： 20.10.17 及以上

  • 宿主机系统：

Docker容器可运行于标准Linux环境，推荐使用以下已验证环境：

* Ubuntu 24.04（x86_64、AArch64）

其他Linux环境在满足 Docker 运行条件的情况下通常也可运行，但未在本产品中进行完整验证。

  • 网络要求：

    • 支持公网访问，用于下载依赖及模型资源

3.1.1.2. 镜像类型说明​

根据功能和平台架构不同，镜像分为以下三类：

  • x86_64全功能镜像：

支持模型量化、模型编译与模型推理。

Dadao-convert-docker-xh2-vx.y.z-ubuntu24.04-x86.64.tar

  • x86_64推理部署镜像（deploy镜像）：

仅支持模型推理运行，不包含模型量化与模型编译。

镜像名称中包含 deploy 标识。

Dadao-deploy-docker-xh2-vx.y.z-ubuntu24.04-x86.64.tar

  • AArch64推理部署镜像：

仅支持ARM64架构下模型推理运行，不包含模型量化与模型编译。

Dadao-deploy-docker-xh2-vx.y.z-ubuntu24.04-aarch64.tar

3.1.1.3. 单芯片（单逻辑设备）部署流程​

对于后摩设备仅搭载单颗M50芯片的单逻辑设备环境，Linux主机端安装和部署流程如下：

../_images/docker.png

图 3.1 Linux主机端部署说明

执行下面步骤，在Linux主机端安装和部署软件平台：

  1. 安装最新版本驱动。详情参看 《软件平台驱动安装指南》。

  2. 烧写和升级后摩设备固件镜像。详情参看 《HmUpdateTool工具使用指南》。

  3. 检测 使用依赖。

  4. 按需下载 Docker 镜像；全功能镜像支持量化、编译和推理，推理部署镜像仅支持推理。

    1. 登录后摩开发者社区。

    2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。

    3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为转换镜像 或部署镜像 的下载资源，选中该资源左边复选框。

    4. 点击 直接下载 、wget链接 、批量直接下载 或 wget批量下载 按钮。

更多Docker镜像详情，参看 Docker镜像发布列表。

  1. 启动Docker容器。

    1. 在Docker镜像存放路径下，运行下面命令导入镜像：
docker load -i <docker_file>

其中 docker_file 为下载的Docker镜像文件名。如果导入成功，则会显示导入后Docker镜像名，示例如下：

Loaded image: harbor.houmo.ai/toolchain/release:Dadao-convert-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-convert-xh2-v1.4.0-ubuntu24.04-x86.64。

  1. （可选）在Docker容器内，设置环境变量。

  2. 完成上述配置后，可在Docker容器中运行 ModelZoo模型库，也可开发新的应用程序。

3.1.1.4. 多M50芯片（多逻辑设备）映射与部署​

本节适用于以下硬件环境下的后摩软件平台安装与部署：

  • 单个后摩设备多芯片场景 ：单个后摩设备上包含多颗M50芯片。在Linux系统层，每颗M50芯片会被识别为一个独立的后摩逻辑设备（即拥有一组专属的 /dev/xh2a_xxx 设备节点）。

  • 跨后摩设备互联场景 ：多个后摩设备通过芯片间互联技术（Chip-to-Chip, CTC）物理连接，需要进行跨芯片或跨设备的联合部署。

3.1.1.4.1. 术语与核心概念说明​

在进行多芯片部署前，需了解以下核心术语，以确保正确配置硬件拓扑：

  • Group_Id： 标识一个独立的、物理隔离的CTC互连域。只有属于同一个 Group_Id 的 M50 芯片之间，才能通过物理CTC通路建立连接。

  • Chip_Id： 标识M50芯片在所属CTC互连组（group_id）内部的唯一硬件索引。该ID属于物理层面的硬编码标识。

3.1.1.4.2. 部署步骤​

执行下面步骤，在Linux主机端安装和部署软件平台：

  1. 安装最新版本驱动。详情参看 《软件平台驱动安装指南》。

  2. 烧写和升级后摩设备固件镜像。详情参看 《HmUpdateTool工具使用指南》。

  3. 检测 使用依赖。

  4. 按需下载 Docker 镜像；全功能镜像支持量化、编译和推理，推理部署镜像仅支持推理。

    1. 登录后摩开发者社区。

    2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。

    3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为转换镜像 或部署镜像 的下载资源，选中该资源左边复选框。

    4. 点击 直接下载 、wget链接 、批量直接下载 或 wget批量下载 按钮。

更多Docker镜像详情，参看 Docker镜像发布列表。

  1. 初始化多设备拓扑连接。主机端调用SMI工具，初始化多颗M50芯片（多逻辑设备）间的物理或逻辑连接：
hm_smi -a

执行后，终端会输出当前系统中所有可用M50芯片的拓扑信息。请记录返回信息中各设备对应的 Group_Id 和 Chip_Id。

  1. 启动Docker容器。

    1. 在Docker镜像存放路径下，运行下面命令导入镜像：
docker load -i <docker_file>

其中 docker_file 为下载的Docker镜像文件名。如果导入成功，则会显示导入后Docker镜像名，示例如下：

Loaded image: harbor.houmo.ai/toolchain/release:Dadao-convert-xh2-v1.4.0-ubuntu24.04-x86.64
 2. 运行下面命令启动Docker容器。请选择同一个 `Group_Id` 下的连续芯片，将其 `Chip_Id` 分别替换至下文中的设备路径 `X` 中：

注意

    * 绝对不支持跨组（`Group_Id`）映射。不能在一个容器内同时映射不同 `Group_Id` 的芯片。

    * 必须保证 `Chip_Id` 连续。在同一个 `Group_Id` 内，必须按照连续的 `Chip_Id` 进行映射，不支持跳跃式映射。例如可以同时挂载0和1，但不能只挂载0和2。
 1docker run -it \
 2  --network=host \
 3  --pid=host \
 4  --privileged \
 5  -w /hmdd \
 6  -v $PWD:/hmdd \
 7  --shm-size 64g \
 8  --name <container_name> \
 9  \
10  --device /dev/xh2a_ctl0:/dev/xh2a_ctl0 \
11  --device /dev/xh2a_system_deviceX:/dev/xh2a_system_deviceY \
12  --device /dev/xh2a_ipuX:/dev/xh2a_ipuY \
13  --device /dev/xh2a_memory_allocator_deviceX_ddr:/dev/xh2a_memory_allocator_deviceY_ddr \
14  --device /dev/xh2a_memory_allocator_deviceX_spm0:/dev/xh2a_memory_allocator_deviceY_spm0 \
15  --device /dev/xh2a_memory_allocator_deviceX_spm1:/dev/xh2a_memory_allocator_deviceY_spm1 \
16  --device /dev/xh2a_memory_transfer_deviceX:/dev/xh2a_memory_transfer_deviceY \
17  --device /dev/xh2a_fast_memory_deviceX:/dev/xh2a_fast_memory_deviceY \
18  --device /dev/xh2a_i2c_deviceX:/dev/xh2a_i2c_deviceY \
19  --device /dev/xh2a_qspi_deviceX:/dev/xh2a_qspi_deviceY \
20  --device /dev/xh2a_rpmsg_deviceX_0:/dev/xh2a_rpmsg_deviceY_0 \
21  \
22  <docker_image_name> \
23  /bin/bash

参数说明：

    * &lt;container_name>：用户自定义的容器名称。

    * &lt;docker_image_name>：上一步导入的 Docker 镜像完整名称，如上一步示例镜像名为 `harbor.houmo.ai/toolchain/release:Dadao-convert-xh2-v1.4.0-ubuntu24.04-x86.64`。

    * deviceX 挂载规则：必须根据SMI指令返回结果，选取相同 `Group_Id` 里的连续 `Chip_Id` 数字，依次替换或添加命令行中的设备节点。

    * `--device` 挂载规则：

格式为 --device /dev/xh2a_xxxX:/dev/xh2a_xxxY。如果需要同时挂载多颗芯片，请复制上方指令中标亮10 ~ 20行代码配置，并为每颗M50芯片指定对应的X和Y数字。

      * `X`：宿主机端的物理 `chip_id`，必须严格根据 `hm_smi -a` 查询到的实际芯片编号填写。

      * `Y`：容器内部看到的逻辑芯片号。默认建议与 `X` 保持一致，但如果有特殊部署需求，也可以自定义，例如将宿主机上同一个CTC互连组内的物理芯片1、芯片2，分别映射为容器内的逻辑0、逻辑1。

进入Docker容器后，运行 hm_smi 工具查询到的 Group_Id 和 Chip_Id 依然是由底层硬件透传的真实物理值，不会发生任何改变。

  1. （可选）在Docker容器内，设置环境变量。

  2. 完成上述配置后，可在Docker容器中运行 ModelZoo模型库，也可开发新的应用程序。

3.1.1.5. 环境变量​

3.1.1.5.1. 环境变量列表​

Linux环境下，可设置的环境变量如下表所示。默认情况下，无需用户设置。

注意

下表中环境变量必须通过CRL（C/C++ Runtime Library）机制进行设置。例如，在 Linux 环境中可使用 setenv。

若通过操作系统级别的方式设置，这些配置可能无效。

表 3.1 Ubuntu 24.04 x86_64环境下软件平台各组件环境变量 环境变量名称描述默认值
HOUMO_PATH工具链安装路径。/usr/local/houmo
TCIM_RUNTIME_PATHTCIM运行时库安装路径。/opt/venv/dadao/lib/python3.12/site-packages/ tcim_lite
HOUMO_SDK_PATH系统软件安装路径。/usr/local/houmo-sdk
LD_LIBRARY_PATH系统软件和TCIM动态链接库所在路径。/usr/local/houmo/lib: /usr/local/houmo-sdk/hal/lib:
PATH软件平台可执行文件和系统软件工具，如SMI工具所在路径。/usr/local/houmo-sdk/tools/hm_smi: /usr/local/houmo-sdk/tools/gui: /usr/local/houmo-sdk/tools/cli: /usr/local/houmo/bin: /usr/local/houmo-sdk/tools: /opt/venv/dadao/bin
表 3.2 Ubuntu 24.04 x86_64 Deploy环境下软件平台各组件环境变量 环境变量名称描述默认值
---------
HOUMO_PATH工具链安装路径。/usr/local/houmo
TCIM_RUNTIME_PATHTCIM运行时库安装路径。/opt/venv/dadao/lib/python3.12/site-packages/ tcim_lite
HOUMO_SDK_PATH系统软件安装路径。/usr/local/houmo-sdk
LD_LIBRARY_PATH系统软件和TCIM动态链接库所在路径。/usr/local/houmo-sdk/hal/lib
PATH软件平台可执行文件和系统软件工具，如SMI工具所在路径。/usr/local/houmo-sdk/tools: /usr/local/houmo/bin: /usr/local/houmo-sdk/tools/hm_smi: /usr/local/houmo-sdk/tools/gui: /usr/local/houmo-sdk/tools/cli:
表 3.3 Ubuntu 24.04 AArch64环境下软件平台各组件环境变量 环境变量名称描述默认值
---------
HOUMO_PATH工具链安装路径。/usr/local/houmo
TCIM_RUNTIME_PATHTCIM运行时库安装路径。/opt/venv/dadao/lib/python3.12/site-packages/ tcim_lite
HOUMO_SDK_PATH系统软件安装路径。/usr/local/houmo-sdk
LD_LIBRARY_PATH系统软件和TCIM动态链接库所在路径。/usr/local/houmo-sdk/hal/lib
PATH软件平台可执行文件和系统软件工具，如SMI工具所在路径。/usr/local/houmo-sdk/tools/hm_smi: /usr/local/houmo-sdk/tools/gui: /usr/local/houmo-sdk/tools/cli: /usr/local/houmo/bin: /usr/local/houmo-sdk/tools:

3.1.2. 运行时开发工具包安装与部署​

用户可在运行时开发工具包中推理模型，但不支持量化和编译模型。

3.1.2.1. 使用依赖​

使用依赖如下：

  • 系统环境：

    • Ubuntu 20.04 及以上版本（x86_64 或 AArch64）

    • Kylin V11（AArch64）

    • openEuler 22.03 LTS 和 openEuler 24.03 LTS（x86_64）

    • openEuler 25.03（AArch64）

  • Python 3.9 及以上（仅用于使用Python接口安装工具包）

  • CMake 3.16.3

  • GCC 13

3.1.2.2. 环境准备​

执行下面步骤完成环境准备：

  1. 在Linux系统主机端安装最新版本驱动。详情参看 《软件平台驱动安装指南》。

  2. 在后摩设备端，烧写和升级固件镜像。详情参看 《HmUpdateTool工具使用指南》。

  3. 下载运行时开发工具包到当前主机：

    1. 登录后摩开发者社区。

    2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。

    3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为Runtime SDK 的下载资源，选中该资源左边复选框。

    4. 点击 直接下载 、wget链接 、批量直接下载 或 wget批量下载 按钮。

  4. 检查并安装 使用依赖。

  5. 安装运行时开发工具包：

    • 通过Python安装，需安装Python 3.9或更高版本，并执行下面指令安装运行时开发工具：
pip3 install houmo_tcim_runtime_<target_hw>_${distro}_$arch-<release>.tar.gz
 * 如直接解压方式安装：

   1. 执行下面指令解压运行时开发工具：
tar -xzf houmo_tcim_runtime_<target_hw>_${distro}_$arch-<release>.tar.gz
cd houmo_tcim_runtime_<target_hw>_${distro}_$arch-<release>
   2. 如果使用Python接口推理模型，配置环境：
source env.sh
cd python
chmod +x build.sh
./build.sh
  1. 设置环境变量，示例如下：
export HOUMO_SDK_PATH=/usr/local/houmo-sdk
export TCIM_BACKEND=Xh2HalBackend
export HOUMO_TARGET=xh2
export LD_LIBRARY_PATH=/path/to/houmo_tcim_runtime_xh2_linux_$arch-<release>/lib: \
$LD_LIBRARY_PATH
export TCIM_RUNTIME_PATH=/path/to/<release>/houmo_tcim_runtime_xh2_linux_$arch-<release>

其中：

 * **HOUMO_SDK_PATH:** 后摩软件平台驱动安装路径，默认为 `/usr/local/houmo-sdk`。

 * **TCIM_BACKEND:** 模型推理使用的后摩计算平台，需设置为 `Xh2HalBackend`。

 * **HOUMO_TARGET:** 模型推理使用的后摩设备，需设置为 `xh2`。

 * **TCIM_RUNTIME_PATH:** TCIM 运行时库安装路径。

   * 如果通过 Python 安装运行时开发工具，TCIM 运行时库安装路径为：

/path/to/python/site-packages/tcim_lite

   * 如果直接解压方式安装运行时开发工具，TCIM 运行时库安装路径为：

/path/to/houmo_tcim_runtime_xh2_linux_$arch-<release>

 * **LD_LIBRARY_PATH:** 系统软件和TCIM 动态链接库所在路径。

系统软件动态链接库所在路径默认为 /usr/local/houmo-sdk/hal/lib。

  1. （可选）部署环境检测。

    1. 下载应用开发示例包到当前主机。部署环境检测工具位于应用开发示例包 houmo-examples-<target_hw>_<release>.zip 中 houmo-examples-xh2/tools/hm_check 目录下。

      1. 登录后摩开发者社区。

      2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。

      3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为示例代码 的下载资源，选中该资源左边复选框。

      4. 点击 直接下载 、wget链接 、批量直接下载 或 wget批量下载 按钮。

    2. 在 houmo-examples-xh2 目录下，执行下面指令配置运行环境：

source env.sh
 3. 执行下面命令编译工具：
cd tools/hm_check
./build_linux.sh -b build -c Release -j 8 --install

编译完成后，生成 hm-check 可执行文件，位于 build 目录下。

 4. 在 `houmo-examples-xh2/tools/hm_check/build` 目录下，运行下面指令检测环境：
hm-check

部署环境检测工具详情，参看 《部署环境检测工具用户指南》。