MLX-VLM

MLX-VLM 是一个用于在您的 Mac 上使用 MLX 对视觉语言模型（VLM）和全能模型（支持音频和视频的 VLM）进行推理和微调的软件包。

目录

• 安装
• 使用
  • 命令行界面 (CLI)
    • 思考预算
  • Gradio 聊天界面
  • Python 脚本
• 激活量化 (CUDA)
• 多图像聊天支持
  • 支持的模型
  • 使用示例
• 模型专用文档
• 视觉特征缓存
• TurboQuant KV 缓存
• 微调

模型专用文档

部分模型提供了详细的文档，包括提示格式、示例和最佳实践：

模型	文档
DeepSeek-OCR	文档
DeepSeek-OCR-2	文档
DOTS-OCR	文档
DOTS-MOCR	文档
GLM-OCR	文档
Phi-4 Reasoning Vision	文档
MiniCPM-o	文档
Phi-4 多模态	文档
MolmoPoint	文档
Moondream3	文档
Gemma 4	文档
Falcon-OCR	文档
Granite Vision 3.2	文档
Granite 4.0 Vision	文档

安装

开始使用的最简单方法是使用 pip 安装 mlx-vlm 包：

pip install -U mlx-vlm

使用

命令行界面 (CLI)

使用 CLI 从模型生成输出：

# 文本生成
mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "你好，最近怎么样？"

# 图像生成
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

# 音频生成（新功能）
mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "描述你听到的内容" --audio /path/to/audio.wav

# 多模态生成（图像 + 音频）
mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "描述你看到和听到的内容" --image /path/to/image.jpg --audio /path/to/audio.wav

思考预算

对于具备思考能力的模型（例如 Qwen3.5），您可以限制思考块中消耗的标记数量：

mlx_vlm.generate --model mlx-community/Qwen3.5-2B-4bit \
  --thinking-budget 50 \
  --thinking-start-token "<think>" \
  --thinking-end-token "</think>" \
  --enable-thinking \
  --prompt "计算 2+2"

标志	描述
--enable-thinking	在聊天模板中启用思考模式
--thinking-budget	思考块内允许的最大标记数
--thinking-start-token	打开思考块的标记（默认：<think>）
--thinking-end-token	关闭思考块的标记（默认：</think>）

当超过预算时，模型会强制输出 \n</think> 并过渡到回答。如果传递了 --enable-thinking 但模型的聊天模板不支持该功能，则只有当模型自行生成起始标记时，预算才会生效。

Gradio 聊天界面

使用 Gradio 启动聊天界面：

mlx_vlm.chat_ui --model mlx-community/Qwen2-VL-2B-Instruct-4bit

Python 脚本

以下是一个在 Python 脚本中使用 MLX-VLM 的示例：

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

# 加载模型
model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit"
model, processor = load(model_path)
config = load_config(model_path)

# 准备输入
image = ["http://images.cocodataset.org/val2017/000000039769.jpg"]
# 也可以使用 PIL.Image.Image 对象：image = [Image.open("...")]
prompt = "请描述这张图片。"

# 应用聊天模板
formatted_prompt = apply_chat_template(
    processor, config, prompt, num_images=len(image)
)

# 生成输出
output = generate(model, processor, formatted_prompt, image, verbose=False)
print(output)

音频示例

from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

# 加载支持音频的模型
model_path = "mlx-community/gemma-3n-E2B-it-4bit"
model, processor = load(model_path)
config = model.config

# 准备音频输入
audio = ["/path/to/audio1.wav", "/path/to/audio2.mp3"]
prompt = "请描述这些音频文件中你听到的内容。"

# 应用包含音频的聊天模板
formatted_prompt = apply_chat_template(
    processor, config, prompt, num_audios=len(audio)
)

# 生成包含音频的输出
output = generate(model, processor, formatted_prompt, audio=audio, verbose=False)
print(output)

多模态示例（图像 + 音频）

from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

