基于 CANNLab 环境开发与提交课程指南

本指南面向希望向 cann-learning-hub 贡献课程的开发者，介绍如何基于 CANNLab 云开发环境完成课程开发、验证与 PR 提交的完整流程。

建议：CANNLab 云开发环境支持持久化开发，但仍建议将开发内容及时 commit 并 push 到个人 fork 仓库分支，避免环境异常或资源回收造成数据丢失。

---

1. 整体流程概览

基于 CANNLab 环境开发并提交课程的整体流程如下：

步骤	操作	说明
1	签署 CLA & Fork 仓库	完成社区准入准备，获取个人开发仓库。
2	创建并进入 CANNLab 云开发环境	申请 NPU 环境，通过 WebIDE 连接。
3	克隆仓库 & 切换开发分支	在环境中拉取代码，切换到 test 分支。
4	开发课程内容	按照目录结构与 Notebook 规范开发课程。
5	提交代码	将开发内容提交并推送到个人 fork 仓库的 test 分支。
6	运行验证	在课程支持的环境中逐 cell 执行 Notebook，确认可正常运行。
7	发起 PR	向 cann/cann-learning-hub 的 test 分支发起 PR。
8	响应评审 & 迭代修改	根据评审意见在环境中修改并更新 PR。

详细规范请参见 新课程上库与上线验收标准，本指南聚焦于 CANNLab 环境下的操作步骤。

---

2. 准备工作

2.1 签署 CLA

在参与贡献之前，请前往 CLA 使用指南 完成 CLA 协议签署。未签署 CLA 的 PR 将无法合入。

2.2 Fork 仓库

1. 在 cann-learning-hub 仓库页面点击 Fork，将仓库 fork 到个人空间。

2. 记下个人 fork 仓库地址，例如 https://gitcode.com/<your_username>/cann-learning-hub.git。Fork 时选择要 Fork 的分支请选择全部。

---

3. 创建并进入 CANNLab 云开发环境

3.1 进入 CANNLab 入口

进入 CANN 开源组织 https://gitcode.com/cann 点击导航栏中的 CANNLab页签后，正式进入 CANNLab 主页。

CANNLab 提供两类环境：云开发环境（可申请 A2/A3）与 950 尝鲜体验环境（可申请 A5）。请根据课程支持的目标硬件选择对应环境。本指南以云开发环境为例。

3.2 创建 NPU 环境

左侧导航栏切换到我的环境，点击新建环境可创建 NPU环境

按课程目标硬件选择规格配置（以 A2 为例）：

环境创建完成后，NPU 环境会自动启动，可以在我的环境页面进行开机/关机/连接/CANN包升级/删除操作。

注意：如果开机时提示资源不足，说明当前时间段使用人数较多，可稍后再尝试。

3.3 通过 WebIDE 连接环境

环境开机后，点击 WebIDE 进入环境（也支持 VS Code 连接）：

进入后界面类似 VS Code，支持源代码管理、扩展安装、终端等操作：

---

4. 克隆仓库与分支管理

4.1 打开终端

在 WebIDE 中通过菜单 Terminal → New Terminal 打开集成终端。

4.2 克隆个人 fork 仓库

执行以下命令，克隆个人 fork 仓库：

cd /mnt/workspace/gitCode/
git clone https://gitcode.com/<your_username>/cann-learning-hub.git
cd cann-learning-hub

4.3 切换到开发分支

课程开发统一基于个人 fork 仓库的 test 分支进行，切换到该分支即可开始开发：

git checkout test

---

5. 开发课程内容

5.1 在 WebIDE 中打开 fork 仓库

克隆完成后，在 WebIDE 中使用快捷键 Ctrl+K Ctrl+O 打开工程，在弹出窗口输入 /mnt/workspace/gitCode/ 目录：

选择当前窗口打开：

即可在左侧资源管理器中看到自己的 fork 仓库目录结构，直接在其中开发。

5.2 确定课程目录位置

• 官方课程：放在 tutorials/ 目录下。
• 社区贡献课程：放在 contrib/tutorials/ 目录下。

课程目录名建议全部小写，多个单词之间用下划线连接，例如 yolov3_inference。

5.3 目录结构

