Closed
[Documentation|文档反馈]: [MhcSinkhorn] README 将批量固定迭代接口描述成二维矩阵、Tensor 迭代参数及自适应早停 #6899
daishuangshuangAdd on  11 days agoClosed at  9 days ago
daishuangshuang
11 days ago Create

1)标题

[Doc Bug][MhcSinkhorn] README 将批量固定迭代接口描述成二维矩阵、Tensor 迭代参数及自适应早停

2)问题描述

MhcSinkhorn README第 49~67、81~82 行与实际定义存在多处直接冲突:

项目 README 描述 当前实现
输入/属性 init_matrix、max_iter、epsilon 都是输入 输入为 h_res;eps、num_iters、out_flag 为属性
矩阵 shape 二维 N×N 只接受 3D/4D 批量输入,N 为 4、6、8
迭代次数 推荐 50~200 num_iters 必须在 1~100
epsilon 作用 误差小于阈值即停止 eps 用于数值稳定,循环按 num_iters 固定执行

依据:OpDef第 23、47~49 行;Host Tiling第 84~88、161~183 行;arch35 Kernel第 222~233、504 行附近。Kernel 还会先做 Exp/Softmax,README 对输入和迭代过程的说明不足以构造一致的参考实现。

3)环境信息

  • 目标硬件:Ascend 950PR / 950DT,配套 CANN;本次未取得实际设备与安装版本。
  • 文档一致性问题可通过仓库直接核查;接口拒绝行为需在目标 Host UT/ACLNN 环境记录。
  • 本次未执行完整算子调用。

4)重现步骤

  1. 按 README 准备 FP32 非负矩阵 [4,4],迭代次数取 50,eps=1e-6。使用实际接口映射到 h_res、num_iters、eps 后调用。
  2. 当前 Host rank 检查要求 3D/4D,该二维输入会被拒绝。
  3. 为单独验证迭代范围,将输入改为合法 [1,4,4]、out_flag=0,但按 README 推荐取 num_iters=150。
  4. 当前 Host 会因超过 100 次而拒绝。
  5. 检查 Kernel 固定次数循环,确认不存在 README 所称的“行/列和误差小于 epsilon 就提前停止”判断。

5)预期结果

README 应描述真实接口名称、属性类型、批量 shape、N 范围和 1~100 次迭代约束,明确 eps 的稳定计算作用及实际输出含义。用户按照文档构造的基础用例应能通过参数校验。

6)日志截图等

源码中的错误字符串,未冒充本次运行日志:

the dim of x must be 3 or 4
num_iters must be between 1 and 100
x nDim must be 4, 6, or 8

对应 Host Tiling 第 163~164、86~87、182~183 行。

7)备注

应修正文档,不将“支持二维输入、200 次迭代、增加早停”混写成缺陷修复要求。建议文档示例使用 h_res=[1,4,4]、num_iters=20、eps=1e-6,并与实际算法的 golden 一起校对。

likedislike
周云飞
周云飞Collaborators
11 days ago Comments:

感谢您详细列出文档差异,并明确区分源码中的错误字符串与实际运行日志。此问题的重点是让 README 准确描述现有接口,而不是扩展二维输入、迭代上限或早停能力。

问题分析

按您提供的接口定义和实现位置,README 中需要重点对齐以下内容:

  • 输入与属性:区分输入张量 h_res 和属性 eps、num_iters、out_flag,避免将迭代次数与稳定计算参数描述为张量输入。
  • 形状与范围:说明 3D/4D 批量输入的维度含义、矩阵阶数 N 为 4、6、8,以及 num_iters 为 1~100 的约束。按报告中的检查逻辑,二维 [4,4] 和 num_iters=150 分别不满足维度与迭代次数要求。
  • 计算语义:区分用于数值稳定的 eps 与收敛阈值,避免把固定次数迭代写成自适应早停。您指出的 Exp/Softmax 预处理也直接影响参考结果,不能仅用“对非负矩阵反复归一化”代替实际计算过程。

这些差异会影响用户构造输入和参考实现。具体接口约束与计算顺序仍需结合对应实现完整确认;目前没有目标设备上的调用结果。

处理方向

一个可行的调整方向是同步修订参数表、形状约束、算法说明和示例,并补充 out_flag 各取值对应的输出含义。示例可采用您建议的 h_res 形状 [1,4,4]、num_iters=20、eps=1e-6,同时明确 out_flag 及其余适用条件;参考实现则需与预处理、归一化顺序和稳定项的使用位置保持一致。

当前应聚焦文档与实现的一致性,不将支持二维输入、超过 100 次迭代或增加早停混入本次文档修正范围。

likedislike
fengjiawei1Collaborators
11 days ago Comments:

/assign

likedislike
CANN-robotCANN-robotCollaborators
11 days ago Assign fengjiawei1 as responsible person
Ffengjiawei1Collaborators
10 days ago Associated pull request
Ddaishuangshuang
10 days ago changed custom category from 任务 to 缺陷
CANN-robotCANN-robotCollaborators
9 days ago Close issue
CANN-robotCANN-robotCollaborators
9 days ago Added label: resolved