diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 5f4bfb4..9cfd18a 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -146,3 +146,32 @@ jobs: set -x df -h docker images -a + + push-readme: + name: Push README + runs-on: ubuntu-latest + needs: prepare + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Push README to DockerHub + if: ${{ github.event_name == 'release' }} + uses: christian-korneck/update-container-description-action@v1 + env: + DOCKER_USER: ${{ secrets.DOCKER_USERNAME }} + DOCKER_PASS: ${{ secrets.DOCKER_TOKEN }} + with: + destination_container_repo: ascendai/cann + provider: dockerhub + readme_file: 'README.md' + + - name: Push README to Quay.io + if: ${{ github.event_name == 'release' }} + uses: christian-korneck/update-container-description-action@v1 + env: + DOCKER_APIKEY: ${{ secrets.APIKEY__QUAY_IO }} + with: + destination_container_repo: quay.io/ascend/cann + provider: quay + readme_file: 'README.md' diff --git a/README.md b/README.md index 03eeee8..b126a10 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,30 @@ -# Quick reference +## Quick reference +- The offical Ascend CANN docker images +- Where to get help: [Ascend Community](https://www.hiascend.com/forum/) -- **Where to get help**: - [Ascend Community](https://www.hiascend.com/forum/) +## CANN +CANN (Compute Architecture for Neural Networks) is a heterogeneous computing architecture launched by Ascend for AI scenarios. It supports multiple AI frameworks and serves AI processors and programming. It plays a key role in connecting the upper and lower levels and is a key platform for improving the computing efficiency of Ascend AI processors. At the same time, it provides efficient and easy-to-use programming interfaces for diverse application scenarios, supporting users to quickly build AI applications and businesses based on the Ascend platform.
+
+Ascend-CANN image is based on Ubuntu OS or openEuler OS, and integrates system packages, Python and CANN (Toolkit development kit package, Kernels operator package, NNAL acceleration library). Users can install the artificial intelligence framework based on this basic image according to actual needs and run the corresponding business programs. -- **Where to file issues**: - https://github.com/Ascend/cann-container-image/issues - -- **Published image artifact details**: - - the `remote` directory: - - gathered from the [AscendHub](https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884)/[DockerHub](https://hub.docker.com/r/ascendai/cann/tags)/[Quay.io](https://quay.io/repository/ascend/cann?tab=tags) - - - image digests/blobs, transfer sizes, image metadata, etc. - - - the `local` directory: - - - inspected from the image on-disk after it is pulled - - - installed packages, creation date, architecture, environment variables, detected licenses, etc. - -# Supported tags and respective `Dockerfile` links +## Supported tags and respective Dockerfile links +The tag of each Ascend CANN docker image is consist of the version of CANN and the version of basic image. The details are as follows +- [`8.1.RC1.alpha002-910b-openeuler24.03-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha002-910b-openeuler24.03-py3.10/Dockerfile) +- [`8.1.RC1.alpha002-910b-ubuntu24.04-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha002-910b-ubuntu24.04-py3.10/Dockerfile) - [`8.1.RC1.alpha001-910b-openeuler22.03-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha001-910b-openeuler22.03-py3.10/Dockerfile) - [`8.1.RC1.alpha001-910b-ubuntu22.04-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha001-910b-ubuntu22.04-py3.10/Dockerfile) -# What is CANN? - -CANN (Compute Architecture for Neural Networks) is a heterogeneous computing architecture launched by Ascend for AI scenarios. It supports multiple AI frameworks and serves AI processors and programming. It plays a key role in connecting the upper and lower levels and is a key platform for improving the computing efficiency of Ascend AI processors. At the same time, it provides efficient and easy-to-use programming interfaces for diverse application scenarios, supporting users to quickly build AI applications and businesses based on the Ascend platform. - -## Online Documentation - -You can find the latest CANN documentation, including a programming guide, on the [project web page](https://www.hiascend.com/software/cann). This README file only contains basic setup instructions. - ## Usage -Assuming your NPU device is mounted at `/dev/davinci1` and your NPU driver is installed at `/usr/local/Ascend`: +### Quick start 1: supported devices +- Atlas A2 Training series (Atlas 800T A2, Atlas 900 A2 PoD, Atlas 200T A2 Box16, Atlas 300T A2) +- Atlas 800I A2 Inference series (Atlas 800I A2) -```docker +### Quick start 2: setup environment using container + +```bash +# Assuming your NPU device is mounted at /dev/davinci1 and your NPU driver is installed at /usr/local/Ascend: docker run \ --name cann_container \ --device /dev/davinci1 \ @@ -47,23 +36,25 @@ docker run \ -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ - -it ascendai/cann:latest bash + -it ascend/cann:tag bash ``` -## Build - -Run the following command in the root directory: +### Note: +Configure the abi parameter when executing the CANN environment variable script `/usr/local/Ascend/nnal/atb/set_env.sh`:
+
+**Automatic configuration**: When executing the set_env.sh script, if no parameters are added and the PyTorch environment has been detected, the `torch.compiled_with_cxx11_abi()` interface will be automatically called to automatically select the abi parameter when PyTorch is compiled as the abi parameter of ATB. If the PyTorch environment is not detected, abi=1 is configured by default.
+
+**Manual configuration**: When executing `set_env.sh`, users are supported to specify the abi parameter of ATB through the `--cxx_abi=1` and `--cxx_abi=0` parameters.
+
+In CANN 8.1.RC1.alpha002 and later versions of the image, use ENV to define ATB's `abi=1` (by default, it is processed as if no PyTorch environment is detected), and re-source `/usr/local/Ascend/nnal/atb/set_env.sh` when starting the container in Bash Shell mode to ensure that the value of the abi parameter is correct. However, if you start the container in other ways, the value of abi is 1. If it does not meet the requirements, you can manually specify the abi parameter value of ATB. -```docker -docker build \ - -t ascendai/cann:latest \ - -f cann/tag/dockerfile -``` +## Question and answering +If you don't find the CANN image you want or find any problems when using the image, please feel free to file an [issue](https://github.com/Ascend/cann-container-image/issues). -# License -Licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). +## License +[Apache License, Version 2.0](https://github.com/Ascend/cann-container-image/blob/main/LICENSE) -As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained). +As with all Docker images, these images may also contain other software that may be subject to other licenses (such as Bash in the base distribution, and any direct or indirect dependencies of the included main software). -As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within. \ No newline at end of file +For any use of the pre-built image, it is the image user's responsibility to ensure that any use of this image complies with the relevant licenses of all software contained in it. \ No newline at end of file diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000..b50960f --- /dev/null +++ b/README_CN.md @@ -0,0 +1,59 @@ +## 快速开始 +- 官方的 CANN Ascend docker镜像 +- 如何获取帮助：[Ascend Community](https://www.hiascend.com/forum/) + +## CANN +CANN（Compute Architecture for Neural Networks）是昇腾针对AI场景推出的异构计算架构，对上支持多种AI框架，对下服务AI处理器与编程，发挥承上启下的关键作用，是提升昇腾AI处理器计算效率的关键平台。同时针对多样化应用场景，提供高效易用的编程接口，支持用户快速构建基于昇腾平台的AI应用和业务。
+
+Ascend-CANN镜像，基于Ubuntu OS或openEuler OS，内部集成系统包、Python和CANN （Toolkit开发套件包、Kernels算子包、NNAL加速库）制作。用户根据实际需要，基于该基础镜像安装人工智能框架，即可运行相应业务程序。 + +## 支持的tags和相应的Dockerfile链接 +每个CANN镜像的tag由CANN版本号和基础镜像版本号组成，具体如下 + +- [`8.1.RC1.alpha002-910b-openeuler24.03-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha002-910b-openeuler24.03-py3.10/Dockerfile) +- [`8.1.RC1.alpha002-910b-ubuntu24.04-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha002-910b-ubuntu24.04-py3.10/Dockerfile) +- [`8.1.RC1.alpha001-910b-openeuler22.03-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha001-910b-openeuler22.03-py3.10/Dockerfile) +- [`8.1.RC1.alpha001-910b-ubuntu22.04-py3.10`](https://github.com/Ascend/cann-container-image/blob/main/cann/8.1.RC1.alpha001-910b-ubuntu22.04-py3.10/Dockerfile) + +## 使用方法 + +### 快速入门：支持的设备 +- Atlas A2训练系列 (Atlas 800T A2, Atlas 900 A2 PoD, Atlas 200T A2 Box16, Atlas 300T A2) +- Atlas 800I A2推理系列 (Atlas 800I A2) + +### 快速入门：使用容器设置环境 + +```bash +# 假设您的NPU设备安装在/dev/davinci1上，并且您的NPU驱动程序安装在/usr/local/Ascend上： +docker run \ + --name cann_container \ + --device /dev/davinci1 \ + --device /dev/davinci_manager \ + --device /dev/devmm_svm \ + --device /dev/hisi_hdc \ + -v /usr/local/dcmi:/usr/local/dcmi \ + -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ + -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \ + -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ + -v /etc/ascend_install.info:/etc/ascend_install.info \ + -it ascend/cann:tag bash +``` +### 说明： +执行CANN环境变量脚本`/usr/local/Ascend/nnal/atb/set_env.sh`时配置abi参数：
+
+**自动配置**：执行set_env.sh脚本时，若不加任何参数，且已检测到PyTorch环境时会自动调用`torch.compiled_with_cxx11_abi()`接口，自动选择PyTorch编译时abi参数作为ATB的abi参数，如果没有检测到PyTorch环境则默认配置`abi=1`。
+
+**手动配置**：执行set_env.sh时，支持用户通过`--cxx_abi=1`和`--cxx_abi=0`参数指定ATB的abi参数。
+
+在CANN 8.1.RC1.alpha002及以后版本的镜像中，使用ENV定义ATB的`abi=1`(默认按照没有检测到PyTorch环境处理)，并在以Bash Shell方式启动容器时`source /usr/local/Ascend/nnal/atb/set_env.sh`，确保abi参数的值正确。但若您以其他方式启动容器，abi的值为1，若不满足要求，您可手动自行指定ATB的abi参数值。 + +## 问答 +若您没有找到想要的CANN镜像或者在使用镜像时发现任何问题，请随时向我们提出[issue](https://github.com/Ascend/cann-container-image/issues)。 + + +## 许可证 +[Apache License, Version 2.0](https://github.com/Ascend/cann-container-image/blob/main/LICENSE) + +与所有 Docker 镜像一样，这些镜像可能还包含其他可能受其他许可证约束的软件（例如基础发行版中的 Bash 等，以及所包含主要软件的任何直接或间接依赖项）。 + +对于任何预构建镜像的使用，镜像用户有责任确保此镜像的任何使用均符合其中包含的所有软件的相关许可证。 \ No newline at end of file