1. 安装综述

1.1. 综述

TopsRider 是燧原软件栈的总称，覆盖用户运行所需要的驱动、开发框架、应用软件等，为了帮助大家快速安装，节约开发流程，燧原官方提供了 TopsInstaller 安装方式，快速实现软件栈的安装。

1.2. 名词解释

表 1.2.1 词汇表

名词

解释

GCU

General Compute Unit 的缩写， 燧原科技通用计算单元

TopsInstaller

将 TopsRider 软件栈整体封装后的自解压软件安装包

2. 安装说明

2.1. 使用前说明

当下载好对应的 TopsInstaller 后，需要注意以下事项：

  • 安装时请确保具有 root 权限。

  • TopsInstaller 默认会安装 TopsRider 软件栈， 但不会安装驱动软件。如果需要安装驱动软件，请使用 --driver 参数。

  • TopsInstaller 提供 交互式操作界面安装 和 静默安装。 无论哪种方式，如果需要安装驱动软件，请使用 --driver 参数。

  • TopsInstaller 提供的deb/rpm包不含任何调试符号，在gdb调试过程中看不到函数名，如果需要函数名信息需要安装配套的ddeb的run包。例如 TopsRider_{filename}_deb_amd64.run 和 TopsRider_{filename}_rpm_x86_64.run 会有对应的 TopsRider_{filename}_ddeb_external_amd64.run包（注意：rpm没有单独的符号表的包，deb和rpm对应的符号表信息都在ddeb包中），如果需要这些符号的场景，可以选择安装对应的ddeb的run包，安装参数和普通的deb包保持一致（在rpm包的安装OS场景下，需要客户自行安装dpkg，并且最终安装ddeb的run包的时候，需要加上--force-skip-os --select-all参数）。另外，驱动部分，没有单独的符号表提供，所以仅安装驱动的场景，不需要安装对应的ddeb包。

建议的安装部署环境解释如下

表 2.1.1 安装部署环境建议

安装方式

说明

Host

指物理机，非容器环境，驱动软件需要安装在Host端

Container

指容器环境，驱动软件不能安装在Container端, 建议使用容器环境安装软件栈

建议的安装部署环境内容如下所示：

../../../../_images/env_groups.png

Note

  • 驱动程序只有在 --driver 参数被指定时，才会安装。并且是独立安装，不会与其他软件栈安装在一起安装。如果需要安装驱动程序和软件栈，请分两次执行安装命令。

  • 主机环境下建议有 Dockerfile，IDE 工具，及 GUI 工具安装包， 这些辅助工具是在 host 环境下安装和使用的， 默认不会安装，当需要安装这些辅助工具时，请使用 --host 参数， 这时也会同时安装驱动程序。

2.2. 安装使用

首先请确认 TopsRider_{filename}.run 为可执行文件，如果不是，需要手动添加执行权限后才可正常运行。

chmod +x TopsRider_{filename}.run

2.2.1. 静默安装

步骤一： 下载安装包后，在主机 Host 环境下安装驱动程序

# 需要使用 root 权限， 安装驱动程序
./TopsRider_{filename}.run -y --driver
# or
./TopsRider_{filename}.run --silence --driver

步骤二： 下载安装包后，在容器 Container 环境下安装软件栈

# 需要使用 root 权限， 安装软件栈
./TopsRider_{filename}.run -y
# or
./TopsRider_{filename}.run --silence

这里默认用户已经有 Docker 的环境，如果没有可参考 Docker 制作。

Note

  • TopsInstaller支持多种框架安装，用户通过-C选择不同的框架，推荐用户在使用不同框架时，使用不同的容器，避免同一个容器环境下安装多个框架。不同的安装包可能有不同框架支持，具体请参考安装包内的列表，通过 -h/--help 调出建议的列表。

# 单独只安装 smi 套件
./TopsRider_{filename}.run -y --smi --driver

1、如果安装包支持，安装 topscompressor ，执行如下命令

# 需要使用 root 权限
./TopsRider_{filename}.run -y -C topscompressor

2、 如果安装包支持，安装 vllm-gcu ，执行如下命令

# 需要使用 root 权限
./TopsRider_{filename}.run -y -C vllm-gcu
# 带有 --smi 选项同时安装 efsmi 和 efml
./TopsRider_{filename}.run -y --smi -C vllm-gcu

3、 如果安装包支持，安装 fast-diffusers ，执行如下命令

# 需要使用 root 权限
./TopsRider_{filename}.run -y -C fast-diffusers

4、 如果安装包支持，安装 TopsInference ，执行如下命令

# 需要使用 root 权限
./TopsRider_{filename}.run -y -C TopsInference

5、 如果安装包支持，安装 xfuser ，执行如下命令

# 需要使用 root 权限
./TopsRider_{filename}.run -y -C xfuser

