SmolVLM-256M

SmolVLM-256M 是世界上最小的多模态模型。它接受任意的图像和文本输入序列来生成文本输出，专为高效设计。SmolVLM 可以回答有关图像的问题、描述视觉内容或转录文本。其轻量级架构使其适用于设备端应用，同时在多模态任务上保持强劲性能。它可以在不到 1GB GPU 显存的情况下对一张图像进行推理。

模型摘要

• 开发机构： Hugging Face 🤗
• 模型类型： 多模态模型（图像+文本）
• 语言（NLP）： 英语
• 许可证： Apache 2.0
• 架构： 基于 Idefics3（见技术摘要）

资源

• 演示： SmolVLM-256 演示
• 博客： 博客文章

用途

SmolVLM 可用于对多模态（图像+文本）任务进行推理，输入由文本查询和一个或多个图像组成。文本和图像可以任意交错，从而实现图像描述、视觉问答和基于视觉内容的故事生成等任务。该模型不支持图像生成。

要针对特定任务微调 SmolVLM，您可以遵循微调教程。

技术摘要

SmolVLM 采用轻量级的 SmolLM2 语言模型来提供紧凑而强大的多模态体验。与较大的 SmolVLM 2.2B 模型相比，它引入了多项改进：

• 图像压缩： 与 Idefics3 和 SmolVLM-2.2B 相比，我们引入了更激进的图像压缩，使模型推理更快、占用更少的显存。
• 视觉 Token 编码： SmolVLM-256 使用 64 个视觉 token 来编码 512×512 大小的图像块。较大的图像被分割成多个块，分别进行编码，在不影响性能的情况下提高效率。
• 新的特殊 token： 我们添加了新的特殊 token 来分割子图像。这使得图像的 token 化更加高效。
• 更小的视觉编码器： 我们将 400M 参数的 SigLIP 视觉编码器缩减为更小的 93M 编码器。
• 更大的图像块： 现在我们将 512x512 的图像块传递给视觉编码器，而不是像较大的 SmolVLM 那样使用 384x384。这使得信息能够被更高效地编码。

有关训练和架构的更多详细信息，请参阅我们的技术报告。

如何开始

您可以使用 transformers 来加载、推理和微调 SmolVLM。

import torch
from PIL import Image
from transformers import AutoProcessor, AutoModelForVision2Seq
from transformers.image_utils import load_image

DEVICE = "cuda" if torch.cuda.is_available() else "cpu"

# 加载图像
image = load_image("https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg")

# 初始化处理器和模型
processor = AutoProcessor.from_pretrained("HuggingFaceTB/SmolVLM-256M-Instruct")
model = AutoModelForVision2Seq.from_pretrained(
    "HuggingFaceTB/SmolVLM-256M-Instruct",
    torch_dtype=torch.bfloat16,
    _attn_implementation="flash_attention_2" if DEVICE == "cuda" else "eager",
).to(DEVICE)

# 创建输入消息
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": "Can you describe this image?"}
        ]
    },
]

# 准备输入
prompt = processor.apply_chat_template(messages, add_generation_prompt=True)
inputs = processor(text=prompt, images=[image], return_tensors="pt")
inputs = inputs.to(DEVICE)

# 生成输出
generated_ids = model.generate(**inputs, max_new_tokens=500)
generated_texts = processor.batch_decode(
    generated_ids,
    skip_special_tokens=True,
)

print(generated_texts[0])
"""
助手：这张图片描绘了一尊巨大的、自由女神的历史雕像，位于纽约市。雕像是一座绿色的圆柱形结构，顶端有一个人形人物手持火炬。雕像坐落在一个底座上，类似于位于水域中央小岛上的自由女神像。岛屿周围的水面平静，倒映着蓝天和雕像。

背景中有几座高层建筑，包括帝国大厦，在远处清晰可见。这些建筑由玻璃和钢铁建成，以网格状排列，给人现代感。天空晴朗，只有几朵云彩，表明天气良好。

雕像周围有树木，树木呈绿色，看起来很健康。还有一些小建筑，可能是房屋或建筑，在远处可见。整体场景暗示了一个宁静祥和的环境，是典型的城市景观。

这张照片可能是在雕像安装的白天拍摄的。光线明亮，在雕像和水面上投下强烈的阴影，增强了雕像和周围环境的可见度。

总之，这张照片捕捉了一座重要的自由女神历史雕像，位于水域中央的小岛上，周围有树木和建筑物。天空晴朗，只有几朵云彩，表明天气良好。雕像是绿色的圆柱形，顶端有一个人形人物手持火炬，周围有树木，表明环境宁静和维护良好。整体场景是宁静和历史意义的。
"""

