安装

RAFT 目前提供 C++ 和 Python 库。C++ 库，包括仅头文件库和可选的共享库，可以使用 Conda 安装。

C++ 和 Python API 都需要 CMake 从源代码构建。

目录

• 通过 Conda 安装 C++ 和 Python

• 通过 Pip 安装 Python

• 从源代码构建 C++ 和 Python

  • CUDA/GPU 要求

  • 构建依赖项

    • 必需

    • 可选

    • Conda 环境脚本

  • 仅头文件 C++

  • C++ 共享库

  • ccache 和 sccache

  • C++ 测试

  • C++ 原语微基准测试

  • Python 库

• 直接使用 CMake

• 构建文档

• 在下游项目中使用 RAFT

  • CMake 目标

---

通过 Conda 安装 C++ 和 Python

安装 RAFT 最简单的方法是通过 conda，并提供了几个软件包。

• libraft-headers C++ 头文件

• pylibraft (可选) Python 库

• raft-dask (可选) Python 库，用于部署在 Dask 集群中使用 RAFT 的 raft::comms 抽象层的多节点多 GPU 算法。

根据您的 CUDA 版本，使用以下命令通过 conda 安装所有 RAFT 软件包（将 rapidsai 替换为 rapidsai-nightly 以安装更新但不稳定的每夜构建软件包）。mamba 优于 conda 命令。

# for CUDA 11.8
mamba install -c rapidsai -c conda-forge -c nvidia raft-dask pylibraft cuda-version=11.8

# for CUDA 12.0
mamba install -c rapidsai -c conda-forge -c nvidia raft-dask pylibraft cuda-version=12.8

请注意，上述命令也将安装 libraft-headers 和 libraft。

您也可以使用上面的 mamba 命令单独安装 conda 软件包。例如，如果您想安装 RAFT 的头文件以在您的项目中使用

# for CUDA 12.0
mamba install -c rapidsai -c conda-forge -c nvidia libraft-headers cuda-version=12.8

通过 Pip 安装 Python

pylibraft 和 raft-dask 都有可以通过 通过 pip 安装 的软件包。

对于 CUDA 11 软件包

pip install pylibraft-cu11 --extra-index-url=https://pypi.nvidia.com
pip install raft-dask-cu11 --extra-index-url=https://pypi.nvidia.com

以及 CUDA 12 软件包

pip install pylibraft-cu12 --extra-index-url=https://pypi.nvidia.com
pip install raft-dask-cu12 --extra-index-url=https://pypi.nvidia.com

从源代码构建 C++ 和 Python

CUDA/GPU 要求

• cmake 3.26.4+

• GCC 9.3+ (推荐 9.5.0+ )

• CUDA Toolkit 11.8+

• NVIDIA 驱动程序 450.80.02+

• Volta 架构或更高（计算能力 >= 7.0）

构建依赖项

除了 cudatoolkit 11.8+ 中包含的库之外，下面还有一些其他依赖项用于从源代码构建 RAFT。许多依赖项是可选的，仅取决于所使用的原语。所有这些都可以使用 cmake 或 rapids-cpm 安装，其中许多也可以使用 conda 安装。

必需

• RMM 与 RAFT 版本对应的。

• Thrust v1.17 / CUB

• cuCollections - 用于 raft::sparse::distance API 中。

• CUTLASS v2.9.1 - 用于 raft::distance API 中。

可选

• NCCL - 用于 raft::comms API 中，并且构建 raft-dask 所必需。

• UCX - 用于 raft::comms API 中，并且构建 raft-dask 所必需。

• Googletest - 构建测试所需

• Googlebench - 构建基准测试所需

• Doxygen - 构建文档所需

Conda 环境脚本

提供了 Conda 环境脚本，用于安装构建 C++ 和 Python 库所需的依赖项。优先使用 mamba，因为它比 conda 提供了显著的速度提升。

mamba env create --name rapids_raft -f conda/environments/all_cuda-128_arch-x86_64.yaml
mamba activate rapids_raft

RAFT 的所有 C++ API 都可以仅作为头文件使用。

使用 CUDA 11 从源代码构建的过程略有不同，您的主机系统也需要安装等于或高于您在 conda 环境中安装版本的 CUDA toolkit。将 CUDA toolkit 安装到主机系统是必需的，因为 Conda 的 cudatoolkit 依赖项不提供 CUDA 11 的 nvcc。以下示例将为 CUDA 11.8 conda 环境创建并安装依赖项

