cuBLAS调用前必须初始化并创建句柄，GPU上下文需激活；矩阵需按列主序布局或正确设置转置参数；leading dimension指每列元素数；指针须为GPU内存地址；alpha/beta传地址；调用后需同步。
cuBLAS 初始化和句柄创建必须在调用前完成
不初始化就直接调用 cublasCreate 以外的函数（比如 cublasSgemm），会返回 CUBLAS_STATUS_NOT_INITIALIZED 错误。GPU 上下文必须已激活，通常意味着你得先调用 cudaSetDevice 或确保当前线程已有默认上下文。
常见错误是漏掉 cublasHandle_t 句柄创建，或在多线程中复用非线程安全的句柄（cuBLAS 句柄不是线程安全的，每个线程应有自己的句柄）。
- 务必检查
cublasCreate返回值，失败时不能继续 - 若使用多个 GPU，需为每个设备分别创建句柄并绑定上下文
- 句柄应在生命周期结束时调用
cublasDestroy，否则泄漏资源
矩阵布局和内存地址传参容易搞反
cuBLAS 默认按列主序（column-major），而 C++ 原生二维数组是行主序（row-major）。直接把 float A[M][N] 的首地址传给 cublasSgemm 当作 A 矩阵，结果会错——除非你显式转置运算（通过 CUBLAS_OP_T 参数）或提前重排内存。
更稳妥的做法是：保持数据在 GPU 上为列主序布局，或在调用时用转置参数“假装”它是列主序。例如计算 C = A * B（行主序语义），实际要调用：cublasSgemm(handle, CUBLAS_OP_N, CUBLAS_OP_N, N, P, M, α, d_B, N, d_A, M, β, d_C, N) ——注意这里把 B 放前面、A 放后面，且各自 leading dimension 用的是“行数”，本质是在用列主序视角做行主序乘法。
立即学习“C++免费学习笔记（深入）”；
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- leading dimension（lda/ldb/ldc）不是矩阵行数或列数，而是**存储时每列占的元素个数**（即外维尺寸）
- GPU 内存指针必须是
float*类型，不能传 host 指针，否则报CUBLAS_STATUS_INVALID_VALUE - 所有指针需用
cudaMalloc分配，并用cudaMemcpy同步数据
SGEMM 参数顺序和标量传递有严格要求
cublasSgemm 的参数顺序和 BLAS 标准一致，但 C++ 调用时容易因参数过多而错位，尤其 alpha 和 beta 是 host 内存中的标量地址，不是值本身。传 α 错写成 alpha 会导致非法内存访问。
典型调用签名是：cublasSgemm(handle, transa, transb, m, n, k, α, A, lda, B, ldb, β, C, ldc)
其中 m, n, k 对应 C(m×n) = alpha * op(A)(m×k) * op(B)(k×n) + beta * C，务必对照公式核对维度是否匹配。
-
transa和transb是cublasOperation_t枚举，别用整数硬编码（如 0/1），应写CUBLAS_OP_N/CUBLAS_OP_T -
alpha和beta必须是 host 地址，哪怕它们是栈变量也要取地址 - 若
beta == 0，C可以是未初始化内存；但beta != 0时C必须已分配且可读
同步与性能陷阱：别忘了 cudaDeviceSynchronize
cuBLAS 是异步 API，调用 cublasSgemm 后控制权立刻返回，GPU 还在算。如果紧接着用 cudaMemcpy 把结果拷回 host，大概率拿到旧数据或触发非法访问。必须显式同步，或用 stream 控制依赖。
调试时最简单的办法是加 cudaDeviceSynchronize()；生产环境建议用自定义 stream 并传入 cublasSetStream，再用 cudaStreamSynchronize 细粒度等待。
- 没有同步就读结果 → 表现为输出全零、随机值或程序卡死
- 在循环中反复调用
cublasSgemm却不复用 stream，会累积 kernel 启动开销 - 混合使用 cuBLAS 和自定义 kernel 时，stream 不一致会导致隐式同步，大幅降低吞吐
实际写的时候，最容易被忽略的是 leading dimension 和内存布局的对应关系——它不像 CPU BLAS 那样“自然”，GPU 上少一个 N 或多一个 M，结果就完全不对，而且不容易一眼看出错在哪。