我们还提供模型的 ONNX 权重，您可以使用 ONNX Runtime 运行，如下所示： <details>

<summary>点击查看示例代码</summary>

from transformers import AutoConfig, AutoProcessor
from transformers.image_utils import load_image
import onnxruntime
import numpy as np

# 1. 加载模型
## 加载配置和处理器
model_id = "HuggingFaceTB/SmolVLM-256M-Instruct"
config = AutoConfig.from_pretrained(model_id)
processor = AutoProcessor.from_pretrained(model_id)

## 加载会话
## !wget https://huggingface.co/HuggingFaceTB/SmolVLM-256M-Instruct/resolve/main/onnx/vision_encoder.onnx
## !wget https://huggingface.co/HuggingFaceTB/SmolVLM-256M-Instruct/resolve/main/onnx/embed_tokens.onnx
## !wget https://huggingface.co/HuggingFaceTB/SmolVLM-256M-Instruct/resolve/main/onnx/decoder_model_merged.onnx
vision_session = onnxruntime.InferenceSession("vision_encoder.onnx")
embed_session = onnxruntime.InferenceSession("embed_tokens.onnx")
decoder_session = onnxruntime.InferenceSession("decoder_model_merged.onnx")

## 设置配置值
num_key_value_heads = config.text_config.num_key_value_heads
head_dim = config.text_config.head_dim
num_hidden_layers = config.text_config.num_hidden_layers
eos_token_id = config.text_config.eos_token_id
image_token_id = config.image_token_id


# 2. 准备输入
## 创建输入消息
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image"},
            {"type": "text", "text": "Can you describe this image?"}
        ]
    },
]

## 加载图像并应用处理器
image = load_image("https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg")
prompt = processor.apply_chat_template(messages, add_generation_prompt=True)
inputs = processor(text=prompt, images=[image], return_tensors="np")

## 准备解码器输入
batch_size = inputs['input_ids'].shape[0]
past_key_values = {
    f'past_key_values.{layer}.{kv}': np.zeros([batch_size, num_key_value_heads, 0, head_dim], dtype=np.float32)
    for layer in range(num_hidden_layers)
    for kv in ('key', 'value')
}
image_features = None
input_ids = inputs['input_ids']
attention_mask = inputs['attention_mask']
position_ids = np.cumsum(inputs['attention_mask'], axis=-1)


# 3. 生成循环
max_new_tokens = 1024
generated_tokens = np.array([[]], dtype=np.int64)
for i in range(max_new_tokens):
  inputs_embeds = embed_session.run(None, {'input_ids': input_ids})[0]

  if image_features is None:
    ## 仅在尚未计算视觉特征时计算
    image_features = vision_session.run(
        ['image_features'],  # 输出名称或索引列表
        {
            'pixel_values': inputs['pixel_values'],
            'pixel_attention_mask': inputs['pixel_attention_mask'].astype(np.bool_)
        }
    )[0]
    
    ## 合并文本和视觉嵌入
    inputs_embeds[inputs['input_ids'] == image_token_id] = image_features.reshape(-1, image_features.shape[-1])

  logits, *present_key_values = decoder_session.run(None, dict(
      inputs_embeds=inputs_embeds,
      attention_mask=attention_mask,
      position_ids=position_ids,
      **past_key_values,
  ))

  ## 为下一次生成循环更新值
  input_ids = logits[:, -1].argmax(-1, keepdims=True)
  attention_mask = np.ones_like(input_ids)
  position_ids = position_ids[:, -1:] + 1
  for j, key in enumerate(past_key_values):
    past_key_values[key] = present_key_values[j]

  generated_tokens = np.concatenate([generated_tokens, input_ids], axis=-1)
  if (input_ids == eos_token_id).all():
    break

  ## （可选）流式输出
  print(processor.decode(input_ids[0]), end='')
print()

# 4. 输出结果
print(processor.batch_decode(generated_tokens))

示例输出：

 这张图片描绘了一尊位于水域中央小岛上的大型、历史悠久的自由女神雕像。雕是一座绿色的圆柱形结构，顶端有一个人形人物，即真正的自由女神。雕像安装在一个由圆柱形塔支撑的底座上。底座是矩形的，看起来像是用石头或类似材料制成的。雕像周围有一个大的、平坦的矩形区域，可能是雕像的基座。

背景是城市景观，有各种建筑物，包括摩天大楼和高层建筑。天空晴朗，颜色呈渐变，从顶部的淡蓝色到底部更深的蓝色。建筑物大多是现代的，采用玻璃和混凝土的混合设计。建筑物密集排列，可以看到许多摩天大楼和高层建筑。

