cuBLAS
简介
cuBLAS库提供以下四组API:cuBLAS API、cuBLASXt API、cuBLASLt API、cuBLASDx API
| API | 主要功能 | 典型应用 |
|---|---|---|
| cuBLAS | 基础线性代数计算 | 矩阵乘法、向量运算 |
| cuBLASLt | 更灵活的高性能矩阵乘法(GEMM) | 深度学习、矩阵乘法优化 |
| cuBLASXt | 支持多 GPU 的线性代数运算 | 多 GPU、大规模矩阵计算 |
| cuBLASDx | 在 CUDA Kernel 内执行线性代数运算 | 自定义 Kernel、算子融合 |
这里主要会介绍cuBLAS和cuBLASLt(后续介绍)两个库。
要使用cuBLAS API,应用程序必须在GPU内存空间中分配所需的矩阵和向量,填充数据,调用所需的cuBLAS函数,然后将结果从GPU内存空间上传回主机。cuBLAS API还提供了用于从GPU写入和读取数据的辅助函数。
要使用cuBLASXt API,应用程序的数据可能存储在主机或计算过程中涉及的任意设备上,库会根据用户请求自动将操作调度并传输到系统中的一个或多个GPU。
cuBLASLt是一个轻量级库,专门用于通用矩阵乘法(GEMM)运算,并提供一种新的灵活API。该库通过参数可编程性,在矩阵数据布局、输入类型、计算类型以及算法实现和启发式选择方面增加了灵活性。用户首先确定特定GEMM操作的一组选项后,这些选项便可重复用于不同输入数据。
数据布局
在平常我们使用的C/C++均是使用的行主序储存,即按行连续储存矩阵元素,而cuBLAS通常默认按列主序解释矩阵,即按列连续储存矩阵元素。
这也就导致了元素索引方式的不同。

