祝融说。 Ascend Docker Kit (ADK)

Ascend Docker Kit (ADK)

2026.01.18

DevOps toolkit for Huawei Ascend NPU environment, automating Docker environment configuration to resolve compatibility issues among CANN, drivers, and frameworks.

Project Overview

In the Huawei Ascend NPU environment, complex dependencies exist between CANN versions, driver versions, and PyTorch/MindSpore versions. ADK resolves this issue through the following core features:

Compatibility Matrix Library: Structuring fragmented version compatibility information from Huawei’s official documentation into a single data source
Environment Diagnostician: Automatically detecting the host environment (NPU model, driver version, operating system)
Intelligent Recommendation: Automatically recommending compatible CANN and framework versions based on the current environment

Features

Feature	Description
Environment Detection	Automatically detects NPU model (910A/910B/310P), driver version, and OS distribution
Compatibility Verification	Verifies whether the current environment supports the target CANN version
Version Recommendation	Recommends the optimal CANN and framework combination based on driver version
Framework Configuration	Retrieves the corresponding torch_npu version and installation method for PyTorch/MindSpore

Supported Environments

NPU Models: Atlas 910A / 910B / 910B2 / 910B3 / 310P / 310

Operating Systems: Ubuntu 20.04/22.04/24.04, openEuler 22.03/24.03, Kylin V10

CPU Architectures: x86_64, aarch64

Quick Start

Installation

# Clone the repository
git clone https://github.com/iannil/ascend-docker-kit.git
cd ascend-docker-kit

# Install dependencies
pip install -r requirements.txt

Basic Usage

1. Detect Host Environment

from adk_core import EnvironmentAnalyzer

# Automatically detect environment
env = EnvironmentAnalyzer.analyze()

print(f"Operating System: {env.os_name}")
print(f"CPU Architecture: {env.arch}")
print(f"NPU Model: {env.npu_type}")
print(f"NPU Count: {env.npu_count}")
print(f"Driver Version: {env.driver_version}")

Sample output:

Operating System: ubuntu22.04
CPU Architecture: x86_64
NPU Model: 910B
NPU Count: 8
Driver Version: 24.1.rc1

2. Verify Environment Compatibility

from adk_core import EnvironmentAnalyzer, CompatibilityResolver

# Detect environment
env = EnvironmentAnalyzer.analyze()

# Load compatibility matrix
resolver = CompatibilityResolver.from_yaml('data/compatibility.yaml')

# Validate compatibility
result = resolver.validate_environment(env)

if result.valid:
    print(f"Compatible CANN versions: {result.compatible_cann_versions}")
else:
    print(f"Error: {result.errors}")

3. Query Framework Configuration

from adk_core import CompatibilityResolver

resolver = CompatibilityResolver.from_yaml('data/compatibility.yaml')

# Get PyTorch configuration for CANN 8.0.0
config = resolver.get_framework_config("8.0.0", "pytorch")

print(f"PyTorch Version: {config.version}")
print(f"torch_npu Version: {config.torch_npu_version}")
print(f"Supported Python Versions: {config.python_versions}")
print(f"Download URL: {config.whl_url}")

4. Get Recommended Versions

from adk_core import CompatibilityResolver

resolver = CompatibilityResolver.from_yaml('data/compatibility.yaml')

# Get recommended CANN version based on driver version
recommended = resolver.get_recommended_cann(
    driver_version="24.1.0",
    os_name="ubuntu22.04",
    npu_type="910B"
)

print(f"Recommended CANN version: {recommended}")  # 8.0.0

Shell Script Detection

You can also use the shell script to detect NPU information directly:

bash scripts/check_npu.sh

Output in JSON format:

{
  "status": "ok",
  "driver_version": "24.1.rc1",
  "npu_count": 8,
  "npus": [{"id": 0, "type": "910B"}, {"id": 1, "type": "910B"}]
}

API Reference

EnvironmentAnalyzer

Environment detector that gathers host environment information.

Method	Description	Return Value
`analyze()`	Full environment detection	`EnvironmentInfo`
`analyze_safe()`	Safe mode (does not raise exceptions)	`(EnvironmentInfo, List[str])`
`detect_os()`	Detect operating system	`str`
`detect_arch()`	Detect CPU architecture	`str`
`detect_npu()`	Detect NPU information	`Dict`

CompatibilityResolver

Compatibility query tool for retrieving version compatibility information.

Method	Description
`from_yaml(path)`	Create instance from YAML file
`list_cann_versions()`	List all CANN versions
`find_compatible_cann(driver_version)`	Find compatible CANN versions
`get_recommended_cann(driver_version)`	Get recommended CANN version
`validate_environment(env)`	Validate environment compatibility
`get_framework_config(cann_version, framework)`	Retrieve framework configuration

Data Models

class EnvironmentInfo:
    driver_version: str   # NPU driver version
    os_name: str          # Operating system (e.g., ubuntu22.04)
    npu_type: str         # NPU model (e.g., 910B)
    arch: str             # CPU architecture (x86_64/aarch64)
    npu_count: int        # Number of NPUs
    firmware_version: Optional[str]  # Firmware version

class ValidationResult:
    valid: bool                        # Whether valid
    compatible_cann_versions: List[str]  # List of compatible CANN versions
    errors: List[str]                  # Error messages
    warnings: List[str]                # Warning messages

Exception Classes

Exception	Description
`EnvironmentDetectionError`	Environment detection failed
`DriverNotInstalledError`	NPU driver not installed
`NPUNotDetectedError`	No NPU device detected
`VersionNotFoundError`	Version not found
`DriverIncompatibleError`	Driver version incompatible
`OSNotSupportedError`	Operating system not supported
`NPUNotSupportedError`	NPU model not supported

Project Structure

ascend-docker-kit/
├── adk_core/                    # core library
│   ├── __init__.py              # module exports
│   ├── analyzer.py              # environment analyzer
│   ├── matrix.py                # compatibility resolver
│   ├── models.py                # data models
│   ├── exceptions.py            # exception definitions
│   └── version.py               # version utilities
├── data/
│   └── compatibility.yaml       # compatibility matrix data
├── scripts/
│   └── check_npu.sh             # NPU detection script
├── tests/                       # unit tests
│   ├── test_analyzer.py
│   └── test_matrix.py
├── docs/                        # documentation
├── requirements.txt             # dependencies
└── README.md

Compatibility Matrix

Compatibility data is stored in data/compatibility.yaml, containing the following CANN versions:

CANN Version	Minimum Driver Version	PyTorch	MindSpore	Status
8.0.0	24.1.rc1	2.4.0	2.3.0	Stable
8.0.0rc3	24.1.rc1	2.3.1	2.2.14	RC
7.0.0	23.0.3	2.1.0	2.2.0	Deprecated
6.3.0	22.0.4	1.11.0	1.10.1	Deprecated

Development Guide

Running Tests

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/ -v

Adding a New CANN Version

Edit data/compatibility.yaml to add the new version configuration:

cann_versions:
  "8.1.0":
    min_driver_version: "24.2.0"
    supported_os:
      - ubuntu22.04
      - ubuntu24.04
    supported_npu:
      - 910B
      - 910B3
    supported_arch:
      - x86_64
      - aarch64
    frameworks:
      pytorch:
        version: "2.5.0"
        torch_npu_version: "2.5.0.post1"
        python_versions: ["3.9", "3.10", "3.11"]
    deprecated: false

Acknowledgments

Thank you to the Huawei Ascend team for providing official documentation and technical support.

writings

祝融说。