# mt_docker_image

**Repository Path**: SOC-Device/mt_docker_image

## Basic Information

- **Project Name**: mt_docker_image
- **Description**: 带 conda 环境的摩尔基础镜像
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pytorch-musa-npu-vpu-conda

基于 `pytorch-musa-npu-vpu:v1.0` 构建的 conda 环境镜像，内含 vllm 虚拟环境，用于在摩尔线程 M1000 GPU 上推理大模型。

## 镜像说明

| 镜像 | 说明 |
|------|------|
| `pytorch-musa-npu-vpu-conda-resources:v1.1` | 资源镜像，存放 vLLM MUSA 安装包、vLLM/vllm_musa 补丁和 NPU SDK Python API 资源 |
| `pytorch-musa-npu-vpu-conda:v1.1` | 主镜像，包含 conda + vllm 环境，并在构建期应用 vLLM `arg_utils.py` 补丁和 vllm_musa `ENCODER_ONLY` 注意力修复补丁 |

## 环境信息

- **基础镜像**: `pytorch-musa-npu-vpu:v1.0`
- **OS**: Ubuntu 22.04 aarch64
- **conda 环境**: `vllm` (Python 3.10)
- **torch**: 2.5.0
- **torch_musa**: 2.1.1
- **triton**: 3.1.0
- **vllm**: 0.9.2.dev260
- **vllm_musa**: 1.3.2+m1000
- **mtnn_api**: 1.5（来自 `workspace/npu_sdk_v1.5.0.tar.gz`）
- **主镜像标签**: `pytorch-musa-npu-vpu-conda:v1.1`
- **构建补丁**:
  - `workspace/docker_resources/0004-arg-utils-use-v1.patch` — 应用到 `vllm/engine/arg_utils.py`（`use_v1 = False`）
  - `workspace/docker_resources/0001-paged_attention.patch` — 应用到 `vllm_musa/v0/paged_attention.py`（`ENCODER_ONLY` 注意力）
  - `workspace/docker_resources/0002-flash_attn.patch` — 应用到 `vllm_musa/v0/flash_attn.py`（`ENCODER_ONLY` 注意力）

## 构建

```bash
./build.sh
```

构建脚本先构建资源镜像 `pytorch-musa-npu-vpu-conda-resources:v1.1`，再构建主镜像 `pytorch-musa-npu-vpu-conda:v1.1`。主镜像使用 BuildKit 的 `--mount=type=bind,from=pytorch-musa-npu-vpu-conda-resources:v1.1` 挂载资源镜像内容，并在安装 vLLM/vllm_musa 后从资源镜像里的 patch 对已安装源码打补丁（`0004-arg-utils-use-v1.patch` 应用于 `vllm`，`0001-paged_attention.patch` 和 `0002-flash_attn.patch` 应用于 `vllm_musa`）；同时从资源镜像里的 `npu_sdk/npu_sdk_v1.5.0.tar.gz` 安装 MTNN Python API 到 `vllm` 环境。

## 运行容器

```bash
./run.sh              # 前台交互，直接进入容器
./run.sh --detach     # 后台运行
./run.sh --rm         # 前台交互，退出后自动删除容器
```

容器启动后默认激活 vllm conda 环境。后台模式下通过 `docker exec -it pytorch-musa-npu-vpu-conda bash` 进入。

## 测试模型部署

1. 下载模型到容器内的 `/workspace`（即执行 `run.sh` 的当前目录）：

```bash
modelscope download --model hiruyun/gptq-Qwen3-8B --local_dir /workspace/models/gptq-Qwen3-8B
```

2. 启动 vllm serve：

```bash
export TRITON_CACHE_DIR="/tmp/triton"
ENABLE_MUSA_MMA=1 vllm serve /workspace/models/gptq-Qwen3-8B \
    -tp 1 \
    --gpu_memory_utilization 0.7 \
    --quantization gptq \
    --block_size 32 \
    --num-gpu-blocks-override 512 \
    --max-model-len 16384 \
    --swap_space 0
```

3. 发送测试请求：

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "/workspace/models/gptq-Qwen3-8B",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 512
  }'
```

## 复用验证脚本

`test_resources/` 中提供可在容器内复用的验证脚本。仓库根目录挂载到 `/workspace` 后，可运行：

```bash
bash /workspace/test_resources/run_all_validations.sh \
  --gptq-model /workspace/models/gptq-Qwen3-8B \
  --yolo-model /workspace/workspace/test_resources/yolov8n.mtnn \
  --embedding-model /workspace/models/BAAI/bge-m3 \
  --reranker-model /workspace/models/BAAI/bge-reranker-v2-m3 \
  --port 8000
```

该入口会依次检查 torch MUSA、vLLM MUSA、vLLM 补丁、vllm_musa encoder_only 补丁、YOLO MTNN 推理、BAAI embedding/reranker 推理和 GPTQ Qwen3 vLLM chat 推理。BAAI 的 `bge-m3` 使用本地 `pytorch_model.bin` 时，验证脚本会显式启用本地可信权重加载。

## 挂载说明

容器运行时需 privileged 模式，并挂载宿主机的 MUSA 驱动：

```
-v /usr/local/musa:/usr/local/musa
-v /usr/lib/aarch64-linux-gnu/musa:/usr/lib/aarch64-linux-gnu/musa
-v /usr/lib/aarch64-linux-gnu/dri:/usr/lib/aarch64-linux-gnu/dri
```

详见 `run.sh`。

## 文件结构

```
.
├── Dockerfile                    # 主镜像 Dockerfile
├── Dockerfile.resources          # 资源镜像 Dockerfile
├── build.sh                      # 构建脚本
├── run.sh                        # 运行脚本
├── docs/
│   └── vllm_musa_environment_setup.md  # 摩尔线程文档（AIModule 1.3.0.003）
├── test_resources/               # GPTQ、MTNN、BAAI 模型复用验证脚本
├── .gitignore
└── README.md
```

## 注意事项

- 构建主镜像前需先构建资源镜像，或确保资源镜像已存在
- 宿主机需预装 musa 3.1.3 和 musa-sdk 4.1.4
- 容器内默认激活 conda 环境 `vllm`
- 模型文件建议放在执行 `run.sh` 的当前目录下，该目录会挂载到容器的 `/workspace`，容器销毁后数据不会丢失