{"id":50798073,"url":"https://github.com/iannil/ascend-docker-kit","last_synced_at":"2026-06-12T16:04:10.487Z","repository":{"id":333272148,"uuid":"1136704964","full_name":"iannil/ascend-docker-kit","owner":"iannil","description":"A DevOps toolkit for Huawei Ascend NPU environments that automates Docker environment configuration and resolves CANN/driver/framework version compatibility issues.","archived":false,"fork":false,"pushed_at":"2026-02-02T03:08:55.000Z","size":154,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-02T14:23:59.911Z","etag":null,"topics":["ascend","devops","huawei","npu","toolkit"],"latest_commit_sha":null,"homepage":"https://zhurongshuo.com/products/ascend-docker-kit/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iannil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T07:25:48.000Z","updated_at":"2026-02-02T03:08:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iannil/ascend-docker-kit","commit_stats":null,"previous_names":["iannil/ascend-docker-kit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iannil/ascend-docker-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iannil%2Fascend-docker-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iannil%2Fascend-docker-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iannil%2Fascend-docker-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iannil%2Fascend-docker-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iannil","download_url":"https://codeload.github.com/iannil/ascend-docker-kit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iannil%2Fascend-docker-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34251782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascend","devops","huawei","npu","toolkit"],"created_at":"2026-06-12T16:04:09.576Z","updated_at":"2026-06-12T16:04:10.482Z","avatar_url":"https://github.com/iannil.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ascend Docker Kit (ADK)\n\nA DevOps toolkit for Huawei Ascend NPU environments that automates Docker environment configuration and resolves complex CANN/driver/framework version compatibility issues.\n\n[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green)](LICENSE)\n\n[中文文档](README.zh-CN.md)\n\n---\n\n## Why ADK?\n\nIn Ascend NPU environments, complex dependencies exist between CANN versions, driver versions, and PyTorch/MindSpore versions. A wrong combination can lead to cryptic errors or silent failures. ADK solves this problem by:\n\n- **Structuring Compatibility Data**: Converting scattered Huawei documentation into a single source of truth\n- **Auto-detecting Environment**: Probing host NPU model, driver version, and OS automatically\n- **Smart Recommendations**: Suggesting compatible CANN and framework versions for your setup\n- **Generating Docker Builds**: Creating ready-to-use Dockerfiles with proper multi-stage builds\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| Environment Detection | Auto-detect NPU model (910A/910B/310P), driver version, OS distribution |\n| Compatibility Validation | Verify if current environment supports target CANN version |\n| Version Recommendation | Recommend optimal CANN and framework combinations based on driver |\n| Dockerfile Generation | Generate multi-stage Dockerfiles for training/inference |\n| CLI Interface | Full-featured command-line tool for all operations |\n\n### Supported Environments\n\n| Category | Supported Values |\n|----------|------------------|\n| **NPU Models** | Atlas 910A, 910B, 910B2, 910B3, 310P, 310 |\n| **Operating Systems** | Ubuntu 20.04/22.04/24.04, openEuler 22.03/24.03, Kylin V10 |\n| **CPU Architectures** | x86_64, aarch64 |\n| **Frameworks** | PyTorch (with torch_npu), MindSpore |\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/iannil/ascend-docker-kit.git\ncd ascend-docker-kit\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n## Quick Start\n\n### CLI Usage\n\nADK provides a comprehensive CLI for all operations:\n\n```bash\n# Show help\npython adk.py --help\n\n# Diagnose current environment\npython adk.py diagnose\npython adk.py diagnose --validate  # With compatibility check\npython adk.py diagnose --json      # JSON output\n\n# Query CANN versions\npython adk.py query cann           # List all versions\npython adk.py query cann 8.0.0     # Details for specific version\npython adk.py query cann --all     # Include deprecated versions\n\n# Query framework configuration\npython adk.py query framework 8.0.0 pytorch\npython adk.py query framework 8.0.0 mindspore\n\n# Validate environment for specific CANN version\npython adk.py validate 8.0.0\n\n# Generate Dockerfile and build scripts\npython adk.py build init \\\n  --cann 8.0.0 \\\n  --framework pytorch \\\n  --target train \\\n  --python 3.10 \\\n  -o ./build\n```\n\n### Python API\n\n#### 1. Detect Host Environment\n\n```python\nfrom adk_core import EnvironmentAnalyzer\n\n# Auto-detect environment\nenv = EnvironmentAnalyzer.analyze()\n\nprint(f\"OS: {env.os_name}\")\nprint(f\"CPU Architecture: {env.arch}\")\nprint(f\"NPU Model: {env.npu_type}\")\nprint(f\"NPU Count: {env.npu_count}\")\nprint(f\"Driver Version: {env.driver_version}\")\n```\n\nExample output:\n\n```\nOS: ubuntu22.04\nCPU Architecture: x86_64\nNPU Model: 910B\nNPU Count: 8\nDriver Version: 24.1.rc1\n```\n\n#### 2. Validate Environment Compatibility\n\n```python\nfrom adk_core import EnvironmentAnalyzer, CompatibilityResolver\n\nenv = EnvironmentAnalyzer.analyze()\nresolver = CompatibilityResolver.from_yaml('data/compatibility.yaml')\n\nresult = resolver.validate_environment(env)\n\nif result.valid:\n    print(f\"Compatible CANN versions: {result.compatible_cann_versions}\")\nelse:\n    print(f\"Errors: {result.errors}\")\n```\n\n#### 3. Query Framework Configuration\n\n```python\nfrom adk_core import CompatibilityResolver\n\nresolver = CompatibilityResolver.from_yaml('data/compatibility.yaml')\n\n# Get PyTorch configuration for CANN 8.0.0\nconfig = resolver.get_framework_config(\"8.0.0\", \"pytorch\")\n\nprint(f\"PyTorch Version: {config.version}\")\nprint(f\"torch_npu Version: {config.torch_npu_version}\")\nprint(f\"Supported Python Versions: {config.python_versions}\")\n```\n\n#### 4. Generate Dockerfile\n\n```python\nfrom adk_core import DockerfileGenerator, CompatibilityResolver\nfrom adk_core.generator import BuildTarget, FrameworkType\n\nresolver = CompatibilityResolver.from_yaml('data/compatibility.yaml')\ngenerator = DockerfileGenerator(resolver)\n\ncontext = generator.create_context(\n    cann_version=\"8.0.0\",\n    framework=FrameworkType.PYTORCH,\n    target=BuildTarget.TRAIN,\n    python_version=\"3.10\"\n)\n\noutput = generator.generate(context)\ngenerator.write_output(output, \"./build/\")\n```\n\n### Shell Script Detection\n\n```bash\nbash scripts/check_npu.sh\n```\n\nJSON output:\n\n```json\n{\n  \"status\": \"ok\",\n  \"driver_version\": \"24.1.rc1\",\n  \"npu_count\": 8,\n  \"npus\": [{\"id\": 0, \"type\": \"910B\"}, {\"id\": 1, \"type\": \"910B\"}]\n}\n```\n\n## Examples\n\nReady-to-use examples are provided in the `examples/` directory:\n\n### PyTorch 2.4 + 910B\n\n```bash\ncd examples/pytorch-2.4-910b\n\n# Build the image\ndocker build -t pytorch-910b:2.4 .\n\n# Run container with NPU access\n./run.sh\n\n# Verify NPU inside container\npython test_npu.py\n```\n\n### MindSpore 2.3 + 910B\n\n```bash\ncd examples/mindspore-2.3-910b\n\n# Build and run\ndocker build -t mindspore-910b:2.3 .\n./run.sh\npython test_npu.py\n```\n\n## CLI Reference\n\n### Global Options\n\n```bash\npython adk.py [OPTIONS] COMMAND\n\nOptions:\n  --version              Show version\n  --matrix PATH          Path to compatibility matrix file\n  --help                 Show help message\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `diagnose` | Detect and display host environment information |\n| `validate CANN_VERSION` | Check if environment supports a CANN version |\n| `query cann [VERSION]` | List CANN versions or show details for one |\n| `query framework CANN FRAMEWORK` | Show framework config for CANN version |\n| `build init` | Generate Dockerfile and build scripts |\n\n### Build Command Options\n\n```bash\npython adk.py build init [OPTIONS]\n\nOptions:\n  --cann VERSION         CANN version (required)\n  --framework TYPE       pytorch or mindspore (required)\n  --target TYPE          train or inference (default: train)\n  --python VERSION       Python version (default: auto-detect)\n  -o, --output PATH      Output directory (default: current)\n  --auto-detect          Auto-detect environment settings\n  --no-china-mirror      Disable China mirror for pip\n```\n\n## API Reference\n\n### EnvironmentAnalyzer\n\n| Method | Description | Return |\n|--------|-------------|--------|\n| `analyze()` | Full environment detection | `EnvironmentInfo` |\n| `analyze_safe()` | Safe mode (no exceptions) | `(EnvironmentInfo, List[str])` |\n| `detect_os()` | Detect operating system | `str` |\n| `detect_arch()` | Detect CPU architecture | `str` |\n| `detect_npu()` | Detect NPU information | `Dict` |\n\n### CompatibilityResolver\n\n| Method | Description |\n|--------|-------------|\n| `from_yaml(path)` | Create instance from YAML file |\n| `list_cann_versions()` | List all CANN versions |\n| `get_cann_requirements(version)` | Get requirements for CANN version |\n| `find_compatible_cann(driver)` | Find compatible CANN versions |\n| `validate_environment(env)` | Validate environment compatibility |\n| `get_framework_config(cann, framework)` | Get framework configuration |\n\n### DockerfileGenerator\n\n| Method | Description |\n|--------|-------------|\n| `create_context(...)` | Create build context |\n| `generate(context)` | Generate Dockerfile content |\n| `write_output(output, path)` | Write files to directory |\n\n### Data Models\n\n```python\nclass EnvironmentInfo:\n    driver_version: str       # NPU driver version\n    os_name: str              # Operating system (e.g., ubuntu22.04)\n    npu_type: str             # NPU model (e.g., 910B)\n    arch: str                 # CPU architecture (x86_64/aarch64)\n    npu_count: int            # Number of NPUs\n    firmware_version: Optional[str]\n\nclass ValidationResult:\n    valid: bool\n    compatible_cann_versions: List[str]\n    errors: List[str]\n    warnings: List[str]\n```\n\n### Exception Classes\n\nAll exceptions inherit from `ADKError` and include a `suggestions` list.\n\n| Exception | Raised When |\n|-----------|-------------|\n| `EnvironmentDetectionError` | `/etc/os-release` missing or unreadable |\n| `DriverNotInstalledError` | `npu-smi` command not found |\n| `NPUNotDetectedError` | No NPU devices found |\n| `ConfigurationError` | YAML file invalid or missing |\n| `VersionNotFoundError` | CANN version not in matrix |\n| `DriverIncompatibleError` | Driver version outside supported range |\n| `OSNotSupportedError` | OS not supported by CANN version |\n| `NPUNotSupportedError` | NPU model not supported |\n| `FrameworkNotFoundError` | Framework not available for CANN version |\n\n## Project Structure\n\n```\nascend-docker-kit/\n├── adk.py                       # CLI entry point\n├── adk_core/                    # Core library\n│   ├── __init__.py              # Module exports\n│   ├── analyzer.py              # Environment analyzer\n│   ├── matrix.py                # Compatibility resolver\n│   ├── generator.py             # Dockerfile generator\n│   ├── models.py                # Data models (Pydantic v2)\n│   ├── exceptions.py            # Exception definitions\n│   └── version.py               # Version utilities\n├── data/\n│   └── compatibility.yaml       # Compatibility matrix data\n├── templates/                   # Jinja2 Dockerfile templates\n│   ├── Dockerfile.base.j2\n│   ├── Dockerfile.cann.j2\n│   └── Dockerfile.pytorch.j2\n├── scripts/\n│   ├── check_npu.sh             # NPU detection script\n│   └── install_cann.sh          # CANN silent installation\n├── examples/                    # Ready-to-use examples\n│   ├── pytorch-2.4-910b/\n│   └── mindspore-2.3-910b/\n├── tests/                       # Unit tests\n├── docs/                        # Documentation\n├── pyproject.toml               # Project configuration\n└── requirements.txt             # Dependencies\n```\n\n## Compatibility Matrix\n\nThe compatibility data in `data/compatibility.yaml` includes:\n\n| CANN Version | Min Driver | PyTorch | MindSpore | Status |\n|--------------|------------|---------|-----------|--------|\n| 8.0.0 | 24.1.rc1 | 2.4.0 | 2.3.0 | Stable |\n| 8.0.0rc3 | 24.1.rc1 | 2.3.1 | 2.2.14 | RC |\n| 7.0.0 | 23.0.3 | 2.1.0 | 2.2.0 | Stable |\n| 6.3.0 | 22.0.4 | 1.11.0 | 1.10.1 | Deprecated |\n\n## Development\n\n### Running Tests\n\n```bash\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run tests\npytest tests/ -v\n```\n\n### Adding New CANN Versions\n\nEdit `data/compatibility.yaml`:\n\n```yaml\ncann_versions:\n  \"8.1.0\":\n    min_driver_version: \"24.2.0\"\n    supported_os:\n      - ubuntu22.04\n      - ubuntu24.04\n    supported_npu:\n      - 910B\n      - 910B3\n    supported_arch:\n      - x86_64\n      - aarch64\n    frameworks:\n      pytorch:\n        version: \"2.5.0\"\n        torch_npu_version: \"2.5.0.post1\"\n        python_versions: [\"3.9\", \"3.10\", \"3.11\"]\n    deprecated: false\n```\n\n## Roadmap\n\n### Completed ✅\n\n- **Core Layer**: Compatibility matrix, environment analyzer, data models\n- **Build Layer**: Dockerfile generator, Jinja2 templates (PyTorch \u0026 MindSpore), CLI interface\n- **Examples**: PyTorch and MindSpore ready-to-use configurations\n- **Quality**: 90+ test cases, type annotations, exception handling\n\n### Planned 📋\n\n- [ ] Integration tests on real NPU hardware\n- [ ] PyPI package distribution\n- [ ] GUI tool for visual configuration\n\n## Contributing\n\nIssues and Pull Requests are welcome.\n\n1. Fork this repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Create a Pull Request\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.\n\n## Resources\n\n- [Huawei Ascend Official Website](https://www.hiascend.com/)\n- [CANN Documentation](https://www.hiascend.com/document)\n- [Ascend PyTorch](https://gitee.com/ascend/pytorch)\n- [Ascend MindSpore](https://www.mindspore.cn/)\n\n## Acknowledgments\n\nThanks to the Huawei Ascend team for providing official documentation and technical support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiannil%2Fascend-docker-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiannil%2Fascend-docker-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiannil%2Fascend-docker-kit/lists"}