master

文件	最后提交记录	最后更新时间
chunk_loss.md	docs: 修复AIDD文档质量扫描报告中的语义与示例问题 Co-authored-by: EliasKaslan<eliaskaslan@outlook.com> # message auto-generated for no-merge-commit merge: !163 merge docs/fix-aidd-report-issues into master docs: 修复AIDD文档质量扫描报告中的语义与示例问题 Created-by: EliasKaslan Commit-by: EliasKaslan Merged-by: ascend-robot Description: ## What this PR does / why we need it? 本 PR 修复 AIDD 文档质量扫描报告中的**语义与示例问题**（函数签名、公式、参数/返回值/支持范围、示例可运行性、文档自相矛盾），13 个文件，**纯文档改动，不涉及任何 .py**。 原 PR 里的纯格式改动（术语大小写、错别字、Markdown 格式、中英文之间的空格）已拆到 #183，本 PR 不再包含格式改动。 **首轮改动范围（13 个文件）** - **函数签名与导入路径**：add_rms_norm_bias 更正为实际接口 npu_add_rms_norm_bias；chunk_gate_delta_rule 更正为 chunk_gated_delta_rule - **公式修正**：mhc_post 的 bmm2 与反向公式索引方向修正，与内部前向 permute(0, 1, 3, 2) 的实现一致 - **变量名与示例可运行性**：x_triton 更正为 x、gamma 更正为 norm_gamma、model 更正为 rms_norm_gated；fused_cross_entropy_loss 示例补充 dtype/device 定义，示例不再报 NameError - **参数、返回值与支持范围**：alpha_chunks 接口无默认值、需显式传参；probs 仅 moe_sort_chunks_by_index_with_probs 使用；fused_cross_entropy_loss 返回值为标量；chunk_gated_delta_rule 反向子步骤由 5 更正为 7；recompute_w_u_fwd 补充 arch32/arch35 架构代号说明 - **数据修正**：clipped_swiglu 性能表删除单位失实的 bw(GB/s) 列（该列数值实为 MB/s，标 GB/s 意味着约 109 TB/s，远超 HBM 带宽） **第二轮（收尾修正）**——对首轮改动逐条做源码复核时，发现同批文件内仍有同类问题，一并修正： - **示例可运行性**：add_rms_norm_bias 的 3 个示例与 rmsnorm_without_weight 的示例补齐 NPU device/dtype。算子仅在 PrivateUse1（NPU）后端注册（mindspeed_ops/csrc/torch_binding.cpp:59），CPU 张量必然报 Could not run ... with arguments from the CPU backend；sinkhorn 示例补齐 dtype/device 并改用已定义变量（原先引用了 5 个未定义名字） - **函数签名**：chunk_gated_delta_rule 的**全部 15 处算子调用**逐条按源码签名核对后统一改为关键字调用。其中 2 处是真实错位：chunk_bwd_dv_local(q, k, g, do, scale) 的 g/do 位置互换（真实签名为 (q, k, do, g, ...)）、chunk_gated_delta_rule_bwd_dhu(q, k, w, g, h0, dht, do, dv, scale) 自第 4 个参数起全部错位（真实签名为 (q, k, w, do, dv, g, gk, h0, dht, scale, ...)）；prepare_wy_repr_bwd 的 du 参数名与 du=dv 映射也在正文中写明。其余 13 处改为关键字式以消除"位置参数是否写对"的歧义（已逐个用 AST 校验：关键字名存在于真实签名且顺序递增，arch32/arch35 两套实现均适用） - **支持范围与参数**：cumsum 的 arch35 支持与 4 维分发（原"arch35 暂不支持"与源码 api/triton/cumsum.py:150-160 直接矛盾）；rmsnormgated 的 bias（源码为必传参数且支持非 None，原文"固定为 None"有误）、输出 dtype、residual_in_fp32 作用范围、arch35 支持（原文"不支持arch35"有误，并补上 arch35 的 D 上限约束）；chunk_gated_delta_rule 的 head_first（弃用仅告警，非"仅支持 False"）；sinkhorn 的 mixes 支持 dtype 与 sinkhorn_iters；clipped_swiglu 的 swiglu_limit 非负约束；mhc_pre_only 的 eps 数据类型 - **文档自相矛盾与缺项**：recompute_w_u_fwd 统一"前向/反向"口径；cumsum 参数说明表补 chunk_indices 行；mhc_post 的 h_res 排列约定由 3 处重复收敛为 1 处权威说明，明确"公式采用用户输入排列、源码内部先 permute(0,1,3,2)" **文件清单**：docs/zh/aclnn/add_rms_norm_bias.md、docs/zh/catlass/chunk_loss.md、docs/zh/triton/chunk_gated_delta_rule.md、docs/zh/triton/clipped_swiglu.md、docs/zh/triton/cumsum.md、docs/zh/triton/fused_cross_entropy_loss.md、docs/zh/triton/mhc_post.md、docs/zh/triton/mhc_pre_only.md、docs/zh/triton/recompute_w_u_fwd.md、docs/zh/triton/rmsnorm_without_weight.md、docs/zh/triton/rmsnormgated.md、docs/zh/triton/sinkhorn.md、docs/zh/triton/sort_chunks_by_idx.md **与 #183 的关系**：#183 是本 PR 拆出的格式部分。两者改动行基本不重叠，任一方先合入后，另一方按页面提示变基即可。 ## Does this PR introduce any user-facing change? 无代码接口与算子行为变更，均为文档/示例与实际实现对齐的修正。其中文档描述的支持范围、参数与返回值有更正，以仓内实际实现为准。 ## How was this patch tested? - 逐条对照 mindspeed_ops/ 实际实现核实函数签名、公式、返回值与支持范围（含 arch32/triton/、arch35/triton/、api/triton/、csrc/）； - 公式类改动做了双路验证：内核推导 + UT 参考实现（如 tests/unit_tests/triton/test_mhc_post.py）交叉确认； - 示例可运行性：补齐 device/dtype、修正未定义变量后，示例不再报 NameError 与 CPU/NPU 后端不匹配错误； - 逐条与 #183 的改动做对照：两个 PR 的并集即原 #163 的全部改动，且每条改动只落在其中一个 PR； - 结构与格式自检：13 个文件 53 张表列数一致、git diff --check 干净、无新增中英文空格、无失效链接； - 纯文档改动，无功能逻辑；文档门禁（markdownlint、链接有效性等）由 CI 验证。 ## 已知遗留项（源码侧 docstring，本 PR 有意不修） 以下为**源码文件内**的 docstring 表述过时/有误，属于代码侧文档，修改它们会使本 PR 变为非纯文档改动（Detect_file_changes 判定 non-doc 后会触发 4 个 NPU UT 分片），故本 PR 不改，留待单独的源码清理： - mindspeed_ops/api/triton/sinkhorn.py:23 与 :59 仍写 optimized for GPU performance / with GPU optimization（本仓实现面向昇腾 NPU）； - mindspeed_ops/api/triton/fused_cross_entropy_loss.py:25 仍写 loss: Output tensor with shape [bs * seq_len]，而实际 return out.sum() 为 0 维标量； - mindspeed_ops/api/catlass/chunk_loss.py:107-112 的 docstring 写 "Atlas A3 BF16"，而 csrc/catlass/chunk_loss/chunk_loss_torch.cpp:99 同时允许 Ascend910B(A2) 与 Ascend910_93(A3)。 ## 另一项待确认（源码行为本身存疑，不宜由文档单方面"写死"） docs/zh/triton/chunk_gated_delta_rule.md 把 initial_state 描述为可用入参（含形状 [N, H, K, V]），但 mindspeed_ops/api/triton/chunk_gated_delta_rule.py:329-330 对任何非 None 的 initial_state 都无条件抛出 ValueError("The chunk_gated_delta_rule_fwd_h does not support initial_state.")。 这一条**未在本 PR 修改**：目前无法判断该限制是有意收窄（那文档应改，且需同步改函数签名段与参数表）、还是临时/缺陷（那应改代码）。本 PR 不替源码单方面背书，留待源码侧确认后单独处理。 See merge request: Ascend/MindSpeed-Ops!163	1 个月前
custom_catlass_operator_guide.md	docs: 移除Markdown文档中中英文及中文与数字之间的空格 Co-authored-by: EliasKaslan<eliaskaslan@outlook.com> # message auto-generated for no-merge-commit merge: !176 merge docs/remove-spaces-cn-en into master docs: 移除Markdown文档中中英文及中文与数字之间的空格 Created-by: EliasKaslan Commit-by: EliasKaslan Merged-by: ascend-robot Description: ## What this PR does / why we need it? 统一MindSpeed Ops文档空格规范：移除所有Markdown文档中中文与英文之间、中文与数字之间的空格。 - 覆盖范围：README、docs/zh、docker、ci、tests、tools等目录共35个Markdown文档，合计2346处空格调整 - 仅删除中英文、中文与数字之间的空格；代码块、行内代码、链接URL、表格结构均保持不变 - 相关章节标题同步调整后，已确认仓库内引用的锚点链接无失效（install_guide.md中被引用的章节标题原本即无空格） - docs/zh/release_notes_ops.md的空格调整由"版本说明按模板重构"的关联PR统一覆盖，避免两个PR改动冲突 ## Does this PR introduce any user-facing change? 无，仅文档格式统一，不涉及任何功能变更。 ## How was this patch tested? CI verification only（文档门禁markdownlint与链接有效性检查）。 See merge request: Ascend/MindSpeed-Ops!176	1 个月前