# 加载多模态模型
model_path = "mlx-community/gemma-3n-E2B-it-4bit"
model, processor = load(model_path)
config = model.config

# 准备输入
image = ["/path/to/image.jpg"]
audio = ["/path/to/audio.wav"]
prompt = ""

# 应用聊天模板
formatted_prompt = apply_chat_template(
    processor, config, prompt,
    num_images=len(image),
    num_audios=len(audio)
)

# 生成输出
output = generate(model, processor, formatted_prompt, image, audio=audio, verbose=False)
print(output)

服务器 (FastAPI)

启动服务器：

mlx_vlm.server --port 8080

# 在启动时预加载模型（Hugging Face 仓库或本地路径）
mlx_vlm.server --model <hf_repo_or_local_path>

# 使用适配器预加载模型
mlx_vlm.server --model <hf_repo_or_local_path> --adapter-path <adapter_path>

# 启用信任远程代码（某些模型需要）
mlx_vlm.server --trust-remote-code

服务器选项

• --model: 在服务器启动时预加载模型，接受 Hugging Face 仓库 ID 或本地路径（可选；若省略，则在首次请求时按需加载）
• --adapter-path: 用于与预加载模型一起使用的适配器权重路径
• --host: 主机地址（默认：0.0.0.0）
• --port: 端口号（默认：8080）
• --trust-remote-code: 从 Hugging Face Hub 加载模型时信任远程代码
• --kv-bits: KV 缓存量化位数（例如，3.5 表示 TurboQuant）
• --kv-quant-scheme: KV 缓存量化后端（uniform 或 turboquant）

您也可以通过环境变量设置信任远程代码：

MLX_TRUST_REMOTE_CODE=true mlx_vlm.server

该服务器提供多个端点以满足不同使用场景，并支持动态加载和卸载模型，同时具备缓存功能（一次仅能加载一个模型）。

可用端点

• /models 和 /v1/models：列出本地可用的模型
• /chat/completions 和 /v1/chat/completions：兼容 OpenAI 的聊天式交互端点，支持图像、音频和文本
• /responses 和 /v1/responses：兼容 OpenAI 的响应端点
• /health：检查服务器状态
• /unload：从内存中卸载当前模型

使用示例

列出可用模型

curl "http://localhost:8080/models"

文本输入

curl -X POST "http://localhost:8080/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/Qwen2-VL-2B-Instruct-4bit",
    "messages": [
      {
        "role": "user",
        "content": "你好，最近怎么样"
      }
    ],
    "stream": true,
    "max_tokens": 100
  }'

图像输入

curl -X POST "http://localhost:8080/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/Qwen2.5-VL-32B-Instruct-8bit",
    "messages":
    [
      {
        "role": "system",
        "content": "你是一个有用的助手。"
      },
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "这是加利福尼亚州今日的能源需求图表。你能对这张图进行分析，并谈谈它对加州可再生能源的影响吗？"
          },
          {
            "type": "input_image",
            "image_url": "/path/to/repo/examples/images/renewables_california.png"
          }
        ]
      }
    ],
    "stream": true,
    "max_tokens": 1000
  }'

音频支持（新增）

curl -X POST "http://localhost:8080/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/gemma-3n-E2B-it-4bit",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "请描述这些音频文件中听到的内容" },
          { "type": "input_audio", "input_audio": "/path/to/audio1.wav" },
          { "type": "input_audio", "input_audio": "https://example.com/audio2.mp3" }
        ]
      }
    ],
    "stream": true,
    "max_tokens": 500
  }'

多模态（图像 + 音频）

curl -X POST "http://localhost:8080/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/gemma-3n-E2B-it-4bit",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "input_image", "image_url": "/path/to/image.jpg"},
          {"type": "input_audio", "input_audio": "/path/to/audio.wav"}
        ]
      }
    ],
    "max_tokens": 100
  }'

响应端点

