3.1. 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-deploy-vx.y.z-ubuntu24.04-x86.64.tar

  • AArch64推理部署镜像：

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

    Dadao-deploy-docker-xh2-deploy-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镜像发布列表。

  5. 启动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。

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

  7. 完成上述配置后，可在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镜像发布列表。

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

    hm_smi -a

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

  6. 启动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

      参数说明：

      • <container_name>：用户自定义的容器名称。

      • <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 依然是由底层硬件透传的真实物理值，不会发生任何改变。

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

  8. 完成上述配置后，可在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_PATH

TCIM运行时库安装路径。
/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_PATH

TCIM运行时库安装路径。
/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_PATH

TCIM运行时库安装路径。
/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

  6. 设置环境变量，示例如下：

    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。

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

    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

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