已关闭
[Documentation|文档反馈]: 根目录README快速入门中matmul运行示例与样例自身README存在多处不一致 #217
钟偐创建于  7月4日关闭于  7月16日
钟偐
钟偐
7月4日 创建

Thanks for sending an issue! Please fill in the following template to help quickly solve your problem.

一、问题描述

在阅读仓库根目录 README.md 的「⚡️快速入门」第 4 步「运行验证」选项 B 时,发现该处给出的 matmul 运行示例与样例自身 Samples/0_Introduction/matmul/README.md 存在多处不一致,可能对新手造成困惑。

二、具体不一致项

1. 运行参数无说明

根目录 README 中的运行命令为:
./build_out/0_Introduction/matmul/matmul 100 50 200
三个参数 100 50 200 没有任何说明,用户无法判断其含义。

而样例自身 README 的「参数说明」章节明确指出:

  • m: 矩阵乘中左矩阵的行
  • k: 矩阵乘中左矩阵的列/右矩阵的行
  • n: 矩阵乘中右矩阵的列

建议在根目录 README 中补充参数含义说明,或在命令下方添加简要注释。

2. 预期输出描述不准确

根目录 README 给出的预期输出为:
matmul run successfully!

但样例自身 README 显示,实际运行成功后的输出包含完整精度验证信息:
Data generated successfully!
[verify] shape(1024, 4096), elements=4194304 - summary ...
abs_err: max=..., mean=..., rmse=...
...
[PASS] NPU results are consistent with CPU.

根目录的 matmul run successfully! 与实际输出不符,用户按此预期验证可能误判运行结果。

3. 代码块语言标记不一致

根目录 README 快速入门第 4 步:

  • 选项 A 的运行命令使用 ```sh 标记(正确)
  • 选项 B 的运行命令使用 text 标记(应为 sh)

选项 B 中的 ./build_out/0_Introduction/matmul/matmul 100 50 200 是 shell 命令,应使用 sh 标记以正确渲染语法高亮。

4. 缺少工作目录切换步骤

根目录 README 选项 B 直接给出命令:
./build_out/0_Introduction/matmul/matmul 100 50 200

而样例自身 README 在运行前明确要求:
cd ./build_out/0_Introduction/matmul
./matmul 1024 2048 4096

matmul 可执行文件运行时依赖当前工作目录下的数据生成脚本,不 cd 到对应目录会报错(与 Issue #212 一致)。

三、修改建议

建议将根目录 README 快速入门第 4 步选项 B 修改为:
cd ./build_out/0_Introduction/matmul
./matmul 100 50 200 # 参数依次为 m k n,分别表示左矩阵行数、左矩阵列数/右矩阵行数、右矩阵列数

并将预期输出更新为实际输出的摘要形式,例如:
Data generated successfully!
...
[PASS] NPU results are consistent with CPU.

四、预期价值

  1. 补充参数说明后,新手能理解示例参数的含义,便于自行调整维度进行测试
  2. 修正预期输出后,避免用户因输出不符而误判运行失败
  3. 统一代码块标记,提升文档渲染一致性
  4. 补充 cd 步骤,与样例自身 README 保持一致,避免运行报错
likedislike
songkai111成员
7月6日 评论:

您好,已收到您的反馈,我们将安排责任人处理

likedislike
Yyangyang016成员
7月6日 将 yangyang016 设为负责人
XieQianyiXieQianyi
7月7日 关联了pull request:fix(docs): 修复根目录README快速入门matmul运行示例与样例README不一致 (#217)
yangyang016成员
7月16日 评论:

您好,相关修复已合入,感谢您的反馈,如有问题请进一步联系我们

likedislike
Yyangyang016成员
7月16日 issue状态由 进行中 改变为 已完成
Yyangyang016成员
7月16日 关闭了 issue