waybarrios/vllm-mlx · 上手攻略

• 仓库：waybarrios/vllm-mlx
• 链接：https://github.com/waybarrios/vllm-mlx
• 分类：llm-infra / multimodal
• 作者：Tom
• 更新：2026-07-31

是什么

vllm-mlx 是一个专为 Apple Silicon（M 系列芯片）打造的推理服务器，核心思路是：把 vLLM 在 CUDA 硬件上的核心优化（连续批处理、页级 KV 缓存、前缀缓存）移植到苹果的 MLX 框架上，通过 Metal 驱动统一内存直接跑模型，无需任何格式转换。

它同时暴露 OpenAI /v1/* 和 Anthropic /v1/messages 两套 API，应用只需改一个 base URL 就能在苹果本地跑起 GPT-4o 级推理能力。截至 2026 年 7 月最新版本为 v0.4.0（2026 年 6 月 28 日发布）。

解决什么问题

在 vllm-mlx 出现之前，Apple Silicon 本地跑 LLM 主要靠 Ollama 或直接用 mlx-lm 库，两者的共同问题是：缺乏连续批处理（continuous batching）能力——高并发请求时只能串行处理，吞吐远低于 CUDA 生态的 vLLM。

vllm-mlx 补上了这块短板：在 M4 Max 上，Qwen3-0.6B-8bit 可达 417.9 tok/s，Llama-3.2-3B-4bit 可达 205.6 tok/s，30B MoE 模型（Qwen3-30B-A3B-4bit）也能跑到 127.7 tok/s，单 Stream 性能与 mlx-lm 持平的基础上，并发场景下吞吐优势明显。

快速安装

环境要求

• macOS 13+（Apple Silicon M1/M2/M3/M4/M5）
• Python 3.10+
• 推荐使用 uv 包管理器（性能最优）

安装步骤

# 方式一：uv（推荐）
uv tool install vllm-mlx

# 方式二：pip
pip install vllm-mlx

# 音频功能（可选）
pip install vllm-mlx[audio]
brew install espeak-ng  # macOS 上非英语 TTS 需要

# 从源码安装
git clone https://github.com/waybarrios/vllm-mlx.git
cd vllm-mlx
pip install -e .

⚠️ 注意：仅支持 Apple Silicon，Intel Mac 不支持。需提前安装好 MLX（安装 vllm-mlx 时会自动依赖）。

核心用法

启动推理服务

# 最简启动（默认端口 8000）
vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit

# 带连续批处理和生产级配置
vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit \
  --port 8000 \
  --continuous-batching \
  --ssd-cache-dir ./cache \
  --warm-prompts ./warm_prompts.txt

OpenAI SDK 调用

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

r = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Hi, explain what MLX is in 2 sentences."}]
)
print(r.choices[0].message.content)

Anthropic SDK / Claude Code

export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_API_KEY=not-needed
claude
# 然后直接用 Claude Code 对话，流量走本地 vllm-mlx

视觉模型（多模态）

r = client.chat.completions.create(
    model="default",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What is in this image?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
        ]
    }]
)

支持的视觉模型包括：Gemma 3/4、Qwen3-VL、Pixtral、LLaMA Vision 等。

结构化输出（JSON Schema）

r = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "List 3 colors."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "schema": {
                "type": "object",
                "properties": {"colors": {"type": "array", "items": {"type": "string"}}}
            }
        }
    }
)

思维链推理（Reasoning Extraction）

# Qwen3 / DeepSeek-R1 等推理模型可用 --reasoning-parser
# 启动时加参数：
# vllm-mlx serve mlx-community/Qwen3-8B-4bit --reasoning-parser qwen3

r = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "What is 17 * 23?"}]
)
print("Thinking:", r.choices[0].message.reasoning)
print("Answer:", r.choices[0].message.content)

Rerank

curl http://localhost:8000/v1/rerank \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "default",
    "query": "apple silicon inference",
    "documents": [
      "MLX is Apples framework",
      "Metal kernels on M-series",
      "CUDA on NVIDIA"
    ]
  }'

嵌入模型

vllm-mlx serve <llm-model> --embedding-model mlx-community/all-MiniLM-L6-v2-4bit

emb = client.embeddings.create(
    model="mlx-community/all-MiniLM-L6-v2-4bit",
    input=["Hello", "World"]
)

内置压测工具

vllm-mlx bench-serve \
  --url http://localhost:8000 \
  --concurrency 5 \
  --prompts prompts.txt \
  --output results.csv

模型管理

# 查看模型元数据、文件大小、是否适合本地运行
vllm-mlx model inspect mlx-community/Llama-3.2-3B-Instruct-4bit

# 下载模型（含断点续传）
vllm-mlx model acquire mlx-community/Llama-3.2-3B-Instruct-4bit \
  --target-dir ./models/llama-3b-4bit

# 本地量化转换
vllm-mlx model convert meta-llama/Llama-3.2-3B-Instruct \
  --output ./models/llama-3b-mlx-q4 \
  --quantize --q-bits 4 --q-group-size 64 --q-mode affine

监控指标

vllm-mlx serve <model> --metrics
curl http://localhost:8000/metrics
# Prometheus 格式，暴露吞吐、延迟等关键指标

典型适用场景

坑与注意

1. Apple Silicon only：不支持 Intel Mac，不支持树莓派（需 Metal）。
2. 统一内存是瓶颈：模型越大越吃内存，M2/M3 8GB 用户能跑的模型很有限，M4 Max 128GB 才能跑 30B MoE。
3. 连续批处理不等于极速单请求：单 Stream 性能与 mlx-lm 持平；连续批处理的优势在高并发时才显现。
4. v0.4.0 版本前有 breaking change：旧版本启动参数格式不同，升级后需重调命令行。
5. SSD 缓存需手动配置：--ssd-cache-dir 默认关闭，开启后对长上下文 Agent 场景 TTFT 改善明显（1.3-2.25x），但需要 macOS 13+ 且 SSD 剩余空间充足。
6. TTS 依赖 espeak-ng：非英语 TTS 需提前安装 espeak-ng，否则报错。
7. 模型来源限制：目前只能跑 Hugging Face 上有 MLX 格式的模型，原生 PyTorch 模型需转换。

与同类对比

结论：如果你的场景是高并发 API 服务或需要Claude Code 本地化，vllm-mlx 是目前 Apple Silicon 上唯一同时具备连续批处理和双协议兼容的方案。如果只是单 Stream 跑一个小模型，mlx-lm 更轻量；如果需要全平台兼容，Ollama 更合适。

一句话推荐结论

Apple Silicon 本地跑高并发 LLM API 的最优选——把 vLLM 的生产级优化带进了 MLX 生态，让 M 系列 Mac 真正成为可部署的推理节点。