按照以下结构组织课程内容（以 tutorials/ 下多章节课程为例）：

tutorials/
└── course_name/
    ├── README.md                          # 课程主 README
    ├── 01_chapter_name/
    │   ├── 01.01_chapter_intro.ipynb      # 章节概述（必须为第一小节）
    │   ├── 01.02_section_name.ipynb       # 中间小节
    │   ├── 01.03_chapter_test.ipynb       # 章节实践（必须为最后一小节）
    │   ├── answer/                        # 课后练习/实践答案
    │   ├── images/                        # 章节配图
    │   └── src/                           # 工程源码
    └── 02_chapter_name/
        ├── 02.01_chapter_intro.ipynb
        ├── 02.02_section_name.ipynb
        ├── 02.03_chapter_test.ipynb
        ├── answer/
        ├── images/
        └── src/

命名规范要点：

• 课程目录、章节目录、文件名均使用英文、数字、下划线和点号，不包含中文。
• 章节目录命名符合 0n_abc 格式，例如 01_introduction。
• 小节 notebook 命名符合 0n.0m_abc.ipynb 格式，例如 01.01_chapter_intro.ipynb。

5.4 开发 README.md

课程根目录的 README.md 必须包含：

• 教程整体简介。
• 适用对象。
• 整体学习目标。
• 支持或已验证的硬件型号（必须说明）。
• 在线体验环境说明（必须说明）：明确课程支持在 gitcode 在线 Notebook 环境 还是 CANNLab 环境 中体验。
  • 若支持 gitcode 在线 Notebook 环境：在 README 中说明。gitcode 在线体验链接由仓库维护人员统一配置，开发者无需自行配置；课程提交到 test 分支后，请创建一个 Issue，说明课程名称、目录路径及各 .ipynb 入口文件，请求维护人员协助配置 gitcode 在线体验链接。
  • 若支持 CANNLab 环境：在 README 中说明，并附上 CANNLab 环境体验指导链接：CANNLab 环境体验指南。

5.5 开发 Notebook 内容

每个章节的小节 Notebook 必须包含 小节概述、教程具体内容、课后练习或课后实践 三个部分。

开发要点：

• 章节概述（第一小节）：包含学习前置要求、章节目标、章节内容与跳转链接。
• 章节实践（最后一小节）：至少包含一道综合编程实践题。
• 教程正文：行文通顺、逻辑由浅入深；第一次出现的新概念、新工具、新命令、新参数必须解释清楚；适当添加图片辅助讲解。
• 可运行代码：工程目录创建、依赖安装、代码开发、脚本运行等操作在 code cell 中执行，学习者无需手动打开其他文件夹。
• 课后实践：实践题的代码开发、编译执行等操作在 code cell 中执行；待填写文件通过 %%writefile 命令写入；答案通过 cat 命令展示。
• 源码查看：源码较多放入 src 时，notebook 中通过 cat、tree、ls 等命令展示关键源码结构与内容。

5.6 在 WebIDE 中编辑 Notebook

在左侧资源管理器中找到并双击 .ipynb 文件即可在 Notebook 编辑器中打开，通过顶部工具栏新增单元格编写内容：

• +Code：新增 code cell，用于添加可执行代码。
• +Markdown：新增 markdown cell，用于添加文字说明、图片、表格等。

---

6. 提交代码

在终端中执行以下命令，将开发内容提交到个人 fork 仓库的 test 分支：

git add .
git commit -m "feat: 新增<课程名称>课程"
git push origin test

提交信息建议遵循 Conventional Commits 规范，例如 feat: 新增yolov3推理课程、docs: 补充课程README。

---

7. 运行验证

课程提交前 必须 在课程要支持的环境中完成实际运行验证，确保所有 Notebook 可从上到下顺序执行且不报错。根据课程声明的在线体验环境，分为：

• gitcode 在线 Notebook 环境：在 gitcode 在线 Notebook 中完成运行验证。
• CANNLab 环境：在 CANNLab 云开发环境（或 950 尝鲜体验环境）中完成运行验证。

7.1 打开 Notebook

运行验证前，需先在对应支持环境中打开课程 Notebook。

7.1.1 在 gitcode 在线 Notebook 环境中打开

点击gitcode在线体验链接进入 Notebook 在线体验环境。