mamba env create --name rapids_raft -f conda/environments/all_cuda-118_arch-x86_64.yaml
mamba activate rapids_raft

从源代码构建和安装 RAFT 的推荐方法是使用仓库根目录下的 build.sh 脚本。此脚本可以构建 C++ 和 Python 的工件，并提供 CMake 选项用于构建和安装头文件、测试、基准测试和预编译共享库。

仅头文件 C++

build.sh 使用 rapids-cmake，它将自动下载任何尚未安装的依赖项。需要注意的是，虽然所有头文件都将被安装和可用，但 RAFT API 的某些部分依赖于 CUTLASS 等库，这需要在 build.sh 中明确启用。

以下示例将下载所需的依赖项并将 RAFT 头文件安装到 $INSTALL_PREFIX/include/raft。

./build.sh libraft

可以传递 -n 标志，以便仅让构建过程下载所需的依赖项。由于 RAFT 的 C++ 头文件主要在下游项目的构建时使用，因此 RAFT 构建不会安装这些依赖项。

./build.sh libraft -n

安装后，可以使用 build.sh 卸载 libraft 头文件（以及使用 rapids-cmake 下载和安装的依赖项）。

./build.sh libraft --uninstall

C++ 共享库 (可选)

必须构建共享库才能构建 pylibraft。将 --compile-lib 标志传递给 build.sh 来构建库

./build.sh libraft --compile-lib

在上面的示例中，共享库默认安装到 $INSTALL_PREFIX/lib。要禁用此功能，请传递 -n 标志。

安装后，可以使用 build.sh 卸载共享库、头文件（以及通过 rapids-cmake 下载和安装的任何依赖项）。

./build.sh libraft --uninstall

ccache 和 sccache

ccache 和 sccache 可用于在频繁重新构建时更好地缓存构建部分，例如在开发新功能时。您也可以将 ccache 或 sccache 与 build.sh 一起使用。

./build.sh libraft --cache-tool=ccache

C++ 测试

使用 build.sh 中的 tests 目标编译测试。

./build.sh libraft tests

测试按算法类别划分，因此您会在 cpp/build/ 中找到几个名为 *_TEST 的二进制文件。

例如，运行距离测试

./cpp/build/MATRIX_TEST

编译所有测试可能需要一些时间。您可以通过向 build.sh 中的 --limit-tests 选项提供以分号分隔的列表来构建单个测试。

./build.sh libraft tests -n --limit-tests=CORE_TEST;MATRIX_TEST

C++ 原语微基准测试

基准测试按算法类别划分，因此您会在 cpp/build/ 中找到几个名为 *_PRIMS_BENCH 的二进制文件。

./build.sh libraft bench-prims

编译所有基准测试可能需要一些时间。您可以通过向 build.sh 中的 --limit-bench-prims 选项提供以分号分隔的列表来构建单个基准测试。

./build.sh libraft bench-prims -n --limit-bench=NEIGHBORS_PRIMS_BENCH;MATRIX_PRIMS_BENCH;LINALG_PRIMS_BENCH

Python 库

Python 库可以使用 build.sh 脚本构建和安装。

# to build pylibraft
./build.sh libraft pylibraft --compile-lib
# to build raft-dask (depends on pylibraft)
./build.sh libraft pylibraft raft-dask --compile-lib

setup.py 也可以用于手动构建 Python 库。

cd python/raft-dask
python setup.py build_ext --inplace
python setup.py install

cd python/pylibraft
python setup.py build_ext --inplace
python setup.py install

Python 测试会随相应的库自动安装。要运行 Python 测试

cd python/raft-dask
py.test -s -v

cd python/pylibraft
py.test -s -v

Python 软件包也可以使用 build.sh 脚本卸载。

./build.sh pylibraft raft-dask --uninstall

直接使用 CMake

从源代码构建 RAFT 时，build.sh 脚本提供了一个对 cmake 命令的友好封装，以减轻手动配置各种可用 cmake 选项的负担。当需要对 CMake 配置进行更精细的控制时，可以直接调用 cmake 命令，如下例所示。

使用 CMAKE_INSTALL_PREFIX 将 RAFT 安装到特定位置。以下示例将 RAFT 安装到当前的 Conda 环境中

