npu-docker-launcher

NPU Docker 容器启动器

概述

此技能可直接在 Ascend NPU 服务器上启动 Docker 容器。调用后，执行启动前检查、收集用户需求，并运行相应的 docker run 命令。

工作流

1. 启动前环境检查

继续之前必须执行以下检查：

1.1 检查 NPU 驱动是否可用

# Check if Ascend driver is installed
ls -l /usr/local/Ascend/driver/

# Check driver version (optional)
cat /usr/local/Ascend/driver/version.info 2>/dev/null || echo "Driver version info not found"

如果驱动目录不存在，停止并告知用户：“在 /usr/local/Ascend/driver/ 中未找到 Ascend 驱动。请先安装驱动。”

1.2 检查 NPU 设备是否可用

# List NPU devices
ls -l /dev/davinci* 2>/dev/null

# Check NPU status using npu-smi
npu-smi info 2>/dev/null || echo "npu-smi not available"

如果未找到 /dev/davinci* 设备，停止并告知用户：“未检测到 NPU 设备。请检查硬件和驱动安装情况。”

1.3 检查 Docker 服务

# Check if Docker is running
docker info > /dev/null 2>&1 && echo "Docker is running" || echo "Docker is not running"

如果 Docker 未运行，停止并告知用户。

2. 查询可用的 Docker 镜像

先查询并显示可用镜像，再询问用户：

# List all local Docker images
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}\t{{.CreatedAt}}"

以格式化表格向用户显示镜像。然后询问用户的任务，并根据以下内容推荐合适的镜像：

• PyTorch/TensorFlow 训练：查找包含 "pytorch"、"tensorflow"、"ascend-pytorch"、"ascend-tf" 的镜像
• MindSpore 训练：查找包含 "mindspore" 的镜像
• 推理：查找包含 "inference"、"serving"、"vllm"、"mindie" 的镜像
• 开发：查找包含 "dev"、"devel" 或通用框架的镜像

3. 收集需求

显示可用镜像并了解用户的任务后，询问：

## Docker Container Configuration

1. Container name: (e.g., my-pytorch-env)
2. Privileged mode: (default: yes) - Grants full device access [yes/no]
3. Network mode: (default: host) or specify port mappings [host/custom]
4. NPU cards: Which cards to use? (default: all, or specific like "0,1,2") [all/specific]
5. Mount directories: (format: host:container, comma-separated)
   Example: /home/user:/home/user,/data:/data
6. Work directory inside container: (e.g., /home/user)
7. Environment variables: (space-separated, e.g., "VAR1=value1 VAR2=value2")
8. Additional options: (e.g., auto-remove --rm, shm-size)

4. 构建 Docker 运行命令

默认命令结构：

docker run -it -d \
  --name <container-name> \
  --privileged \
  --network host \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/sbin:/usr/local/sbin \
  -v <user-mounts> \
  -w <work-dir> \
  [-e ENV_VARS...] \
  <image> \
  /bin/bash

关键默认值：

• -it -d：交互式终端 + 分离模式（始终同时使用）
• /bin/bash：默认运行的命令（始终放在末尾）
• --privileged：NPU 访问的默认选项
• --network host：默认网络模式

命令组成部分：

必需参数：

参数	默认值	说明
-it -d	始终使用	交互式 + 分离模式
--name	必需	容器名称
--privileged	是	NPU 的完整设备访问权限
--network host	host	网络模式

驱动挂载（始终包含）：

-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-v /usr/local/sbin:/usr/local/sbin

可选参数：

参数	使用场景
--device=/dev/davinci0	指定 NPU 卡（而非 --privileged）
-p host:container	端口映射（而非 --network host）
--shm-size=16g	分布式训练所需的大容量共享内存
--rm	退出时自动删除容器
-e VAR=value	环境变量

5. 显示命令并确认

显示完整命令并请求确认：

📋 Generated Docker Run Command:

docker run -it -d \
  --name my-container \
  --privileged \
  --network host \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/sbin:/usr/local/sbin \
  -v /home/user:/home/user \
  -w /home/user \
  pytorch/pytorch:latest \
  /bin/bash

Proceed with container launch? [yes/no]

6. 执行并验证

用户确认后：

