基于 llama.cpp 和 SmolVLM 的端侧多模态推理

背景

App 中有几类图像理解需求,例如作品检索、补充图片 Prompt 和生成发布文案,目前主要依赖服务端大模型。为了降低调用成本、图片传输和网络延迟,我们开始探索端侧模型。

此前调研了 MLX、llama.cpp 等推理框架。本文以 SmolVLM 和 llama.cpp 为例,从模型结构入手,继续分析它在 llama.cpp 中的完整推理过程。选择这套组合主要有两个原因:

  • SmolVLM 提供了多种适合端侧运行的量化版本,llama.cpp 较早完成了对该模型的适配。
  • llama.cpp 本身以 C++ 实现,也便于两端复用底层推理代码,减少跨平台语言层的额外适配。

VLM 模型简介

本节内容参考 SmolVLM 论文。

大多数 VLM 都可以拆成三个核心模块:视觉编码器(Vision Encoder)、投影器(Projector)和大语言模型(LLM)。视觉编码器负责提取图像特征,投影器把这些特征映射到语言模型能够处理的嵌入空间,LLM 再结合文本 token 完成理解与生成。

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:VLM 模型简介(图 1)

SmolVLM 沿用了这一结构,并针对内存占用和推理效率做了调整。图像或视频帧先被编码为视觉特征,再与文本嵌入组成混合序列送入语言模型。对应到模型中有三部分:

  1. Vision Model:SigLIP 编码器负责处理输入图像或视频帧,提取视觉特征。
  2. Projector:先通过 Pixel Shuffle 对视觉特征进行压缩,再统一映射到语言模型的嵌入空间,供 LLM 理解与处理。
  3. LLM:基于 SmolLM2,处理视觉与文本组成的混合序列并生成结果。

SmolVLM 的图像切分策略

SmolVLM 在视觉编码前会执行 Image Splitting。这里容易产生误解:它不做对象级语义分割,而是根据图片尺寸和模型限制划分规则网格,同时保留一张低分辨率的全局缩略图。局部切片保留细节,全局图补充整张图片的上下文。

  • 直接编码全图:若将 1920×1080 等高分辨率图片直接缩放到视觉编码器的固定输入尺寸(如 512×512),小文字、图表元素等细节容易丢失。

  • 规则切片:将缩放后的图片按固定网格切成多个子图,每个子图单独编码,可以在模型输入尺寸不变的情况下保留更多局部信息。

视觉编码器

SmolVLM 的视觉编码器基于 SigLIP(Sigmoid Loss for Language-Image Pretraining)。SigLIP 采用 Vision Transformer(ViT)架构,通过图文对预训练,把视觉信息编码为紧凑的特征表示。与 CLIP 的全局 softmax 不同,SigLIP 对每个图文对独立计算 sigmoid loss,不需要对批次内所有相似度做全局归一化,因此对 batch size 的依赖更小。

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:视觉编码器(图 2)

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:视觉编码器(图 3)

对比维度 CLIP SigLIP
提出时间 OpenAI,2021 Google,2023
训练目标 在一个 batch 内对图文相似度进行全局 softmax 归一化 对每个图文对独立计算 sigmoid loss
对 batch 的依赖 通常需要较大的 batch 才能获得足够多的负样本 不依赖全局归一化,在较小 batch 下也能保持较好的训练效果

SmolVLM 会根据模型规模和应用场景选用不同的 SigLIP 变体:

  • SigLIP base patch-16/512:参数量约 93M,patch 大小为 16×16 像素,用于 SmolVLM-256M 和 SmolVLM-500M,适合资源受限的设备。

  • SigLIP-SO400M:参数量约 428M,patch 大小为 14×14 像素,用于 SmolVLM-2.2B,面向更高性能需求。

SmolVLM 的实验表明,增大视觉编码器并不一定能显著提升整体效果。搭配 135M 语言模型时,428M 视觉编码器的表现反而不及 93M 版本;搭配 360M 语言模型时,较大的编码器虽然带来了 11.6% 的性能提升,参数量也随之增加了 66%。