示例代码、文档等文件会默认安装到/usr/local/topsrider/ 下。

2.2.2. 交互式操作界面安装

步骤一： 安装驱动程序，在下载安装包后，在Host端执行，菜单项会根据具体软件安装包内容而有所不同，选项-l/--list可查看安装包内包含的软件组件。

# 需要使用 root 权限安装驱动程序
./TopsRider_{filename}.run --driver

在主机 host 环境下会勾选如下默认组件：

用户可通过上下箭头来选择菜单项

  • 点击空格键可选择对应组件。

  • 选择 Driver Options ，并点击回车键，会进入驱动安装高级选项。

  • 选择 Quit ，并点击回车键，会中止并退出安装过程。

  • 选择 Install ，并点击回车键，会进入安装流程。

../../../../_images/install-i-host.png ../../../../_images/driver_options.png

安装成功后，执行如下操作即为驱动安装成功。

# 需要使用 root 权限
lsmod | grep enflame

步骤二： 安装软件栈，在下载安装包后，在容器 Container 环境下执行，菜单项会根据具体软件安装包内容而有所不同，选项-l/--list可查看安装包内包含的软件组件。

# 需要使用 root 权限
./TopsRider_{filename}.run

这里默认用户已经有容器 Container 环境，如果没有可参考 Docker 制作 ， 在容器 Container 环境中会默认勾选如下组件，用户可参照步骤一中的操作说明，进行选择确认：

../../../../_images/install-i-docker.png

安装示例代码、文档、其它文件到指定目录下，默认安装到/usr/local/topsrider/ 下。

Note

  • 针对已经装好的组件，如在上层 python 调用时报出诸如：ImportError: libxxx.so: cannot open shared object file: No such file or directory 等某个共享库找不到对应的文件或目录的情况，可能是共享库路径未正确配置所致。可依次按如下操作进行配置：

  1. 可以使用 ldd [对应共享库名] 命令检查共享库的依赖项；

  2. 如果依赖项存在 not found ，请尝试在当前环境下运行 ldconfig 命令更新动态链接器的配置。

  • 更多可以参考 ldconfig 相关 Linux man pages (man 8 ldconfig)。

2.3. 软件栈安装状态检查

TopsRider 软件栈安装后可以使用 topsinfo 检查当前安装的软件栈组件列表，相关的硬件信息，驱动软件，以及指定 Python 环境中的相关模块信息。 使用如下命令，检查软件栈安装状态。

topsinfo

显示内容示意大致如下， 分别是lspci板卡信息， driver版本信息， 软件栈安装状态信息：

Hardware: # lspci 信息
   2d:00.0 Processing accelerators: ... ...

Driver(enflame):
   Version: 1.6.0
   Firmware:
      SSM BOOT Version:  31.5.3
      ... ...
   efsmi:
      ( Device information... )

Installer: /home/user/TopsRider_xxxx.run
   Date: 2025-10-25 02:09:36
   Installed: # TopsRider 安装的系统模块
      [topsfactor:3.6.109] topsfactor_3.6.109-1 ... ...
      [tops-sdk:3.6.109] tops-sdk_3.6.109-1 ... ...
       ... ...

      Sub-Installer: TopsPlatform ... # TopsPlatform 安装的系统模块
            [efml:1.6.0.604] enflame-x86_64-gcc-1.6.0.604 ... ...
            [topsgdb:1.6.0.604] topsgdb_1.6.0.604   ... ...
            [topscc:1.6.0.604] topscc_1.6.0.604-1   ... ...
            [topsruntime:1.6.0.604] topsruntime_1.6.0.604 ... ...
             ... ...

   Python 3.10 Installed: # TopsRider 为 Python3 环境安装的模块
      [topsgraph:3.6.0] topsgraph-3.6.0-cp310-cp310-linux_x86_64.whl
      [vllm_gcu:0.9.2+3.6.102] vllm_gcu-0.9.2+3.6.102 ... ...
      ... ...

   Python 3.10 Related Modules Installed:
      # TopsRider 软件栈关系的其它社区 Python 模块版本信息
      torch 2.6.0+cpu
      torchvision 0.21.0+cpu
      torchaudio 2.6.0+cpu
      vllm 0.9.2

2.4. 软件栈卸载

使用如下命令，直接卸载本安装包内安装过的软件， 卸载驱动程序请使用 --driver 参数。

# 需要使用 root 权限
# 卸载驱动程序
./TopsRider_{filename}.run --uninstall --driver
# or
# 卸载软件栈
./TopsRider_{filename}.run --uninstall

2.5. TopsInstaller 命令说明

2.5.1. 参数解释

表 2.5.1 词汇表

参数

说明

-x, --extract-only

解压安装包的文件到一个目录中，而不执行安装脚本

-l, --list

查看安装包内可安装的软件模块列表，其中括号中为模块id

-C, --components

