Closed
[Documentation|文档反馈]: Xlogy算子README调用说明缺失与aclnn接口文档dtype声明/公式语义/样例健壮性问题 #4397
zhaoxinmengAdd on  12 days agoClosed at  9 days ago
zhaoxinmengCollaborators
12 days ago Create

一、文档链接 (必填)

  • 算子README:math/xlogy/README.md
  • aclnn接口文档(中英各3份):math/xlogy/docs/aclnnXLogYTensor&aclnnInplaceXLogYTensor.md、math/xlogy/docs/aclnnXLogYScalarSelf.md、math/xlogy/docs/aclnnXLogYScalarOther&aclnnInplaceXLogYScalarOther.md(及对应_en.md)
  • 调用样例:math/xlogy/examples/

二、问题文档片段 (必填)

  1. README"调用说明"仅一行"图模式调用",未覆盖已交付的aclnn API通路(docs/下3份接口文档、examples/下3个test_aclnn_x_log_y_*.cpp样例无入口);表头"调用样例"与用语"图模式调用"不符README模板固定要求(表头应为"调用方式/样例代码/说明",调用方式仅允许aclnn API/GE图模式/PyTorch API)。
  2. 三份aclnn接口文档的数据类型声明仅挂在 npu="A3" 产品过滤标签内,Ascend 950PR&950DT等产品无任何dtype声明。
  3. 接口文档功能说明公式 out_i = self_i * log(other_i) 缺少零保护(self_i=0输出0)与NaN传播(other为NaN输出NaN)语义,与README公式不一致。
  4. 标量参数(aclScalar*)说明误套Tensor的"支持非连续的Tensor"与"[数据格式]支持ND"描述(标量句柄不存在布局与连续性概念)。
  5. 标量样例aclCreateScalar失败分支返回遗留的0退出码且无错误输出(含文档内嵌示例同病);GEIR样例未检查AddGraph返回值即打印成功、成功路径未释放new分配的ge::Session;标量样例失败提前返回时不清理已创建的aclTensor/aclScalar、device内存与stream。

💡 存在的问题(修复方案)

  • README调用说明按样例分行补齐aclnn API行(链接3份接口文档、列全5个两段式接口)与GE图模式行,表头/用语对齐模板。约束说明保持算子级口径(输入x1和x2同数据类型),aclnn通路的数据类型推导规则由接口文档各自声明。
  • 接口文档dtype改为所有产品支持类型并集,产品差异(Atlas推理/训练系列:self和other不支持BFLOAT16)在表下方按"产品:描述"说明。
  • 功能说明公式对齐README分段形式并补NaN传播声明(中英同步)。
  • 删除标量参数误套的非连续/ND描述(中英同步)。
  • 样例修复:aclCreateScalar失败分支打印日志并返回ACL_ERROR_FAILURE(含文档内嵌示例);GEIR样例检查AddGraph返回值、成功路径补delete session;标量样例改为unique_ptr+aclGuard RAII写法补齐失败路径资源清理。

实测验证(Ascend 950PR):dtype并集口径与aclnnXLogY*第一段接口校验行为一致——tensor输入9种含BF16;InplaceScalarOther的selfRef实际可用类型为FLOAT/FLOAT16/BF16(9种列表与浮点cast约束的交集)。

关联PR:https://gitcode.com/cann/ops-math/pull/6987(资料与样例部分,已合入)

likedislike
ZzhaoxinmengCollaborators
12 days ago Added label: documentation
ZzhaoxinmengCollaborators
12 days ago Associated pull request
ZzhaoxinmengCollaborators
12 days ago Modify description of issue
zhaoxinmengCollaborators
12 days ago Comments:

/assign @zhaoxinmeng

likedislike
CANN-robotCANN-robotCollaborators
12 days ago Assign zhaoxinmeng as responsible person
ZzhaoxinmengCollaborators
11 days ago Modify description of issue
ZzhaoxinmengCollaborators
10 days ago Modify description of issue
CANN-robotCANN-robotCollaborators
9 days ago Close issue
CANN-robotCANN-robotCollaborators
9 days ago Added label: resolved
ZzhaoxinmengCollaborators
9 days ago Modify description of issue
ZzhaoxinmengCollaborators
9 days ago Associated pull request
ZzhaoxinmengCollaborators
9 days ago Modify description of issue
ZzhaoxinmengCollaborators
9 days ago Associated pull request
ZzhaoxinmengCollaborators
8 days ago Associated pull request
ZzhaoxinmengCollaborators
8 days ago Modify description of issue
ZzhaoxinmengCollaborators
8 days ago Modify description of issue
ZzhaoxinmengCollaborators
8 days ago Modify description of issue