对紧凑型 VLM 来说,单独增大视觉编码器未必划算。语言模型太小时,额外增加的视觉特征不一定能被充分利用。

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:视觉编码器(图 4)

类似的紧凑型 VLM 也常采用“语言模型参数量高于视觉编码器”的配置。

大语言模型

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:大语言模型(图 5)

SmolLM2.jpg

Hugging Face 发布的 SmolLM2 是一组面向端侧应用的小型语言模型,包含 0.1B、0.3B 和 1.7B 三种规模。它延续了 SmolLM1 的轻量化方向,适合对延迟、隐私和硬件资源较为敏感的场景。

其中,SmolLM2-1.7B 使用 FineWeb-Edu、DCLM 和 The Stack 等数据集中的约 11 万亿个 token 进行训练,内容以英语为主,并针对文本重写、摘要和函数调用等任务做了优化。从公开材料看,训练过程有几个值得注意的地方:

  • 长时间训练:模型规模较小,但训练 token 数量远高于以往同等规模模型的常见配置。

  • 多阶段训练:先使用大规模 Web 文本,再逐步加入高质量数学、代码和指令数据,并动态调整数据源的混合比例。

  • 数据评估与选择:分别评估 Web、代码、数学和指令遵循数据,并根据结果决定训练数据的组成。

  • 数据集增强:补充 FineMath、Stack-Edu 和 SmolTalk,分别加强数学推理、代码和指令遵循能力。

  • 在线重平衡:根据模型在关键基准测试上的表现,持续调整数据集比例。

投影层

SmolVLM 的投影层负责把 SigLIP 输出并经过 Pixel Shuffle 处理的视觉特征映射到语言模型的嵌入空间。Pixel Shuffle 将每个视觉 token 的特征维度扩展为原来的 倍,随后通过线性投影映射到语言模型的 hidden size,这样便能和文本 token 一起处理。

这一层的结构很轻,计算开销也不高。不过它做的主要是维度和特征空间对齐,投影时可能丢失一部分细节,也不会主动建模更复杂的跨模态关系。

像素重排

Pixel Shuffle 最初用于图像超分辨率,通过重新排列空间维度与通道维度,在不丢弃元素的情况下改变特征图形状。SmolVLM 使用相反方向的重排,把部分空间信息压入通道维度,减少送入语言模型的视觉 token 数量。结果是特征向量变宽,token 序列变短。

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:像素重排(图 7)

标准 Pixel Shuffle 的形状变化可以写成: 。

  • B :批次大小(batch size)。

  • :总通道数,包含 个子单位( 是缩放因子)。

  • H:图片高度。

  • W :图片宽度。

上式对应超分辨率方向。SmolVLM 使用逆向重排,可表示为 。

以一个典型变换为例:

。这一操作降低了空间分辨率,同时按比例扩展通道数。

在 SmolVLM-256M 模型中,一张 512×512 的图像会被划分为 64 个独立图像块,每个图像块被编码为一个视觉 token,最终仅用 64 个 token 完成整张图像的表征。这种设计大幅减少了输入语言模型的视觉 token 数量,既降低了内存占用,也显著加速了推理速度。

SmolVLM-256M 使用 SigLIP base patch-16。对于 512×512 的输入图,patch 大小为 16×16,因此会产生 1024 个视觉 token。接下来再通过 Pixel Shuffle 将其压缩到 64 个。

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:像素重排(图 8)

1024 个 patch 对应一个 32x32 的空间网格。将 token 数量从 1024 减少到 64 时,压缩比为:

,因此空间缩放因子为 4,对应 。其中 是 token 的特征维度。这个过程把部分空间信息压入通道维度,缩短视觉 token 序列,并降低后续注意力计算与 KV Cache 的开销:

  • 对 Transformer 而言,注意力计算通常随序列长度呈平方增长。若 token 序列长度为 Len、特征维度为 Dim,则 和 的形状为 ,注意力矩阵的形状为 。

    Undefined control sequence \boldsymbol

  • 在推理过程中,模型会生成并缓存键 (Key) 和值 (Value) 向量(KV Cache)。KV Cache 的大小直接与输入序列长度和批次大小成正比。

进入语言模型后,视觉 token 仍然会被展平成一维序列。二维空间关系主要由视觉编码器及位置相关信息表达,LLM 接收到的是按序排列的视觉特征。SmolVLM 论文对这一过程有更完整的说明。

推理框架

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:推理框架(图 9)

llama.cpp 是以 C/C++ 实现的本地大模型推理框架,目标是在多种硬件环境中以较少依赖完成模型部署,并提供具有竞争力的推理性能。

框架特性:

  • 基于纯 C/C++ 实现,无任何外部依赖;

  • 原生支持苹果芯片(Apple silicon),并通过 ARM NEON、Accelerate 框架及 Metal 框架进行深度优化;

  • 针对 x86 、RISC-V 架构,提供各自的指令集支持;

  • 支持 1.5 位、2 位、3 位、4 位、5 位、6 位及 8 位整数量化,实现更快的推理速度并降低内存占用;

  • 提供定制化 CUDA 核函数,用于在 NVIDIA GPU 上运行大语言模型(LLMs);同时通过 HIP 支持 AMD GPU,通过 MUSA 支持摩尔线程(Moore Threads)GPU;

  • 支持 Vulkan 及 SYCL 后端;

  • 支持 CPU+GPU 混合推理模式,可对超出显存总容量的大型模型实现部分加速运行。

在这次接入中,我们主要用到的是 llama.cpp 的多模态推理链路:语言模型、视觉投影器和图文输入都由同一套接口组织。再加上 iOS、Android 两端都能运行,底层模型逻辑可以共用,客户端只需处理各自的平台接入。

模型文件

GGUF 是 GGML 生态使用的一种模型交换与存储格式,针对快速加载和推理做了优化。它是 GGML、GGMF 和 GGJT 的后续格式,可以在文件中保存模型结构、配置和权重,也允许在保持兼容性的前提下扩展元数据。随着 llama.cpp 的发展,GGUF 已被许多本地推理工具采用。

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:模型文件(图 10)

GGUF 文件是一种二进制格式,由三个主要部分组成:文件头、元数据和张量数据。

  1. 文件头: 包含魔数 GGUF 和格式版本号,供加载器识别文件并处理版本差异。

  2. 元数据: 以键值形式保存模型架构、名称、embedding 维度、词表和张量信息等配置,使加载器不必依赖额外配置文件。

  3. 张量数据: 连续存放权重、偏置和归一化参数。量化模型还会保存低精度数据及反量化所需的信息,并按照 Q4_0、Q5_K、Q8_0、F16、F32 等类型进行组织。张量通常按特定字节边界对齐,以便高效地进行内存映射和加载。

与 Safetensors 相比,GGUF 更强调面向推理的自描述能力:除了权重,还可以保存模型架构、量化方式和词表等元数据;Safetensors 虽然也支持文件级元数据,但模型配置和 tokenizer 通常由其他文件提供。对于多模态模型,语言模型与视觉投影器仍可能分别存放在不同的 GGUF 文件中。

  • 自描述:权重、架构和量化信息放在同一个模型组件中,加载器可以直接从文件读取所需参数。

  • 内存映射:张量按规则对齐,可以通过 mmap 映射,避免启动时复制整份模型。

  • 可扩展:元数据采用键值结构,新增字段时不必重新设计整个文件格式。

以 SmolVLM-256M-Instruct-GGUF 为例,可以直接在 Hugging Face 查看语言模型与视觉模型的元数据和张量描述。

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:模型文件(图 11)

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:模型文件(图 12)

推理过程