curl -X POST "http://localhost:8080/responses" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/Qwen2-VL-2B-Instruct-4bit",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "这张图片里有什么？"},
          {"type": "input_image", "image_url": "/path/to/image.jpg"}
        ]
      }
    ],
    "max_tokens": 100
  }'

请求参数

• model: 模型标识符（必填）
• messages: 用于聊天/OpenAI 兼容端点的对话消息
• max_tokens: 最大生成标记数
• temperature: 采样温度
• top_p: Top-p 采样参数
• top_k: Top-k 采样截断值
• min_p: Min-p 采样阈值
• repetition_penalty: 重复标记惩罚因子
• stream: 启用流式响应

激活量化（CUDA）

当在配备 MLX CUDA 的 NVIDIA GPU 上运行时，使用 mxfp8 或 nvfp4 模式量化的模型需要启用激活量化才能正常工作。这会将 QuantizedLinear 层转换为 QQLinear 层，从而对权重和激活都进行量化。

命令行

使用 -qa 或 --quantize-activations 标志：

mlx_vlm.generate --model /path/to/mxfp8-model --prompt "描述这张图片" --image /path/to/image.jpg -qa

Python API

在 load 函数中传入 quantize_activations=True：

from mlx_vlm import load, generate

# 启用激活量化后加载模型
model, processor = load(
    "path/to/mxfp8-quantized-model",
    quantize_activations=True
)

# 正常生成
output = generate(model, processor, "描述这张图片", image=["image.jpg"])

支持的量化模式

• mxfp8：8 位 MX 浮点数
• nvfp4：4 位 NVIDIA 浮点数

注意：此功能是 CUDA 上 mxfp/nvfp 量化模型所必需的。而在 Apple Silicon（Metal）上，这些模型无需该标志即可正常工作。

多图像聊天支持

MLX-VLM 支持使用部分模型同时分析多张图像。此功能能够实现更复杂的视觉推理任务，并在单次对话中对多张图像进行全面分析。

使用示例

Python 脚本

from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

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

images = ["path/to/image1.jpg", "path/to/image2.jpg"]
prompt = "比较这两张图片。"

formatted_prompt = apply_chat_template(
    processor, config, prompt, num_images=len(images)
)

output = generate(model, processor, formatted_prompt, images, verbose=False)
print(output)

命令行

mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "比较这些图片" --image path/to/image1.jpg path/to/image2.jpg

视频理解

MLX-VLM 还支持视频分析，例如字幕生成、摘要提取等，适用于部分模型。

支持的模型

以下模型支持视频聊天：

1. Qwen2-VL
2. Qwen2.5-VL
3. Idefics3
4. LLaVA

更多模型即将推出。

使用示例

命令行

mlx_vlm.video_generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "描述这段视频" --video path/to/video.mp4 --max-pixels 224 224 --fps 1.0

这些示例展示了如何使用 MLX-VLM 处理多张图片，以完成更复杂的视觉推理任务。

视觉特征缓存

在关于同一张图片的多轮对话中，即使图片没有变化，视觉编码器也会在每一轮都运行。VisionFeatureCache 会将投影后的视觉特征存储在一个基于图片路径的 LRU 缓存中，这样昂贵的视觉编码器就只需对每张唯一图片调用一次。

工作原理

1. 第一轮（缓存未命中） —— encode_image() 会运行完整的视觉处理流程（视觉塔 + 投影器），并将结果存储在缓存中，然后传递给语言模型。
2. 后续轮次（缓存命中） —— 直接通过 cached_image_features 传递缓存中的特征，完全跳过视觉编码器。
3. 图片切换 —— 当图片发生变化时，会生成一个新的缓存键，因此需要重新计算并缓存特征。如果再次切换回之前的图片，则会命中缓存。

缓存最多可容纳 8 个条目（可配置），并采用 LRU 策略进行淘汰。

命令行界面

所有聊天界面都会自动使用 VisionFeatureCache：

# Gradio 聊天界面
python -m mlx_vlm.chat_ui --model google/gemma-4-26b-a4b-it