cd cpp
mkdir build
cd build
cmake -D BUILD_TESTS=ON -DRAFT_COMPILE_LIBRARY=ON -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX ../
make -j<parallel_level> install

RAFT 的 CMake 有以下可配置标志可用

标志	可能的值	默认值	行为
BUILD_TESTS	ON, OFF	ON	编译 Googletests
BUILD_PRIMS_BENCH	ON, OFF	OFF	编译基准测试
CUDA_ENABLE_KERNELINFO	ON, OFF	OFF	在 nvcc 中启用 kernelinfo。这对于 compute-sanitizer 非常有用。
CUDA_ENABLE_LINEINFO	ON, OFF	OFF	为 nvcc 启用 -lineinfo 选项
CUDA_STATIC_RUNTIME	ON, OFF	OFF	静态链接 CUDA 运行时
CUDA_STATIC_MATH_LIBRARIES	ON, OFF	OFF	静态链接 CUDA 数学库
DETECT_CONDA_ENV	ON, OFF	ON	启用对依赖项的 conda 环境检测
raft_FIND_COMPONENTS	compiled distributed		将可选组件配置为空格分隔列表
RAFT_COMPILE_LIBRARY	ON, OFF	如果 BUILD_TESTS 或 BUILD_PRIMS_BENCH 为 ON 则为 ON；否则为 OFF	编译所有 libraft 共享库（Googletests 需要这些库）
RAFT_ENABLE_CUBLAS_DEPENDENCY	ON, OFF	ON	在 raft::raft 中链接 cublas 库
RAFT_ENABLE_CUSOLVER_DEPENDENCY	ON, OFF	ON	在 raft::raft 中链接 cusolver 库
RAFT_ENABLE_CUSPARSE_DEPENDENCY	ON, OFF	ON	在 raft::raft 中链接 cusparse 库
RAFT_ENABLE_CUSOLVER_DEPENDENCY	ON, OFF	ON	在 raft::raft 中链接 curand 库
RAFT_NVTX	ON, OFF	OFF	启用 NVTX 标记

构建文档

文档要求 C++ 和 Python 库已经构建并安装。以下命令将构建文档以及 C++ 和 Python 软件包。

./build.sh libraft pylibraft raft-dask docs --compile-lib

在下游项目中使用 RAFT C++

在下游项目中包含 RAFT 有几种不同的策略，这取决于 所需的构建依赖项 是否已经安装并位于 lib 和 include 搜索路径中。

使用 RAFT 的 GPU 部分时，您需要在 CMake 项目声明中启用 CUDA 支持。

project(YOUR_PROJECT VERSION 0.1 LANGUAGES CXX CUDA)

请注意，在针对 RAFT 构建时可能需要添加一些额外的编译器标志。例如，如果您看到类似 The experimental flag '--expt-relaxed-constexpr' can be used to allow this. 的错误。必要的标志可以使用 CMake 设置

target_compile_options(your_target_name PRIVATE $<$<COMPILE_LANGUAGE:CUDA>:--expt-extended-lambda --expt-relaxed-constexpr>)

此外，重要的是将语言级别设置为至少 C++ 17。这可以使用 cmake 完成。

set_target_properties(your_target_name
PROPERTIES CXX_STANDARD                        17
           CXX_STANDARD_REQUIRED               ON
           CUDA_STANDARD                       17
           CUDA_STANDARD_REQUIRED              ON
           POSITION_INDEPENDENT_CODE           ON
           INTERFACE_POSITION_INDEPENDENT_CODE ON)

CMake 目标

当将 RAFT 包含到您的 CMake 项目中时，raft::raft CMake 目标将可用，但可以通过在 CMake 的 find_package(raft) 的 COMPONENTS 选项中添加来提供额外的 CMake 目标（参考 CMake 文档 了解更多）。组件应以空格分隔。raft::raft 目标将始终可用。请注意，distributed 组件也导出额外的依赖项。

组件	目标	描述	基本依赖项
n/a	raft::raft	完整的 RAFT 头文件库	CUDA toolkit, RMM, NVTX, CCCL, CUTLASS
compiled	raft::compiled	预编译模板实例化和运行时库	raft::raft
distributed	raft::distributed	raft::comms API 的依赖项	raft::raft, UCX, NCCL