指定软件模块id安装软件模块，多个模块id用逗号分隔

-y, --silence

使用静默安装

-h, --help

打印帮助指令

--python

指定Python版本安装

--driver

指定只安装驱动，如果安装包里含有驱动

--host

指定安装驱动，以及IDE/GUI工具包，Dockerfile等

--toolkit

指定安装软件栈，但不安装驱动

--smi

指定安装系统管理套件 efsmi 和 efml

--uninstall

卸载

--with-dkms

安装dkms, 默认不安装

--no-auto-load

重启默认不自动加载, 默认加载

--with-vgcu

以vgcu模式加载kmd

--peermem

安装分布式相关驱动

2.5.2. 重点参数说明

  • 参数 peermem ：安装 Peer Memory 驱动插件

# 需要使用 root 权限
bash ./TopsRider_{filename}.run -y --driver --peermem
# 会同时安装驱动和 Peer Memory 驱动插件

默认情况下，驱动软件包支持传统模式的RDMA功能，即跨机架的两个设备想通过RDMA的方式传输数据时，需要将数据从设备HBM存储拷贝至系统内存，再通过网卡传输。 如果系统中有支持相关功能的Mellanox硬件，可以开启GCUDirect RDMA，来对RDMA功能进行加速，使得设备HBM存储中的数据可以直接通过网卡进行传输，不再需要拷贝至系统内存。

安装该驱动插件，即可开启GCUDirect RDMA功能。该插件安装在 HOST 端，安装前请确认已安装 Mellanox OFED ，仅支持版本“5.0-2.1.8.0”、“5.4-3.1.0.0”， 具体请参考Mellanox OFED文档，安装命令建议使用：

# ./mlnxofedinstall --add-kernel-support

Note

  • TopsRider 驱动插件(如果安装包含有)依赖 Mellanox OFED 以及 TopsRider 驱动软件。如果系统中没有安装 Mellanox OFED 或者安装 TopsRider 驱动软件失败，该插件都会安装失败。

  • 安装好之后插件独立运行，对主模块功能没有影响。可以随时卸载或者重新安装。

  • 在卸载后，驱动将不会使用 GCUDirect RDMA ，转而使用传统方式完成 RDMA 功能。

  • 在 Host OS 卸载驱动软件（如有必要）：如果有安装驱动插件，首先卸载驱动插件。

  • 参数 components ：安装指定的组件列表

# 需要使用 root 权限
./TopsRider_{filename}.run -y -C TopsInference

安装 TopsInference 框架及其依赖的软件组件， 可选的组件列表可以通过 -l 参数查看。

  • 参数 python ：指定Python版本

# 需要使用 root 权限
./TopsRider_{filename}.run -y --python /usr/bin/python3.10
# or
./TopsRider_{filename}.run -y --python python3.10

安装whl安装包时，安装到指定的 Python 版本环境中，如不指定参数将会默认选择python3命令对应的版本，请通过命令 “ python3 -V ” 查看对应版本号。

3. 附录

3.1. Docker 制作

Docker 环境准备请参照官网最新说明 Install on Linux。

软件栈安装推荐使用 HOST+Docker 形式。用户下载的 TopsInstaller 安装包中提供了 Dockerfile ，用户可在 Host OS 中完成 Docker image 的编译， Dockerfile 在文件系统中能够访问到。

例如：/usr/local/topsrider/dockerfile/ubuntu_amd64_22.04_dockerfile/dockerfile，下述命令也是根据该路径执行，用户可根据实际情况更换对应的文件路径。

cd /usr/local/topsrider/dockerfile/ubuntu_amd64_22.04_dockerfile
docker build --network host -t enflame:ubuntu_amd64_22.04_dockerfile .
docker image ls

编译中如遇到相关内容下载失败，可自行更换其他国内源进行重新下载。

Note

  • 如果遇到 ubuntu 22.04 的 dockerfile build 时提示 apt 更新错误，而 ubuntu 20.04 的 dockerfile build 正常，请确保 docker server 版本在 24.0.2 以上，其中的 runc 版本应该在 1.1.7 以上。

  • 查询版本的命令是 docker version。

3.2. Docker 启动

在 Host OS 中运行 Docker 时候, 具体根据你的工作目录，需要通过 --volume 映射工作目录进入容器内：

  • --privileged 使得板卡在 Docker 内可见。

  • --name 选项指定 container 名称。

docker run -it --name enflame_container --ipc host --network host --privileged enflame:ubuntu_amd64_22.04_dockerfile

3.3. 版本历史

表 3.3.1 版本历史

版本

描述

日期

V2.0

初版

2022年10月15日

V2.1

修订版

2023年1月21日

V3.0

修订版

2024年3月5日

V3.3

修订版

2024年12月12日

V3.4

修订版

2025年2月22日

V3.5

修订版

2025年7月7日

V3.6

修订版

2025年10月22日