# 带有 Rich UI 的交互式聊天（使用 /image 命令加载图片）
python -m mlx_vlm.chat --model google/gemma-4-26b-a4b-it

# 内联聊天模式
python -m mlx_vlm.generate \
  --model google/gemma-4-26b-a4b-it \
  --image path/to/image.jpg \
  --chat \
  --max-tokens 200

Python 示例

from mlx_vlm import load, stream_generate, VisionFeatureCache
from mlx_vlm.prompt_utils import apply_chat_template

model, processor = load("google/gemma-4-26b-a4b-it")
cache = VisionFeatureCache()

image = "path/to/image.jpg"

# 第一轮 —— 缓存未命中，编码图片
prompt1 = apply_chat_template(processor, model.config, "请描述这张图片。", num_images=1)
for chunk in stream_generate(model, processor, prompt1, image=[image],
                              max_tokens=200, vision_cache=cache):
    print(chunk.text, end="")

# 第二轮 —— 缓存命中，跳过视觉编码器
prompt2 = apply_chat_template(processor, model.config, "你看到了哪些颜色？", num_images=1)
for chunk in stream_generate(model, processor, prompt2, image=[image],
                              max_tokens=200, vision_cache=cache):
    print(chunk.text, end="")

服务器端

服务器会自动为同一张图片的多个请求缓存视觉特征。无需任何配置——缓存会在模型加载时创建，并在卸载时清空。

mlx_vlm.server --model google/gemma-4-26b-a4b-it

通过 /v1/chat/completions（流式和非流式）以及 /responses 接口进行的多轮对话都将受益于这一功能。同一张图片在多个请求中只会被编码一次。

性能

在 google/gemma-4-26b-a4b-it 模型上进行了 10 轮多轮对话测试：

指标	无缓存	有缓存
提示词 TPS	~48	~550-825
加速倍数	--	11 倍以上
峰值内存	52.66 GB	52.66 GB（持平）

生成速度（约 31 tok/s）和内存占用不受影响——只有提示词的处理速度得到了提升。

TurboQuant KV 缓存

TurboQuant 在生成过程中压缩 KV 缓存，从而在保持质量的同时，以更少的内存实现更长的上下文长度。

快速入门

# 3.5 位 KV 缓存量化（3 位键 + 4 位值）
mlx_vlm generate \
  --model mlx-community/Qwen3.5-4B-4bit \
  --kv-bits 3.5 \
  --kv-quant-scheme turboquant \
  --prompt "您的长提示在这里..."

from mlx_vlm import generate

result = generate(
    model, processor, prompt,
    kv_bits=3.5,
    kv_quant_scheme="turboquant",
    max_tokens=256,
)

# 启用 TurboQuant 的服务器
mlx_vlm server \
  --model google/gemma-4-26b-a4b-it \
  --kv-bits 3.5 \
  --kv-quant-scheme turboquant

工作原理

TurboQuant 使用随机旋转 + 码本量化（arXiv:2504.19874）将 KV 缓存条目从 16 位压缩到每维 2–4 位：

• 键与值：采用 Hadamard 旋转的 MSE 码本量化
• 分数位（如 3.5 位）：使用较低的位数表示键，较高的位数表示值（3 位键 + 4 位值）

自定义 Metal 内核可以直接在打包的量化数据上融合打分计算和值聚合，避免在解码过程中进行完全的反量化。

性能

在 Qwen3.5-4B-4bit 模型上，使用 128k 上下文长度进行测试：

指标	基线	TurboQuant 3.5 位
KV 内存	4.1 GB	0.97 GB（减少 76%）
峰值内存	18.3 GB	17.3 GB（减少 1.0 GB）

在 512k+ 上下文长度下，由于减少了内存带宽需求，TurboQuant 的逐层注意力计算速度比 FP16 SDPA 更快。

在 gemma-4-31b-it 模型上，使用 128k 上下文长度进行测试：

指标	基线	TurboQuant 3.5 位
KV 内存	13.3 GB	4.9 GB（减少 63%）
峰值内存	75.2 GB	65.8 GB（减少 9.4 GB）

