Star1118
1174
代码
代码
Issues123
Pull Requests363
Actions
项目讨论
Wiki
分析
Star1118
1174
已合并
docs: optimize devcontainer configuration and documentation #1567
zhugexun_sjtu创建于 4月13日
docs: optimize devcontainer configuration and documentation #1567
已合并
zhugexun_sjtu创建于 4月13日
从xun_zhuge/asc-devkitquick_start_opt合入到cann/asc-devkitmaster
共 3 个文件变更+131-71
M.devcontainer/Dockerfile+5-18
@@ -1,22 +1,5 @@
1# Build:1# Build:
2-# docker buildx build --network host -t ascendc:ubuntu24.04 .2+# docker buildx build --network host -t ascendc:ubuntu24.04 .devcontainer/
3-#
4-# Run (standalone, without devcontainer):
5-# docker run -it --runtime=runc --privileged \
6-# --net=host --pid=host --ipc=host \
7-# --cap-add=SYS_PTRACE \
8-# -e ASCEND_VISIBLE_DEVICES=all \
9-# --device=/dev/davinci_manager \
10-# --device=/dev/devmm_svm \
11-# --device=/dev/hisi_hdc \
12-# -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
13-# -v /usr/local/Ascend/add-ons:/usr/local/Ascend/add-ons:ro \
14-# -v /usr/local/dcmi:/usr/local/dcmi:ro \
15-# -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi:ro \
16-# -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
17-# -v /var/log/npu:/var/log/npu \
18-# -v /usr/slog:/usr/slog \
19-# ascendc:ubuntu24.04
20#3#
21# Mirror sources (override with --build-arg):4# Mirror sources (override with --build-arg):
22# APT_MIRROR: mirrors.huaweicloud.com (default) | mirrors.tuna.tsinghua.edu.cn | mirrors.ustc.edu.cn5# APT_MIRROR: mirrors.huaweicloud.com (default) | mirrors.tuna.tsinghua.edu.cn | mirrors.ustc.edu.cn
@@ -140,6 +123,10 @@ echo "██║ ██║███████║╚██████╗██
140echo "╚═╝ ╚═╝╚══════╝ ╚═════╝╚══════╝╚═╝ ╚═══╝╚═════╝ ╚═════╝"\n\123echo "╚═╝ ╚═╝╚══════╝ ╚═════╝╚══════╝╚═╝ ╚═══╝╚═════╝ ╚═════╝"\n\
141echo "\\033[0m"\n' >> /root/.zshrc124echo "\\033[0m"\n' >> /root/.zshrc
142 125 
126+# Ascend driver environment
127+RUN printf '\n[ -f /usr/local/Ascend/driver/bin/setenv.bash ] && source /usr/local/Ascend/driver/bin/setenv.bash\n' \
128+ >> /root/.zshrc
129+ 
143RUN rm -rf /tmp/*130RUN rm -rf /tmp/*
144 131 
145WORKDIR /root132WORKDIR /root
M.devcontainer/README.md+114-35
@@ -4,15 +4,12 @@ Ubuntu 24.04 development environment for AscendC NPU kernel development.
4 4 
5## Prerequisites5## Prerequisites
6 6 
7-| Requirement | Version |7+| Requirement | With NPU | Without NPU |
8-|-------------|---------|8+|-------------|----------|-------------|
9-| Docker | ≥ 23.0.0 |9+| Docker ≥ 23.0.0 | required | required |
10-| docker buildx | any |10+| docker buildx | required | required |
11-| Ascend driver | installed on host |11+| Ascend driver on host (`/usr/local/Ascend/driver`) | required | not needed |
12- 12+| NPU device nodes (`/dev/davinciN`, etc.) | required | not needed |
13-> The Ascend **driver** is installed on the host and mounted read-only into the container (`/usr/local/Ascend/driver`, `/usr/local/Ascend/add-ons`).
14->
15-> The **CANN toolkit and ops packages** should be installed inside the container, not on the host. Installing CANN on the host risks overwriting a shared environment when multiple developers use the same machine. After opening the container, install the matching CANN packages **manually**.
16 13 
17Check your Docker version:14Check your Docker version:
18```bash15```bash
@@ -28,6 +25,8 @@ curl -fsSL "https://github.com/docker/buildx/releases/latest/download/buildx-lin
28chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx25chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx
29```26```
30 27 
28+> The Ascend **driver** directory (`/usr/local/Ascend/driver`) is mounted read-only into the container. The **CANN toolkit and ops packages** should be installed inside the container after startup — not on the host. Installing CANN on the host risks overwriting a shared environment.
29+ 
31## Build the Image30## Build the Image
32 31 
33> **Build time:** approximately 5 minutes on a typical connection. The dominant cost is downloading the conda environment and PyTorch. Subsequent rebuilds hit the Docker layer cache and complete in seconds if only non-package layers changed.32> **Build time:** approximately 5 minutes on a typical connection. The dominant cost is downloading the conda environment and PyTorch. Subsequent rebuilds hit the Docker layer cache and complete in seconds if only non-package layers changed.
@@ -36,7 +35,104 @@ chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx
36docker buildx build --network host -t ascendc:ubuntu24.04 .devcontainer/35docker buildx build --network host -t ascendc:ubuntu24.04 .devcontainer/
37```36```
38 37 
39-To override mirror sources:38+## Quick Start (Human Users)
39+ 
40+> If you are an AI agent, skip to [Quick Start (AI Agent)](#quick-start-ai-agent).
41+ 
42+### With NPU
43+ 
44+Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension, then:
45+ 
46+```
47+Ctrl+Shift+P → Dev Containers: Reopen in Container
48+```
49+ 
50+### Without NPU
51+ 
52+Copy `devcontainer.json` to a local override and remove all NPU-specific entries:
53+ 
54+**In `runArgs`**, remove all `--device` lines (davinci0-7, davinci_manager, devmm_svm, hisi_hdc). If you have no other args, set:
55+```jsonc
56+"runArgs": []
57+```
58+ 
59+**In `mounts`**, remove the driver and device-related bind mounts:
60+```
61+source=/usr/local/Ascend/driver,...
62+source=/usr/local/dcmi,...
63+source=/usr/local/bin/npu-smi,...
64+source=/etc/ascend_install.info,...
65+```
66+ 
67+Keep the ccache volume and any data directories you've added. Then reopen in container as normal.
68+ 
69+## Quick Start (AI Agent)
70+ 
71+Agents (e.g. Claude Code, CI runners) can run the container directly without VS Code.
72+ 
73+**Before running the container, confirm the following with the user:**
74+ 
75+1. **Repository path** — where is the project checked out on the host? (default: current directory `$PWD`)
76+2. **Data directories** — are there any additional data directories to mount (e.g. datasets, model weights)?
77+3. **NPU availability** — does the host have Ascend NPUs? (determines which variant to use below)
78+ 
79+Then **show the user the exact `docker run` command** you are about to execute and wait for confirmation before proceeding.
80+ 
81+> Some steps require user action: CANN toolkit and ops packages must be installed inside the container
82+> after startup. Ask the user to provide the CANN package paths or installer commands.
83+ 
84+### With NPU
85+ 
86+```bash
87+docker run -itd --name ascendc_container \
88+ --device=/dev/davinci0 \
89+ --device=/dev/davinci1 \
90+ --device=/dev/davinci2 \
91+ --device=/dev/davinci3 \
92+ --device=/dev/davinci4 \
93+ --device=/dev/davinci5 \
94+ --device=/dev/davinci6 \
95+ --device=/dev/davinci7 \
96+ --device=/dev/davinci_manager \
97+ --device=/dev/devmm_svm \
98+ --device=/dev/hisi_hdc \
99+ -v /usr/local/dcmi:/usr/local/dcmi:ro \
100+ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi:ro \
101+ -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
102+ -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
103+ ascendc:ubuntu24.04
104+```
105+ 
106+If the user has fewer than 8 NPUs, remove the corresponding `--device=/dev/davinciN` lines (use `ls /dev/davinci*` to check the number).
107+ 
108+If the user needs to mount data directories, append each as `-v /host/path:/container/path`.
109+ 
110+### Without NPU
111+ 
112+```bash
113+docker run -itd --name ascendc_container ascendc:ubuntu24.04
114+```
115+ 
116+If the user needs to mount data directories, append each as `-v /host/path:/container/path`.
117+ 
118+> After starting the container, install CANN toolkit and ops packages manually, or automate via a setup script.
119+ 
120+## Python Environments
121+ 
122+One conda environment is pre-installed:
123+ 
124+| Environment | Python | PyTorch |
125+|-------------|--------|---------|
126+| `py312` | 3.12 | 2.7.1 |
127+ 
128+Default active environment is `py312`.
129+ 
130+## Configuration
131+ 
132+### Mirror Sources
133+ 
134+To override mirror sources at build time:
135+ 
40```bash136```bash
41docker buildx build --network host \137docker buildx build --network host \
42 --build-arg APT_MIRROR=mirrors.ustc.edu.cn \138 --build-arg APT_MIRROR=mirrors.ustc.edu.cn \
@@ -53,39 +149,22 @@ Available mirrors:
53| `CONDA_MIRROR` | `mirrors.tuna.tsinghua.edu.cn/anaconda` | `mirrors.tuna.tsinghua.edu.cn/anaconda` | `mirrors.ustc.edu.cn/anaconda` | — |149| `CONDA_MIRROR` | `mirrors.tuna.tsinghua.edu.cn/anaconda` | `mirrors.tuna.tsinghua.edu.cn/anaconda` | `mirrors.ustc.edu.cn/anaconda` | — |
54| `PYPI_MIRROR` | `repo.huaweicloud.com/repository/pypi/simple` | `pypi.tuna.tsinghua.edu.cn/simple` | `pypi.mirrors.ustc.edu.cn/simple` | `repo.huaweicloud.com/repository/pypi/simple` |150| `PYPI_MIRROR` | `repo.huaweicloud.com/repository/pypi/simple` | `pypi.tuna.tsinghua.edu.cn/simple` | `pypi.mirrors.ustc.edu.cn/simple` | `repo.huaweicloud.com/repository/pypi/simple` |
55 151 
56-## Open in VS Code152+### Data Directory
57 153 
58-> If the image has not been built manually, VS Code will build it automatically on first open — expect the same ~5 minute build time.154+The data directory varies per developer. Add your own in `devcontainer.json`:
59- 
60-Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension, then:
61- 
62-```
63-Ctrl+Shift+P → Dev Containers: Reopen in Container
64-```
65- 
66-## Python Environments
67- 
68-One conda environment is pre-installed:
69- 
70-| Environment | Python | PyTorch |
71-|-------------|--------|---------|
72-| `py312` | 3.12 | 2.7.1 |
73- 
74-Default active environment is `py312`.
75- 
76-## Data Directory
77- 
78-The `/data` mount is not included as it varies per developer. Add your own in `devcontainer.json`:
79 155 
80```jsonc156```jsonc
81// mounts157// mounts
82"source=/your/data,target=/your/data,type=bind"158"source=/your/data,target=/your/data,type=bind"
83```159```
84 160 
85-## NPU Devices161+### NPU Device Selection
86 162 
87-`ASCEND_VISIBLE_DEVICES=all` exposes all available NPU cards automatically. Override at runtime if needed:163+Device nodes are passed explicitly with `--device=/dev/davinciN`. If the host has fewer than 8 NPUs, remove the corresponding lines. For example, for a 4-NPU host:
88 164 
89```bash165```bash
90-docker run -e ASCEND_VISIBLE_DEVICES=0,1 ...166+--device=/dev/davinci0 \
167+--device=/dev/davinci1 \
168+--device=/dev/davinci2 \
169+--device=/dev/davinci3 \
91```170```
M.devcontainer/devcontainer.json+12-18
@@ -6,34 +6,28 @@
6 },6 },
7 "remoteUser": "root",7 "remoteUser": "root",
8 8 
9- // --privileged covers davinci compute devices; control devices must be listed explicitly9+ // Explicitly list each davinci compute device and the three control devices.
10- // --runtime=runc avoids conflict with ascend-docker-runtime set as Docker's default runtime
11 "runArgs": [10 "runArgs": [
12- "--runtime=runc",11+ "--device=/dev/davinci0",
13- "--privileged",12+ "--device=/dev/davinci1",
14- "--net=host",13+ "--device=/dev/davinci2",
15- "--pid=host",14+ "--device=/dev/davinci3",
16- "--ipc=host",15+ "--device=/dev/davinci4",
17- "--cap-add=SYS_PTRACE",16+ "--device=/dev/davinci5",
17+ "--device=/dev/davinci6",
18+ "--device=/dev/davinci7",
18 "--device=/dev/davinci_manager",19 "--device=/dev/davinci_manager",
19 "--device=/dev/devmm_svm",20 "--device=/dev/devmm_svm",
20 "--device=/dev/hisi_hdc"21 "--device=/dev/hisi_hdc"
21 ],22 ],
22- "containerEnv": {
23- // Automatically adapts to the actual number of NPU cards
24- "ASCEND_VISIBLE_DEVICES": "all"
25- },
26 23 
27 "mounts": [24 "mounts": [
28 "source=ascendc-ccache,target=/root/.ccache,type=volume",25 "source=ascendc-ccache,target=/root/.ccache,type=volume",
29- "source=/usr/local/Ascend/driver,target=/usr/local/Ascend/driver,type=bind,readonly",
30- "source=/usr/local/Ascend/add-ons,target=/usr/local/Ascend/add-ons,type=bind,readonly",
31 "source=/usr/local/dcmi,target=/usr/local/dcmi,type=bind,readonly",26 "source=/usr/local/dcmi,target=/usr/local/dcmi,type=bind,readonly",
32 "source=/usr/local/bin/npu-smi,target=/usr/local/bin/npu-smi,type=bind,readonly",27 "source=/usr/local/bin/npu-smi,target=/usr/local/bin/npu-smi,type=bind,readonly",
33- "source=/etc/ascend_install.info,target=/etc/ascend_install.info,type=bind,readonly",28+ "source=/usr/local/Ascend/driver,target=/usr/local/Ascend/driver,type=bind,readonly",
34- "source=/var/log/npu,target=/var/log/npu,type=bind",29+ "source=/etc/ascend_install.info,target=/etc/ascend_install.info,type=bind,readonly"
35- "source=/usr/slog,target=/usr/slog,type=bind"30+ // Add your own data directory, e.g.: "source=/data,target=/data,type=bind"
36- // Add your own data directory, e.g.: "source=/your/data,target=/your/data,type=bind"
37 ],31 ],
38 32 
39 "customizations": {33 "customizations": {