HuggingFaceTB/SmolVLM-256M-Instruct · 昇腾 NPU 图像到文本

本仓库将 HuggingFaceTB/SmolVLM-256M-Instruct（一个轻量级多模态视觉-语言模型，输入图像 + 文本提示，输出文本回答）适配到昇腾 (Ascend) NPU（torch-npu，设备 npu:0）。权重在首次使用时自动从镜像下载，无需手动干预。

• 模型权重镜像：https://ai.gitcode.com/hf_mirrors/HuggingFaceTB/SmolVLM-256M-Instruct
• HuggingFace 原始仓库：https://huggingface.co/HuggingFaceTB/SmolVLM-256M-Instruct
• 模型架构：Idefics3ForConditionalGeneration（model_type: idefics3），基于 SmolLM2-135M-Instruct 文本骨干 + 轻量 SigLIP 视觉编码器。每 512×512 图像块使用 64 个视觉 token。权重类型 bfloat16，显存占用 <1 GB。

模型信息

昇腾 NPU 适配说明

1. 无任何 CUDA 代码 — 模型与所有输入 Tensor 全部在 npu:0 上运行。
2. NPU 初始化 包裹在 init_npu() 中，失败时输出 JSON 错误并退出。
3. 权重自动下载 — 首次运行时从 GitCode 镜像（ai.gitcode.com）自动下载到 model_weights/HuggingFaceTB/SmolVLM-256M-Instruct/，本地缓存优先；由于该模型可能未在 GitCode 镜像，自动回退到 hf-mirror.com。下载后对 model.safetensors 做 8 字节 header + JSON + 数据偏移 + NaN/Inf 校验。
4. 生成使用 model.generate()，max_new_tokens=256，do_sample=False（贪心解码）。
5. 输出 JSON 包含 model、device、status、elapsed_ms、prompt、image 及生成的 answer 文本。

权重

权重在首次使用时自动从镜像下载，缓存于 model_weights/HuggingFaceTB/SmolVLM-256M-Instruct/。后续运行优先加载本地缓存，避免重复下载。

• GitCode 镜像（主）：https://ai.gitcode.com/hf_mirrors/HuggingFaceTB/SmolVLM-256M-Instruct
• 备用镜像：https://hf-mirror.com/HuggingFaceTB/SmolVLM-256M-Instruct

使用方法

命令行（单图像推理）

python3 inference.py --img examples/demo_image.png --prompt "Describe this image in detail."

输出 JSON 到 stdout（设备 npu:0，含生成的文本回答）。

FastAPI 服务

python3 inference.py --mode server --port 8783

• GET / — 最小化 HTML 上传页面（暗色终端风格）
• POST /predict — multipart 上传图像文件（.png/.jpg）及可选的 prompt 表单字段 → 回答 JSON

示例：

curl -s -F file="@examples/demo_image.png" -F prompt="Describe this image." http://127.0.0.1:8783/predict

输出 JSON

{
  "model": "HuggingFaceTB/SmolVLM-256M-Instruct",
  "source": "https://ai.gitcode.com/hf_mirrors/HuggingFaceTB/SmolVLM-256M-Instruct",
  "device": "npu:0",
  "status": "success",
  "elapsed_ms": 1234.56,
  "prompt": "Describe this image in detail.",
  "image": "demo_image.png",
  "answer": "The image shows a blue circle with a green dot in the center on a dark background."
}

示例图像

examples/demo_image.png 是一张 512×512 合成测试图像，包含一个蓝色圆形轮廓，内部有一个绿色圆形，背景为深色。用于验证 NPU 上的图像理解流程。

环境

• Python 3.11.14，PyTorch（昇腾 NPU 版），torch_npu
• 昇腾 Ascend 910
• 依赖：transformers>=4.57 torch torch-npu fastapi uvicorn safetensors Pillow einops

文件说明

• inference.py — 双模式推理入口（CLI + FastAPI，NPU 适配）
• make_screenshots.py — 生成验证截图
• examples/demo_image.png — 合成测试图像
• assets/ — 验证截图（agent_workflow / npu_device_call / model_result）

引用

@misc{smolvlm2025,
  title={SmolVLM: Small Vision Language Model},
  author={HuggingFace},
  year={2025},
  publisher={HuggingFace},
  howpublished={\url{https://huggingface.co/HuggingFaceTB/SmolVLM-256M-Instruct}}
}