支持的位宽

位数	压缩比	最佳用途
2	~8x	最大压缩，质量略有损失
3	~5x	质量与压缩之间的良好平衡
3.5	~4.5x	推荐默认设置（3 位键 + 4 位值）
4	~4x	质量最佳，压缩适度

兼容性

TurboQuant 会自动量化 KVCache 层（全局注意力）。对于具有 RotatingKVCache（滑动窗口）或 ArraysCache（MLA/吸收键）的模型，它们的原生缓存格式将保持不变，因为这些层本身已经非常高效地利用了内存。

微调

MLX-VLM 支持使用 LoRA 和 QLoRA 对模型进行微调。

LoRA 和 QLoRA

要了解更多关于 LoRA 的信息，请参阅 LoRA.md 文件。

MLX-VLM 快速上手指南

MLX-VLM 是一个专为 Mac 设计的开源工具包，支持在本地运行和微调视觉语言模型（VLM）及多模态模型（支持音频和视频）。它基于 Apple MLX 框架，能够高效利用 Mac 的 GPU 进行推理。

环境准备

系统要求

• 操作系统: macOS (推荐 macOS 14.0 及以上)
• 硬件: Apple Silicon 芯片 (M1, M2, M3 系列等)
• Python 版本: Python 3.9 - 3.12

前置依赖

确保已安装 pip 和基础开发工具。如果是首次使用 MLX 相关工具，建议先更新 pip：

python3 -m pip install --upgrade pip

注意：本工具主要针对 Apple Silicon Mac 优化。虽然部分功能支持 NVIDIA GPU (CUDA)，但核心体验建议在 Mac 上进行。

安装步骤

通过 pip 直接安装最新版本的 mlx-vlm：

pip install -U mlx-vlm

如果需要从国内镜像源加速安装（推荐中国开发者使用）：

pip install -U mlx-vlm -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

安装完成后，你可以通过命令行、Python 脚本或启动本地服务器来使用模型。

1. 命令行界面 (CLI)

这是最简单的使用方式，支持文本、图像、音频及多模态输入。

纯文本生成：

mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit --max-tokens 100 --prompt "Hello, how are you?"

图像理解（传入图片 URL 或本地路径）：

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

音频分析（需支持音频的模型）：

mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit --max-tokens 100 --prompt "Describe what you hear" --audio /path/to/audio.wav

多模态输入（图像 + 音频）：

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

2. 启动聊天界面 (Gradio)

快速启动一个网页版的聊天交互界面：

mlx_vlm.chat_ui --model mlx-community/Qwen2-VL-2B-Instruct-4bit

启动后，终端会显示本地访问地址（通常是 http://127.0.0.1:7860），在浏览器打开即可对话。

3. Python 脚本调用

在你的项目中集成 MLX-VLM：

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

# 加载模型
model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit"
model, processor = load(model_path)
config = load_config(model_path)

# 准备输入 (支持本地路径或 URL)
image = ["http://images.cocodataset.org/val2017/000000039769.jpg"]
prompt = "Describe this image."

# 应用聊天模板
formatted_prompt = apply_chat_template(
    processor, config, prompt, num_images=len(image)
)

# 生成输出
output = generate(model, processor, formatted_prompt, image, verbose=False)
print(output)

4. 启动 API 服务器 (FastAPI)

将模型部署为兼容 OpenAI 格式的 API 服务：

# 启动默认服务
mlx_vlm.server --port 8080

# 预加载特定模型
mlx_vlm.server --model mlx-community/Qwen2-VL-2B-Instruct-4bit --port 8080

调用示例 (curl)：

curl -X POST "http://localhost:8080/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mlx-community/Qwen2-VL-2B-Instruct-4bit",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you"
      }
    ],
    "stream": true,
    "max_tokens": 100
  }'

提示：更多高级功能（如思维链预算控制 thinking-budget、量化配置等）请参考官方完整文档。