# mt-docker

**Repository Path**: SOC-Device/mt-docker

## Basic Information

- **Project Name**: mt-docker
- **Description**: mt-docker 的基础镜像
- **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 基础镜像

基于长江 SoC 平台的 AI 开发基础环境，支持 PyTorch MUSA (GPU 计算)、NPU (AI 推理加速) 和 VPU (硬件视频编解码)。

## 环境说明

| 组件 | 版本 | 说明 |
|------|------|------|
| 基础镜像 | Ubuntu 22.04 LTS | ARM64 架构 |
| PyTorch | 2.5.0 | 深度学习框架 |
| torch_musa | 2.1.0 | MUSA GPU 加速后端 |
| torchvision | 0.20.0 | 视觉工具库 |
| torchaudio | 2.5.0 | 音频工具库 |
| triton | 3.1.0 | GPU 编译优化 |
| NPU SDK | 1.5 | AI 推理加速 |
| VPU 驱动 | mtgpu | 硬件视频编解码 |

## 前置条件

### 硬件要求
- 长江 SoC 开发板 (支持 VAAPI 加速的版本)
- 电源适配器
- 确保宿主机存在以下设备节点：
  - `/dev/dri/renderD128` (VPU 访问节点)
  - `/dev/npucore` (NPU 访问节点)

### 软件要求
- 长江 SoC 平台已安装 `MUSA 驱动` 或更高版本
- 操作系统为 `Ubuntu 22.04 LTS (jammy)`
- 已安装 Docker (推荐 27.5.0 或更高版本)
- 网络通畅，可访问 Docker 镜像仓库与 MUSA 相关资源

## 项目管理脚本

本项目使用 `manage.sh` 脚本统一管理镜像和容器，提供交互式菜单和命令行两种使用方式。

### 脚本位置

```
pytorch-musa-base/
├── manage.sh              # 主管理入口
└── scripts/
    ├── build.sh           # 构建镜像
    ├── run.sh             # 运行容器
    ├── stop.sh            # 停止容器
    ├── exec.sh            # 进入容器
    └── logs.sh            # 查看日志
```

### 使用方法

#### 方式一：交互式菜单（推荐）

```bash
./manage.sh
```

启动后显示交互式菜单，按数字键选择操作。

#### 方式二：命令行

```bash
# 查看帮助
./manage.sh help

# 构建镜像
./manage.sh build
./manage.sh build --no-cache                    # 不使用缓存
./manage.sh build -t v2.0                       # 指定标签

# 运行容器
./manage.sh run
./manage.sh run -n my-env                       # 指定容器名称
./manage.sh run -w /path/to/workspace           # 指定工作目录
./manage.sh run --attach                        # 前台运行

# 进入容器
./manage.sh exec

# 查看日志
./manage.sh logs
./manage.sh logs -f                             # 实时跟踪
./manage.sh logs -n 50                          # 最后 50 行

# 停止/删除容器
./manage.sh stop
./manage.sh stop -f                             # 强制停止

# 查看状态
./manage.sh status
```

### 快速开始

```bash
# 1. 进入项目目录
cd pytorch-musa-base

# 2. 构建镜像
./manage.sh build

# 3. 运行容器
./manage.sh run

# 4. 进入容器
./manage.sh exec
```

## 工作目录

容器默认挂载宿主机的 `./workspace` 目录到容器的 `/workspace`：

```
pytorch-musa-base/
├── workspace/           # 工作目录（自动创建）
│   └── ...             # 你的代码和数据
```

可以在运行容器时指定其他目录：
```bash
./manage.sh run -w /path/to/your/workspace
```

## 环境验证

进入容器后，运行综合检查脚本：

```bash
bash /feature_test/check_all.sh
```

或分别测试各个组件：

```bash
# 测试 PyTorch MUSA
python /feature_test/test_musa.py

# 测试 NPU
python /feature_test/test_npu.py

# 测试 VPU
bash /feature_test/test_vpu.sh
```

## 挂载说明

容器启动时自动挂载以下关键路径：

| 宿主机路径 | 容器内路径 | 用途 |
|------------|------------|------|
| `/dev` | `/dev` | 设备文件访问 |
| `/usr/local/musa` | `/usr/local/musa` | MUSA SDK 库文件 |
| `/usr/lib/aarch64-linux-gnu/musa` | `/usr/lib/aarch64-linux-gnu/musa` | MUSA 系统库 |
| `/usr/lib/aarch64-linux-gnu/dri` | `/usr/lib/aarch64-linux-gnu/dri` | DRI 驱动 |
| `/lib/modules` | `/lib/modules` | 内核模块 |
| `/tmp/.X11-unix` | `/tmp/.X11-unix` | X11 图形支持 |
| `./workspace` | `/workspace` | 工作目录映射 |

## 故障排查

### 1. 镜像构建失败

```bash
# 不使用缓存重新构建
./manage.sh build --no-cache
```

### 2. 容器启动失败

```bash
# 查看详细日志
./manage.sh logs

# 强制删除旧容器后重建
./manage.sh stop -f
./manage.sh run
```

### 3. MUSA 不可用

1. 确认宿主机已正确安装 MUSA SDK
2. 检查 `/usr/local/musa` 目录是否存在
3. 重新运行容器: `./manage.sh stop && ./manage.sh run`

### 4. NPU 设备未找到

1. 确认宿主机上 NPU 驱动已正确加载
2. 检查宿主机是否存在 `/dev/npucore` 设备节点
3. 确认容器以 `--privileged` 模式启动

### 5. VPU 初始化失败

1. 确认宿主机上 VPU 驱动已正确安装
2. 检查 `/dev/dri/renderD128` 设备节点是否存在

## 相关资源

- [PyTorch MUSA 开发者手册](https://apollo-appstore-pre.tos-cn-beijing.volces.com/appstore/release/document/MooreThreads-Torch_MUSA-Developer-Guide-CN-v1.3.0.pdf)
- [MUSA SDK 官方文档](https://docs.mthreads.com/musa-sdk/musa-sdk-doc-online/programming_guide)

## 更新日志

| 版本 | 日期 | 变更描述 |
|------|------|----------|
| 1.0.0 | 2026-03-05 | 初始版本，整合 PyTorch MUSA + NPU + VPU 环境 |