1. 使用 Bash 工具执行命令
2. 验证容器是否正在运行：

   docker ps | grep <container-name>
   

3. 报告状态并提供访问说明

7. 报告状态

✅ Container started successfully
- Container ID: abc123def456
- Container name: my-container
- Image: pytorch/pytorch:latest
- Status: Running

📌 Access Instructions:
- Enter container: docker exec -it my-container bash
- View logs: docker logs -f my-container
- Stop container: docker stop my-container
- Remove container: docker rm my-container

决策规则

特权模式与设备挂载

方式	使用场景	命令
特权模式（默认）	开发、多张 NPU 卡、快速设置	--privileged
设备挂载	生产环境、指定卡、安全性要求较高	--device=/dev/davinci0

**规则：**除非用户明确要求设备挂载，否则默认使用 --privileged。

网络模式

模式	使用场景	命令
Host（默认）	开发、本地访问、无端口冲突	--network host
Bridge	生产环境、需要端口隔离、服务部署	--network bridge -p 8080:80

**规则：**NPU 服务器默认使用 --network host。

NPU 卡选择

• 全部（默认）：使用 --privileged 访问所有 NPU
• 指定：对每张卡使用 --device=/dev/davinci{i}

常见场景

场景 1：开发环境（最常见）

用户请求：“帮我启动一个开发容器”或“我想要一个开发容器”

步骤：

1. 检查环境（驱动、NPU、Docker）
2. 列出可用镜像
3. 根据任务推荐合适的镜像
4. 使用默认设置（特权模式、主机网络、所有 NPU）
5. 挂载主目录

命令：

docker run -it -d \
  --name pytorch-dev \
  --privileged \
  --network host \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/sbin:/usr/local/sbin \
  -v /home/user:/home/user \
  -w /home/user \
  pytorch/pytorch:latest \
  /bin/bash

场景 2：单卡 NPU 训练

用户请求：“我只用卡 0 训练”

命令：

docker run -it -d \
  --name train-card0 \
  --network host \
  --device=/dev/davinci0 \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/sbin:/usr/local/sbin \
  -v /data:/data \
  -w /data \
  -e ASCEND_DEVICE_ID=0 \
  ascend-pytorch:latest \
  /bin/bash

场景 3：多卡分布式训练

用户请求：“我要用所有卡进行分布式训练”

命令：

docker run -it -d \
  --name distributed-train \
  --privileged \
  --network host \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/sbin:/usr/local/sbin \
  -v /home/user:/workspace \
  -w /workspace \
  --shm-size=16g \
  -e ASCEND_VISIBLE_DEVICES=0,1,2,3 \
  -e RANK_SIZE=4 \
  ascend-mindspore:latest \
  /bin/bash

场景 4：带端口映射的推理服务

用户请求：“我需要启动一个推理服务，端口 8080”

命令：

docker run -it -d \
  --name inference-svc \
  --network bridge \
  -p 8080:8000 \
  --device=/dev/davinci0 \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /usr/local/sbin:/usr/local/sbin \
  -v /models:/models \
  -w /models \
  ascend-inference:latest \
  /bin/bash

启动前检查清单

执行 docker run 前，请确认：

• Ascend 驱动位于 /usr/local/Ascend/driver/
• NPU 设备可用（/dev/davinci*）
• Docker 服务正在运行
• 镜像已在本地，或可以拉取
• 容器名称与现有容器不冲突
• 用户已确认命令

错误处理

错误	解决方案
"driver not found"	请用户安装 Ascend 驱动
"No NPU devices"	检查硬件连接和驱动
"Docker not running"	启动 Docker：systemctl start docker
"Image not found"	拉取镜像或使用其他镜像
"Container name exists"	删除旧容器：docker rm -f <name>，或使用新名称
"Permission denied"	检查用户是否属于 docker 组，或使用 sudo

参考文件

• npu-devices.md - NPU 设备查询和挂载详情
• examples.md - 更多详细示例

快速参考命令

# List local images
docker images

# Check NPU devices
ls -l /dev/davinci* && npu-smi info

# List running containers
docker ps

# Enter container
docker exec -it <name> bash

# View logs
docker logs -f <name>

# Stop container
docker stop <name>

# Remove container
docker rm <name>

# Force remove container
docker rm -f <name>