PyPTO Vector 算子错误码全解析FC0–FC2XXX从触发场景到排查实战【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto本文以 CANN / PyPTO 开源仓库的 Vector向量算子错误码参考文档为骨架系统讲解 FC0XXX参数校验、FC1XXXTile/对齐配置、FC2XXX运行时三类共 8 个错误码的触发原因、典型错误示例与处理方式并结合仓库源码framework/include/tilefwk/error_code.h、framework/src/interface/operation/、python/pypto/_controller.py等给出底层实现依据。读完本文你将能够在 PyPTO 的 Vector 算子开发与调优中快速定位FC前缀报错按图索骥完成 Shape、dtype、TileShape、对齐约束等问题的修复。一、错误码体系总览读懂 FC 前缀的含义在 PyPTO 中算子接口层会按不同计算域对输入参数、配置与运行时状态做约束校验校验失败时抛出形如FC0XXX / FC1XXX / FC2XXX的错误码。从仓库中的错误码定义文件 framework/include/tilefwk/error_code.h 可以看到完整的编码分区注释// FCXXXX: OPERATION // FC0-FC2XXX: VECTOR // FC3-FC5XXX: MATMUL // FC6-FC8XXX: CONV // FC9XXX: VIEW OP enum class VectorErrorCode : uint32_t { ERR_PARAM_INVALID 0xC0000U, // FC0000 ERR_PARAM_DTYPE_UNSUPPORTED 0xC0001U, // FC0001 ERR_PARAM_SHAPE_DIM_UNSUPPORTED 0xC0002U, // FC0002 ERR_PARAM_COUNT_INVALID 0xC0003U, // FC0003 ERR_CONFIG_TILE 0xC1000U, // FC1000 ERR_CONFIG_ALIGNMENT 0xC1001U, // FC1001 ERR_RUNTIME_NULLPTR 0xC2000U, // FC2000 ERR_RUNTIME_LOGIC 0xC2001U, // FC2001 };由此可以提炼出三条规律中间一位表示错误类别FC0XXX为参数Param类、FC1XXX为配置Config类、FC2XXX为运行时Runtime类错误属于哪个计算域由首位决定Vector 占FC0–FC2Matmul 占FC3–FC5Conv 占FC6–FC8View 算子为FC9。因此看到FC3XXX时应优先排查 matmul 类算子如pypto.matmul而不是 Vector 算子同类错误在不同计算域有独立的枚举值例如 Matmul 的ERR_PARAM_INVALID是0xC3000U与 Vector 的0xC0000U并不相同排查时需要先确认报错算子的归属。下表汇总了 Vector 域全部错误码的速查信息详情见各小节错误码枚举名错误类别一句话定位FC0000ERR_PARAM_INVALID参数校验Shape 越界空 Tensor / 超 INT32_MAX、归约轴越界FC0001ERR_PARAM_DTYPE_UNSUPPORTED参数校验dtype 不被算子支持或二元运算两输入 dtype 不一致FC0002ERR_PARAM_SHAPE_DIM_UNSUPPORTED参数校验维度数超出算子支持范围如超过 4 维或多输入维度数不一致FC0003ERR_PARAM_COUNT_INVALID参数校验输入/输出操作数个数与算子预期不符FC1000ERR_CONFIG_TILE配置校验set_vec_tile_shapes设置的 TileShape 非法FC1001ERR_CONFIG_ALIGNMENT配置校验地址或 Shape 未满足硬件对齐要求如尾轴 32 字节对齐FC2000ERR_RUNTIME_NULLPTR运行时传入 Tensor 为空指针FC2001ERR_RUNTIME_LOGIC运行时计算流程进入未定义或异常分支注意本文所有约束均针对 Vector 算子且以当前仓库文档描述为准。set_vec_tile_shapes等能力支持的产品范围如 Ascend 950PR/950DT、Atlas A3、Atlas A2 等可参见 pypto.set_vec_tile_shapes 的产品支持情况说明。二、FC0XXX 参数校验类错误FC0 段错误发生在算子接口层对输入参数Shape、dtype、维度、操作数个数做静态校验的阶段。从源码结构看这类校验大量集中在framework/src/interface/operation/目录如 operation_impl.cpp、各 vector 算子实现文件并通过ASSERT/CHECK宏抛出对应错误码因此多数情况下在编译/建图阶段即可暴露无需真正上板运行。2.1 FC0000 ERR_PARAM_INVALID入参非法错误描述Vector 入参非法错误如参数取值、维度、格式等不满足约束。可能原因与示例1不满足 Shape 约束输入输出 Tensor 为空 Tensor某维度为 0或 Shape Size 大于2147483647即INT32_MAX。# 错误示例 - Shape Size 大于 INT32_MAX a pypto.tensor([65536, 65536], pypto.DT_FP16) # 65536*65536 INT32_MAX b pypto.tensor([65536, 65536], pypto.DT_FP16) out pypto.pow(a, b) # 触发 ERR_PARAM_INVALID2不满足归约轴约束归约类算子如amax的dim超出输入维度范围。# 错误示例 - amax 的 dim 超出输入维度范围 x pypto.tensor([2, 3], pypto.DT_FP32) # 2 维 out pypto.amax(x, 2) # dim2 越界仅支持 0、1 或负索引处理方式查阅对应算子文档如 pypto.add、pypto.sin、pypto.cast、pypto.amax确认输入输出 Shape、维度等满足要求。例如 pypto.amax 明确约束不支持空 TensorShape 仅支持 1-4 维Shape Size 不大于 2147483647。# 正确示例 - 输入为 2 维 Tensor a pypto.tensor([4, 4], pypto.DT_FP16) b pypto.tensor([4, 4], pypto.DT_FP16) out pypto.add(a, b)若问题仍未解决请访问社区提交 Issue。源码佐证在 operation_impl.cpp 中可以看到ASSERT(VectorErrorCode::ERR_PARAM_INVALID, operand-shape.size() operand-offset.size())这类对操作数 Shape 与偏移一致性的校验归约类算子如 reduction.cpp则会在归约轴合法性检查中抛出该错误码。可以推断FC0000是 Vector 算子参数校验中最基础、最常见的兜底错误码。2.2 FC0001 ERR_PARAM_DTYPE_UNSUPPORTED数据类型不支持错误描述Vector 入参数据类型不支持使用了当前算子或硬件不支持的 dtype。可能原因与示例1不满足算子数据类型约束输入 dtype 不在该算子支持集合内。各算子支持的数据类型详见对应算子文档。例如 pypto.sin 仅支持DT_FP32 / DT_FP16# 错误示例 - sin 仅支持 DT_FP32/DT_FP16传入 sin 不支持的 DT_INT64 x pypto.tensor([4], pypto.DT_INT64) out pypto.sin(x) # 触发 ERR_PARAM_DTYPE_UNSUPPORTED2不满足输入数据类型一致性约束二元运算两输入 Tensor 数据类型不一致# 错误示例 - 两输入数据类型不一致DT_FP16 DT_FP32 a pypto.tensor([4, 4], pypto.DT_FP16) b pypto.tensor([4, 4], pypto.DT_FP32) out pypto.add(a, b)处理方式查阅对应算子文档如 pypto.add、pypto.sin、pypto.cast确认输入输出数据类型满足要求切换为兼容的数据类型重试。# 正确示例 - sin 使用支持的 DT_FP32 x pypto.tensor([4], pypto.DT_FP32) out pypto.sin(x)若问题仍未解决请访问社区提交 Issue。源码佐证dtype 校验在 Vector 算子实现中非常普遍。例如 binary_scalar.cpp 中的CHECK(VectorErrorCode::ERR_PARAM_DTYPE_UNSUPPORTED, other.GetDataType() self.GetDataType())即对应二元运算两输入 dtype 必须一致的约束cast.cpp 在遇到不支持的源/目标类型组合时也会直接CHECK(..., false)抛出该错误码。不同算子的 dtype 支持集合还因硬件平台而异详见各算子文档的约束说明。2.3 FC0002 ERR_PARAM_SHAPE_DIM_UNSUPPORTEDShape 维度不支持错误描述Vector 入参 Shape 维度不支持输入输出 Tensor 的维度数不在算子支持的范围内或多输入间维度数不一致。可能原因与示例1不满足维度数约束输入输出 Tensor 的维度数不在算子支持的范围内如多数 Vector 算子仅支持 1-4 维。# 错误示例 - 输入为 5 维超过 Vector 支持的 1-4 维范围 a pypto.tensor([2, 2, 2, 2, 2], pypto.DT_FP16) # 5 维 b pypto.tensor([2, 2, 2, 2, 2], pypto.DT_FP16) out pypto.pow(a, b) # 触发 ERR_PARAM_SHAPE_DIM_UNSUPPORTED2不满足多输入维度一致性约束参与运算的多个 Tensor 维度数不一致。# 错误示例 - 两输入维度数不一致2 维与 3 维 a pypto.tensor([4, 4], pypto.DT_FP16) # 2 维 b pypto.tensor([2, 4, 4], pypto.DT_FP16) # 3 维 out pypto.pow(a, b)处理方式查阅对应算子文档如 pypto.pow、pypto.gcd、pypto.amax确认支持的维度范围并保证各输入 Tensor 维度数一致且在范围内。# 正确示例 - 输入为 2 维 Tensor 且维度数一致 a pypto.tensor([4, 4], pypto.DT_FP16) b pypto.tensor([4, 4], pypto.DT_FP16) out pypto.pow(a, b)若问题仍未解决请访问社区提交 Issue。源码佐证维度数上限校验在算子实现中可见一斑例如 gather.cpp 中CHECK(VectorErrorCode::ERR_PARAM_SHAPE_DIM_UNSUPPORTED, result-shape.size() NUM_VALUE_5)与indices-shape.size() NUM_VALUE_2dequantize.cpp、quantize.cpp 等量化算子同样对输入维度做了类似约束。可以看到维度数上限是每个算子自行声明的因此排查时应以具体算子文档为准而不是假定所有 Vector 算子都统一支持 4 维。2.4 FC0003 ERR_PARAM_COUNT_INVALID操作数个数非法错误描述Vector 入参操作数operand个数非法算子在执行或输出 shape 推导时检测到输入/输出操作数个数与预期不符。可能原因不满足操作数个数约束传入算子的输入/输出操作数个数与该算子预期不符错误日志通常形如iOperands.size() should be ...。多见于调用方式与算子文档要求的输入输出个数不一致或框架内部算子接线错误。处理方式对照打屏日志中的操作数期望个数查阅对应算子文档如 pypto.scatter_、pypto.concat、pypto.where确认输入输出个数与调用方式匹配。例如pypto.where(condition, x, y)需要三个输入若只传入两个就会触发本错误码。若调用方式正确仍报此错疑似框架内部接线问题请访问社区提交 Issue。源码佐证从 operation_impl.cpp 等实现看框架会对操作数个数做显式断言如ASSERT(VectorErrorCode::ERR_PARAM_INVALID, iOperand.size() 1 oOperand.size() NUM_VALUE_5)。这类断言中的iOperands.size()/oOperands.size()就是打屏日志中期望值的来源。三、FC1XXX 配置类错误TileShape 与对齐FC1 段错误与切分配置强相关Vector 算子在昇腾硬件上运行时数据会被切分为一个个 Tile分块放入向量单元处理切分方式由set_vec_tile_shapes配置。配置不合法或与硬件对齐要求冲突时即抛出 FC1XXX。3.1 FC1000 ERR_CONFIG_TILETile 配置非法错误描述Vector 切分Tile配置非法。可能原因与示例1不满足 Tile 值约束set_vec_tile_shapes传入的某维度小于等于 0。# 错误示例 - TileShape 第二维为 0 pypto.set_vec_tile_shapes(4, 0) # 每个维度必须大于 0 a pypto.tensor([4, 16], pypto.DT_FP16) out pypto.sin(a)2不满足 TileShape 维度数量约束set_vec_tile_shapes传入的维度数超过 4 个。# 错误示例 - TileShape 超过 4 个维度 pypto.set_vec_tile_shapes(1, 1, 1, 1, 1) # 最多不超过 4 个维度3不满足 TileShape 大小约束set_vec_tile_shapes设置超过该算子的 TileShape 大小约束。例如 pypto.amax 的约束说明中写明TileShape 大小不超过 64KB# 错误示例 - amax 的 TileShape 超过 64KB pypto.set_vec_tile_shapes(1024, 1024) # FP16 下 1024*1024*2Byte2MB超过 64KB x pypto.tensor([1024, 1024], pypto.DT_FP16) out pypto.amax(x, -1, True)4不满足 TileShape 维度一致性约束TileShape 维度数与输出或输入Tensor 维度数不匹配。# 错误示例 - TileShape 维度与输入维度不一致 pypto.set_vec_tile_shapes(4, 16) # 2 维 TileShape a pypto.tensor([2, 2, 2, 2], pypto.DT_FP16) # 4 维输入 out pypto.add(a, a)处理方式查阅 pypto.set_vec_tile_shapes 及对应算子文档确认 TileShape 取值满足要求。该 API 的函数原型为set_vec_tile_shapes(*args: int) - None约束为每个维度必须大于 0维度数最多不超过 4 个。调用 pypto.set_vec_tile_shapes 前确认各维度均为正数、维度数不超过 4且与输出维度一致。# 正确示例 - TileShape 各维度为正且与输入维度一致 pypto.set_vec_tile_shapes(4, 16) a pypto.tensor([4, 16], pypto.DT_FP16) out pypto.sin(a)通过 pypto.get_vec_tile_shapes 回读实际生效的 TileShape核对是否符合切分约束pypto.set_vec_tile_shapes(4, 16) tile_shape_info pypto.get_vec_tile_shapes() print(tile_shape_info) # 输出[4, 16]若问题仍未解决请访问社区提交 Issue。源码佐证set_vec_tile_shapes/get_vec_tile_shapes的 Python 入口定义在 python/pypto/_controller.pyset_vec_tile_shapes会将各维度数值写入当前作用域pypto_impl.SetScope({vec_tile_shapes: concrete_shapes})get_vec_tile_shapes则从当前作用域回读。也就是说TileShape 是按作用域scope生效的配置切换作用域后需要重新设置。在框架侧operation_impl.cpp 对 Tile 配置做了校验例如ASSERT(VectorErrorCode::ERR_CONFIG_TILE, vecTile.size() viewShape.size()); ASSERT(VectorErrorCode::ERR_CONFIG_TILE, viewShape[0] vecTile[0]);即TileShape 维度数必须不少于 view 维度数、且各轴切分粒度不能大于对应轴长度这就是第4类维度不一致问题在底层的直接体现。补充set_vec_tile_shapes的官方调用示例为pypto.set_vec_tile_shapes(1, 1, 8, 8)常见于 4 维 Tensor 的切分场景对于 2 维 Tensor 通常传 2 个参数即可如pypto.set_vec_tile_shapes(4, 16)。3.2 FC1001 ERR_CONFIG_ALIGNMENT对齐约束不满足错误描述Vector 对齐约束不满足地址或 shape 未按硬件要求对齐。可能原因不满足尾轴对齐约束不满足算子如amax尾轴 32 字节对齐的约束。# 错误示例 - amax 尾轴未 32 字节对齐 pypto.set_vec_tile_shapes(4, 10) # FP16 下 10*2Byte20Byte非 32 字节对齐 x pypto.tensor([4, 10], pypto.DT_FP16) out pypto.amax(x, -1, True)处理方式查阅对应算子文档如 pypto.amax及 pypto.set_vec_tile_shapes 确认对齐要求。关注 reshape/view、交换维度转置等是否改变内轴对齐要求必要时调整 Tensor 形状或 TileShape 取值。例如 FP16 下尾轴 16 个元素恰好 32 字节# 正确示例 - amax 尾轴 32 字节对齐FP16 下 16 元素 pypto.set_vec_tile_shapes(4, 16) x pypto.tensor([4, 16], pypto.DT_FP16) out pypto.amax(x, -1, True)若问题仍未解决请访问社区提交 Issue。源码佐证对齐校验在 Vector 算子实现中非常常见且不同算子的对齐粒度不一sort.cppCHECK(VectorErrorCode::ERR_CONFIG_ALIGNMENT, vecTileShape[axis] % NUM_VALUE_32 0)尾轴按 32 的倍数对齐compare.cppCHECK(VectorErrorCode::ERR_CONFIG_ALIGNMENT, resultShape.empty() || resultShape.back() % NUM_VALUE_8 0)比较类算子尾轴元素数按 8 对齐FP32 下即 32 字节where.cpp对tileShape尾轴及存储 shape 尾轴做位宽取整校验。从这些实现可以看出尾轴对齐本质是向量单元按整块取数的硬件要求尾轴字节数必须是硬件存取粒度的整数倍。因此尾轴长度而非总元素数是对齐的关键reshape/view/转置改变尾轴归属后原本合法的 Tensor 也可能变得不合法。四、FC2XXX 运行时类错误FC2 段错误发生在实际执行阶段通常与 Tensor 生命周期、计算流程状态有关而非静态参数。4.1 FC2000 ERR_RUNTIME_NULLPTR运行时空指针错误描述Vector 运行时空指针传入的 Tensor 为空。可能原因NA文档未给出具体原因通常与 Tensor 未分配地址或生命周期管理不当有关。处理方式确认传入 Vector 接口的输入输出 Tensor 均非空且已完成地址分配确认是否存在nullptr# 正确示例 - 输入 Tensor 均已分配数据 a pypto.tensor([16, 32], pypto.DT_FP16, a) b pypto.tensor([16, 32], pypto.DT_FP16, b) out pypto.add(a, b)若问题仍未解决请访问社区提交 Issue。提示上面的示例为 Tensor 显式命名并构造第三个参数为 Tensor 名称。实战中若 Tensor 来自其他算子的输出应确认上游算子已正常执行完成、输出地址已有效分配再传入下游 Vector 算子。4.2 FC2001 ERR_RUNTIME_LOGIC运行时逻辑错误错误描述Vector 运行时逻辑错误计算流程进入未定义或异常分支。可能原因NA文档未给出具体原因属于兜底性运行时错误。处理方式通过相关日志定位异常路径核对计算流程是否进入未定义/异常分支确认中间结果、索引值是否符合预期。例如 index_add.cpp 中CHECK(VectorErrorCode::ERR_RUNTIME_LOGIC, false)表明代码走到了预期不该到达的分支compare.cpp 也会在元素大小为 0 时抛出该错误码并提示Element size cannot be zero.。检查核心计算逻辑的前置条件如 TileShape 设置、上下文与配置句柄初始化是否满足。若问题仍未解决请访问社区提交 Issue。五、通用排查方法论与最佳实践综合以上 8 个错误码可以沉淀出一套针对 PyPTO Vector 算子的通用排查流程先分类再定位根据错误码中间位判断是参数FC0、配置FC1还是运行时FC2问题根据首位判断是否属于 Vector 域FC0–FC2避免去 matmul/conv 文档里找答案。对照算子文档核对约束每个算子的文档如 pypto-add、pypto-pow、pypto-amax都会列出 dtype 支持集合、Shape 维度范围、Shape Size 上限INT32_MAX、TileShape 大小上限如 64KB等约束这是排查 FC0XXX 的第一依据。围绕 TileShape 检查 FC1XXX确认set_vec_tile_shapes各维为正、维度数 ≤ 4、与输入/输出维度一致、总大小不超算子上限、尾轴满足对齐要求FP16 按 16 元素 / FP32 按 8 元素即 32 字节对齐用 pypto.get_vec_tile_shapes 回读实际生效值。警惕隐式改变布局的操作reshape/view、转置transpose/permute会改变尾轴的归属进而改变对齐与切分语义。执行这类操作后建议重新审视并重设 TileShape。运行时报错检查生命周期确认所有输入输出 Tensor 均已分配有效地址、上游算子执行完成、上下文与配置句柄已正确初始化。保留可复现脚本提交 Issue 时附上最小可复现代码、打屏日志尤其是iOperands.size() should be ...这类带期望值的日志与算子文档版本便于社区快速定位。最后建议开发者在使用 Vector 算子前通读 docs/zh/guide/appendix/trouble_shooting/index.md 中的错误码参考索引将本类错误码作为日常开发时的查错字典遇到FC报错先查本文对应小节再结合算子文档与上述排查流程即可在绝大多数场景下自行定位并修复问题。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyPTO Vector 算子错误码全解析（FC0–FC2XXX）：从触发场景到排查实战
PyPTO Vector 算子错误码全解析FC0–FC2XXX从触发场景到排查实战【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto本文以 CANN / PyPTO 开源仓库的 Vector向量算子错误码参考文档为骨架系统讲解 FC0XXX参数校验、FC1XXXTile/对齐配置、FC2XXX运行时三类共 8 个错误码的触发原因、典型错误示例与处理方式并结合仓库源码framework/include/tilefwk/error_code.h、framework/src/interface/operation/、python/pypto/_controller.py等给出底层实现依据。读完本文你将能够在 PyPTO 的 Vector 算子开发与调优中快速定位FC前缀报错按图索骥完成 Shape、dtype、TileShape、对齐约束等问题的修复。一、错误码体系总览读懂 FC 前缀的含义在 PyPTO 中算子接口层会按不同计算域对输入参数、配置与运行时状态做约束校验校验失败时抛出形如FC0XXX / FC1XXX / FC2XXX的错误码。从仓库中的错误码定义文件 framework/include/tilefwk/error_code.h 可以看到完整的编码分区注释// FCXXXX: OPERATION // FC0-FC2XXX: VECTOR // FC3-FC5XXX: MATMUL // FC6-FC8XXX: CONV // FC9XXX: VIEW OP enum class VectorErrorCode : uint32_t { ERR_PARAM_INVALID 0xC0000U, // FC0000 ERR_PARAM_DTYPE_UNSUPPORTED 0xC0001U, // FC0001 ERR_PARAM_SHAPE_DIM_UNSUPPORTED 0xC0002U, // FC0002 ERR_PARAM_COUNT_INVALID 0xC0003U, // FC0003 ERR_CONFIG_TILE 0xC1000U, // FC1000 ERR_CONFIG_ALIGNMENT 0xC1001U, // FC1001 ERR_RUNTIME_NULLPTR 0xC2000U, // FC2000 ERR_RUNTIME_LOGIC 0xC2001U, // FC2001 };由此可以提炼出三条规律中间一位表示错误类别FC0XXX为参数Param类、FC1XXX为配置Config类、FC2XXX为运行时Runtime类错误属于哪个计算域由首位决定Vector 占FC0–FC2Matmul 占FC3–FC5Conv 占FC6–FC8View 算子为FC9。因此看到FC3XXX时应优先排查 matmul 类算子如pypto.matmul而不是 Vector 算子同类错误在不同计算域有独立的枚举值例如 Matmul 的ERR_PARAM_INVALID是0xC3000U与 Vector 的0xC0000U并不相同排查时需要先确认报错算子的归属。下表汇总了 Vector 域全部错误码的速查信息详情见各小节错误码枚举名错误类别一句话定位FC0000ERR_PARAM_INVALID参数校验Shape 越界空 Tensor / 超 INT32_MAX、归约轴越界FC0001ERR_PARAM_DTYPE_UNSUPPORTED参数校验dtype 不被算子支持或二元运算两输入 dtype 不一致FC0002ERR_PARAM_SHAPE_DIM_UNSUPPORTED参数校验维度数超出算子支持范围如超过 4 维或多输入维度数不一致FC0003ERR_PARAM_COUNT_INVALID参数校验输入/输出操作数个数与算子预期不符FC1000ERR_CONFIG_TILE配置校验set_vec_tile_shapes设置的 TileShape 非法FC1001ERR_CONFIG_ALIGNMENT配置校验地址或 Shape 未满足硬件对齐要求如尾轴 32 字节对齐FC2000ERR_RUNTIME_NULLPTR运行时传入 Tensor 为空指针FC2001ERR_RUNTIME_LOGIC运行时计算流程进入未定义或异常分支注意本文所有约束均针对 Vector 算子且以当前仓库文档描述为准。set_vec_tile_shapes等能力支持的产品范围如 Ascend 950PR/950DT、Atlas A3、Atlas A2 等可参见 pypto.set_vec_tile_shapes 的产品支持情况说明。二、FC0XXX 参数校验类错误FC0 段错误发生在算子接口层对输入参数Shape、dtype、维度、操作数个数做静态校验的阶段。从源码结构看这类校验大量集中在framework/src/interface/operation/目录如 operation_impl.cpp、各 vector 算子实现文件并通过ASSERT/CHECK宏抛出对应错误码因此多数情况下在编译/建图阶段即可暴露无需真正上板运行。2.1 FC0000 ERR_PARAM_INVALID入参非法错误描述Vector 入参非法错误如参数取值、维度、格式等不满足约束。可能原因与示例1不满足 Shape 约束输入输出 Tensor 为空 Tensor某维度为 0或 Shape Size 大于2147483647即INT32_MAX。# 错误示例 - Shape Size 大于 INT32_MAX a pypto.tensor([65536, 65536], pypto.DT_FP16) # 65536*65536 INT32_MAX b pypto.tensor([65536, 65536], pypto.DT_FP16) out pypto.pow(a, b) # 触发 ERR_PARAM_INVALID2不满足归约轴约束归约类算子如amax的dim超出输入维度范围。# 错误示例 - amax 的 dim 超出输入维度范围 x pypto.tensor([2, 3], pypto.DT_FP32) # 2 维 out pypto.amax(x, 2) # dim2 越界仅支持 0、1 或负索引处理方式查阅对应算子文档如 pypto.add、pypto.sin、pypto.cast、pypto.amax确认输入输出 Shape、维度等满足要求。例如 pypto.amax 明确约束不支持空 TensorShape 仅支持 1-4 维Shape Size 不大于 2147483647。# 正确示例 - 输入为 2 维 Tensor a pypto.tensor([4, 4], pypto.DT_FP16) b pypto.tensor([4, 4], pypto.DT_FP16) out pypto.add(a, b)若问题仍未解决请访问社区提交 Issue。源码佐证在 operation_impl.cpp 中可以看到ASSERT(VectorErrorCode::ERR_PARAM_INVALID, operand-shape.size() operand-offset.size())这类对操作数 Shape 与偏移一致性的校验归约类算子如 reduction.cpp则会在归约轴合法性检查中抛出该错误码。可以推断FC0000是 Vector 算子参数校验中最基础、最常见的兜底错误码。2.2 FC0001 ERR_PARAM_DTYPE_UNSUPPORTED数据类型不支持错误描述Vector 入参数据类型不支持使用了当前算子或硬件不支持的 dtype。可能原因与示例1不满足算子数据类型约束输入 dtype 不在该算子支持集合内。各算子支持的数据类型详见对应算子文档。例如 pypto.sin 仅支持DT_FP32 / DT_FP16# 错误示例 - sin 仅支持 DT_FP32/DT_FP16传入 sin 不支持的 DT_INT64 x pypto.tensor([4], pypto.DT_INT64) out pypto.sin(x) # 触发 ERR_PARAM_DTYPE_UNSUPPORTED2不满足输入数据类型一致性约束二元运算两输入 Tensor 数据类型不一致# 错误示例 - 两输入数据类型不一致DT_FP16 DT_FP32 a pypto.tensor([4, 4], pypto.DT_FP16) b pypto.tensor([4, 4], pypto.DT_FP32) out pypto.add(a, b)处理方式查阅对应算子文档如 pypto.add、pypto.sin、pypto.cast确认输入输出数据类型满足要求切换为兼容的数据类型重试。# 正确示例 - sin 使用支持的 DT_FP32 x pypto.tensor([4], pypto.DT_FP32) out pypto.sin(x)若问题仍未解决请访问社区提交 Issue。源码佐证dtype 校验在 Vector 算子实现中非常普遍。例如 binary_scalar.cpp 中的CHECK(VectorErrorCode::ERR_PARAM_DTYPE_UNSUPPORTED, other.GetDataType() self.GetDataType())即对应二元运算两输入 dtype 必须一致的约束cast.cpp 在遇到不支持的源/目标类型组合时也会直接CHECK(..., false)抛出该错误码。不同算子的 dtype 支持集合还因硬件平台而异详见各算子文档的约束说明。2.3 FC0002 ERR_PARAM_SHAPE_DIM_UNSUPPORTEDShape 维度不支持错误描述Vector 入参 Shape 维度不支持输入输出 Tensor 的维度数不在算子支持的范围内或多输入间维度数不一致。可能原因与示例1不满足维度数约束输入输出 Tensor 的维度数不在算子支持的范围内如多数 Vector 算子仅支持 1-4 维。# 错误示例 - 输入为 5 维超过 Vector 支持的 1-4 维范围 a pypto.tensor([2, 2, 2, 2, 2], pypto.DT_FP16) # 5 维 b pypto.tensor([2, 2, 2, 2, 2], pypto.DT_FP16) out pypto.pow(a, b) # 触发 ERR_PARAM_SHAPE_DIM_UNSUPPORTED2不满足多输入维度一致性约束参与运算的多个 Tensor 维度数不一致。# 错误示例 - 两输入维度数不一致2 维与 3 维 a pypto.tensor([4, 4], pypto.DT_FP16) # 2 维 b pypto.tensor([2, 4, 4], pypto.DT_FP16) # 3 维 out pypto.pow(a, b)处理方式查阅对应算子文档如 pypto.pow、pypto.gcd、pypto.amax确认支持的维度范围并保证各输入 Tensor 维度数一致且在范围内。# 正确示例 - 输入为 2 维 Tensor 且维度数一致 a pypto.tensor([4, 4], pypto.DT_FP16) b pypto.tensor([4, 4], pypto.DT_FP16) out pypto.pow(a, b)若问题仍未解决请访问社区提交 Issue。源码佐证维度数上限校验在算子实现中可见一斑例如 gather.cpp 中CHECK(VectorErrorCode::ERR_PARAM_SHAPE_DIM_UNSUPPORTED, result-shape.size() NUM_VALUE_5)与indices-shape.size() NUM_VALUE_2dequantize.cpp、quantize.cpp 等量化算子同样对输入维度做了类似约束。可以看到维度数上限是每个算子自行声明的因此排查时应以具体算子文档为准而不是假定所有 Vector 算子都统一支持 4 维。2.4 FC0003 ERR_PARAM_COUNT_INVALID操作数个数非法错误描述Vector 入参操作数operand个数非法算子在执行或输出 shape 推导时检测到输入/输出操作数个数与预期不符。可能原因不满足操作数个数约束传入算子的输入/输出操作数个数与该算子预期不符错误日志通常形如iOperands.size() should be ...。多见于调用方式与算子文档要求的输入输出个数不一致或框架内部算子接线错误。处理方式对照打屏日志中的操作数期望个数查阅对应算子文档如 pypto.scatter_、pypto.concat、pypto.where确认输入输出个数与调用方式匹配。例如pypto.where(condition, x, y)需要三个输入若只传入两个就会触发本错误码。若调用方式正确仍报此错疑似框架内部接线问题请访问社区提交 Issue。源码佐证从 operation_impl.cpp 等实现看框架会对操作数个数做显式断言如ASSERT(VectorErrorCode::ERR_PARAM_INVALID, iOperand.size() 1 oOperand.size() NUM_VALUE_5)。这类断言中的iOperands.size()/oOperands.size()就是打屏日志中期望值的来源。三、FC1XXX 配置类错误TileShape 与对齐FC1 段错误与切分配置强相关Vector 算子在昇腾硬件上运行时数据会被切分为一个个 Tile分块放入向量单元处理切分方式由set_vec_tile_shapes配置。配置不合法或与硬件对齐要求冲突时即抛出 FC1XXX。3.1 FC1000 ERR_CONFIG_TILETile 配置非法错误描述Vector 切分Tile配置非法。可能原因与示例1不满足 Tile 值约束set_vec_tile_shapes传入的某维度小于等于 0。# 错误示例 - TileShape 第二维为 0 pypto.set_vec_tile_shapes(4, 0) # 每个维度必须大于 0 a pypto.tensor([4, 16], pypto.DT_FP16) out pypto.sin(a)2不满足 TileShape 维度数量约束set_vec_tile_shapes传入的维度数超过 4 个。# 错误示例 - TileShape 超过 4 个维度 pypto.set_vec_tile_shapes(1, 1, 1, 1, 1) # 最多不超过 4 个维度3不满足 TileShape 大小约束set_vec_tile_shapes设置超过该算子的 TileShape 大小约束。例如 pypto.amax 的约束说明中写明TileShape 大小不超过 64KB# 错误示例 - amax 的 TileShape 超过 64KB pypto.set_vec_tile_shapes(1024, 1024) # FP16 下 1024*1024*2Byte2MB超过 64KB x pypto.tensor([1024, 1024], pypto.DT_FP16) out pypto.amax(x, -1, True)4不满足 TileShape 维度一致性约束TileShape 维度数与输出或输入Tensor 维度数不匹配。# 错误示例 - TileShape 维度与输入维度不一致 pypto.set_vec_tile_shapes(4, 16) # 2 维 TileShape a pypto.tensor([2, 2, 2, 2], pypto.DT_FP16) # 4 维输入 out pypto.add(a, a)处理方式查阅 pypto.set_vec_tile_shapes 及对应算子文档确认 TileShape 取值满足要求。该 API 的函数原型为set_vec_tile_shapes(*args: int) - None约束为每个维度必须大于 0维度数最多不超过 4 个。调用 pypto.set_vec_tile_shapes 前确认各维度均为正数、维度数不超过 4且与输出维度一致。# 正确示例 - TileShape 各维度为正且与输入维度一致 pypto.set_vec_tile_shapes(4, 16) a pypto.tensor([4, 16], pypto.DT_FP16) out pypto.sin(a)通过 pypto.get_vec_tile_shapes 回读实际生效的 TileShape核对是否符合切分约束pypto.set_vec_tile_shapes(4, 16) tile_shape_info pypto.get_vec_tile_shapes() print(tile_shape_info) # 输出[4, 16]若问题仍未解决请访问社区提交 Issue。源码佐证set_vec_tile_shapes/get_vec_tile_shapes的 Python 入口定义在 python/pypto/_controller.pyset_vec_tile_shapes会将各维度数值写入当前作用域pypto_impl.SetScope({vec_tile_shapes: concrete_shapes})get_vec_tile_shapes则从当前作用域回读。也就是说TileShape 是按作用域scope生效的配置切换作用域后需要重新设置。在框架侧operation_impl.cpp 对 Tile 配置做了校验例如ASSERT(VectorErrorCode::ERR_CONFIG_TILE, vecTile.size() viewShape.size()); ASSERT(VectorErrorCode::ERR_CONFIG_TILE, viewShape[0] vecTile[0]);即TileShape 维度数必须不少于 view 维度数、且各轴切分粒度不能大于对应轴长度这就是第4类维度不一致问题在底层的直接体现。补充set_vec_tile_shapes的官方调用示例为pypto.set_vec_tile_shapes(1, 1, 8, 8)常见于 4 维 Tensor 的切分场景对于 2 维 Tensor 通常传 2 个参数即可如pypto.set_vec_tile_shapes(4, 16)。3.2 FC1001 ERR_CONFIG_ALIGNMENT对齐约束不满足错误描述Vector 对齐约束不满足地址或 shape 未按硬件要求对齐。可能原因不满足尾轴对齐约束不满足算子如amax尾轴 32 字节对齐的约束。# 错误示例 - amax 尾轴未 32 字节对齐 pypto.set_vec_tile_shapes(4, 10) # FP16 下 10*2Byte20Byte非 32 字节对齐 x pypto.tensor([4, 10], pypto.DT_FP16) out pypto.amax(x, -1, True)处理方式查阅对应算子文档如 pypto.amax及 pypto.set_vec_tile_shapes 确认对齐要求。关注 reshape/view、交换维度转置等是否改变内轴对齐要求必要时调整 Tensor 形状或 TileShape 取值。例如 FP16 下尾轴 16 个元素恰好 32 字节# 正确示例 - amax 尾轴 32 字节对齐FP16 下 16 元素 pypto.set_vec_tile_shapes(4, 16) x pypto.tensor([4, 16], pypto.DT_FP16) out pypto.amax(x, -1, True)若问题仍未解决请访问社区提交 Issue。源码佐证对齐校验在 Vector 算子实现中非常常见且不同算子的对齐粒度不一sort.cppCHECK(VectorErrorCode::ERR_CONFIG_ALIGNMENT, vecTileShape[axis] % NUM_VALUE_32 0)尾轴按 32 的倍数对齐compare.cppCHECK(VectorErrorCode::ERR_CONFIG_ALIGNMENT, resultShape.empty() || resultShape.back() % NUM_VALUE_8 0)比较类算子尾轴元素数按 8 对齐FP32 下即 32 字节where.cpp对tileShape尾轴及存储 shape 尾轴做位宽取整校验。从这些实现可以看出尾轴对齐本质是向量单元按整块取数的硬件要求尾轴字节数必须是硬件存取粒度的整数倍。因此尾轴长度而非总元素数是对齐的关键reshape/view/转置改变尾轴归属后原本合法的 Tensor 也可能变得不合法。四、FC2XXX 运行时类错误FC2 段错误发生在实际执行阶段通常与 Tensor 生命周期、计算流程状态有关而非静态参数。4.1 FC2000 ERR_RUNTIME_NULLPTR运行时空指针错误描述Vector 运行时空指针传入的 Tensor 为空。可能原因NA文档未给出具体原因通常与 Tensor 未分配地址或生命周期管理不当有关。处理方式确认传入 Vector 接口的输入输出 Tensor 均非空且已完成地址分配确认是否存在nullptr# 正确示例 - 输入 Tensor 均已分配数据 a pypto.tensor([16, 32], pypto.DT_FP16, a) b pypto.tensor([16, 32], pypto.DT_FP16, b) out pypto.add(a, b)若问题仍未解决请访问社区提交 Issue。提示上面的示例为 Tensor 显式命名并构造第三个参数为 Tensor 名称。实战中若 Tensor 来自其他算子的输出应确认上游算子已正常执行完成、输出地址已有效分配再传入下游 Vector 算子。4.2 FC2001 ERR_RUNTIME_LOGIC运行时逻辑错误错误描述Vector 运行时逻辑错误计算流程进入未定义或异常分支。可能原因NA文档未给出具体原因属于兜底性运行时错误。处理方式通过相关日志定位异常路径核对计算流程是否进入未定义/异常分支确认中间结果、索引值是否符合预期。例如 index_add.cpp 中CHECK(VectorErrorCode::ERR_RUNTIME_LOGIC, false)表明代码走到了预期不该到达的分支compare.cpp 也会在元素大小为 0 时抛出该错误码并提示Element size cannot be zero.。检查核心计算逻辑的前置条件如 TileShape 设置、上下文与配置句柄初始化是否满足。若问题仍未解决请访问社区提交 Issue。五、通用排查方法论与最佳实践综合以上 8 个错误码可以沉淀出一套针对 PyPTO Vector 算子的通用排查流程先分类再定位根据错误码中间位判断是参数FC0、配置FC1还是运行时FC2问题根据首位判断是否属于 Vector 域FC0–FC2避免去 matmul/conv 文档里找答案。对照算子文档核对约束每个算子的文档如 pypto-add、pypto-pow、pypto-amax都会列出 dtype 支持集合、Shape 维度范围、Shape Size 上限INT32_MAX、TileShape 大小上限如 64KB等约束这是排查 FC0XXX 的第一依据。围绕 TileShape 检查 FC1XXX确认set_vec_tile_shapes各维为正、维度数 ≤ 4、与输入/输出维度一致、总大小不超算子上限、尾轴满足对齐要求FP16 按 16 元素 / FP32 按 8 元素即 32 字节对齐用 pypto.get_vec_tile_shapes 回读实际生效值。警惕隐式改变布局的操作reshape/view、转置transpose/permute会改变尾轴的归属进而改变对齐与切分语义。执行这类操作后建议重新审视并重设 TileShape。运行时报错检查生命周期确认所有输入输出 Tensor 均已分配有效地址、上游算子执行完成、上下文与配置句柄已正确初始化。保留可复现脚本提交 Issue 时附上最小可复现代码、打屏日志尤其是iOperands.size() should be ...这类带期望值的日志与算子文档版本便于社区快速定位。最后建议开发者在使用 Vector 算子前通读 docs/zh/guide/appendix/trouble_shooting/index.md 中的错误码参考索引将本类错误码作为日常开发时的查错字典遇到FC报错先查本文对应小节再结合算子文档与上述排查流程即可在绝大多数场景下自行定位并修复问题。【免费下载链接】pyptoPyPTO发音: pai p-t-oParallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考