NVBLAS

NVBLAS 用户指南，即插即用型 BLAS 替代库，多 GPU 加速

1. 简介

NVBLAS 库是一个 GPU 加速库，它实现了 BLAS（基本线性代数子程序）。当调用的特性使其在 GPU 上加速时，它可以通过动态地将 BLAS 调用路由到一个或多个系统中存在的 NVIDIA GPU 来加速大多数 BLAS Level-3 例程。

2. NVBLAS 概述

NVBLAS 库构建于 cuBLAS 库之上，仅使用 CUBLASXT API（有关更多详细信息，请参阅 cuBLAS 文档的 CUBLASXT API 部分）。NVBLAS 还要求系统上存在 CPU BLAS 库。目前，NVBLAS 仅拦截计算密集型 BLAS Level-3 调用（见下表）。根据这些 BLAS 调用的特性，NVBLAS 会将调用重定向到系统中存在的 GPU 或 CPU。该决策基于一个简单的启发式方法，该方法估计 BLAS 调用是否会执行足够长的时间来摊销输入和输出数据到 GPU 的 PCI 传输。 由于 NVBLAS 不支持所有标准 BLAS 例程，因此可能需要将其与现有的完整 BLAS 库关联。请参阅用法部分了解更多详细信息。

3. GPU 加速例程

NVBLAS 仅卸载计算密集型 BLAS3 例程，这些例程在 GPU 上具有最佳加速潜力。

下表显示了当前支持的例程

例程	类型	操作
gemm	S,D,C,Z	2 个矩阵的乘法
syrk	S,D,C,Z	对称秩-k 更新
herk	C,Z	埃尔米特秩-k 更新
syr2k	S,D,C,Z	对称秩-2k 更新
her2k	C,Z	埃尔米特秩-2k 更新
trsm	S,D,C,Z	具有多个右侧的三角求解
trmm	S,D,C,Z	三角矩阵-矩阵乘法
symm	S,D,C,Z	对称矩阵-矩阵乘法
hemm	C,Z	埃尔米特矩阵-矩阵乘法

4. BLAS 符号拦截

标准 BLAS 库实现通常为相同的例程公开多个符号。假设 func 是 BLAS 例程名称，func_ 和/或 func 通常被定义为外部符号。一些 BLAS 库也可能公开带有专有附加前缀的一些符号。NVBLAS 仅拦截符号 func_ 和 func。用户需要确保旨在通过 NVBLAS 进行 GPU 加速的应用程序实际上调用了这些定义的符号。任何其他符号都不会被拦截，在这些情况下将执行原始 BLAS 例程。

5. 设备内存支持

从 Release 8.0 开始，数据可以位于任何 GPU 设备上，甚至可以位于未配置为计算一部分的 GPU 设备上。当任何数据位于 GPU 上时，无论问题的大小，计算都将完全在 GPU 上完成。此外，必须谨慎使用此功能：用户必须确保 BLAS 调用确实会被 NVBLAS 拦截，否则当 CPU BLAS 尝试执行它时会导致崩溃。

6. 安全注意事项

由于 NVBLAS 库依赖于符号拦截机制，因此必须确保它没有被破坏。在这方面，永远不应从以提升的权限运行的进程中使用 NVBLAS，例如 Windows 上的管理员或 Linux 上的 root 用户。

7. 配置

由于 NVBLAS 是 BLAS 的即插即用替代品，因此必须通过 ASCII 文本文件对其进行配置，该文件描述了有多少 GPU 以及哪些 GPU 可以参与拦截的 BLAS 调用。配置文件在库加载时进行解析。配置文件的格式基于关键字，可以选择后跟一个或多个用户定义的参数。每行最多允许一个关键字。空白行或以字符 # 开头的行将被忽略。

7.1. NVBLAS_CONFIG_FILE 环境变量

配置文件的位置和名称必须由环境变量 NVBLAS_CONFIG_FILE 定义。默认情况下，如果未定义 NVBLAS_CONFIG_FILE，NVBLAS 将尝试打开当前目录中的文件 nvblas.conf。为了安全使用 NVBLAS，配置文件应具有受限的写入权限。

7.2. 配置关键字

以下小节描述了配置关键字语法。