接下来从 mtmd-cli.cpp 的入口往下走,看看图像切分、视觉编码、Pixel Shuffle 和语言模型推理分别落在哪段代码里。

加载模型

llama.cpp 的初始化入口位于 mtmd-cli.cpp 的 main() 方法中。

1
2
3
4
5
6
int main(int argc, char ** argv) {
...
if (!common_params_parse(argc, argv, params, LLAMA_EXAMPLE_MTMD, show_additional_info)) {
}
...
}

common_params_parse() 负责把环境变量与命令行参数归一化到 common_params,并完成模型下载和参数约束校验。后续的模型加载、上下文创建与推理都会直接使用这个统一参数结构。

构建 Context

1
2
3
4
5
int main(int argc, char ** argv) {
...
mtmd_cli_context ctx(params);
...
}

构建 mtmd_cli_context 时会加载语言模型与视觉模型,并初始化模型参数、Chat Template、词表和缓存,最终得到后续推理所需的 llama_context。

Prompt 处理

不同模型使用的 Chat Template 并不相同。SmolVLM 基于 IDEFICS3 架构,Prompt 需要按照官方的 Chat Template 组织。该模板也会写入模型文件,可以在加载模型时直接读取。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<|im_start|>
{% for message in messages %}
{{message['role'] | capitalize}}
{% if message['content'][0]['type'] == 'image' %}{{':'}}{% else %}{{': '}}{% endif %}
{% for line in message['content'] %}
{% if line['type'] == 'text' %}
{{line['text']}}
{% elif line['type'] == 'image' %}
{{ '<image>' }}
{% endif %}
{% endfor %}
<end_of_utterance>
\n
{% endfor %}
{% if add_generation_prompt %}
{{ 'Assistant:' }}
{% endif %}

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:Prompt 处理(图 13)

Image Marker、User Prompt 和 System Prompt 必须按照模板规定的顺序拼接。图片与文本位置颠倒可能导致异常输出。

1
2
3
<|im_start|>System: You are a helpful assistant.<end_of_utterance>
User:<image>Describe this image.<end_of_utterance>
Assistant:

llama.cpp 中的 Image Marker 可以改为官方模板使用的 \<image\>。这个标记不会被转换成普通 token id,而是被解析成独立的图片 chunk;进入 Transformer 前,它会被替换为图片的 embedding 向量。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//mtmd.cpp
const char * mtmd_default_marker() {
return "<image>";
// return "<__media__>";
}

struct mtmd_tokenizer {
int32_t tokenize(mtmd_input_chunks * output) {
//文本转 token id <image> 转成图片chunk
...
*output = std::move(cur);
return 0;
}
}

在这里使用的 llama.cpp 版本中,System Prompt 和 User Prompt 会分别调用一次 eval_message(),而不是一次性完成处理。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//mtmd-cli.cpp
int main(int argc, char ** argv) {
...
auto eval_system_prompt_if_present = [&] {
...
msg.role = "system";
//如果系统Prompt存在,做一次Prefill
return eval_message(ctx, msg);
};
...
if (is_single_turn) {
...
// userprompt存在,做一次Prefill
if (eval_message(ctx, msg)) {
return 1;
}
...
}
}

基于 llama.cpp 和 SmolVLM 的端侧多模态推理:Prompt 处理(图 14)

当时的实现没有为 System Prompt 添加结束标记 \<end_of_utterance\>,因此需要补上这段逻辑。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
//llama-chat.cpp
int32_t llm_chat_apply_template(
llm_chat_template tmpl,
const std::vector<const llama_chat_message *> & chat,
std::string & dest, bool add_ass) {
...
else if (tmpl == LLM_CHAT_TEMPLATE_SMOLVLM) {
// SmolVLM
ss << "<|im_start|>"; // uses <|im_start|> as BOS, but the actual content is NOT chatml
for (auto message : chat) {
std::string role(message->role);
if (role == "system") {
// ss << "System: " << message->content << "\n\n";
//修改结尾标志
ss << "System: " << message->content << "<end_of_utterance>\n";
} else if (role == "user") {
ss << "User: " << message->content << "<end_of_utterance>\n";
} else {
ss << "Assistant: " << message->content << "<end_of_utterance>\n";
}
}
if (add_ass) {
ss << "Assistant:";
}
}
....
}

