Closed
[Documentation|文档反馈]: aclnnBlockSparseAttention.md aclnnBlockSparseAttentionV2.md示例代码有误 #5774
Xu-XuePengAdd on Sep 30Closed at 27 days ago
Sep 30 Added label: documentation
Xu-XuePengSep 30 Change title to "[Documentation|文档反馈]: aclnnBlockSparseAttention.md aclnnBlockSparseAttentionV2.md示例代码有误", originally titled "[Documentation|文档反馈]: aclnnBlockSparseAttention.md".
Sep 30 Change title to "[Documentation|文档反馈]: aclnnBlockSparseAttention.md aclnnBlockSparseAttentionV2.md示例代码有误", originally titled "[Documentation|文档反馈]: aclnnBlockSparseAttention.md".
Sep 30 Assign IceBearPolar as responsible person
Oct 7 Associated pull request
游震
Oct 8 Comments：
Oct 8 Comments：
/assign @IceBearPolar
27 days ago changed custom state from 进行中 to 已完成
27 days ago Close issue
周云飞
25 days ago Comments：
25 days ago Comments：
您好，补充 PR !13293 已合入master的具体内容：V1/V2约束中的 attentionMaskOptional 改为 attenMaskOptional；V2不再笼统写 innerPrecise 只能为4；示例资源释放改为 aclrtDestroyStream(*stream)。
这里的解引用对应FreeResource形参是 aclrtStream *stream，需要取出其中的stream句柄；若在main中持有的已经是 aclrtStream，则直接传句柄，不应机械添加 *。示例芯片判断中的字符串 Ascend910 能匹配 Ascend910B 和 Ascend910_93，这些名称会选择0，不能仅因A3被称为A3就认定该判断会误传4。
blockShapeOptional必须传入 位于FP8专属约束中，不能推广为所有dtype的无条件要求。
还需按实际代码保留精度模式差别：当前 29f3b8185af2 的tiling检查在950的FP16/BF16输入下接受0或4，其他dtype接受4；910/910_93接受0或1，但BF16只接受0。这比页面中“950仅4、A2/A3为0或1”的简写更细。本轮核对的是参数门禁，不代表这些组合已逐项完成设备精度验证。
Thanks for sending an issue! Please fill in the following template to help quickly solve your problem.
Document Link（文档链接）
aclnnBlockSparseAttention.md
aclnnBlockSparseAttentionV2.md
Issues Section（问题文档片段）
aclnnBlockSparseAttention.md
1 示例代码中innerPrecise的芯片判断逻辑有误，非910芯片默认设为4，但文档约束明确指出Atlas A3仅支持0或1，会导致A3平台运行报错。 "bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
int64_t innerPrecise = isArch22 ? 0 : 4;" 文档检测-综合 代码错误 严重 用户在Atlas A3等芯片上运行示例代码时，会因innerPrecise参数不合法导致算子初始化失败或返回错误码。 "bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
int64_t innerPrecise = isArch22 ? 0 : 1; // 根据实际芯片型号调整，A3仅支持0或1"
2 约束说明中参数名拼写错误，将attenMaskOptional误写为attentionMaskOptional，易引起用户对照文档时产生混淆。 attentionMaskOptional当前只支持传入nullptr。 文档检测-综合 术语错误 一般 用户对照文档查找参数说明时可能因名称不一致产生困惑，影响查阅效率。 attenMaskOptional当前只支持传入nullptr。
aclnnBlockSparseAttentionV2.mdAscend 950PR&950DT系列产品 仅支持配置为4，Atlas A2系列产品 、Atlas A3系列产品 仅支持配置为0或1
1 示例代码中aclrtDestroyStream(stream)参数传递错误，函数签名要求传入值而非指针，将导致编译失败。 aclrtDestroyStream(stream); 文档检测-综合 代码错误 致命 用户直接复制示例代码编译时会报类型不匹配错误，无法运行。 " aclrtDestroyStream(*stream);
aclrtResetDevice(deviceId);
aclFinalize();"
2 innerPrecise参数说明与约束说明严重矛盾，参数表称支持0/1/4且按芯片区分，约束称仅支持4，易导致用户传参错误。 "参数说明：当前只支持传0或1或4，其中，
约束说明：innerPrecise仅支持配置4，表示混合精度运算，在性能与精度上取得一个折中。" 文档检测-综合 文档矛盾 严重 用户无法确定应传入何值，在A2/A3芯片上可能传入4导致算子初始化报错。 统一参数说明与约束说明。若以参数表为准，建议将约束说明修改为：innerPrecise支持配置0、1或4，具体取值需根据芯片型号选择（950系列仅支持4，A2/A3系列仅支持0或1）。
3 blockShapeOptional参数说明与约束说明矛盾，参数表称未配mask时忽略，约束称必须传入，导致用户困惑。 "参数说明：当未配置blockSparseMaskOptional时：无论此项如何配置，算子均将忽略。
约束说明：blockShapeOptional必须传入。" 文档检测-综合 文档矛盾 严重 用户在不使用块稀疏mask时，不确定是否仍需传入blockShapeOptional，可能导致调用失败或资源浪费。 统一说明。若约束说明为准，建议将参数说明修改为：当未配置blockSparseMaskOptional时，算子仍会读取blockShapeOptional作为默认稀疏块尺寸。
4 示例代码中innerPrecise判断逻辑与芯片约束不符，非910芯片默认传4，但A2/A3芯片仅支持0或1。 " bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
int64_t innerPrecise = isArch22 ? 0 : 4;" 文档检测-综合 代码错误 严重 用户在Atlas A2/A3系列芯片上运行示例代码时，会传入非法值4，导致算子初始化报错。 " bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
bool is950 = socVersion.find(""Ascend950"") != std::string::npos;
int64_t innerPrecise = is950 ? 4 : 0;"
5 API参数名拼写错误，attentionMaskOptional应为attenMaskOptional - attentionMaskOptional当前只支持传入nullptr。 英文拼写错误 英文技术场景错误 一般 读者可能根据文档中的参数名attentionMaskOptional进行代码编写，导致编译错误或运行时错误，因为实际API中参数名为attenMaskOptional - attenMaskOptional当前只支持传入nullptr。
Existing Issues（存在的问题）
aclnnBlockSparseAttention.md
1 示例代码中innerPrecise的芯片判断逻辑有误，非910芯片默认设为4，但文档约束明确指出Atlas A3仅支持0或1，会导致A3平台运行报错。 "bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
int64_t innerPrecise = isArch22 ? 0 : 4;" 文档检测-综合 代码错误 严重 用户在Atlas A3等芯片上运行示例代码时，会因innerPrecise参数不合法导致算子初始化失败或返回错误码。 "bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
int64_t innerPrecise = isArch22 ? 0 : 1; // 根据实际芯片型号调整，A3仅支持0或1"
2 约束说明中参数名拼写错误，将attenMaskOptional误写为attentionMaskOptional，易引起用户对照文档时产生混淆。 attentionMaskOptional当前只支持传入nullptr。 文档检测-综合 术语错误 一般 用户对照文档查找参数说明时可能因名称不一致产生困惑，影响查阅效率。 attenMaskOptional当前只支持传入nullptr。
aclnnBlockSparseAttentionV2.mdAscend 950PR&950DT系列产品 仅支持配置为4，Atlas A2系列产品 、Atlas A3系列产品 仅支持配置为0或1
1 示例代码中aclrtDestroyStream(stream)参数传递错误，函数签名要求传入值而非指针，将导致编译失败。 aclrtDestroyStream(stream); 文档检测-综合 代码错误 致命 用户直接复制示例代码编译时会报类型不匹配错误，无法运行。 " aclrtDestroyStream(*stream);
aclrtResetDevice(deviceId);
aclFinalize();"
2 innerPrecise参数说明与约束说明严重矛盾，参数表称支持0/1/4且按芯片区分，约束称仅支持4，易导致用户传参错误。 "参数说明：当前只支持传0或1或4，其中，
约束说明：innerPrecise仅支持配置4，表示混合精度运算，在性能与精度上取得一个折中。" 文档检测-综合 文档矛盾 严重 用户无法确定应传入何值，在A2/A3芯片上可能传入4导致算子初始化报错。 统一参数说明与约束说明。若以参数表为准，建议将约束说明修改为：innerPrecise支持配置0、1或4，具体取值需根据芯片型号选择（950系列仅支持4，A2/A3系列仅支持0或1）。
3 blockShapeOptional参数说明与约束说明矛盾，参数表称未配mask时忽略，约束称必须传入，导致用户困惑。 "参数说明：当未配置blockSparseMaskOptional时：无论此项如何配置，算子均将忽略。
约束说明：blockShapeOptional必须传入。" 文档检测-综合 文档矛盾 严重 用户在不使用块稀疏mask时，不确定是否仍需传入blockShapeOptional，可能导致调用失败或资源浪费。 统一说明。若约束说明为准，建议将参数说明修改为：当未配置blockSparseMaskOptional时，算子仍会读取blockShapeOptional作为默认稀疏块尺寸。
4 示例代码中innerPrecise判断逻辑与芯片约束不符，非910芯片默认传4，但A2/A3芯片仅支持0或1。 " bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
int64_t innerPrecise = isArch22 ? 0 : 4;" 文档检测-综合 代码错误 严重 用户在Atlas A2/A3系列芯片上运行示例代码时，会传入非法值4，导致算子初始化报错。 " bool isArch22 = socVersion.find(""Ascend910"") != std::string::npos;
bool is950 = socVersion.find(""Ascend950"") != std::string::npos;
int64_t innerPrecise = is950 ? 4 : 0;"
5 API参数名拼写错误，attentionMaskOptional应为attenMaskOptional - attentionMaskOptional当前只支持传入nullptr。 英文拼写错误 英文技术场景错误 一般 读者可能根据文档中的参数名attentionMaskOptional进行代码编写，导致编译错误或运行时错误，因为实际API中参数名为attenMaskOptional - attenMaskOptional当前只支持传入nullptr。