昇腾 NPU 物理设备与逻辑设备映射指南

一、核心概念区分

1.1 物理设备（Physical Device）

• 定义：硬件设备文件，位于 /dev 目录下
• 命名规则：/dev/davinci0 ~ /dev/davinci7（对应 8 张物理 NPU 卡）
• 特点：
  • 由操作系统内核直接识别
  • 与硬件物理插槽位置一一对应
  • 通过 ls -la /dev/davinci* 查看

1.2 逻辑设备（Logical Device）

• 定义：昇腾驱动在容器内创建的虚拟设备编号
• 命名规则：0, 1, 2, …（从 0 开始的整数）
• 特点：
  • 由 devices 挂载顺序动态决定（CANN 8.0+ 默认行为）
  • 与物理设备无固定映射关系
  • 通过 ASCEND_RT_VISIBLE_DEVICES 环境变量指定

1.3 关键映射规则（CANN 8.0+）

逻辑设备编号 = 挂载顺序的索引

• 逻辑设备 0 → 第一个挂载的物理设备
• 逻辑设备 1 → 第二个挂载的物理设备
• 逻辑设备 2 → 第三个挂载的物理设备
• …以此类推

⚠️ 重要提示：

• /etc/ascend_install.info 不包含设备映射配置（CANN 8.0+ 采用简单顺序映射）
• ASCEND_RT_VISIBLE_DEVICES 设置的是逻辑编号，不是物理设备编号
• 逻辑编号与物理卡的映射关系完全由 devices 挂载顺序决定

---

二、映射示例

2.1 单卡配置

挂载配置	逻辑设备 0	ASCEND_RT_VISIBLE_DEVICES	说明
仅挂载 /dev/davinci4	物理卡 4	"0"	逻辑 0 = 物理 4
仅挂载 /dev/davinci5	物理卡 5	"0"	逻辑 0 = 物理 5

2.2 双卡配置

挂载顺序	逻辑设备 0	逻辑设备 1	ASCEND_RT_VISIBLE_DEVICES	说明
/dev/davinci4, /dev/davinci5	物理卡 4	物理卡 5	"0,1"	顺序决定映射
/dev/davinci5, /dev/davinci4	物理卡 5	物理卡 4	"0,1"	交换顺序 → 交换映射

2.3 验证方法（容器内执行）

# 查看逻辑设备与物理卡的映射关系
docker exec <容器名> npu-smi info

# 预期输出示例（挂载了 davinci4 和 davinci5）：
# +---------------------------+---------------+
# | NPU   Name                | Health        |
# | Chip                      | Bus-Id        |
# +===========================+===============+
# | 0     910B4-1             | OK            |  ← 逻辑设备 0 = 物理卡 4
# | 0                         | 0000:C1:00.0  |
# +===========================+===============+
# | 1     910B4-1             | OK            |  ← 逻辑设备 1 = 物理卡 5
# | 0                         | 0000:C2:00.0  |
# +===========================+===============+

---

三、Docker Compose 配置示例

3.1 单卡配置（使用物理卡 4）

services:
  pdf-server-vllm:
    image: pdf-server-vllm:260112-ascend-arm
    container_name: pdf-server-vllm
    environment:
      ASCEND_RT_VISIBLE_DEVICES: "0"  # 逻辑设备 0（映射到第一个挂载的物理设备）
      ASCEND_SLOG_PRINT_TO_STDOUT: "1"
      HCCL_WHITELIST_DISABLE: "1"
    devices:
      - "/dev/davinci4:/dev/davinci4"  # 第一个挂载 → 逻辑设备 0
      - "/dev/davinci_manager:/dev/davinci_manager"
      - "/dev/devmm_svm:/dev/devmm_svm"
      - "/dev/hisi_hdc:/dev/hisi_hdc"
    volumes:
      - "/usr/local/Ascend/driver:/usr/local/Ascend/driver:ro"
      - "/etc/ascend_install.info:/etc/ascend_install.info:ro"
    security_opt:
      - "seccomp=unconfined"

3.2 双卡配置（使用物理卡 4 和 5）

services:
  pdf-server-vllm:
    image: pdf-server-vllm:260112-ascend-arm
    container_name: pdf-server-vllm
    environment:
      ASCEND_RT_VISIBLE_DEVICES: "0,1"  # 逻辑 0=卡4, 逻辑 1=卡5
      ASCEND_SLOG_PRINT_TO_STDOUT: "1"
      HCCL_WHITELIST_DISABLE: "1"
    devices:
      - "/dev/davinci4:/dev/davinci4"  # 第一个 → 逻辑 0
      - "/dev/davinci5:/dev/davinci5"  # 第二个 → 逻辑 1
      - "/dev/davinci_manager:/dev/davinci_manager"
      - "/dev/devmm_svm:/dev/devmm_svm"
      - "/dev/hisi_hdc:/dev/hisi_hdc"
    volumes:
      - "/usr/local/Ascend/driver:/usr/local/Ascend/driver:ro"
      - "/etc/ascend_install.info:/etc/ascend_install.info:ro"
    security_opt:
      - "seccomp=unconfined"
    command:
      - "--host"
      - "0.0.0.0"
      - "--port"
      - "30000"
      - "--gpu-memory-utilization"
      - "0.9"
      - "--tensor-parallel-size"
      - "2"  # 与卡数一致