Prefill 过程

在 LLaMA、GPT 等自回归语言模型中,第一次把完整输入序列送入模型,计算隐藏状态、logits 和 KV Cache 的过程通常称为 Prefill。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
static int eval_message(mtmd_cli_context & ctx, common_chat_msg & msg) {
...
int32_t res = mtmd_tokenize(ctx.ctx_vision.get(),
chunks.ptr.get(), // output
&text, // text
bitmaps_c_ptr.data(),
bitmaps_c_ptr.size());
...
llama_pos new_n_past;
if (mtmd_helper_eval_chunks(ctx.ctx_vision.get(),
ctx.lctx, // lctx
chunks.ptr.get(), // chunks
ctx.n_past, // n_past
0, // seq_id
ctx.n_batch, // n_batch
true, // logits_last
&new_n_past)) {
LOG_ERR("Unable to eval prompt\n");
return 1;
}
ctx.n_past = new_n_past;
...
}

一次 eval_message() 就对应一次 Prefill:先由 mtmd_tokenize() 对 Prompt 进行 token 化并拆分 chunk,再由 mtmd_helper_eval_chunks() 执行前向推理。

Prefill 流程

System Prompt 和 User Prompt 会分别执行一次 eval_message(),也就是分两段完成前向推理。从 llama.cpp 的实现来看,只要 token 的位置连续、KV Cache 按顺序追加,分段处理就不会改变最终序列。第一段产生的 logits_0 不参与后续采样,真正用于生成的是最后一个 chunk 的 logits。代价是中间段仍然会计算一份最终不会使用的 logits。

mtmd_helper_eval_chunks() 负责把图像与文本 chunk 按顺序送入模型,并分别处理图像编码和文本 decode。

如图所示,System Prompt 会形成文本 chunk0,先进入语言模型完成一次前向推理并生成 logits_0。User Prompt 则被拆成文本 chunk1、图片 chunk2 和文本 chunk3,再依次送入模型。只有最后一个文本 chunk 产生的 logits_last 会用于自回归采样。

llama.cpp 中的图像预处理