7.2.1. NVBLAS_LOGFILE

此关键字定义了 NVBLAS 应在其中打印状态和错误消息的文件。默认情况下，如果未定义，将使用标准错误输出文件（例如 stderr）。建议在配置文件的早期定义此关键字，以捕获解析该文件本身时出现的错误。

7.2.2. NVBLAS_TRACE_LOG_ENABLED

定义此关键字后，每个拦截的 BLAS 调用都将记录到 NVBLAS_LOGFILE 中。即使这种功能具有侵入性，它对于调试目的也可能很有用。

7.2.3. NVBLAS_CPU_BLAS_LIB

此关键字定义了 CPU BLAS 动态库文件（例如，Linux 上的 .so 文件或 Windows 上的 .dll），NVBLAS 应打开该文件以查找 CPU BLAS 符号定义。必须定义此关键字，NVBLAS 才能工作。由于 CPU Blas 库通常由多个文件组成，因此即使此关键字设置为 CPU 库主文件的完整路径，仍然可能需要在系统环境中定义正确的路径以查找库文件的其余部分。在 Linux 上，可以通过设置环境变量 LD_LIBRARY_PATH 来完成此操作，而在 Windows 上，可以通过设置环境变量 PATH 来完成此操作。

为了安全使用 NVBLAS，强烈建议采取以下预防措施

CPU BLAS 库应位于普通用户没有写入权限的位置。
指定的路径应该是绝对路径，而不是相对路径。

7.2.4. NVBLAS_GPU_LIST

此关键字定义了应参与拦截的 BLAS 调用计算的 GPU 列表。如果未定义，则仅使用 GPU 设备 0，因为这通常是系统中安装的计算能力最强的 GPU。此关键字可以设置为以空格字符分隔的设备编号列表。为了简单起见，还接受以下通配符关键字

关键字	含义
`ALL`	系统上检测到的所有具有计算能力的 GPU 都将被 NVBLAS 使用
`ALL0`	GPU 设备 0，以及检测到的所有其他具有与设备 0 相同计算能力的 GPU 都将被 NVBLAS 使用

注意

在当前版本的 CUBLAS 中，如果 CUBLASXT API 支持两个 GPU，则它们必须在同一块板卡上，例如 Tesla K10 或 GeForce GTX690，否则只能支持一个 GPU。由于 NVBLAS 构建于 CUBLASXT API 之上，因此 NVBLAS 具有相同的限制。如果需要访问更多 GPU 设备，请访问 cublasXt 了解许可详情。

7.2.5. NVBLAS_TILE_DIM

此关键字定义了应用于划分计算中涉及的矩阵的瓦片维度。此定义直接映射到 cublasXt API 例程 cublasXtSetBlockDim 的调用。请参阅 cuBLAS 文档以了解与将其设置为较大或较小值相关的权衡。

7.2.6. NVBLAS_GPU_DISABLED_<BLAS_FUNC_NAME>

此关键字附加了 BLAS 例程的名称，禁止 NVBLAS 在 GPU 上运行指定的例程。此功能主要用于调试目的。默认情况下，所有受支持的 BLAS 例程都已启用。

7.2.7. NVBLAS_CPU_RATIO_<BLAS_FUNC_NAME>

此关键字附加了 BLAS 例程的名称，定义了当 NVBLAS 决定将该例程的工作负载卸载到 GPU 时，应保留在 CPU 上的工作负载的比率。此功能直接映射到 cublasXt API 例程 cublasXtSetCpuRatio。默认情况下，所有例程的比率都定义为零。有关详细信息以及支持此功能的例程列表，请参阅 cuBLAS 文档。

7.2.8. NVBLAS_AUTOPIN_MEM_ENABLED

此关键字启用固定内存模式。此功能直接映射到 cublasXt API 例程 cublasXtSetPinningMemMode。如果配置文件中不存在此关键字，则固定内存模式将设置为 CUBLASXT_PINNING_DISABLED。

注意

使用此功能有一些限制，如底层例程 cublasXtSetPinningMemMode 的 cuBLAS 文档中所述。特别是当 NVBLAS 在多线程应用程序中使用时，如果不同线程使用的矩阵在调用 NVBLAS 时有可能重叠，则不应使用此选项。有关详细信息，请参阅例程 `cublasXtSetPinningMemMode <https://docs.nvda.net.cn/cuda/cublas/index.html#cublasxt_setPinningMemMode>`__ 的 cuBLAS 文档。

