1. 安装综述

1.1. 综述

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

../../../../_images/arch.png

1.2. 名词解释

名词

解释

GCU

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

TopsInstaller

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

2. 安装说明

2.1. 使用前说明

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

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

  • TopsInstaller 会自动识别用户安装环境是 Host 或 Docker 环境，默认会在 Host 环境安装 Driver 相关内容，在 Docker 环境安装除 Driver 外的其他软件内容。用户也可以将全部软件安装在 Host 环境中，但在 Docker 环境中只能安装 Driver 以外的软件

  • TopsInstaller 提供 交互式操作界面安装 和 静默安装

  • TopsInstaller 提供的deb/rpm包不含任何调试符号，在gdb调试过程中看不到函数名，如果需要函数名信息需要安装配套的ddeb的run包。例如 TopsRider_i3x_{filename}_deb_amd64.run 和 TopsRider_i3x_{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包。

安装方式解释如下

安装方式

说明

适用人群

静默安装

一行命令，无需其他操作即可完成 TopsRider 的安装

已对于燧原软件栈比较了解的开发者

交互式操作界面安装

提供可视化交互界面，让用户清晰感知 TopsInstaller 中内容

首次接触燧原软件栈的开发者

2.2. 安装使用

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

chmod +x TopsRider_{filename}.run

2.2.1. 静默安装

步骤一： 下载安装包后，在 Host 端执行

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

步骤二： 下载安装包后，在 Docker 端执行

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

Note

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

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

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

2、 如果安装包支持，安装 Text Generation Inference ，执行如下命令

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

3、 如果安装包支持，安装 vllm ，执行如下命令

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

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

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

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

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

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

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

TopsRider安装时若不指定路径，示例代码、文档等文件会默认安装到/usr/local/topsrider/ 下；通过以下方法用户可以实现安装到指定路径下。

# 需要使用 root 权限
./TopsRider_{filename}.run -y --install-dir /your_dir

2.2.2. 交互式操作界面安装

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# 需要使用 root 权限
./TopsRider_{filename}.run -y --install-dir /your_dir

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. 软件栈卸载

使用如下命令，直接卸载本安装包内安装过的软件，在 Host 下会卸载所有包含软件，包含驱动软件，在 Docker 下会卸载除了驱动软件包外所有其它软件。

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

2.4. TopsInstaller 命令说明

2.4.1. 参数解释

参数

说明

-x, --extract-only

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

-l, --list

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

-C, --components

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

-y, --silence

使用静默安装

-h, --help

打印帮助指令

--python

指定Python版本安装

--install-dir

指定安装路径

--uninstall

卸载

--cn

中文模式下安装

--with-dkms

安装dkms, 默认不安装

--no-auto-load

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

--with-vgcu

以vgcu模式加载kmd

--peermem

安装分布式相关驱动

2.4.2. 重点参数说明

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

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

默认情况下，驱动软件包支持传统模式的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_20.04_dockerfile/dockerfile，下述命令也是根据该路径执行，用户可根据实际情况更换对应的文件路径

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

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

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_20.04_dockerfile

3.3. 版本历史

版本

描述

日期

V2.0

初版

2022年10月

V2.1

修订版

2023年1月

V3.0

修订版

2024年3月