知识就是力量。——培根

MLX-VLM：住在你 Mac 里的多模态小精灵——一边看图、一边听声、还能认真“想一会儿”再回答

MLX-VLM 不是一个冷冰冰的库。

它更像一个在 Apple Silicon 上长大的多模态精灵：
住在你的 Mac 里，靠着 MLX 的筋骨行走江湖，能 推理、能 看图、能 听音频，甚至还能在需要的时候把“思考”单独掏出来——控制预算，控制节奏，不把算力浪费在无意义的胡思乱想上。

它在 GitHub 上的自我介绍非常直接：

MLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) and Omni Models (VLMs with audio and video support) on your Mac using MLX. (github.com)

它的身份也很清晰：
一个让你在 Mac 上用 MLX 进行 视觉语言模型推理与微调 的工具包，而且不仅仅是“看图说话”的 VLM，还把“音频/视频支持”的 Omni Models 一起带进来。(github.com)

目录（它自己都把路给你铺好了）

MLX-VLM 的 README 像一个很会带人的队长，先把全局地图递给你：

  • Installation
  • Usage
    • CLI
      • Thinking Budget
    • Gradio Chat UI
    • Python Script
  • Activation Quantization (CUDA)
  • Multi-Image Chat Support
  • Model-Specific Documentation
  • Vision Feature Caching
  • TurboQuant KV Cache
  • Fine-tuning (github.com)

你会发现：它不是“能跑就行”的 demo 项目，它像一个真的准备好让你长期使用、长期折腾的工具箱。

安装：它最喜欢你用 pip 叫它一声

它给的起手式很简单：

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
pip install -U mlx-vlm
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

这一句就像召唤咒语——你一念完，它就会带着自己的能力包落在你的 Python 环境里。

---

## 先玩起来：CLI 让它当场表演“文本 / 图片 / 音频 / 图+音”四连击

MLX-VLM 的 CLI 名字很统一：`mlx_vlm.generate`。  
你可以把它当成一个“多模态出入口”，你给它什么，它就用模型去生成什么。

### 1）纯文本生成

```bash
mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
  --max-tokens 100 \
  --prompt "Hello, how are you?"
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

它会像一个礼貌的对话者，先把话接住，再把回答吐出来。

### 2）图片理解 / 看图说话

```bash
mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
  --max-tokens 100 \
  --temperature 0.0 \
  --image http://images.cocodataset.org/val2017/000000039769.jpg
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

这时它的眼睛睁开：  
“你给我一张图，我给你一句稳定、干净、温度为 0 的描述。”

### 3）音频理解（New）

```bash
mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit \
  --max-tokens 100 \
  --prompt "Describe what you hear" \
  --audio /path/to/audio.wav
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

它不只会看，它也会听。你把 wav 文件递给它，它就认真听完再回答。([github.com](https://github.com/Blaizzy/mlx-vlm))

### 4）图 + 音频：多模态一起上

```bash
mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit \
  --max-tokens 100 \
  --prompt "Describe what you see and hear" \
  --image /path/to/image.jpg \
  --audio /path/to/audio.wav
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

