debug-cuda-crash

此技能为开发人员与 AI 工程师提供了一份详尽指南，用于除错使用 FlashInfer 库时遇到的复杂 CUDA 崩溃问题。CUDA 错误（例如非法内存访问、越界错误、NaN/Inf 数值不稳定与内存溢出 OOM）通常难以追踪，因为它们往往会立即终止执行环境。此技能教导用户如何利用 @flashinfer_api 装饰器来检测代码，从而在失败前系统化地观察张量状态与 API 调用序列。

• 在核心执行前捕获输入元数据，包含张量形状、数据类型、设备分配与内存布局。

• 记录张量内部统计数据，如最小值、最大值、平均值以及 NaN/Inf 计数，以准确定位模型中的数值不稳定性。

• 设定日志等级与存储位置，支持标准输出与文件日志，适用于多进程（如 torchrun）环境。

• 识别诸如头维度不匹配、错误数据类型（FP16 与 BF16）或 CPU 到 GPU 传输错误等结构性问题。

• 与进阶外部诊断工具（如 compute-sanitizer）整合，进行深层硬件内存分析。

• 用户应设定环境变量（如 FLASHINFER_LOGLEVEL 1 到 5 与 FLASHINFER_LOGDEST）来控制日志详细程度与输出目标。

• 本指南假设用户是在基于 PyTorch 的推理流水线中使用 FlashInfer 的优化 Attention 或 GEMM 核心。

• 在进行多 Rank/多 GPU 除错时，务必在日志路径中使用 %i 模式，以防止多进程间的日志写入冲突。

• 虽然该工具已针对捕捉运行时失败进行了优化，但它不能取代核心级分析，性能瓶颈分析应使用 FlashInfer 专用分析工具。

• 若在频繁调用核心时启用等级 5 的日志（张量统计），请确保磁盘有足够的存储空间，以避免执行期间的 I/O 阻塞。