图片左侧可见树木和绿地，表明雕像位于公园或绿地附近。前景中的水面平静，有小小的波纹，表明雕像位于水中。

整体场景暗示了一个宁静祥和的环境，可能是城市中的公共公园或绿地。雕像可能是自由的象征，代表着城市对自由和民主的承诺。

### 分析与描述：

#### 自由女神像：
- **位置**：雕像位于水域中央的小岛上。
- **雕像**：雕是一座绿色的圆柱形结构，顶端有一个人形人物，即真正的自由女神。
- **底座**：底座是矩形的，支撑着雕像。
- **基座**：底座周围是一个平坦的矩形区域。
- **水**：水面平静，有小小的波纹，表明雕像位于水中。

#### 城市景观：
- **建筑物**：建筑物是现代的，采用玻璃和混凝土的混合设计。
- **天空**：天空晴朗，颜色呈渐变，从顶部的淡蓝色到底部更深的蓝色。
- **树木**：图片左侧可见树木和绿地，表明雕像位于公园或绿地附近。

#### 环境：
- **水**：水面平静，有小小的波纹，表明雕像位于水中。
- **天空**：天空晴朗，颜色呈渐变，从顶部的淡蓝色到底部更深的蓝色。

### 结论：
这张图片描绘了一个宁静祥和的城市公共公园或绿地，自由女神像位于其中。背景中的城市景观包括现代建筑和晴朗的天空，表明这是一个维护良好的公共空间。

</details>

模型优化

精度：为了获得更好的性能，如果您的硬件支持，请以半精度（torch.bfloat16）加载和运行模型。

from transformers import AutoModelForVision2Seq
import torch

model = AutoModelForVision2Seq.from_pretrained(
    "HuggingFaceTB/SmolVLM-Instruct",
    torch_dtype=torch.bfloat16
).to("cuda")

您还可以使用 bitsandbytes、torchao 或 Quanto 以 4/8 位量化加载 SmolVLM。其他选项请参阅此页面。

from transformers import AutoModelForVision2Seq, BitsAndBytesConfig
import torch

quantization_config = BitsAndBytesConfig(load_in_8bit=True)
model = AutoModelForVision2Seq.from_pretrained(
    "HuggingFaceTB/SmolVLM-Instruct",
    quantization_config=quantization_config,
)

视觉编码器效率：初始化处理器时，通过设置 size={"longest_edge": N*512} 来调整图像分辨率，其中 N 是您想要的值。默认的 N=4 效果很好，这会导致输入图像的大小为 2048×2048。减小 N 可以节省 GPU 显存，适用于较低分辨率的图像。如果您想在视频上进行微调，这也很有用。

滥用和超出范围的使用

SmolVLM 不适用于影响个人福祉或生计的高风险场景或关键决策过程。模型可能会产生看似事实但可能不准确的内容。滥用包括但不限于：

• 禁止的用途：
  • 评估或评分个人（如就业、教育、信用）
  • 关键自动化决策
  • 生成不可靠的事实内容
• 恶意活动：
  • 垃圾信息生成
  • 虚假信息活动
  • 骚扰或虐待
  • 未经授权的监控

许可证

SmolVLM 基于 SigLIP 作为图像编码器，SmolLM2 作为文本解码器部分。

我们在 Apache 2.0 许可证下发布 SmolVLM 检查点。

训练详情

训练数据

训练数据来自 The Cauldron 和 Docmatix 数据集，重点强调文档理解（25%）和图像描述（18%），同时保持对其他关键能力（如视觉推理、图表理解和大指令遵循）的平衡覆盖。 <img src="https://huggingface.co/HuggingFaceTB/SmolVLM-Instruct/resolve/main/mixture_the_cauldron.png" alt="示例图像" style="width:90%;" />

评估

引用信息

您可以通过以下方式引用我们：

@article{marafioti2025smolvlm,
  title={SmolVLM: Redefining small and efficient multimodal models}, 
  author={Andrés Marafioti and Orr Zohar and Miquel Farré and Merve Noyan and Elie Bakouch and Pedro Cuenca and Cyril Zakka and Loubna Ben Allal and Anton Lozhkov and Nouamane Tazi and Vaibhav Srivastav and Joshua Lochner and Hugo Larcher and Mathieu Morlon and Lewis Tunstall and Leandro von Werra and Thomas Wolf},
  journal={arXiv preprint arXiv:2504.05299},
  year={2025}
}