这就是它“Omni”的那一面：  
眼睛和耳朵同时工作，把世界的不同信号拼成一段更完整的理解。([github.com](https://github.com/Blaizzy/mlx-vlm))

---

## Thinking Budget：它会思考，但你可以管住它“想多久”

有些模型是“thinking models”（例如 README 提到的 Qwen3.5）。  
MLX-VLM 允许你限定它在 `<think>...</think>` 这段“思考块”里最多花多少 token。

示例命令：

```bash
mlx_vlm.generate --model mlx-community/Qwen3.5-2B-4bit \
  --thinking-budget 50 \
  --thinking-start-token "<think>" \
  --thinking-end-token "</think>" \
  --enable-thinking \
  --prompt "Solve 2+2"
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

它还把每个旗标的性格解释得明明白白：([github.com](https://github.com/Blaizzy/mlx-vlm))

- `--enable-thinking`：在 chat template 里启用 thinking 模式  
- `--thinking-budget`：思考块内允许的最大 token 数  
- `--thinking-start-token` / `--thinking-end-token`：思考块边界 token  

如果预算超了，它会被“强制收尾”：输出 `\n</think>`，然后从思考切换到最终答案。([github.com](https://github.com/Blaizzy/mlx-vlm))

这感觉就像你在旁边敲了敲桌子：  
“想够了，给结论。”

---

## Chat UI：它也愿意变成一个 Gradio 聊天窗口

如果你想让它从命令行走出来，坐到一个可对话的界面里：

```bash
mlx_vlm.chat_ui --model mlx-community/Qwen2-VL-2B-Instruct-4bit
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

它会披上���层 Gradio 外衣，变成你桌面上的一个“可视化多模态聊天搭子”。([github.com](https://github.com/Blaizzy/mlx-vlm))

---

## Python 脚本：把它当成你的函数，而不是你的命令

MLX-VLM 在 Python 侧提供了更“工程化”的用法：`load` + `generate`，再配合 chat template。

下面这段就是它给的示例：([github.com](https://github.com/Blaizzy/mlx-vlm))

```python
import mlx.core as mx
from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

# Load the model
model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit"
model, processor = load(model_path)
config = load_config(model_path)

# Prepare input
image = ["http://images.cocodataset.org/val2017/000000039769.jpg"]
# image = [Image.open("...")] can also be used with PIL.Image.Image objects
prompt = "Describe this image."

# Apply chat template
formatted_prompt = apply_chat_template(
    processor, config, prompt, num_images=len(image)
)

# Generate output
output = generate(model, processor, formatted_prompt, image, verbose=False)
print(output)

它的习惯很明确：

  1. load(model_path)：把模型和 processor 请进来
  2. load_config(model_path)：把配置拿到手
  3. apply_chat_template(...)：把 prompt 变成模型真正爱吃的格式
  4. generate(...)：输出结果

它像一位严谨的翻译官：
你说人话，它帮你套好模板，再把“机器能吃的格式”喂给模型。(github.com)

音频脚本：它也能在 Python 里“听”

README 也给了音频版本的示例：(github.com)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

# Load model with audio support
model_path = "mlx-community/gemma-3n-E2B-it-4bit"
model, processor = load(model_path)
config = model.config

# Prepare audio input
audio = ["/path/to/audio1.wav", "/path/to/audio2.mp3"]
prompt = "Describe what you hear in these audio files."

# Apply chat template with audio
formatted_prompt = apply_chat_template(
    processor, config, prompt, num_audios=len(audio)
)

# Generate output with audio
output = generate(model, processor, formatted_prompt, audio=audio, verbose=False)
print(output)

它甚至允许你一次塞多个音频文件，让它像一位认真听证的记录员，把每个声音细节都串起来。(github.com)

图 + 音频脚本：多模态在代码里也能并肩作战

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

# Load multi-modal model
model_path = "mlx-community/gemma-3n-E2B-it-4bit"
model, processor = load(model_path)
config = model.config

# Prepare inputs
image = ["/path/to/image.jpg"]
audio = ["/path/to/audio.wav"]
prompt = ""

# Apply chat template
formatted_prompt = apply_chat_template(
    processor, config, prompt,
    num_images=len(image),
    num_audios=len(audio)
)

# Generate output
output = generate(model, processor, formatted_prompt, image, audio=audio, verbose=False)
print(output)
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

一边看、一边听，然后给结论。  
它的“多模态人格”在这一刻会显得特别完整。([github.com](https://github.com/Blaizzy/mlx-vlm))

---

## Server（FastAPI）：它还能站起来当一个服务

当你不想每次都在脚本里 load 模型，或者你想让别的程序来调用它时，它会自己站起来开一个服务端：

```bash
mlx_vlm.server --port 8080
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

你还可以在启动时预加载模型：

```bash
mlx_vlm.server --model <hf_repo_or_local_path>
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

或者预加载模型 + adapter：

```bash
mlx_vlm.server --model <hf_repo_or_local_path> --adapter-path <adapter_path>
``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

有些模型需要 trust remote code，它也给你开关：([github.com](https://github.com/Blaizzy/mlx-vlm))

```bash
mlx_vlm.server --trust-remote-code

或者用环境变量：

MLX_TRUST_REMOTE_CODE=true mlx_vlm.server

``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

它像一个店长：  
“你要堂食（CLI/脚本）我也欢迎；你要外卖（HTTP 服务）我也能接单。”

---

## Activation Quantization (CUDA)：它也愿意去 NVIDIA 那边出差

虽然它的主要舞台在 Mac（MLX/Metal），但 README 也写了：如果你在 NVIDIA GPU 上跑 MLX CUDA，某些量化模型（`mxfp8` / `nvfp4`）需要 activation quantization 才能正常工作。([github.com](https://github.com/Blaizzy/mlx-vlm))

它把原因解释得很工程化：  
把 `QuantizedLinear` 转成 `QQLinear`，让权重和激活都量化。([github.com](https://github.com/Blaizzy/mlx-vlm))

### CLI 方式：加 `-qa` / `--quantize-activations`

```bash
mlx_vlm.generate --model /path/to/mxfp8-model \
  --prompt "Describe this image" \
  --image /path/to/image.jpg \
  -qa

``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

### Python 方式：`load(..., quantize_activations=True)`

```python
from mlx_vlm import load, generate

# Load with activation quantization enabled

model, processor = load(
    "path/to/mxfp8-quantized-model",
    quantize_activations=True
)

# Generate as usual

output = generate(model, processor, "Describe this image", image=["image.jpg"])

``` ([github.com](https://github.com/Blaizzy/mlx-vlm))

支持的量化模式：([github.com](https://github.com/Blaizzy/mlx-vlm))

- `mxfp8`
- `nvfp4`

---

## Multi-Image Chat：它不怕多图一起上（它甚至喜欢）

README 里明确写了它支持“同时分析多张图”的能力，并指出这能用于更复杂的视觉推理和跨图综合分析。([github.com](https://github.com/Blaizzy/mlx-vlm))

这就像它说：  
“别只给我一张，我更想看一组——我更擅长把它们放在同一个故事里理解。”

---

## Vision Feature Caching：它讨厌重复劳动，会把“看图后的特征”记下来

多轮对话里，如果你一直在聊同一张图，视觉编码器理论上每回合都得跑一次，代价很高。

MLX-VLM 的 `VisionFeatureCache` 会把投影后的视觉特征放进 LRU 缓存，按 image path 做 key，这样同一张图只需要跑一次视觉编码器。([github.com](https://github.com/Blaizzy/mlx-vlm))

它���一个很会偷懒但偷得很聪明的助手：  
“同一张图我都看过了，还要我每次重新看？我把笔记放抽屉里了，直接拿出来。”

---

## TurboQuant KV Cache：它连“注意力的记忆”都想帮你省

README 里提到 TurboQuant 会自动量化 `KVCache` 层（global attention）。  
同时对一些已经更省内存的 cache 结构（如 sliding window 或 MLA 等）会保留原生格式。([github.com](https://github.com/Blaizzy/mlx-vlm))

它的心态很像一个懂分寸的性能工程师：  
“该省的我省，不该动的我不动。”

---

## Fine-tuning：它不仅能推理，还能训练（LoRA / QLoRA）

MLX-VLM 不满足于“我能跑模型”，它也想让你说：

“我能把模型微调成更像我想要的样子。”

README 写得很直接：

- MLX-VLM supports fine-tuning models with **LoRA and QLoRA**。([github.com](https://github.com/Blaizzy/mlx-vlm))
- 想深入了解 LoRA，可以看仓库里的 `LoRA.md`。([github.com](https://github.com/Blaizzy/mlx-vlm))

它像一个愿意被你训练的伙伴：  
“你不只是使用我——你也可以塑造我。”

---

## Model-Specific Documentation：它还给不同模型准备了“专属说明书”

README 列出了一批模型的 Docs（例如 DeepSeek-OCR、Phi-4 Multimodal、Moondream3、Gemma 4 等），并说明这些文档会包含 prompt format、示例、best practices。([github.com](https://github.com/Blaizzy/mlx-vlm))

它像一个很会做知识库的管家：  
“不同模型脾气不同，我给你每个人的使用手册，你别硬怼。”

---

## 结语：它的名字叫 MLX-VLM，但它更像一个“Mac 上的多模态工作台”

MLX-VLM 的核心气质只有一句话：  
**把 VLM/Omni 的推理与微调，拉到你 Mac 的桌面上，让它变得像 pip 一样轻、像 CLI 一样快、像脚本一样可控、像服务一样可集成。** ([github.com](https://github.com/Blaizzy/mlx-vlm))

你给它一张图，它就睁眼。  
你给它一段音频，它就竖耳。  
你让它思考，它会思考；你给它预算，它就按预算办事。([github.com](https://github.com/Blaizzy/mlx-vlm))