7.2.9. 配置文件示例

以下示例显示了一个典型的 NVBLAS 配置文件

# This is the configuration file to use NVBLAS Library
# Setup the environment variable NVBLAS_CONFIG_FILE to specify your own config file.
# By default, if NVBLAS_CONFIG_FILE is not defined,
# NVBLAS Library will try to open the file "nvblas.conf" in its current directory
# Example : NVBLAS_CONFIG_FILE  /home/cuda_user/my_nvblas.conf
# The config file should have restricted write permissions accesses

# Specify which output log file (default is stderr)
NVBLAS_LOGFILE  nvblas.log

# Enable trace log of every intercepted BLAS calls
NVBLAS_TRACE_LOG_ENABLED

#Put here the CPU BLAS fallback Library of your choice
#It is strongly advised to use full path to describe the location of the CPU Library
NVBLAS_CPU_BLAS_LIB  /usr/lib/libopenblas.so
#NVBLAS_CPU_BLAS_LIB  <mkl_path_installtion>/libmkl_rt.so

# List of GPU devices Id to participate to the computation
# Use ALL if you want all your GPUs to contribute
# Use ALL0, if you want all your GPUs of the same type as device 0 to contribute
# However, NVBLAS consider that all GPU have the same performance and PCI bandwidth
# By default if no GPU are listed, only device 0 will be used

#NVBLAS_GPU_LIST 0 2 4
#NVBLAS_GPU_LIST ALL
NVBLAS_GPU_LIST ALL0

# Tile Dimension
NVBLAS_TILE_DIM 2048

# Autopin Memory
NVBLAS_AUTOPIN_MEM_ENABLED

#List of BLAS routines that are prevented from running on GPU (use for debugging purpose
# The current list of BLAS routines supported by NVBLAS are
# GEMM, SYRK, HERK, TRSM, TRMM, SYMM, HEMM, SYR2K, HER2K

#NVBLAS_GPU_DISABLED_SGEMM
#NVBLAS_GPU_DISABLED_DGEMM
#NVBLAS_GPU_DISABLED_CGEMM
#NVBLAS_GPU_DISABLED_ZGEMM

# Computation can be optionally hybridized between CPU and GPU
# By default, GPU-supported BLAS routines are ran fully on GPU
# The option NVBLAS_CPU_RATIO_<BLAS_ROUTINE> give the ratio [0,1]
# of the amount of computation that should be done on CPU
# CAUTION : this option should be used wisely because it can actually
# significantly reduced the overall performance if too much work is given to CPU

#NVBLAS_CPU_RATIO_CGEMM 0.07

8. NVBLAS 安装

NVBLAS 库是 CUDA 工具包的一部分，并将与其他所有 CUDA 库一起安装。它在 64 位操作系统上可用。NVBLAS 库构建于 cuBLAS 之上，因此 cuBLAS 库需要可供 NVBLAS 访问。

9. 用法

要使用 NVBLAS 库，用户应用程序必须重新链接到 NVBLAS 以及原始 CPU Blas（从技术上讲，除非应用程序使用 NVBLAS 不支持的一些 BLAS 例程，否则只需要 NVBLAS）。为了确保链接器链接到 NVBLAS 的公开符号而不是 CPU BLAS 的符号，NVBLAS 库需要放在链接命令行上 CPU BLAS 之前。

在 Linux 上，使用 NVBLAS 库的另一种方法是使用 LD_PRELOAD 环境变量；此技术的优点是避免了重新链接步骤。但是，用户应避免全局定义该环境变量，因为它会导致系统上执行的每个 shell 命令都加载 NVBLAS 库，从而导致系统响应速度变慢。

最后，数学工具和库通常提供通过环境变量或配置文件指定要使用的 BLAS 库的机会。由于 NVBLAS 不支持所有标准 BLAS 例程，因此即使您的应用程序仅调用受支持的 NVBLAS 例程，也可能需要将 NVBLAS 与完整的 BLAS 库配对。幸运的是，这些工具和库通常提供一种指定多个 BLAS 库的方法。请参阅相应工具和库的文档以了解详细信息。