SmolVLM 论文提到,图片进入 SigLIP 编码器前会先被切成多个局部图,再分别编码为图片 embedding。llama.cpp 的对应入口是 clip_image_preprocess()。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
clip.h
bool clip_image_preprocess(struct clip_ctx * ctx, const clip_image_u8 * img, struct clip_image_f32_batch * res_imgs) {
case PROJECTOR_TYPE_IDEFICS3:{
...
//保留一张全局预览原图
instructions.overview_size = clip_image_size{params.image_size, params.image_size};
//原图按比例缩放,最长边不超过指定值的最后宽高
instructions.refined_size = refined_size;
//refined_size的图片要被裁成多少个子图片块
instructions.grid_size = clip_image_size{
static_cast<int>(std::ceil(static_cast<float>(refined_size.width) / params.image_size)),
static_cast<int>(std::ceil(static_cast<float>(refined_size.height) / params.image_size)),
};
...

这段逻辑会先确定全局预览图的尺寸 overview_size,再计算原图按模型限制缩放后的 refined_size,最后根据单张切片的目标尺寸得到网格数量 grid_size。

SmolVLM 的 preprocessor_config.json 中,size.longest_edge 为 2048,表示缩放后图片的最长边限制;max_image_size.longest_edge 为 512,对应视觉编码器处理单张图片的目标尺寸。例如,1024×512 的原图会被缩放为 2048×1024,再切成 8 张 512×512 的局部图,加上一张全局预览图,共有 9 张图片参与编码。这里使用的 llama.cpp 与视觉 GGUF 没有单独保存 longest_edge,实际运行时只处理了全局预览图;若要启用完整切片,需要在读取视觉模型超参数时补充相应的 longest_edge。

Llama Decode

llama_context::decode() 是推理过程的核心入口:它接收一批 token,执行 Transformer 前向计算,更新 KV Cache,并得到 logits。

其主要步骤有:

  1. 构建计算图
  2. 运行 Transformer
  3. 写入 KV Cache
  4. 生成 logits
1
2
3
4
5
6
7
8
9
10
11
12
13
14
int llama_context::decode(const llama_batch & batch_inp) {
...
const auto * res = process_ubatch(ubatch, LLM_GRAPH_TYPE_DECODER, mctx.get(), status);
...
auto *t_logits = res->get_logits();
...
if (logits.data && t_logits && n_outputs > 0 && needs_raw_logits(ubatch, sampling.samplers)) {
...
float * logits_out = logits.data + n_outputs_prev*n_vocab;
if (n_outputs) {
ggml_backend_tensor_get_async(backend_res, t_logits, logits_out, 0, n_outputs * n_vocab * sizeof(float));
}
}
}

process_ubatch() 负责构建计算图、设置输入数据并调度 Metal 后端执行,同时保存本轮生成的 KV Cache。计算完成后,logits 会异步拷贝到 CPU 侧的 llama_context::logits.data 缓存,供后续自回归采样使用。后端张量和计算图调度涉及更多细节,本文暂不展开。

自回归解码

自回归解码(Autoregressive Decoding)是主流大语言模型在生成阶段普遍采用的解码方式。

模型每次只生成一个 token,新 token 依赖 Prompt、KV Cache 和此前已经生成的全部 token。

Prefill 得到首个采样位置的 logits 后,模型从中采样 token,将它追加到 batch,再执行下一轮 decode。这个过程持续循环,直到命中停止条件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
static int generate_response(mtmd_cli_context & ctx, int n_predict) {

// 采样最新的token id
llama_token token_id = common_sampler_sample(ctx.smpl, ctx.lctx, -1);
generated_tokens.push_back(token_id);
...
//转换成字符串
std::string piece = common_token_to_piece(ctx.lctx, token_id);
...
//继续下一次推理
common_batch_add(ctx.batch, token_id, ctx.n_past++, {0}, true);
if (llama_decode(ctx.lctx, ctx.batch)) {
on_token(piece, GEN_DECODE_FAIL);
LOG_ERR("failed to decode token\n");
return 1;
}
...
}

总结

回头看这条链路,图像和文本其实走了两条不同的准备路径。图像经过切分和视觉编码,再由 Pixel Shuffle 缩短视觉 token 序列,最后通过投影层进入语言模型的嵌入空间。文本则按照 Chat Template 被拆成 token 和 chunk。两者按 Prompt 中的位置合并,在 Prefill 阶段写入 KV Cache,随后进入逐 token 的自回归 Decode。

如果输出结果不符合预期,可以先核对 Chat Template、Image Marker、图像预处理参数,以及各段 Prefill 是否连续更新位置和 KV Cache。这几处都会直接影响输出内容、图像理解效果和内存占用。

-------------本文结束 感谢您的阅读-------------
坚持原创技术分享,您的支持将鼓励我继续创作!

本文标题:基于 llama.cpp 和 SmolVLM 的端侧多模态推理

文章作者:lingyun

发布时间:2026年10月07日 - 19:10

最后更新:2026年10月11日 - 00:10

原始链接:https://tsuijunxi.github.io/2026/10/07/%E5%9F%BA%E4%BA%8E%20llama.cpp%20%E5%92%8C%20SmolVLM%20%E7%9A%84%E7%AB%AF%E4%BE%A7%E5%A4%9A%E6%A8%A1%E6%80%81%E6%8E%A8%E7%90%86/

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。