CANN PyPTO Matmul 错误码全解FC3000–FC5002 根因定位与排查实战【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto导读PyPTOParallel Tensor/Tile Operation是 CANN 面向昇腾 AI 处理器的张量编程范式其矩阵乘类接口pypto.matmul与pypto.scaled_mm在框架内部校验失败或运行异常时会以FC3XXX/FC5XXX错误码的形式抛出。本文以仓库中的 Matmul 排障文档为核心系统梳理 FC3000、FC3001、FC3002、FC5000、FC5002 五个错误码的触发含义、常见根因与处理步骤并结合 error_code.h 中的错误码定义、matmul.py 中的入参校验逻辑与 cube_operation_impl.cpp 中的运行时断言给出可复现、可对照源码的排查路径帮助开发者在使用 PyPTO 编写矩阵乘 kernel 时快速定位并解决参数与运行时问题。一、错误码体系速览FC 前缀背后的分类规则在深入每个错误码之前先理解 PyPTO 框架错误码的编码规则有助于快速缩小排查范围。错误码定义位于 framework/include/tilefwk/error_code.h源码中的分类注释给出了明确的区间划分// // FCXXXX: OPERATION // FC0-FC2XXX: VECTOR // FC3-FC5XXX: MATMUL // FC6-FC8XXX: CONV // FC9XXX: VIEW OP // 即FC3XXX段0xC3xxx属于Matmul 参数类错误FC5XXX段0xC5xxx属于Matmul 运行时错误。MatmulErrorCode枚举完整定义如下enum class MatmulErrorCode : uint32_t { ERR_PARAM_INVALID 0xC3000U, // FC3000 参数非法 ERR_PARAM_MISMATCH 0xC3001U, // FC3001 参数不匹配 ERR_PARAM_UNSUPPORTED 0xC3002U, // FC3002 参数组合不支持 ERR_CONFIG_TILE 0xC4000U, // FC4000 Tile 配置错误 ERR_CONFIG_ALIGNMENT 0xC4001U, // FC4001 对齐配置错误 ERR_CONFIG_UNSUPPORTED 0xC4002U, // FC4002 配置不支持 ERR_RUNTIME_NULLPTR 0xC5000U, // FC5000 运行时出现空指针/空 Tensor ERR_RUNTIME_STATE 0xC5001U, // FC5001 运行时状态异常 ERR_RUNTIME_LOGIC 0xC5002U, // FC5002 运行时逻辑异常 };可以看到FC3xxx与FC5xxx之间还隔着FC4xxxTile 配置类错误。这些错误码在 C 侧通过ASSERT/CHECK宏触发例如 cube_operation_impl.cpp 中对输入输出 Tensor 指针的空值断言ASSERT(MatmulErrorCode::ERR_RUNTIME_NULLPTR, tensorGraphNodes.aTensorPtr ! nullptr); ASSERT(MatmulErrorCode::ERR_RUNTIME_NULLPTR, tensorGraphNodes.bTensorPtr ! nullptr); ASSERT(MatmulErrorCode::ERR_RUNTIME_NULLPTR, tensorGraphNodes.outTensorPtr ! nullptr);理解这条编码链后下文将逐一展开排障文档中记载的五个错误码。二、FC3000 ERR_PARAM_INVALIDMatmul 内部入参非法错误描述Matmul 内部入参非法框架内部 Shape、Format 等参数取值不满足约束。该错误在排障文档中标注的“可能原因”为 NA未进一步细分但从源码看它通常由 C 侧对 Shape 维度、Format 组合等的硬性断言触发。源码层面的触发点在 cube_operation_impl.cpp 中ERR_PARAM_INVALID常出现在以下场景输出 Shape 维度不为 2 维或 3 维ASSERT(MatmulErrorCode::ERR_PARAM_INVALID, dstShape.size() SHAPE_DIM2 || dstShape.size() SHAPE_DIM3)输入 Tensor 的 Shape 维度不足 2 维GetShape().size() SHAPE_DIM2内部 Tensor 图tensor graph结构非法ASSERT(MatmulErrorCode::ERR_PARAM_INVALID, false) Invalid tensor graphK 轴 L1 Tile 配置为 0kL1TileShape ! 0。这些断言表明Shape 维度、Format、Tile 配置的任意一项不满足内部约束都可能以 FC3000 呈现。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档逐项核对输入输出是否满足要求。重点检查输入矩阵维度必须为2 维、3 维、4 维且左右矩阵维度需保持一致Format 支持情况TILEOP_ND与TILEOP_NZ注意DT_FP32、DT_FP8E5M2、DT_HF8输入不支持TILEOP_NZ格式调用 matmul 前必须通过pypto.set_cube_tile_shapes设置 M、K、N 轴上的切分大小详见下文前置配置核查一节。若问题仍未解决请访问社区提交 Issue。三、FC3001 ERR_PARAM_MISMATCHMatmul 内部入参不匹配错误描述Matmul 内部入参不匹配框架内部参数之间维度等不一致。源码层面的触发点ERR_PARAM_MISMATCH在 cube_operation_impl.cpp 中与维度一致性强相关典型断言包括ASSERT(MatmulErrorCode::ERR_PARAM_MISMATCH, operandVec.size() operandVecSize) // 操作数个数不匹配 ASSERT(MatmulErrorCode::ERR_PARAM_MISMATCH, kSizeA kSizeB) // 左右矩阵 K 维度不一致 ASSERT(MatmulErrorCode::ERR_PARAM_MISMATCH, gmPartialSums.size() kLoop) // 部分和数量与 K 循环次数不匹配也就是说当左右矩阵的 K 维无法对齐、操作数数量与期望不符、或 GM 累加部分和个数异常时都会抛出 FC3001。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档确认输入输出满足要求。核对要点K 维度一致非转置时左矩阵为[M, K]、右矩阵为[K, N]若设置了a_trans/b_trans则对应排布会交换内外轴需保证转置后 K 维相等左右矩阵维度一致不能出现 2 维 × 3 维的混合输入左右矩阵数据类型必须一致FP8 混合输入除外例如 BF16BF16、FP16FP16不支持 BF16FP32 这类混合输入。若问题仍未解决请访问社区提交 Issue。四、FC3002 ERR_PARAM_UNSUPPORTEDMatmul 内部入参不支持错误描述Matmul 内部入参不支持框架内部使用了不支持的参数组合。可能原因排障文档明确给出了一条已确认的触发原因不满足 scale_tensor 数据类型约束scale_tensor非DT_UINT64/DT_INT64或量化/反量化场景输入、输出数据类型不满足约束DT_INT8输入搭配DT_FP16输出或任意输入搭配DT_INT8输出之外的组合。源码层面的佐证在 matmul.py 中量化和反量化输出类型通过QUANT_OUT_DTYPES表严格校验QUANT_OUT_DTYPES { pypto_impl.DataType.DT_INT8: (pypto_impl.DataType.DT_FP16, pypto_impl.DataType.DT_INT8), pypto_impl.DataType.DT_BF16: (pypto_impl.DataType.DT_INT8,), pypto_impl.DataType.DT_FP16: (pypto_impl.DataType.DT_INT8,), pypto_impl.DataType.DT_FP32: (pypto_impl.DataType.DT_INT8,), ... }一旦传入extend_params中的scale/scale_tensor非零即进入量化/反量化分支out_dtype必须命中上表否则 Python 侧会直接抛出ValueErrorPyptoError 0xF00002该错误在框架内部的对应形态即 FC3002。此外scale_tensor的约束还包括输入固定为uint64_t或int64_t的 Tensor计算时取 64 bit 中低 32 bit 转为 float 参与运算scale_tensor倒数第二维度形状必须置 1且 N 维度需与mat2的 N 维度相等只支持ND格式量化输出为DT_INT8场景时需提前调用torch_npu.npu_trans_quant_param并传入 float32 类型的 torch.tensor以获取 int64 数据类型的scale_tensor。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档重点核对scale_tensor的数据类型、Shape 约束以及量化/反量化场景的数据类型支持表见下文第五节。若问题仍未解决请访问社区提交 Issue。五、与 FC3xxx 强相关的入参约束速查FC3xxx 错误码的排查几乎都归结为入参是否满足 API 约束。以下是两个接口的核心约束摘要完整内容请参阅 pypto.matmul 与 pypto.scaled_mm 文档。5.1 基础场景支持的数据类型pypto.matmulinputmat2out_dtypebias_tensorDT_FP16DT_FP16DT_FP16/DT_FP32DT_FP16/DT_FP32DT_BF16DT_BF16DT_BF16/DT_FP32DT_BF16/DT_FP32DT_FP32DT_FP32DT_FP32DT_FP32DT_INT8DT_INT8DT_INT32DT_INT32DT_FP8E5M2DT_FP8E5M2/DT_FP8E4M3DT_FP16/DT_BF16/DT_FP32DT_FP16/DT_BF16/DT_FP32DT_FP8E4M3DT_FP8E5M2/DT_FP8E4M3DT_FP16/DT_BF16/DT_FP32DT_FP16/DT_BF16/DT_FP32DT_HF8DT_HF8DT_FP16/DT_BF16/DT_FP32DT_FP16/DT_BF16/DT_FP32Python 侧对应的白名单定义在 matmul.py 的INPUT_COMBOS中不在组合内的输入会直接抛错。5.2 反量化与量化场景pypto.matmul反量化场景通过extend_params[scale]或scale_tensor触发DT_INT8 × DT_INT8 → DT_FP16量化场景DT_BF16/DT_FP16/DT_FP32/DT_INT8/DT_FP8E5M2/DT_FP8E4M3/DT_HF8 × 对应类型 → DT_INT8。5.3 scaled_mm 的量化参数 Shape 约束pypto.scaled_mm实现out (mat_a * scale_a) (mat_b * scale_b)的 MX 量化矩阵乘其量化参数 Shape 有严格规则scale_a/scale_b比对应矩阵多 1 维mat_a为 2/3/4 维时scale_a分别为 3/4/5 维记Ks CeilAlign(K, 64) / 64其中CeilAlign(value, align) (value align - 1) / align * align二维场景非转置时scale_a为[M, Ks, 2]、scale_b为[Ks, N, 2]转置时对应为[Ks, M, 2]、[N, Ks, 2]三维、四维场景在二维基础上增加矩阵自身的 Batch 前缀scale_a的每个 Batch 轴必须与mat_a严格相等scale_b同理且矩阵与配对 scale 使用相同的广播索引。这些 Shape 校验在 matmul.py 的__validate_scaled_shape系列函数中逐一实现例如Scale K ! ceil(input K, 64)的 K 维对齐校验。K 不满足 64 对齐、scale 的 M/N 维度与矩阵不一致、末维不为 2都会在 Python 侧或框架内部报出对应参数错误。六、FC5000 ERR_RUNTIME_NULLPTRMatmul 运行时出现空 Tensor错误描述Matmul 运行时错误Matmul 在运行时出现了空 Tensor。可能原因排障文档将可能原因记为 NA但从源码可以明确FC5000 直接对应 C 侧对输入输出 Tensor 存储Storage的非空断言。例如 cube_operation_impl.cppCHECK(MatmulErrorCode::ERR_RUNTIME_NULLPTR, operand1.GetStorage() ! nullptr) A Tensor cannot be null; CHECK(MatmulErrorCode::ERR_RUNTIME_NULLPTR, operand2.GetStorage() ! nullptr) B Tensor cannot be null;scaled_mm场景还会对aScale/bScale做同样检查aScale cannot be nullptr、bScale cannot be nullptr。因此凡是传入 matmul/scaled_mm 的 Tensor含 extend_params 中的 bias_tensor、scale_tensor未完成地址分配均可能触发 FC5000。处理方式确认传入 matmul 接口的输入输出 Tensor 均非空且已完成地址分配确认是否存在 nullptr。排障文档给出了正确示例# 正确示例-输入Tensor均已分配数据 a pypto.tensor([16, 32], pypto.DT_FP16, a) b pypto.tensor([32, 64], pypto.DT_FP16, b) out pypto.matmul(a, b, pypto.DT_FP16)这里的pypto.tensor(...)创建 Tensor 的同时完成数据分配确保 Storage 非空。若问题仍未解决请访问社区提交 Issue。七、FC5002 ERR_RUNTIME_LOGICMatmul 运行时逻辑异常错误描述Matmul 运行时逻辑异常前置校验未通过或计算流程进入异常分支。可能原因排障文档列出的可能原因用户输入未通过合法校验Matmul 内部运行出现了空 Tensor。源码层面的佐证ERR_RUNTIME_LOGIC在 cube_operation_impl.cpp 中常用于操作数检查失败的兜底断言例如CHECK(MatmulErrorCode::ERR_RUNTIME_LOGIC, checkStatus SUCCESS) Matmul operands check failed; CHECK(MatmulErrorCode::ERR_RUNTIME_LOGIC, checkMXStatus SUCCESS) MXMatmul operands check failed;Matmul与MXMatmulscaled_mm 对应的 MX 量化路径分别维护自己的操作数检查流程任何前置合法性检查未通过都会落到该错误码。此外ASSERT(MatmulErrorCode::ERR_RUNTIME_LOGIC, BytesOf(dataType) 0)表明非法数据类型字节数为 0也会进入此分支。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档确认输入输出满足要求重点复检上一节的全部约束项维度一致性、K 维对齐、数据类型组合、Format 支持、量化参数 Shape。若问题仍未解决请访问社区提交 Issue。八、实战排查清单从报错到定位的最小步骤综合排障文档与源码遇到FC3XXX/FC5XXX错误码时建议按以下顺序自检8.1 前置配置核查高频根因是否已调用pypto.set_cube_tile_shapesmatmul/scaled_mm 调用前必须设置 M、K、N 轴切分大小。接口签名见 python/pypto/_controller.pym/k/n均为长度为 2 的列表L1/L0 两级缓存切分例如pypto.set_cube_tile_shapes([128, 128], [128, 128], [128, 128])3 维/4 维矩阵的 vector TileShape矩阵维度为 3 维或 4 维时需要调用pypto.set_vec_tile_shapes设置 vector 的 TileShape 切分如未设置接口内部会默认设置 2 维的vec_tile_shape其值为[128, 128]。NZ 格式与 reshape 场景的 matrix_size调用 matmul 的输入若为pypto.reshape后的 NZ 格式或输入矩阵为 3 维/4 维且数据格式为 NZ需要调用pypto.set_matrix_size设置输入到 matmul 的原始 Shape 的 m、k、n 值。8.2 数据类型与 Format 核查左右矩阵数据类型必须一致FP8 混合除外可对照 5.1 节的数据类型表DT_FP32、DT_FP8E5M2、DT_HF8输入不支持TILEOP_NZ格式对应NZ_UNSUPPORTED_INPUT_DTYPES见 matmul.py输出矩阵目前仅支持ND格式c_matrix_nz当前仅支持False量化/反量化场景的out_dtype必须命中QUANT_OUT_DTYPES表trans_modeTF32 舍入模式仅在左右矩阵与输出均为DT_FP32时支持且 A2/A3 平台不支持仅 Ascend 950 系列支持。枚举取值见 python/src/bindings/enum.cppTransMode.CAST_NONE不转换、CAST_RINT舍入到最近整数中间值舍入到偶数、CAST_ROUND舍入到最近整数中间值远离零舍入。8.3 对齐与 Shape 核查ND 格式下外轴范围为[1, 2^31 - 1]内轴范围为[1, 65535]NZ 格式下Shape 维度需满足内轴 32 字节对齐、外轴 16 元素对齐使用pypto.view接口时传入 View 的 Shape 维度也需满足同样对齐scaled_mm的 K 轴需满足 64 对齐规则Ks CeilAlign(K, 64) / 64scale_a/scale_b的 Batch 前缀、M/N 维度必须与配对矩阵一致末维固定为 2DT_FP4_E2M1量化场景需保证内轴为偶数。8.4 运行时空指针核查确认所有传入接口的 Tensor含bias_tensor、scale_tensor均已通过pypto.tensor完成创建与地址分配排查是否存在把未初始化或None的 Tensor 传入extend_params的情况。九、参考文档与源码索引排障文档本文主题来源docs/zh/guide/appendix/trouble_shooting/matmul.mdAPI 文档pypto.matmul、pypto.scaled_mm、ReLuType、TransMode错误码定义framework/include/tilefwk/error_code.hMatmul 实现与断言framework/src/interface/operation/cube_operation_impl.cppPython 侧入参校验python/pypto/op/matmul.pyTileShape 设置接口python/pypto/_controller.py枚举绑定python/src/bindings/enum.cpp【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CANN PyPTO Matmul 错误码全解FC3000–FC5002 根因定位与排查实战【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto导读PyPTOParallel Tensor/Tile Operation是 CANN 面向昇腾 AI 处理器的张量编程范式其矩阵乘类接口pypto.matmul与pypto.scaled_mm在框架内部校验失败或运行异常时会以FC3XXX/FC5XXX错误码的形式抛出。本文以仓库中的 Matmul 排障文档为核心系统梳理 FC3000、FC3001、FC3002、FC5000、FC5002 五个错误码的触发含义、常见根因与处理步骤并结合 error_code.h 中的错误码定义、matmul.py 中的入参校验逻辑与 cube_operation_impl.cpp 中的运行时断言给出可复现、可对照源码的排查路径帮助开发者在使用 PyPTO 编写矩阵乘 kernel 时快速定位并解决参数与运行时问题。一、错误码体系速览FC 前缀背后的分类规则在深入每个错误码之前先理解 PyPTO 框架错误码的编码规则有助于快速缩小排查范围。错误码定义位于 framework/include/tilefwk/error_code.h源码中的分类注释给出了明确的区间划分// // FCXXXX: OPERATION // FC0-FC2XXX: VECTOR // FC3-FC5XXX: MATMUL // FC6-FC8XXX: CONV // FC9XXX: VIEW OP // 即FC3XXX段0xC3xxx属于Matmul 参数类错误FC5XXX段0xC5xxx属于Matmul 运行时错误。MatmulErrorCode枚举完整定义如下enum class MatmulErrorCode : uint32_t { ERR_PARAM_INVALID 0xC3000U, // FC3000 参数非法 ERR_PARAM_MISMATCH 0xC3001U, // FC3001 参数不匹配 ERR_PARAM_UNSUPPORTED 0xC3002U, // FC3002 参数组合不支持 ERR_CONFIG_TILE 0xC4000U, // FC4000 Tile 配置错误 ERR_CONFIG_ALIGNMENT 0xC4001U, // FC4001 对齐配置错误 ERR_CONFIG_UNSUPPORTED 0xC4002U, // FC4002 配置不支持 ERR_RUNTIME_NULLPTR 0xC5000U, // FC5000 运行时出现空指针/空 Tensor ERR_RUNTIME_STATE 0xC5001U, // FC5001 运行时状态异常 ERR_RUNTIME_LOGIC 0xC5002U, // FC5002 运行时逻辑异常 };可以看到FC3xxx与FC5xxx之间还隔着FC4xxxTile 配置类错误。这些错误码在 C 侧通过ASSERT/CHECK宏触发例如 cube_operation_impl.cpp 中对输入输出 Tensor 指针的空值断言ASSERT(MatmulErrorCode::ERR_RUNTIME_NULLPTR, tensorGraphNodes.aTensorPtr ! nullptr); ASSERT(MatmulErrorCode::ERR_RUNTIME_NULLPTR, tensorGraphNodes.bTensorPtr ! nullptr); ASSERT(MatmulErrorCode::ERR_RUNTIME_NULLPTR, tensorGraphNodes.outTensorPtr ! nullptr);理解这条编码链后下文将逐一展开排障文档中记载的五个错误码。二、FC3000 ERR_PARAM_INVALIDMatmul 内部入参非法错误描述Matmul 内部入参非法框架内部 Shape、Format 等参数取值不满足约束。该错误在排障文档中标注的“可能原因”为 NA未进一步细分但从源码看它通常由 C 侧对 Shape 维度、Format 组合等的硬性断言触发。源码层面的触发点在 cube_operation_impl.cpp 中ERR_PARAM_INVALID常出现在以下场景输出 Shape 维度不为 2 维或 3 维ASSERT(MatmulErrorCode::ERR_PARAM_INVALID, dstShape.size() SHAPE_DIM2 || dstShape.size() SHAPE_DIM3)输入 Tensor 的 Shape 维度不足 2 维GetShape().size() SHAPE_DIM2内部 Tensor 图tensor graph结构非法ASSERT(MatmulErrorCode::ERR_PARAM_INVALID, false) Invalid tensor graphK 轴 L1 Tile 配置为 0kL1TileShape ! 0。这些断言表明Shape 维度、Format、Tile 配置的任意一项不满足内部约束都可能以 FC3000 呈现。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档逐项核对输入输出是否满足要求。重点检查输入矩阵维度必须为2 维、3 维、4 维且左右矩阵维度需保持一致Format 支持情况TILEOP_ND与TILEOP_NZ注意DT_FP32、DT_FP8E5M2、DT_HF8输入不支持TILEOP_NZ格式调用 matmul 前必须通过pypto.set_cube_tile_shapes设置 M、K、N 轴上的切分大小详见下文前置配置核查一节。若问题仍未解决请访问社区提交 Issue。三、FC3001 ERR_PARAM_MISMATCHMatmul 内部入参不匹配错误描述Matmul 内部入参不匹配框架内部参数之间维度等不一致。源码层面的触发点ERR_PARAM_MISMATCH在 cube_operation_impl.cpp 中与维度一致性强相关典型断言包括ASSERT(MatmulErrorCode::ERR_PARAM_MISMATCH, operandVec.size() operandVecSize) // 操作数个数不匹配 ASSERT(MatmulErrorCode::ERR_PARAM_MISMATCH, kSizeA kSizeB) // 左右矩阵 K 维度不一致 ASSERT(MatmulErrorCode::ERR_PARAM_MISMATCH, gmPartialSums.size() kLoop) // 部分和数量与 K 循环次数不匹配也就是说当左右矩阵的 K 维无法对齐、操作数数量与期望不符、或 GM 累加部分和个数异常时都会抛出 FC3001。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档确认输入输出满足要求。核对要点K 维度一致非转置时左矩阵为[M, K]、右矩阵为[K, N]若设置了a_trans/b_trans则对应排布会交换内外轴需保证转置后 K 维相等左右矩阵维度一致不能出现 2 维 × 3 维的混合输入左右矩阵数据类型必须一致FP8 混合输入除外例如 BF16BF16、FP16FP16不支持 BF16FP32 这类混合输入。若问题仍未解决请访问社区提交 Issue。四、FC3002 ERR_PARAM_UNSUPPORTEDMatmul 内部入参不支持错误描述Matmul 内部入参不支持框架内部使用了不支持的参数组合。可能原因排障文档明确给出了一条已确认的触发原因不满足 scale_tensor 数据类型约束scale_tensor非DT_UINT64/DT_INT64或量化/反量化场景输入、输出数据类型不满足约束DT_INT8输入搭配DT_FP16输出或任意输入搭配DT_INT8输出之外的组合。源码层面的佐证在 matmul.py 中量化和反量化输出类型通过QUANT_OUT_DTYPES表严格校验QUANT_OUT_DTYPES { pypto_impl.DataType.DT_INT8: (pypto_impl.DataType.DT_FP16, pypto_impl.DataType.DT_INT8), pypto_impl.DataType.DT_BF16: (pypto_impl.DataType.DT_INT8,), pypto_impl.DataType.DT_FP16: (pypto_impl.DataType.DT_INT8,), pypto_impl.DataType.DT_FP32: (pypto_impl.DataType.DT_INT8,), ... }一旦传入extend_params中的scale/scale_tensor非零即进入量化/反量化分支out_dtype必须命中上表否则 Python 侧会直接抛出ValueErrorPyptoError 0xF00002该错误在框架内部的对应形态即 FC3002。此外scale_tensor的约束还包括输入固定为uint64_t或int64_t的 Tensor计算时取 64 bit 中低 32 bit 转为 float 参与运算scale_tensor倒数第二维度形状必须置 1且 N 维度需与mat2的 N 维度相等只支持ND格式量化输出为DT_INT8场景时需提前调用torch_npu.npu_trans_quant_param并传入 float32 类型的 torch.tensor以获取 int64 数据类型的scale_tensor。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档重点核对scale_tensor的数据类型、Shape 约束以及量化/反量化场景的数据类型支持表见下文第五节。若问题仍未解决请访问社区提交 Issue。五、与 FC3xxx 强相关的入参约束速查FC3xxx 错误码的排查几乎都归结为入参是否满足 API 约束。以下是两个接口的核心约束摘要完整内容请参阅 pypto.matmul 与 pypto.scaled_mm 文档。5.1 基础场景支持的数据类型pypto.matmulinputmat2out_dtypebias_tensorDT_FP16DT_FP16DT_FP16/DT_FP32DT_FP16/DT_FP32DT_BF16DT_BF16DT_BF16/DT_FP32DT_BF16/DT_FP32DT_FP32DT_FP32DT_FP32DT_FP32DT_INT8DT_INT8DT_INT32DT_INT32DT_FP8E5M2DT_FP8E5M2/DT_FP8E4M3DT_FP16/DT_BF16/DT_FP32DT_FP16/DT_BF16/DT_FP32DT_FP8E4M3DT_FP8E5M2/DT_FP8E4M3DT_FP16/DT_BF16/DT_FP32DT_FP16/DT_BF16/DT_FP32DT_HF8DT_HF8DT_FP16/DT_BF16/DT_FP32DT_FP16/DT_BF16/DT_FP32Python 侧对应的白名单定义在 matmul.py 的INPUT_COMBOS中不在组合内的输入会直接抛错。5.2 反量化与量化场景pypto.matmul反量化场景通过extend_params[scale]或scale_tensor触发DT_INT8 × DT_INT8 → DT_FP16量化场景DT_BF16/DT_FP16/DT_FP32/DT_INT8/DT_FP8E5M2/DT_FP8E4M3/DT_HF8 × 对应类型 → DT_INT8。5.3 scaled_mm 的量化参数 Shape 约束pypto.scaled_mm实现out (mat_a * scale_a) (mat_b * scale_b)的 MX 量化矩阵乘其量化参数 Shape 有严格规则scale_a/scale_b比对应矩阵多 1 维mat_a为 2/3/4 维时scale_a分别为 3/4/5 维记Ks CeilAlign(K, 64) / 64其中CeilAlign(value, align) (value align - 1) / align * align二维场景非转置时scale_a为[M, Ks, 2]、scale_b为[Ks, N, 2]转置时对应为[Ks, M, 2]、[N, Ks, 2]三维、四维场景在二维基础上增加矩阵自身的 Batch 前缀scale_a的每个 Batch 轴必须与mat_a严格相等scale_b同理且矩阵与配对 scale 使用相同的广播索引。这些 Shape 校验在 matmul.py 的__validate_scaled_shape系列函数中逐一实现例如Scale K ! ceil(input K, 64)的 K 维对齐校验。K 不满足 64 对齐、scale 的 M/N 维度与矩阵不一致、末维不为 2都会在 Python 侧或框架内部报出对应参数错误。六、FC5000 ERR_RUNTIME_NULLPTRMatmul 运行时出现空 Tensor错误描述Matmul 运行时错误Matmul 在运行时出现了空 Tensor。可能原因排障文档将可能原因记为 NA但从源码可以明确FC5000 直接对应 C 侧对输入输出 Tensor 存储Storage的非空断言。例如 cube_operation_impl.cppCHECK(MatmulErrorCode::ERR_RUNTIME_NULLPTR, operand1.GetStorage() ! nullptr) A Tensor cannot be null; CHECK(MatmulErrorCode::ERR_RUNTIME_NULLPTR, operand2.GetStorage() ! nullptr) B Tensor cannot be null;scaled_mm场景还会对aScale/bScale做同样检查aScale cannot be nullptr、bScale cannot be nullptr。因此凡是传入 matmul/scaled_mm 的 Tensor含 extend_params 中的 bias_tensor、scale_tensor未完成地址分配均可能触发 FC5000。处理方式确认传入 matmul 接口的输入输出 Tensor 均非空且已完成地址分配确认是否存在 nullptr。排障文档给出了正确示例# 正确示例-输入Tensor均已分配数据 a pypto.tensor([16, 32], pypto.DT_FP16, a) b pypto.tensor([32, 64], pypto.DT_FP16, b) out pypto.matmul(a, b, pypto.DT_FP16)这里的pypto.tensor(...)创建 Tensor 的同时完成数据分配确保 Storage 非空。若问题仍未解决请访问社区提交 Issue。七、FC5002 ERR_RUNTIME_LOGICMatmul 运行时逻辑异常错误描述Matmul 运行时逻辑异常前置校验未通过或计算流程进入异常分支。可能原因排障文档列出的可能原因用户输入未通过合法校验Matmul 内部运行出现了空 Tensor。源码层面的佐证ERR_RUNTIME_LOGIC在 cube_operation_impl.cpp 中常用于操作数检查失败的兜底断言例如CHECK(MatmulErrorCode::ERR_RUNTIME_LOGIC, checkStatus SUCCESS) Matmul operands check failed; CHECK(MatmulErrorCode::ERR_RUNTIME_LOGIC, checkMXStatus SUCCESS) MXMatmul operands check failed;Matmul与MXMatmulscaled_mm 对应的 MX 量化路径分别维护自己的操作数检查流程任何前置合法性检查未通过都会落到该错误码。此外ASSERT(MatmulErrorCode::ERR_RUNTIME_LOGIC, BytesOf(dataType) 0)表明非法数据类型字节数为 0也会进入此分支。处理方式查阅 pypto.matmul、pypto.scaled_mm 文档确认输入输出满足要求重点复检上一节的全部约束项维度一致性、K 维对齐、数据类型组合、Format 支持、量化参数 Shape。若问题仍未解决请访问社区提交 Issue。八、实战排查清单从报错到定位的最小步骤综合排障文档与源码遇到FC3XXX/FC5XXX错误码时建议按以下顺序自检8.1 前置配置核查高频根因是否已调用pypto.set_cube_tile_shapesmatmul/scaled_mm 调用前必须设置 M、K、N 轴切分大小。接口签名见 python/pypto/_controller.pym/k/n均为长度为 2 的列表L1/L0 两级缓存切分例如pypto.set_cube_tile_shapes([128, 128], [128, 128], [128, 128])3 维/4 维矩阵的 vector TileShape矩阵维度为 3 维或 4 维时需要调用pypto.set_vec_tile_shapes设置 vector 的 TileShape 切分如未设置接口内部会默认设置 2 维的vec_tile_shape其值为[128, 128]。NZ 格式与 reshape 场景的 matrix_size调用 matmul 的输入若为pypto.reshape后的 NZ 格式或输入矩阵为 3 维/4 维且数据格式为 NZ需要调用pypto.set_matrix_size设置输入到 matmul 的原始 Shape 的 m、k、n 值。8.2 数据类型与 Format 核查左右矩阵数据类型必须一致FP8 混合除外可对照 5.1 节的数据类型表DT_FP32、DT_FP8E5M2、DT_HF8输入不支持TILEOP_NZ格式对应NZ_UNSUPPORTED_INPUT_DTYPES见 matmul.py输出矩阵目前仅支持ND格式c_matrix_nz当前仅支持False量化/反量化场景的out_dtype必须命中QUANT_OUT_DTYPES表trans_modeTF32 舍入模式仅在左右矩阵与输出均为DT_FP32时支持且 A2/A3 平台不支持仅 Ascend 950 系列支持。枚举取值见 python/src/bindings/enum.cppTransMode.CAST_NONE不转换、CAST_RINT舍入到最近整数中间值舍入到偶数、CAST_ROUND舍入到最近整数中间值远离零舍入。8.3 对齐与 Shape 核查ND 格式下外轴范围为[1, 2^31 - 1]内轴范围为[1, 65535]NZ 格式下Shape 维度需满足内轴 32 字节对齐、外轴 16 元素对齐使用pypto.view接口时传入 View 的 Shape 维度也需满足同样对齐scaled_mm的 K 轴需满足 64 对齐规则Ks CeilAlign(K, 64) / 64scale_a/scale_b的 Batch 前缀、M/N 维度必须与配对矩阵一致末维固定为 2DT_FP4_E2M1量化场景需保证内轴为偶数。8.4 运行时空指针核查确认所有传入接口的 Tensor含bias_tensor、scale_tensor均已通过pypto.tensor完成创建与地址分配排查是否存在把未初始化或None的 Tensor 传入extend_params的情况。九、参考文档与源码索引排障文档本文主题来源docs/zh/guide/appendix/trouble_shooting/matmul.mdAPI 文档pypto.matmul、pypto.scaled_mm、ReLuType、TransMode错误码定义framework/include/tilefwk/error_code.hMatmul 实现与断言framework/src/interface/operation/cube_operation_impl.cppPython 侧入参校验python/pypto/op/matmul.pyTileShape 设置接口python/pypto/_controller.py枚举绑定python/src/bindings/enum.cpp【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![Atuin TUI 高级键位绑定完全指南：用 `[keymap]` 定制你的搜索快捷键](http://pic.xiahunao.cn/yaotu/Atuin TUI 高级键位绑定完全指南：用 `[keymap]` 定制你的搜索快捷键)