3.3 切换 NPU 卡操作（30秒完成）

# 1. 停止容器
docker-compose down pdf-server-vllm

# 2. 修改配置（切换到物理卡 5）
sed -i 's|/dev/davinci4:/dev/davinci4|/dev/davinci5:/dev/davinci5|' docker-compose.yml
# ASCEND_RT_VISIBLE_DEVICES 保持 "0"（逻辑设备 0 始终映射到第一个挂载的物理设备）

# 3. 启动新配置
docker-compose up -d pdf-server-vllm

# 4. 验证（等待 2-3 分钟）
sleep 120
docker exec pdf-server-vllm npu-smi info -i 0 | grep "HBM-Usage"
# 正确输出: HBM-Usage(MB)        48128/ 65536（逻辑设备 0 显存被占用）

---

四、Docker Run 配置示例

4.1 单卡配置（使用物理卡 4）

docker run -d \
  --name pdf-server-vllm \
  --net host \
  --restart always \
  -e ASCEND_RT_VISIBLE_DEVICES="0" \          # 逻辑设备 0
  -e ASCEND_SLOG_PRINT_TO_STDOUT="1" \
  -e HCCL_WHITELIST_DISABLE="1" \
  --device=/dev/davinci4:/dev/davinci4 \      # 第一个挂载 → 逻辑 0
  --device=/dev/davinci_manager:/dev/davinci_manager \
  --device=/dev/devmm_svm:/dev/devmm_svm \
  --device=/dev/hisi_hdc:/dev/hisi_hdc \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
  -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
  --security-opt seccomp=unconfined \
  pdf-server-vllm:260112-ascend-arm \
  mineru-openai-server serve /model --host 0.0.0.0 --port 30000

4.2 双卡配置（使用物理卡 4 和 5）

docker run -d \
  --name pdf-server-vllm \
  --net host \
  --restart always \
  -e ASCEND_RT_VISIBLE_DEVICES="0,1" \        # 逻辑 0=卡4, 逻辑 1=卡5
  -e ASCEND_SLOG_PRINT_TO_STDOUT="1" \
  -e HCCL_WHITELIST_DISABLE="1" \
  --device=/dev/davinci4:/dev/davinci4 \      # 第一个 → 逻辑 0
  --device=/dev/davinci5:/dev/davinci5 \      # 第二个 → 逻辑 1
  --device=/dev/davinci_manager:/dev/davinci_manager \
  --device=/dev/devmm_svm:/dev/devmm_svm \
  --device=/dev/hisi_hdc:/dev/hisi_hdc \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
  -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
  --security-opt seccomp=unconfined \
  pdf-server-vllm:260112-ascend-arm \
  mineru-openai-server serve /model --host 0.0.0.0 --port 30000 \
    --gpu-memory-utilization 0.9 --tensor-parallel-size 2

4.3 快速切换脚本

#!/bin/bash
# switch-npu.sh <物理卡编号>
# 示例: ./switch-npu.sh 5

PHYSICAL_CARD=$1
LOGICAL_DEVICE="0"  # 始终使用逻辑设备 0（单卡场景）

# 停止旧容器
docker stop pdf-server-vllm 2>/dev/null
docker rm pdf-server-vllm 2>/dev/null

# 启动新容器（挂载指定物理卡）
docker run -d \
  --name pdf-server-vllm \
  --net host \
  --restart always \
  -e ASCEND_RT_VISIBLE_DEVICES="$LOGICAL_DEVICE" \
  -e ASCEND_SLOG_PRINT_TO_STDOUT="1" \
  -e HCCL_WHITELIST_DISABLE="1" \
  --device=/dev/davinci${PHYSICAL_CARD}:/dev/davinci${PHYSICAL_CARD} \
  --device=/dev/davinci_manager:/dev/davinci_manager \
  --device=/dev/devmm_svm:/dev/devmm_svm \
  --device=/dev/hisi_hdc:/dev/hisi_hdc \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
  -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
  --security-opt seccomp=unconfined \
  pdf-server-vllm:260112-ascend-arm \
  mineru-openai-server serve /model --host 0.0.0.0 --port 30000

echo "✅ 已切换到物理 NPU 卡 ${PHYSICAL_CARD}（逻辑设备 ${LOGICAL_DEVICE}）"

---

五、常见问题排查

问题现象	原因	解决方案
available visible devices:[]	逻辑设备编号超出范围	检查 devices 挂载数量，ASCEND_RT_VISIBLE_DEVICES 最大值 = 挂载数-1
Invalid device ID	物理设备未挂载	确保 devices 列表包含目标物理设备
容器启动后无显存占用	逻辑/物理设备映射错误	对照挂载顺序修正 ASCEND_RT_VISIBLE_DEVICES
多卡配置失败	未设置 --tensor-parallel-size	在 vLLM 启动命令中添加张量并行参数

💡 生产环境建议：

1. 切换前先停止旧容器（避免资源冲突）
2. 首次切换后等待 3 分钟让模型加载到新 NPU 卡
3. 通过 docker exec <容器名> npu-smi info -i X 验证显存占用
4. 保留原配置备份：cp docker-compose.yml docker-compose.yml.bak.$(date +%Y%m%d)