假设矩阵A有M行、N列,访问第row行、第col列的元素。
| 对比 | C/C++ 行主序 | cuBLAS 列主序 |
|---|---|---|
| 存储方向 | 从左往右,逐行 | 从上往下,逐列 |
| 连续方向 | 列索引变化 | 行索引变化 |
| 元素索引 | row * N + col |
row + col * M |
| 主维度 | 每行跨度 | 每列跨度 |
Floating Point Emulation(浮点模拟)--CUDA 12.9以上
Floating Point Emulation(浮点模拟计算)是cuBLAS提供的一种矩阵乘法加速技术,其核心思想是:首先将输入数据转换为多个低精度值,然后利用低精度硬件单元计算部分结果,最后将这些结果重新组合成完整精度的输出。这些算法在保持相同或更高精度的同时,可显著优于原生精度算术运算的性能。
| 算法 | 模拟精度 | 支持的CC | CUDA版本 |
|---|---|---|---|
| BF16x9 | FP32 | 10.0、10.3 | CUDA 12.9+ |
| Fixed-Point | FP64 | 8.x、9.0、10.x、11.0、12.x | CUDA 13.0+ |
cuda数据类型
cuda数据类型通常保存在library_types.h头文件中,该头文件主要用于定义CUDA数学库共享的数据类型和枚举。
通常在引入后续的<cublas_v2.h>等头文件时,就会间接引入它。
通常来说浮点模拟的使用场景较为严苛,因此在实际使用中较少出现。
指定数据存储类型和精度--cudaDataType_t
cudaDataType_t 是 CUDA 中定义的枚举类型,用于指定数据的存储类型和精度,例如 FP16、FP32、FP64、INT8 等。
枚举值 数据类型 大小 CUDA_R_16FFP16 半精度浮点数 16 bit CUDA_R_16BFBF16 浮点数 16 bit CUDA_R_32FFP32 单精度浮点数 32 bit CUDA_R_64FFP64 双精度浮点数 64 bit CUDA_R_8IINT8 有符号整数 8 bit CUDA_R_8UUINT8 无符号整数 8 bit CUDA_R_32IINT32 有符号整数 32 bit CUDA_R_8F_E4M3FP8(E4M3 格式) 8 bit CUDA_R_8F_E5M2FP8(E5M2 格式) 8 bit CUDA_R_4F_E2M1FP4(E2M1 格式) 4 bit 其中各个枚举值中的R可以转变为其他的参数枚举值
R:实数
C:复数
指定浮点模拟使用策略--cudaEmulationStrategy_t
其功能与后面的指定浮点模拟使用策略--cublasEmulationStrategy_t相同,这里不做过多赘述
浮点模拟中有效尾数保留方法--cudaEmulationMantissaControl_t
cudaEmulationMantissaControl_t 是 CUDA 中定义的枚举类型,用于控制浮点模拟算法中有效尾数位的保留方式。主要应用于浮点模拟。
枚举值 数值 含义 CUDA_EMULATION_MANTISSA_CONTROL_DYNAMIC0 动态计算需要保留的尾数位数 CUDA_EMULATION_MANTISSA_CONTROL_FIXED1 使用固定的尾数位数 DYNAMIC
根据实际计算情况动态确定需要保留的尾数位数
目标是获得不低于原生浮点表示的计算精度
可以根据数据特点调整计算过程
FIXED
按照预先配置的尾数位数进行计算
不会根据运行时数据动态调整保留位数
适合需要明确控制计算精度的场景
浮点模拟中需要支持的特殊浮点数值--cudaEmulationSpecialValuesSupport_t
cudaEmulationSpecialValuesSupport_t 是 CUDA 中定义的枚举类型,用于指定浮点模拟算法需要支持哪些特殊浮点数值。主要用于控制无穷大和非数值的处理要求。
枚举值 数值 含义 CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_DEFAULT65535 默认模式,要求支持无穷大和非数值 CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NONE0 不要求浮点模拟算法额外支持特殊值 CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_INFINITY1 要求支持正无穷和负无穷 CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NAN2 要求支持非数值 其中无穷大主要是浮点溢出的情况、非数值主要是0/0的情况
查询CUDA数学库的版本信息--libraryPropertyType_t
libraryPropertyType_t 是 CUDA 中定义的枚举类型,用于指定需要查询 CUDA 数学库的哪一项版本信息。主要用于查询 cuBLAS、cuBLASLt、cuSOLVER 等数学库的版本属性。
枚举值 数值 含义 MAJOR_VERSION0 查询主版本号 MINOR_VERSION1 查询次版本号 PATCH_LEVEL2 查询补丁版本号
cuBLAS API
使用方法
需要引用头文件<cublas_v2.h>,同时需要链接cublas.lib,在windows下的VS中可以使用如下方式
Delphi
#include <cuda_runtime.h>
#include <cublas_v2.h>
#ifdef _MSC_VER
#pragma comment(lib, "cublas.lib")
#endif
在linux下,可以使用cmake链接动态库
Delphi
find_package(CUDAToolkit REQUIRED)
target_link_libraries(main PRIVATE
CUDA::cublas.so
)
cuBLAS数据类型
cuBLAS上下文指针--cublasHandle_t
cublasHandle_t 类型是一种指向不透明结构的指针,该结构用于存储 cuBLAS 库上下文。必须使用 cublasCreate() 初始化 cuBLAS 库上下文,然后将返回的句柄传递给所有后续的库函数调用。在结束时应使用 cublasDestroy() 销毁该上下文。
错误状态--cublasStatus_t
所有cuBLAS库函数调用均返回错误状态--cublasStatus_t
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_STATUS_SUCCESS |
0 | 执行成功 |
CUBLAS_STATUS_NOT_INITIALIZED |
1 | cuBLAS 未正确初始化 |
CUBLAS_STATUS_ALLOC_FAILED |
3 | 内存或内部资源分配失败 |
CUBLAS_STATUS_INVALID_VALUE |
7 | 传入的参数无效 |
CUBLAS_STATUS_ARCH_MISMATCH |
8 | GPU 架构不支持所需功能 |
CUBLAS_STATUS_MAPPING_ERROR |
11 | GPU 内存映射或访问失败 |
CUBLAS_STATUS_EXECUTION_FAILED |
13 | GPU 内核执行失败 |
CUBLAS_STATUS_INTERNAL_ERROR |
14 | cuBLAS 内部操作发生错误 |
CUBLAS_STATUS_NOT_SUPPORTED |
15 | 不支持请求的操作或功能 |
CUBLAS_STATUS_LICENSE_ERROR |
16 | 功能许可证检查失败 |
auto err = cublasCreate(&handle); if(err != CUBLAS_STATUS_SUCCESS){ printf("%s\n", cublasGetStatusString(status)); }cublasGetStatusString:将cublasStatus_t状态码转化为对应的错误描述字符串。
矩阵转置相关参数--cublasOperation_t
cublasOperation_t 是 cuBLAS 中定义的一个枚举类型,用于指定矩阵计算时是否需要对矩阵进行转置或共轭转置。
| 枚举值 | 数值 | 含义 | 数学表示 |
|---|---|---|---|
CUBLAS_OP_N |
0 | 不转置(Non-transpose) | A |
CUBLAS_OP_T |
1 | 普通转置(Transpose) | |
CUBLAS_OP_C |
2 | 共轭转置(Conjugate transpose) |
在线代中有对这个的具体讲解和求解,这里主要提一点,对于实数矩阵,普通转置和共轭转置结果相同--即
矩阵有效部分相关参数--cublasFillMode_t
cublasFillMode_t 是 cuBLAS 中定义的枚举类型,用于指定矩阵的哪一部分有效或需要参与计算,通常用于对称矩阵、Hermitian(厄米)矩阵和三角矩阵相关操作。
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_FILL_MODE_LOWER |
0 | 下三角部分有效(包含主对角线) |
CUBLAS_FILL_MODE_UPPER |
1 | 上三角部分有效(包含主对角线) |
CUBLAS_FILL_MODE_FULL |
2 | 整个矩阵有效 |
cublasFillMode_t只是指定矩阵的有效区域,但是不会自动将矩阵其他位置数据全部清零。
主对角线上元素处理相关参数--cublasDiagType_t
cublasDiagType_t 是 cuBLAS 中定义的枚举类型,用于指定矩阵的主对角线元素是否被视为 1,主要应用于三角矩阵相关计算。
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_DIAG_NON_UNIT |
0 | 非单位对角线,使用矩阵中实际存储的主对角线元素 |
CUBLAS_DIAG_UNIT |
1 | 单位对角线,所有主对角线元素均被视为 1 |
矩阵计算位置定义相关参数--cublasSideMode_t
cublasSideMode_t 是 cuBLAS 中定义的枚举类型,用于指定矩阵在矩阵运算中的位置,即矩阵位于乘法运算的左侧还是右侧。主要应用于对称矩阵、Hermitian(厄米)矩阵以及三角矩阵相关运算。
下面以矩阵A为例
| 枚举值 | 数值 | 含义 | 数学表示 |
|---|---|---|---|
CUBLAS_SIDE_LEFT |
0 | 指定矩阵位于左侧 | AB |
CUBLAS_SIDE_RIGHT |
1 | 指定矩阵位于右侧 | BA |
AB≠BA
标量参数指向内存方向--cublasPointerMode_t
cublasPointerMode_t 是 cuBLAS 中定义的枚举类型,用于指定标量参数的指针指向 CPU 主机内存(Host)还是 GPU 设备内存(Device)。主要用于控制 alpha、beta 等标量参数的存储位置,以及部分 cuBLAS 函数的标量结果存储位置。
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_POINTER_MODE_HOST |
0 | 标量参数的指针指向 CPU 主机内存 |
CUBLAS_POINTER_MODE_DEVICE |
1 | 标量参数的指针指向 GPU 设备内存 |
CUBLAS_POINTER_MODE_HOST
标量参数存储在CPU内存中
cuBLAS从主机内存获取标量值
创建cuBLAS句柄后的默认模式
CUBLAS_POINTER_MODE_DEVICE
标量参数存储在GPU显存中
cuBLAS从GPU设备内存中获取标量值
适合标量数据已经储存在GPU上的情况
通常可以使用
cublasSetPointerMode()设置,通过cublasGetPointerMode()获取当前模式。
原子操作相关参数--cublasAtomicsMode_t
cublasAtomicsMode_t 是 cuBLAS 中定义的枚举类型,用于指定是否允许 cuBLAS 使用原子操作实现相关计算。主要用于控制部分矩阵运算在计算性能与结果可重复性之间的权衡。
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_ATOMICS_NOT_ALLOWED |
0 | 不允许使用基于原子操作的替代实现 |
CUBLAS_ATOMICS_ALLOWED |
1 | 允许使用基于原子操作的替代实现 |
CUBLAS_ATOMICS_NOT_ALLOWED
cuBLAS 不使用基于原子操作的替代算法
有利于保证相同条件下计算结果的可重复性
是 cuBLAS 句柄初始化后的默认模式
CUBLAS_ATOMICS_ALLOWED
允许 cuBLAS 使用基于原子操作的替代算法
某些运算可以获得更高的计算性能
由于原子操作的执行顺序可能不同,浮点计算结果可能存在微小差异
可以通过
cublasSetAtomicsMode()设置,通过cublasGetAtomicsMode()获取当前模式。
GEMM计算算法--cublasGemmAlgo_t
cublasGemmAlgo_t 是 cuBLAS 中定义的枚举类型,用于指定 GEMM(通用矩阵乘法)所采用的计算算法。主要用于控制矩阵乘法的算法选择方式,例如使用默认算法、指定算法或自动调优算法。
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_GEMM_DEFAULT |
-1 | 使用启发式策略自动选择 GEMM 算法 |
CUBLAS_GEMM_ALGO0 ~ CUBLAS_GEMM_ALGO23 |
0~23 | 显式指定编号为 0~23 的 GEMM 算法 |
CUBLAS_GEMM_AUTOTUNE |
999 | 通过实际性能测试选择算法,实验性功能 |
CUBLAS_GEMM_DEFAULT
由 cuBLAS 根据矩阵维度、数据类型、GPU 架构等信息,通过启发式策略选择合适的 GEMM 算法。
CUBLAS_GEMM_ALGO0 ~ CUBLAS_GEMM_ALGO23
对应 24 个算法编号。这些编号由 cuBLAS 内部定义,并不代表简单的性能排名,也不意味着编号越大性能越高。
CUBLAS_GEMM_AUTOTUNE
cuBLAS 实际测试多个候选算法,选择适合当前计算配置的算法,并将选择结果缓存在 cuBLAS 句柄中,供后续相同配置的计算使用。
通常使用CUBLAS_GEMM_DEFAULT和CUBLAS_GEMM_AUTOTUNE
对比项目 CUBLAS_GEMM_DEFAULTCUBLAS_GEMM_AUTOTUNE选择方式 启发式算法 实际性能测试 是否测试多个算法 不进行逐一性能测试 会测试多个候选算法 首次调用开销 通常较低 较高 算法选择依据 矩阵维度、数据类型、GPU 架构等 实际运行性能 是否缓存调优结果 不需要专门的实测调优缓存 会缓存到 cuBLAS Handle 性能表现 较好 有机会获得更高性能 是否为实验性功能 否 是
矩阵计算数学运算模式--cublasMath_t
cublasMath_t 是 cuBLAS 中定义的枚举类型,用于指定矩阵计算采用的数学运算模式,主要控制计算精度、Tensor Core 加速方式以及中间结果的精度。
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_DEFAULT_MATH |
0 | 默认计算模式,在满足所要求精度的前提下优先考虑性能 |
CUBLAS_PEDANTIC_MATH |
2 | 严格数学计算模式,遵循规定精度与标准算术行为 |
CUBLAS_TF32_TENSOR_OP_MATH |
3 | 使用 TF32 Tensor Core 加速单精度计算 |
CUBLAS_FP32_EMULATED_BF16X9_MATH |
4 | 使用 BF16x9 算法模拟 FP32 计算 |
CUBLAS_FP64_EMULATED_FIXEDPOINT_MATH |
8 | 使用定点模拟算法加速 FP64 计算 |
CUBLAS_MATH_DISALLOW_REDUCED_PRECISION_REDUCTION |
16 | 禁止在特定混合精度矩阵乘法的归约过程中降低累加精度 |
CUBLAS_DEFAULT_MATH
cuBLAS 默认使用的模式
在满足规定计算精度要求的情况下优化计算性能
在适用条件下允许使用 Tensor Core
CUBLAS_PEDANTIC_MATH
使用规定的计算精度和标准算术操作
主要用于数值稳定性研究、测试和调试
相比默认模式,可能降低计算性能
CUBLAS_TF32_TENSOR_OP_MATH
允许使用 TF32 Tensor Core 加速单精度计算
TF32 保留与 FP32 相同的指数位宽,但乘法输入的尾数精度更低
通常可以获得较高的计算吞吐量,但可能产生更大的数值误差
CUBLAS_MATH_DISALLOW_REDUCED_PRECISION_REDUCTION
在部分混合精度 GEMM 中,禁止使用精度低于计算类型的归约
例如计算类型为 FP32、输出类型为 FP16 时,要求归约使用 FP32 累加精度,而不在归约中降为 FP16
属于可与其他数学模式通过按位或
|组合的标志可以通过
cublasSetMathMode()设置,通过cublasGetMathMode()查询
计算精度和模式相关参数--cublasComputeType_t
cublasComputeType_t 是 cuBLAS 中定义的枚举类型,用于指定矩阵乘法的计算精度和计算模式。主要应用于 cublasGemmEx()、cublasLtMatmul() 及其批量矩阵乘法版本。
| 枚举值 | 数值 | 含义 |
|---|---|---|
CUBLAS_COMPUTE_16F |
64 | 默认 FP16 计算模式,允许 Tensor Core 加速 |
CUBLAS_COMPUTE_16F_PEDANTIC |
65 | 严格 FP16 计算模式,禁用 Tensor Core |
CUBLAS_COMPUTE_32F |
68 | 默认 FP32 计算模式 |
CUBLAS_COMPUTE_32F_PEDANTIC |
69 | 严格 FP32 计算模式,禁用部分算法优化 |
CUBLAS_COMPUTE_32F_FAST_16F |
74 | 允许将 FP32 输入转换为 FP16,利用 Tensor Core 加速 |
CUBLAS_COMPUTE_32F_FAST_16BF |
75 | 允许将 FP32 输入转换为 BF16,利用 Tensor Core 加速 |
CUBLAS_COMPUTE_32F_FAST_TF32 |
77 | 允许使用 TF32 Tensor Core 加速 FP32 计算 |
CUBLAS_COMPUTE_32F_EMULATED_16BFX9 |
78 | 使用 BF16x9 浮点模拟算法执行 FP32 计算 |
CUBLAS_COMPUTE_64F |
70 | 默认 FP64 计算模式 |
CUBLAS_COMPUTE_64F_PEDANTIC |
71 | 严格 FP64 计算模式,禁用部分算法优化 |
CUBLAS_COMPUTE_64F_EMULATED_FIXEDPOINT |
79 | 使用 Fixed-Point 浮点模拟算法执行 FP64 计算 |
CUBLAS_COMPUTE_32I |
72 | 默认 INT32 整数计算模式 |
CUBLAS_COMPUTE_32I_PEDANTIC |
73 | 严格 INT32 整数计算模式 |
这里需要区分和cublasMath_t以及cudaDataType_t之间的区别
对比 cublasMath_tcublasComputeType_t主要作用 设置 cuBLAS 句柄的数学计算模式 指定特定 GEMM 运算的计算精度和模式 配置范围 句柄级别 单次操作级别 是否可以指定 FP16/FP32/FP64 不直接指定具体计算数据类型 可以
对比 cudaDataType_tcublasComputeType_t作用 指定数据的存储类型 指定计算精度及计算模式 关注对象 矩阵 A、B、C 等数据 矩阵乘法内部计算 含义 数据以 FP16 存储 计算采用 FP32 精度
指定浮点模拟使用策略--cublasEmulationStrategy_t
cublasEmulationStrategy_t 是 cuBLAS 中定义的枚举类型,用于指定浮点模拟的使用策略。它主要控制 cuBLAS 在什么条件下使用 BF16x9、Fixed-Point 等浮点模拟算法。
枚举值 数值 含义 CUBLAS_EMULATION_STRATEGY_DEFAULT0 默认策略,通常等同于 PERFORMANTCUBLAS_EMULATION_STRATEGY_PERFORMANT1 仅在浮点模拟能够带来性能优势时使用 CUBLAS_EMULATION_STRATEGY_EAGER2 只要条件允许,就尽可能使用浮点模拟
cuBLAS函数
基本函数
上下文指针的创建和销毁--cublasCreate()、cublasDestroy()
cublasStatus_t cublasCreate(cublasHandle_t *handle);
cublasStatus_t cublasDestroy(cublasHandle_t handle);
在调用cuBLAS库函数的开始和结束,可以使用cublasCreate和cublasDestroy来创建和销毁上下文。
cuBLAS允许用户使用多个主机线程和多个GPU,但是这需要明确句柄上下文,因此可以使用cudaSetDevice()将不同的设备与不同的主机线程关联,并在每个主机线程中初始化一个唯一的cuBLAS库上下文句柄。
获取cuBLAS版本号--cublasGetVersion()
cublasStatus_t cublasGetVersion(cublasHandle_t handle, int *version)
此函数返回 cuBLAS 库的版本号。
获取返回状态字符串表示--cublasGetStatusString
const char* cublasGetStatusString(cublasStatus_t status)
此函数返回指定状态的字符串表示。
设置流--cublasSetStream()
cublasStatus_t cublasSetStream(cublasHandle_t handle, cudaStream_t streamId)
此函数用于设置cuBLAS库的stream,该stream将用于执行后续所有对cuBLAS库函数的调用。如果未设置cuBLAS库stream,则所有内核使用NULL stream。
在同一时刻,一个句柄只能控制一个stream,可以通过cublasSetStream()在不同stream之间切换,但切换前控制的stream重置为NULL。
因此通常使用多句柄多stream进行控制。
设置工作空间--cublasSetWorkspace
cublasStatus_t cublasSetWorkspace(cublasHandle_t handle, void *workspace, size_t workspaceSizeInBytes)
工作空间是GPU显存中的一块临时存储区域,用于存储矩阵计算过程中的中间数据或供内部算法使用。
如果未设置cuBLAS库的工作空间,则所有内核将使用在创建cuBLAS上下文时分配的默认工作空间池。
同时cublasSetStream()会无条件地将cuBLAS库的工作空间重置会默认的工作空间池。因此其使用的正确顺序如下:
cublasSetStream(handle, stream1); cublasSetWorkspace(handle, workspace1, size); cublasSgemm(...);而对于工作空间大小的分配,首先必须对齐至少256字节,同时如果分配的内存过小,可能导致错误,或者性能下降。
通常来说SM9.0及以后的GPU架构可以分配32MiB(32×1024×1024字节)的大小,如下
size_t workspaceSize = 32 * 1024 * 1024; void* workspace = nullptr; cudaMalloc(&workspace, workspaceSize); cublasSetWorkspace(handle, workspace, workspaceSize);
获取stream编号--cublasGetStream()
cublasStatus_t cublasGetPointerMode(cublasHandle_t handle, cublasPointerMode_t *mode)
此函数获取用于执行所有cuBLAS库函数调用的cuBLAS库流。如果未设置cuBLAS库流,则所有内核将使用默认的NULL流。
设置使用的指针模式--cublasSetPointerMode()
cublasStatus_t cublasSetPointerMode(cublasHandle_t handle, cublasPointerMode_t mode)
此函数用于设置 cuBLAS 库所使用的指针模式。默认情况下,值通过主机的引用方式传递。详情见上文。
获取使用的指针模式--cublasGetPointerMode()
cublasStatus_t cublasGetPointerMode(cublasHandle_t handle, cublasPointerMode_t *mode)
此函数用于获取 cuBLAS 库所使用的指针模式。详情见上文。
一维向量数据传输--cublasSetVector()/cublasGetVector()
cublasStatus_t cublasSetVector(int n, int elemSize, const void *x, int incx, void *y, int incy)
cublasStatus_t cublasGetVector(int n, int elemSize, const void *x, int incx, void *y, int incy)
n:需要复制的元素数量
elemSize:每个元素的字节大小
x:CPU端源数据指针/GPU端目标数据指针
incx:CPU源向量的元素步长/GPU源向量的元素步长,单位为元素数量
y:GPU端目标数据指针/CPU端源数据指针
incy:GPU源向量的元素步长/CPU源向量的元素步长,单位为元素数量
cublasSetVector()固定为CPU传输给GPU端,cublasGetVector()固定为GPU传输给CPU端
float x[6] = {1, 2, 3, 4, 5, 6}; float* d_y = nullptr; cudaMalloc(&d_y, 3 * sizeof(float)); cublasSetVector( 3, // 复制3个元素 sizeof(float), // 每个元素4字节 x, // CPU源地址 2, // 每隔2个元素读取一个 d_y, // GPU目标地址 1 // GPU连续存储 ); cudaFree(d_y); // GPU内存为[1, 3, 5];
二维向量数据传输--cublasSetMatrix()/cublasGetMatrix()
cublasStatus_t cublasSetMatrix(int rows, int cols, int elemSize, const void *A, int lda, void *B, int ldb)
cublasStatus_t cublasGetMatrix(int rows, int cols, int elemSize, const void *A, int lda, void *B, int ldb)
rows:矩阵行数
cols:矩阵列数
elemSize:每个元素的字节大小
A:CPU端源数据指针/GPU端目标数据指针
lda:CPU源向量的前导维度/GPU源向量的前导维度,单位为元素数量
B:GPU端目标数据指针/CPU端源数据指针
ldb:GPU源向量的前导维度/CPU源向量的前导维度,单位为元素数量
cublasSetMatrix()固定为CPU传输给GPU端,cublasGetMatrix()固定为GPU传输给CPU端同时需要注意的是,Matrix函数按照列主序来存储二维矩阵
// 2行3列,按照列主序存储 float h_A[6] = { 1, 4, 2, 5, 3, 6 }; int rows = 2; int cols = 3; // 分配GPU显存 float* d_A = nullptr; cudaMalloc(&d_A, rows * cols * sizeof(float)); // 将CPU矩阵复制到GPU cublasStatus_t status = cublasSetMatrix( rows, // 行数 cols, // 列数 sizeof(float), // 每个元素的字节数 h_A, // CPU源矩阵 rows, // CPU矩阵前导维度 d_A, // GPU目标矩阵 rows // GPU矩阵前导维度 ); cudaFree(d_A); // d_A[6] = { 1, 4, 2, 5, 3, 6 };
异步向量传输
cublasStatus_t cublasSetVectorAsync(int n, int elemSize, const void *hostPtr, int incx, void *devicePtr, int incy, cudaStream_t stream)
cublasStatus_t cublasGetVectorAsync(int n, int elemSize, const void *devicePtr, int incx, void *hostPtr, int incy, cudaStream_t stream)
cublasStatus_t cublasSetMatrixAsync(int rows, int cols, int elemSize, const void *A, int lda, void *B, int ldb, cudaStream_t stream)
cublasStatus_t cublasGetMatrixAsync(int rows, int cols, int elemSize, const void *A, int lda, void *B, int ldb, cudaStream_t stream)
这四个函数相较于上面的函数后缀多了Async(),因此其相较于上面的函数多出了一个异步的功能,参数也多出一个,其余皆是相同的。
多出的参数均是cudaStream_t stream,用于指定数据复制操作所在的CUDA Stream。
需要注意的是,由于向量传输是异步的,因此使用常规的cudaMalloc()复制可能失败,CPU端通常使用cudaMallocHost()等方式分配锁页内存,GPU端正常使用cudaMalloc()复制即可。需要需要CPU读取复制结果,可以使用cudaStreamSynchronize()等方式确保传输已经完成。
float* h_A = nullptr; float* d_A = nullptr; size_t bytes = 1024 * sizeof(float); // CPU:锁页内存 cudaMallocHost(&h_A, bytes); // GPU:普通显存 cudaMalloc(&d_A, bytes); // 异步传输 cublasSetVectorAsync( 1024, sizeof(float), h_A, 1, d_A, 1, stream ); cudaStreamSynchronize(stream); cudaFree(d_A); cudaFreeHost(h_A); cudaStreamDestroy(stream);
原子操作模式--cublasSetAtomicsMode()/cublasGetAtomicsMode
cublasStatus_t cublasSetAtomicsMode(cublasHandle_t handle, cublasAtomicsMode_t mode)
cublasStatus_t cublasGetAtomicsMode(cublasHandle_t handle, cublasAtomicsMode_t *mode)
此函数是原子操作模式设置/获取函数,用于控制指定 cuBLAS Handle 是否允许使用基于原子操作的计算算法,或是直接获取当前Handle中基于原子操作的计算算法。详情见上文。
可以通过
cublasSetAtomicsMode()设置,通过cublasGetAtomicsMode()获取当前模式。
矩阵计算数学运算模式--cublasSetMathMode()/cublasGetMathMode
cublasStatus_t cublasSetMathMode(cublasHandle_t handle, cublasMath_t mode)
cublasStatus_t cublasGetMathMode(cublasHandle_t handle, cublasMath_t *mode)
这两个函数用于设置和查询 cuBLAS Handle 的数学计算模式,主要影响计算精度、数值行为及部分计算优化策略。详情见上文。
可以通过
cublasSetMathMode()设置,通过cublasGetMathMode()查询
一维函数
为了更简洁清晰地呈现所实现的函数,我们将使用 <type> 表示类型,<t> 表示对应的短类型。在阅读时可以直接将该字符串替换为对应的意思
| <type> | <t> | Meaning |
|---|---|---|
float |
s or S |
实数单精度 |
double |
d or D |
实数双精度 |
cuComplex |
c or C |
复数单精度 |
cuDoubleComplex |
z or Z |
复数双精度 |
同时需要注意的是,cuBLAS返回的索引从 1 开始,而 C/C++ 数组索引从 0 开始。
部分后续参数说明
handle:cuBLAS句柄
n:参与计算的元素数量
x:GPU端输入向量指针
incx:向量x的访问向量的步长
y:GPU端输入/输出向量指针(默认为输入向量)
incy:向量y的访问向量的步长
result:返回的结果
x和y必须位于GPU端,但是result可以位于CPU和GPU中,具体取决于cuBLAS的指针模式,指针模式可以通过cublasSetPointerMode()来指定,具体参考上文
查找向量绝对值的最大/最小值--cublasI<t>amax()/cublasI<t>amin()
cublasStatus_t cublasIsamax(cublasHandle_t handle, int n, const float *x, int incx, int *result)
cublasStatus_t cublasIdamax(cublasHandle_t handle, int n, const double *x, int incx, int *result)
cublasStatus_t cublasIcamax(cublasHandle_t handle, int n, const cuComplex *x, int incx, int *result)
cublasStatus_t cublasIzamax(cublasHandle_t handle, int n, const cuDoubleComplex *x, int incx, int *result)
cublasStatus_t cublasIsamin(cublasHandle_t handle, int n, const float *x, int incx, int *result)
cublasStatus_t cublasIdamin(cublasHandle_t handle, int n, const double *x, int incx, int *result)
cublasStatus_t cublasIcamin(cublasHandle_t handle, int n, const cuComplex *x, int incx, int *result)
cublasStatus_t cublasIzamin(cublasHandle_t handle, int n, const cuDoubleComplex *x, int incx, int *result)
result:返回索引
#include <cuda_runtime.h> #include <cublas_v2.h> #include <iostream> #pragma comment(lib, "cublas.lib") #pragma comment(lib, "cudart.lib") int main() { float h_x[] = {2, -8, 5, 3, -6}; float* d_x = nullptr; int n = 5; int result = 0; cudaMalloc((void**)&d_x, n * sizeof(float)); cudaMemcpy(d_x, h_x, n * sizeof(float), cudaMemcpyHostToDevice); cublasHandle_t handle; cublasCreate(&handle); cublasIsamax(handle, n, d_x, 1, &result); std::cout << "索引: " << result << std::endl; std::cout << "元素: " << h_x[result - 1] << std::endl; cublasDestroy(handle); cudaFree(d_x); return 0; }如果多个元素具有相同的最大绝对值,返回第一个元素的索引
若n ≤ 0或者incv ≤ 0则返回索引为0
对于复数类型,比较的是实部的绝对值+虚部的绝对值,而不是模长
这里后不再介绍实数双精度以及复数的函数API,函数具体用法均相同,替换函数名以及向量指针类型,替换参数对应表参考上述表格。比如cublasI<t>amax()对于
cublasIsamax():单精度实数、cublasIdamax():双精度实数、cublasIcamax():单精度复数和cublasIzamax():双精度复数这四个函数的功能及参数含义一致,主要区别是函数名称及输入数据类型,输出结果均为最大绝对值元素的索引。
并非所有 cuBLAS 函数都具有完整的四种类型版本,部分函数还存在特殊命名、不同返回类型或其他参数差异。对于此类函数,后续将单独说明,不直接套用统一规则。
计算所有元素的绝对值之和--cublas<t>asum()
cublasStatus_t cublasSasum(cublasHandle_t handle, int n, const float *x, int incx, float *result)
result返回索引
参数和注意事项同上
一次函数--cublas<t>axpy()
cublasStatus_t cublasSaxpy(cublasHandle_t handle, int n, const float *alpha, const float *x, int incx, float *y, int incy)
y作为输入向量也作为输出向量
参数和注意事项同上
alpha:斜率
这里需要注意索引问题,若
x = {1, 2, 3, 4}; y = {5, 6, 7, 8}; alpha = 2;当n=2,incx=1,incy=1时y={7,10,7,8}(1×2+5=7,2×2+6=10,7=7,8=8)
当n=2,incx=1,incy=2时y={7,6,11,8}
但是当n=4,incx=2,incy=1时,x索引越界,其至少需要7个元素,因此会导致结果的错误
需要注意的是,x和y都必须在GPU端,不能在CPU端使用
正比例函数--cublas<t>scal()
cublasStatus_t cublasSscal(cublasHandle_t handle, int n, const float *alpha, float *x, int incx)
参数和注意事项同上
alpha:斜率
赋值函数--cublas<t>copy()
cublasStatus_t cublasScopy(cublasHandle_t handle, int n, const float *x, int incx, float *y, int incy)
y作为输入向量也作为输出向量
参数和注意事项同上
由于cuda在内存复制时,不连续会大大降低性能,因此该函数即是用于非连续向量元素的赋值
交换函数--cublas<t>swap()
y作为输入向量也作为输出向量
参数和注意事项同上
需要区分和上面一个函数的区别,上一个函数是将x的值直接赋值给y,而该函数是将x与y的值相交换
点积函数--cublas<t>dot()
cublasStatus_t cublasSdot (cublasHandle_t handle, int n, const float *x, int incx, const float *y, int incy, float *result)
result返回点积结果
参数和注意事项同上
需要注意的是复数点积需要对x进行共轭
欧几里得范数函数--cublas<t>nrm2()
cublasStatus_t cublasSnrm2(cublasHandle_t handle, int n, const float *x, int incx, float *result)
result返回范数结果
对于复数向量,计算的是复数模长平方和再开方
吉文斯旋转--cublas<t>rot()
cublasStatus_t cublasSrot(cublasHandle_t handle, int n, float *x, int incx, float *y, int incy, const float *c, const float *s)
c:旋转参数,通常为cosθ
s:旋转参数,通常为sinθ
同时这里的x和y会因为该函数而改变具体的值
求取吉文斯旋转参数--cublas<t>rotg()
cublasStatus_t cublasSrotg(cublasHandle_t handle, float *a, float *b, float *c, float *s)
a:输入标量,执行后被更新为r
b:输入标量,执行后被更新为辅助参数z
c:输出旋转系数c
s:输出旋转系数s这四个标量都可以存储在CPU端