MingTok-Vision Ascend NPU 部署指南

项目简介

MingTok-Vision 是由 inclusionAI 开发的统一视觉 Tokenizer，实现了无向量量化的高保真图像重建。该模型采用连续潜空间表示，支持统一的视觉理解和生成。

特性

🖼️ 首个连续统一视觉 Tokenizer：通过连续潜空间实现视觉理解和生成的统一
🎯 高保真图像重建：三阶段架构（编码、扩展、重建）捕获精细细节和全局结构
⚡ 加速自回归收敛：掩码建模与多级监督塑造紧凑语义潜空间

模型信息

属性	值
模型类型	MingTok (视觉Tokenizer)
参数量	0.7B
输入尺寸	512x512
任务类型	图像重建
精度类型	BF16 (NPU) / FP32 (CPU)

环境要求

硬件: 华为 Ascend 910B3 系列 NPU
CANN: 8.5.0 或更高版本
PyTorch: 2.8.0+ with torch_npu 2.8.0.post2
Python: 3.11+

目录结构

/data/ysws/agentsp/5-14/MingTok-Vision-ascend/
├── inference.py                 # 推理测试脚本
├── log.txt                     # 测试日志
├── README.md                   # 本文档
├── precision_result.json       # 精度测试结果
├── test_image.png              # 测试输入图像(真实样本)
├── test_sample.png             # 原始测试样本
├── reconstructed.png           # 重建输出图像
└── real_image_reconstruction.png  # 真实图像重建结果

部署步骤

1. 环境准备

确保 CANN 环境变量已设置：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

2. 验证 NPU 可用性

python3 -c "import torch; print(f'NPU available: {torch.npu.is_available()}')"

3. 推理测试

使用方式

方式一：普通推理模式

运行推理脚本进行图像重建：

cd /data/ysws/agentsp/5-14/MingTok-Vision-ascend/

# 使用默认测试图像 (随机噪声)
python3 inference.py

# 使用指定图像文件
python3 inference.py --image_path /path/to/your/image.jpg

# 指定设备
python3 inference.py --device npu:0

方式二：精度测试模式 (CPU vs NPU)

运行精度对比测试，验证 NPU 计算结果与 CPU 一致性：

cd /data/ysws/agentsp/5-14/MingTok-Vision-ascend/

# 运行完整精度测试
python3 inference.py --precision_test

命令行参数说明

参数	说明	默认值
`--image_path`	输入图像文件路径	自动生成随机测试图像
`--device`	运行设备	`npu:0`
`--precision_test`	运行精度测试模式	`False`
`--output_dir`	输出目录	`/data/ysws/agentsp/5-14/MingTok-Vision-ascend`

测试验证

精度测试结果

指标	实测值	阈值	状态
Cosine similarity	1.000036	> 0.99	PASS

性能数据

操作	耗时
模型加载	~5s
NPU 推理时间 (512x512)	5.71s
CPU 推理时间 (512x512)	47.17s
加速比	~8.3x

Python API 使用示例

基本推理

import sys
sys.path.insert(0, '/data/ysws/agentsp/5-14/MingTok-Vision')

import torch
from PIL import Image
from mingtok.modeling_mingtok import MingTok, MingTokConfig
from mingtok.utils import CenterCropProcessor
from omegaconf import OmegaConf
import json
import torchvision.transforms as T

# 加载模型
config_path = '/data/ysws/agentsp/5-14/MingTok-Vision/config.json'
with open(config_path, 'r') as f:
    config_dict = json.load(f)
cfg = OmegaConf.create(config_dict)
mingtok_config = MingTokConfig.from_omegaconf(cfg)

model = MingTok(mingtok_config).to("npu:0").eval()
from safetensors.torch import load_file
state_dict = load_file('/data/ysws/agentsp/5-14/MingTok-Vision/model.safetensors')
model.load_state_dict(state_dict, strict=False)

# 加载并预处理图像
image = Image.open("your_image.jpg").convert("RGB")
processor = CenterCropProcessor(image_size=512, mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5])
img_tensor = processor(image).unsqueeze(0).to("npu:0")

# 推理
with torch.no_grad():
    output = model.forward_enc_dec(img_tensor)

# 后处理并保存
output_mean = torch.tensor([0.5, 0.5, 0.5]).view(1, -1, 1, 1).to("npu:0")
output_std = torch.tensor([0.5, 0.5, 0.5]).view(1, -1, 1, 1).to("npu:0")
output_image = (output * output_std + output_mean)[0].cpu()
output_image = output_image.clamp(0, 1)
output_image = T.ToPILImage()(output_image)
output_image.save("reconstructed.png")

模型结构

架构类型: 三阶段视觉Tokenizer (Low-level Encoder + Semantic Decoder + Pixel Decoder)
Low-level Encoder: 12层 ViT, embed_dim=768, patch_size=32, out_dim=32
Semantic Decoder: 24层, embed_dim=1024, patch_size=32
Pixel Decoder: 24层, embed_dim=1024, patch_size=16
参数量: 0.7B

组件	说明
low_level_encoder	图像 → 32维潜码
semantic_decoder	潜码 → 语义特征
pixel_decoder	语义特征 → 重建图像

输入输出格式

输入: PIL Image 或 3x512x512 张量, 值范围 [-1, 1] (归一化)
输出: 3x512x512 张量, 值范围 [-1, 1]
预处理: CenterCrop(512) + Normalize(mean=[0.5,0.5,0.5], std=[0.5,0.5,0.5])
后处理: 反归一化 + clamp(0,1) + ToPILImage

常见问题

Q: 如何提高精度?

A: 如需更高精度，可使用 --precision_mode=force_fp32 进行 ATC 转换（会降低性能）。但对于大多数视觉任务，BF16 精度已足够。

Q: 推理速度慢?

A: 确保使用 NPU 设备。首次运行需要加载模型（约 5s），后续推理约 5.7s。8x 加速比证明 NPU 正常工作。

参考链接

原始模型: https://huggingface.co/inclusionAI/MingTok-Vision
GitHub: https://github.com/inclusionAI/Ming-UniVision
技术报告: https://arxiv.org/pdf/2510.06590

许可证

本项目遵循 Apache-2.0 许可证。