已关闭
[Documentation|文档反馈]: 大模型扫描文档问题修改 #112
liujing987913创建于  9 天前关闭于  14 分钟前
liujing987913
9 天前 创建

Document Link(文档链接)

https://gitcode.com/cann/ops-ras/blob/master/docs/QUICKSTART.md
https://gitcode.com/cann/ops-ras/blob/master/docs/QUICKSTART_en.md

Issues Section(问题文档片段)

文件名 问题描述 原文文本 建议
docs/QUICKSTART.md 文档给出的样例文件路径 add_example/examples/test_aclnn_add_example.cpp 在项目根目录下不存在(实测 ls add_example/... → No such file or directory);真实路径是 examples/add_example/examples/test_aclnn_add_example.cpp。文档其他位置(第 120、238 行)都写的是 ops-ras/examples/add_example/...,此处少了 examples/ 前缀。 add_example/examples/test_aclnn_add_example.cpp 改为 examples/add_example/examples/test_aclnn_add_example.cpp(或与全文统一为 ops-ras/examples/add_example/examples/test_aclnn_add_example.cpp)。
docs/QUICKSTART.md 文档“三、算子调试 / 1. 打印 / printf”代码块前三行与仓库 9.1.0 分支 examples/add_example/op_kernel/add_example.h 的 Init() 实际代码不一致:实际为 blockLength_ = tilingData->totalLength / AscendC::GetBlockNum(); 与 tileLength_ = blockLength_ / tileNum_ / BUFFER_NUM;,文档却给出了向上取整的三元表达式版本,读者在文件中找不到这些行。 blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum(); 将代码块的前三行改成仓库实际存在的 tiling 计算行(blockLength_ = tilingData->totalLength / AscendC::GetBlockNum(); 等),或只展示需要新增的 // 打印当前核计算Block长度 与 AscendC::PRINTF("Tiling blockLength is %llu\n", blockLength_); 两行并说明插入位置在 Init()
docs/QUICKSTART.md “使用须知”中文字重复:“CANNLab或Docker环境默认提供最新最新版CANN包”,同一句里“最新”重复两次;同样的问题在§一.1 的 CANNLab 分支说明中再次出现(“默认提供最新最新版CANN包配套的项目源码”)。属文字校对问题,不影响执行。 > 说明:CANNLab或Docker环境默认提供最新最新版CANN包;如需体验master分支最新能力,可手动搭建环境。 改为“默认提供最新版CANN包”,并同步修正§一.1(第29行)“默认提供最新版CANN包配套的项目源码”。
docs/QUICKSTART.md 文档 §一.1 让用户按 git clone -b ${tag_version} https://gitcode.com/cann/ops-ras.git 下载源码(tag 为标签,如 v9.1.0),此时 HEAD 处于 detached 状态。实测在这样克隆出的源码目录执行 git branch 只输出 * (no branch),查不到任何版本信息;紧接着第 46 行说的“若源码已存在,执行 git pull 拉取最新源码”也失败:You are not currently on a branch. Please specify which branch you want to merge with.。 在源码目录执行git branch,查询当前源码版本。 改为用能反映标签版本的方式查询,例如 git describe --tags --always(或 git log -1 --oneline);并说明检出 tag 后处于 detached HEAD,如需 git pull 应先 git checkout <分支名>(或改用 git fetch + 重新 git checkout <tag>)。
docs/QUICKSTART.md §三.1 要求“请在 examples/add_example/op_kernel/add_example.h 中进行代码修改”,并给出 192-197 行片段作为待改代码上下文;但仓库实际源码(v9.1.0 tag 与 master 分支均如此)Init 中为:blockLength_ = tilingData->totalLength / AscendC::GetBlockNum(); 与 tileLength_ = blockLength_ / tileNum_ / BUFFER_NUM;。文档片段里的向上取整写法 (tilingData->totalLength + AscendC::GetBlockNum() - 1) / ... 和三元表达式 ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) ? ... : 1 在源码中根本不存在(grep 均无命中)。照抄替换会改变分块/tile 切分逻辑,与“仅添加打印”的意图不符。 blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum(); 把片段中的三行换成本仓库实际代码(blockLength_ = tilingData->totalLength / AscendC::GetBlockNum(); tileNum_ = tilingData->tileNum; tileLength_ = blockLength_ / tileNum_ / BUFFER_NUM;),仅保留新增的 AscendC::PRINTF("Tiling blockLength is %llu\n", blockLength_); 一行,或直接说明“在上述 Init 的现有赋值语句之后追加一行 PRINTF”。
docs/QUICKSTART.md 说明文字中“最新最新版”重复用词,为输入笔误;第 29 行“默认提供最新最新版CANN包配套的项目源码”存在同一处重复。 默认提供最新最新版CANN包 改为“默认提供最新版CANN包”
docs/QUICKSTART.md 文档让用户“参考selfX,同理修改selfY、selfZ的输入”,但 example 源码 examples/add_example/examples/test_aclnn_add_example.cpp 中并不存在 selfZ 变量,输出张量实际命名为 out(std::vector<int64_t> outShape / outHostData / CreateAclTensor(..., &out))。按字面理解无法定位到要修改的对象。 // === ② 参考selfX,同理修改selfY、selfZ的输入 === 改为“参考 selfX,同理修改 selfY 与输出张量 out(outShape/outHostData)”,或把注释写成 // === ② 参考selfX,同理修改selfY、out 的 shape 与数据 ===。
docs/QUICKSTART.md L185 要求「请在 examples/add_example/op_kernel/add_example.h 中进行代码修改」,但 L192-195 给出的 printf 示例上下文与真实源码不一致:9.1.0 分支 examples/add_example/op_kernel/add_example.h 的 Init 实际为 blockLength_ = tilingData->totalLength / AscendC::GetBlockNum(); tileLength_ = blockLength_ / tileNum_ / BUFFER_NUM;(无向上取整、无三元保护),仓库自带 docs/zh/debug/op_debug_prof.md 的同一示例也是这一版本。完整搜索仓库,文档里那三行"(totalLength + GetBlockNum() - 1) / GetBlockNum()"与"? ... : 1"在源码中不存在。因此读者按文档去文件里找这 3 行对不上;若整段粘贴(已实测),会静默替掉可工作的 tiling 计算(向上取整语义下当 totalLength 不能被 blockNum 整除时 blockLength_ 会大于均分长度,而 SetGlobalBuffer 仍用 blockLength_ 做偏移,有越界风险)。 blockLength_ = (tilingData->totalLength + AscendC::GetBlockNum() - 1) / AscendC::GetBlockNum(); 把示例上下文改成与真实源码一致的三行:blockLength_ = tilingData->totalLength / AscendC::GetBlockNum(); tileNum_ = tilingData->tileNum; tileLength_ = blockLength_ / tileNum_ / BUFFER_NUM;,只把 AscendC::PRINTF("Tiling blockLength is %llu\n", blockLength_); 作为新增行,并注明它在 Init 里、初始化 pipe 之前。
docs/QUICKSTART.md 文档第64-68行把「编译成功」的提示写成 Self-extractable archive "cann-ops-ras-custom_linux-${arch}.run" successfully created.,但本项目(9.1.0 分支/CANN 9.1.0)用第55行的编译命令实际产出的提示与产物名是 Self-extractable archive "cann-ops-ras-custom-linux.x86_64.run" successfully created.:vendor 名与 linux 之间是连字符 - 而不是下划线 _,架构标识是 .x86_64 而不是 -${arch}。按原文给出的字符串比对会认为「没有出现成功提示」,且第67行暗示的产物名与 build_out 中真实文件(cann-ops-ras-custom-linux.x86_64.run)不符。 Self-extractable archive "cann-ops-ras-custom_linux-${arch}.run" successfully created. 把第67行的成功提示改成与实际一致的形式,例如 Self-extractable archive "cann-ops-ras-custom-linux.x86_64.run" successfully created.(或写成 cann-ops-ras-custom-linux.${arch}.run),并让紧随其后的「run包存放于 build_out 目录」示例名与之一致。
docs/QUICKSTART_en.md III.1 printf 示例声称是 examples/add_example/op_kernel/add_example.h 中的代码,但仓库中该文件 Init() 实际为 blockLength_ = tilingData->totalLength / AscendC::GetBlockNum(); 与 tileLength_ = blockLength_ / tileNum_ / BUFFER_NUM;;示例多出的向上取整/三元保护与实际实现不同。逐字套用会静默改变分块计算(本次实测仍可编译运行,blockLength 256),但用户对照源码时会发现代码对不上。 tileLength_ = ((blockLength_ + tileNum_ - 1) / tileNum_ / BUFFER_NUM) ? 让示例与实际文件一致:只保留 AscendC::PRINTF("Tiling blockLength is %llu\n", blockLength_); 插入说明(并标注插入位置),或把示例中的三行改为文件当前实现。
docs/QUICKSTART_en.md I.2 的编译成功提示串与实机实际输出不一致:文档写 cann-ops-ras-custom_linux-${arch}.run(vendor 名后用下划线),而 bash build.sh --pkg --soc=ascend910b --ops=add_example -j16 的实际输出为 Self-extractable archive "cann-ops-ras-custom-linux.x86_64.run" successfully created.(vendor 名后用连字符),build_out 下实际文件名也是 cann-ops-ras-custom-linux.x86_64.run。 Self-extractable archive "cann-ops-ras-custom_linux-${arch}.run" successfully created. 把提示串改为实际格式 Self-extractable archive "cann-ops-ras-${vendor_name}-linux.${arch}.run" successfully created.(或直接引用 build_out 下的实际文件名 cann-ops-ras-custom-linux.x86_64.run)。

Existing Issues(存在的问题)

详见问题表格

likedislike
ZzWaNg3
6 天前 关联了pull request:docs: 修复 QUICKSTART 文档与源码不一致问题
LLiuZonggu成员
2 天前 将 caiwenwen 设为负责人
CANN-robotCANN-robot成员
14 分钟前 关闭了 issue