进入环境后，点击页签右侧的加号：

在弹出菜单中选择打开 Terminal 终端界面：

在终端中执行以下命令，克隆个人 fork 仓库并切换到 test 分支：

cd
rm -rf cann-learning-hub/
git clone https://gitcode.com/<your_username>/cann-learning-hub.git
cd cann-learning-hub/
git checkout test

从左侧菜单栏点击进入 cann-learning-hub 仓库，即可在 Notebook 中查看并打开个人 fork 仓库 test 分支下的新增课程内容：

7.1.2 在 CANNLab 环境中打开

按照本指南第 3 节创建并进入 CANNLab 云开发环境，通过 WebIDE 在左侧资源管理器中双击课程 .ipynb 文件即可打开 Notebook。

7.2 逐 cell 执行验证

7.2.1 注册 Jupyter 内核

在终端中依次执行以下命令，注册 Python 3.11.4 (CANN) 内核：

# 安装 ipykernel（如已安装会提示 already satisfied，忽略即可）
/opt/buildtools/Python-3.11.4/bin/python3.11 -m pip install ipykernel
# 注册内核
/opt/buildtools/Python-3.11.4/bin/python3.11 -m ipykernel install --user \
  --name cann_py311 \
  --display-name "Python 3.11.4 (CANN)"

7.2.2 设置环境变量自动加载

创建 usercustomize.py，让 Python 启动时自动设置 CANN 环境变量：

# 获取 CANN 路径
CANN_PATH=$(echo $ASCEND_TOOLKIT_HOME)
mkdir -p ~/.local/lib/python3.11/site-packages
cat > ~/.local/lib/python3.11/site-packages/usercustomize.py << EOF
import os
os.environ.setdefault('ASCEND_OPP_PATH', '${CANN_PATH}/opp')
os.environ.setdefault('ASCEND_TOOLKIT_HOME', '${CANN_PATH}')
os.environ.setdefault('ASCEND_HOME_PATH', '${CANN_PATH}')
os.environ.setdefault('ASCEND_AICPU_PATH', '${CANN_PATH}')
EOF

7.2.3 关机重新开机并执行验证

完成上述配置后，关机并重新开机，使内核与环境变量配置生效。开机后通过 WebIDE 重新进入环境，打开每个 .ipynb 文件，在右上角 选择内核，选择 Python 3.11.4 (CANN)：

内核选择完成后，从第一个 code cell 开始依次点击运行按钮，确认：

• 每个 code cell 均能正常执行，无报错。
• 运行结果与预期一致。
• Kernel 不会中断或重启。

执行 code cell 及成功结果示意：

7.3 验证记录

在 PR 描述中需要说明：

• 验证使用的硬件型号（如 NPU 910B3）。
• 运行环境（如 CANNLab 云开发环境，模板及规格）。
• 验证结果（所有 Notebook 运行通过 / 存在的已知问题）。

7.4 多硬件验证

若课程同时支持多种硬件，需在每种硬件对应的体验环境中分别完成运行验证：

课程支持硬件	验证环境	验证要求
A2 / A3	CANNLab 云开发环境	所有 Notebook 可从上到下顺序执行且不报错。
A5	CANNLab 950 尝鲜体验环境	所有 Notebook 可从上到下顺序执行且不报错。
A2	gitcode 在线 Notebook 环境	所有 Notebook 可从上到下顺序执行且不报错。

验证完成后，在 PR 描述中按硬件型号分别说明：

• 验证使用的硬件型号（如 NPU 910B3、NPU 950）。
• 运行环境（如 CANNLab 云开发环境、950 尝鲜体验环境、gitcode 在线 Notebook 环境）。
• 各环境下的验证结果（所有 Notebook 运行通过 / 存在的已知问题）。

仅支持单一硬件的课程，完成对应环境验证即可，无需多硬件验证。

---

8. PR 提交与准入自检

8.1 提交前自检

提 PR 前，请完成以下自检工作，确保课程达到可对外展示的发布级水准：