10. 声明

10.1. 声明

本文档仅供参考，不应被视为对产品的特定功能、条件或质量的保证。NVIDIA Corporation（“NVIDIA”）不对本文档中包含的信息的准确性或完整性做出任何明示或暗示的陈述或保证，并且对本文档中包含的任何错误不承担任何责任。NVIDIA 对使用此类信息或因使用此类信息而可能导致的侵犯第三方专利或其他权利的行为的后果或用途不承担任何责任。本文档不承诺开发、发布或交付任何材料（如下所定义）、代码或功能。

NVIDIA 保留随时对此文档进行更正、修改、增强、改进和任何其他更改的权利，恕不另行通知。

客户在下订单前应获取最新的相关信息，并应验证此类信息是否为最新且完整。

除非 NVIDIA 和客户的授权代表签署的单独销售协议（“销售条款”）另有约定，否则 NVIDIA 产品受订单确认时提供的 NVIDIA 标准销售条款和条件的约束。NVIDIA 在此明确反对将任何客户通用条款和条件应用于购买本文档中引用的 NVIDIA 产品。本文档未直接或间接形成任何合同义务。

NVIDIA 产品并非设计、授权或保证适用于医疗、军事、航空器、航天或生命维持设备，也不适用于 NVIDIA 产品发生故障或故障可能合理预期会导致人身伤害、死亡或财产或环境损害的应用。NVIDIA 对在此类设备或应用中包含和/或使用 NVIDIA 产品不承担任何责任，因此，此类包含和/或使用由客户自行承担风险。

NVIDIA 不保证或声明基于本文档的产品将适用于任何特定用途。NVIDIA 不一定对每个产品的所有参数进行测试。客户全权负责评估和确定本文档中包含的任何信息的适用性，确保产品适合客户计划的应用，并为应用执行必要的测试，以避免应用或产品出现缺陷。客户产品设计中的缺陷可能会影响 NVIDIA 产品的质量和可靠性，并可能导致超出本文档中包含的附加或不同条件和/或要求。NVIDIA 对可能基于以下原因或归因于以下原因的任何缺陷、损坏、成本或问题不承担任何责任：（i）以任何违反本文档的方式使用 NVIDIA 产品，或（ii）客户产品设计。

本文档未授予 NVIDIA 专利权、版权或本文档下的其他 NVIDIA 知识产权下的任何明示或暗示的许可。NVIDIA 发布的有关第三方产品或服务的信息并不构成 NVIDIA 授予使用此类产品或服务的许可，也不构成对其的保证或认可。使用此类信息可能需要获得第三方的专利或其他知识产权下的第三方许可，或获得 NVIDIA 的专利或其他 NVIDIA 知识产权下的 NVIDIA 许可。

只有在事先获得 NVIDIA 书面批准的情况下，才允许复制本文档中的信息，复制时不得进行更改，并且必须完全遵守所有适用的出口法律和法规，并附带所有相关的条件、限制和声明。

本文档和所有 NVIDIA 设计规范、参考板、文件、图纸、诊断程序、列表和其他文档（统称为“材料”，单独称为“材料”）均按“原样”提供。NVIDIA 不对材料做出任何明示、暗示、法定或其他形式的保证，并且明确否认对非侵权性、适销性和特定用途适用性的所有暗示保证。在法律未禁止的范围内，在任何情况下，NVIDIA 均不对因使用本文档而引起的任何损害（包括但不限于任何直接、间接、特殊、偶然、惩罚性或后果性损害，无论何种原因造成，也无论责任理论如何）承担责任，即使 NVIDIA 已被告知可能发生此类损害。尽管客户可能因任何原因而遭受任何损害，但 NVIDIA 对本文所述产品的客户的累计责任应根据产品的销售条款进行限制。

10.2. OpenCL

OpenCL 是 Apple Inc. 的商标，已获得 Khronos Group Inc. 的许可使用。

10.3. 商标

NVIDIA 和 NVIDIA 徽标是 NVIDIA Corporation 在美国和其他国家/地区的商标或注册商标。其他公司和产品名称可能是与其相关的各自公司的商标。