1. AI 低错检查：使用 AI 工具检查拼写、格式、语法、链接等低级错误。
2. Checklist 自检：逐项对照 PR 准入 Checklist 完成自检，全部通过后方可发起 PR。
3. 在线体验环境验证：在课程支持的在线体验环境中完整执行所有 Notebook，确保运行正确、无报错。
4. 同步主 README：更新仓库根目录 README 中的课程简介、学习人群、硬件产品、环境配置、章节目录等信息。

8.2 发起 PR

1. 在 GitCode 上进入个人 fork 仓库页面，切换到 test 分支。
2. 点击 发起 Pull Request。
3. 目标仓库 选择 cann/cann-learning-hub，目标分支 选择 test。
4. 按照 PR 模板填写以下内容：
   • 描述：本次改动的背景、目的与方案。
   • 测试：说明运行验证情况（硬件型号、环境、验证结果）。
   • 文档更新：如涉及 README 等文档更新请说明。
   • 类型标签：勾选 新特性 或对应类型。
5. 提交 PR。

---

9. 课程上线流程

课程从开发到正式发布，按照"设计开发 → 合入 test 分支 → 优化打磨 → 合入 master 分支"四个阶段推进。完整流程共 8 个步骤，各步骤的核心任务、责任方和验收关注点详见 新课程上库与上线验收标准。

简要流程如下：

阶段	步骤	核心任务	责任方
设计开发	1. 课程大纲设计与评审	设计课程大纲并完成内部分层评审	课程组
	2. 课程内容开发与验证	开发教程内容并本地验证通过	课程组
合入 test	3. 提 PR 到 test 分支	完成质量自检后提 PR	课程组
	4. 合入 test 分支	审核内容质量与低错，通过后合入	课程组长、Committer
优化打磨	5. 内测（持续打磨）	在 test 分支上持续完善课程内容	课程组
合入 master	6. 提 PR 到 master 分支	选择性合并 test 分支内容到 master	课程组
	7. 公测（体验 & 评审）	评审团队在线体验并评论，课程组逐条闭环	评审团队、Committer、课程组
	8. 上线 master 分支	Committer 审核通过，合入 master 并发布	Committer

test → master 合并操作指引：步骤 6 中如何选择性合并 test 分支内容到 master 分支，详见 附录二：test → master 选择性合并操作指引。

---

10. 响应评审与迭代修改

10.1 test 分支评审（步骤 3-4）

PR 提交后，课程组组长与 Committer 会依据准入 Checklist 进行评审。评审意见会在 PR 评论中给出。

如需修改，在原开发环境（CANNLab 云开发环境）中继续开发。若使用 CANNLab 环境，环境关机后重新开机并进入即可，代码已保存在 fork 仓库。拉取最新代码：

cd cann-learning-hub
git checkout test
git pull origin test

修改完成后再次到对应环境运行验证，然后推送更新：

git add .
git commit -m "fix: 根据评审意见修改<具体内容>"
git push origin test

推送后 PR 会自动更新，在 PR 评论中回复评审意见并说明修改情况。

10.2 master 分支公测（步骤 7-8）

课程合入 master 分支后，评审团队在线体验并评论，Committer 执行验证。如需修改，流程与 10.1 相同，在开发环境中修改后推送到 master 分支即可。

---

11. 常见问题

Q1：课程应该提交到 test 分支还是 master 分支？

所有课程 PR 统一提交到 test 分支，经内测闭环后再由课程组提 PR 合入 master。具体流程见 课程上线流程。

Q2：如何选择 CANNLab 环境规格？

根据课程目标硬件选择：A2/A3 选择 云开发环境，A5 选择 950 尝鲜体验环境。具体规格以课程 README 中声明的支持硬件为准。

Q3：环境关机后代码会丢失吗？

已 commit 并 push 到 fork 仓库的代码不会丢失。CANNLab 环境关机仅释放计算资源，重新开机后可继续开发；但未提交的本地修改需重新创建，建议频繁提交并 push。

Q4：课程中需要使用第三方数据集怎么办？

在文档中说明数据集的下载方式与使用方法即可，无需直接提供数据集。

---

12. 相关文档

文档	说明
贡献指南	项目整体贡献流程与要求。
新课程上库与上线验收标准	课程上线流程、目录结构规范、PR 准入 Checklist、test → master 合并操作指引等。
CANNLab 环境体验指南	CANNLab 云开发环境的体验流程（面向学习者）。