Zakaria
240 lines
8.9 KiB
Markdown
240 lines
8.9 KiB
Markdown
---
|
||
sidebar_position: 2
|
||
title: "在 Mac 上运行本地 LLM"
|
||
description: "使用 llama.cpp 或 MLX 在 macOS 上搭建兼容 OpenAI 的本地 LLM 服务器，涵盖模型选择、内存优化以及 Apple Silicon 上的实测基准数据"
|
||
---
|
||
|
||
# 在 Mac 上运行本地 LLM
|
||
|
||
本指南介绍如何在 macOS 上运行一个兼容 OpenAI API 的本地 LLM 服务器。你将获得完整的隐私保护、零 API 费用，以及 Apple Silicon 上出乎意料的出色性能。
|
||
|
||
我们涵盖两个后端：
|
||
|
||
| 后端 | 安装方式 | 优势 | 格式 |
|
||
|---------|---------|---------|--------|
|
||
| **llama.cpp** | `brew install llama.cpp` | 首 token 延迟最低，量化 KV 缓存节省内存 | GGUF |
|
||
| **omlx** | [omlx.ai](https://omlx.ai) | token 生成速度最快，原生 Metal 优化 | MLX (safetensors) |
|
||
|
||
两者均暴露兼容 OpenAI 的 `/v1/chat/completions` 端点。Hermes 支持任意一个——只需将其指向 `http://localhost:8080` 或 `http://localhost:8000`。
|
||
|
||
:::info 仅限 Apple Silicon
|
||
本指南面向搭载 Apple Silicon（M1 及更新）的 Mac。Intel Mac 可使用 llama.cpp，但无 GPU 加速——性能会明显更慢。
|
||
:::
|
||
|
||
---
|
||
|
||
## 选择模型
|
||
|
||
入门推荐 **Qwen3.5-9B**——这是一个强推理模型，量化后可在 8GB+ 统一内存上轻松运行。
|
||
|
||
| 变体 | 磁盘占用 | 所需内存（128K 上下文） | 后端 |
|
||
|---------|-------------|---------------------------|---------|
|
||
| Qwen3.5-9B-Q4_K_M (GGUF) | 5.3 GB | ~10 GB（含量化 KV 缓存） | llama.cpp |
|
||
| Qwen3.5-9B-mlx-lm-mxfp4 (MLX) | ~5 GB | ~12 GB | omlx |
|
||
|
||
**内存估算规则：** 模型大小 + KV 缓存。9B Q4 模型约 5 GB。128K 上下文下 Q4 量化的 KV 缓存额外占用约 4–5 GB。若使用默认（f16）KV 缓存，则会膨胀至约 16 GB。llama.cpp 中的量化 KV 缓存参数是内存受限系统的关键技巧。
|
||
|
||
对于更大的模型（27B、35B），你需要 32 GB+ 的统一内存。9B 是 8–16 GB 机器的最佳选择。
|
||
|
||
---
|
||
|
||
## 方案 A：llama.cpp
|
||
|
||
llama.cpp 是移植性最强的本地 LLM 运行时。在 macOS 上，它开箱即用地通过 Metal 进行 GPU 加速。
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
brew install llama.cpp
|
||
```
|
||
|
||
安装后即可全局使用 `llama-server` 命令。
|
||
|
||
### 下载模型
|
||
|
||
你需要 GGUF 格式的模型。最简便的来源是通过 `huggingface-cli` 从 Hugging Face 下载：
|
||
|
||
```bash
|
||
brew install huggingface-cli
|
||
```
|
||
|
||
然后下载：
|
||
|
||
```bash
|
||
huggingface-cli download unsloth/Qwen3.5-9B-GGUF Qwen3.5-9B-Q4_K_M.gguf --local-dir ~/models
|
||
```
|
||
|
||
:::tip 受限模型
|
||
Hugging Face 上的部分模型需要身份验证。如果遇到 401 或 404 错误，请先运行 `huggingface-cli login`。
|
||
:::
|
||
|
||
### 启动服务器
|
||
|
||
```bash
|
||
llama-server -m ~/models/Qwen3.5-9B-Q4_K_M.gguf \
|
||
-ngl 99 \
|
||
-c 131072 \
|
||
-np 1 \
|
||
-fa on \
|
||
--cache-type-k q4_0 \
|
||
--cache-type-v q4_0 \
|
||
--host 0.0.0.0
|
||
```
|
||
|
||
各参数说明：
|
||
|
||
| 参数 | 用途 |
|
||
|------|---------|
|
||
| `-ngl 99` | 将所有层卸载到 GPU（Metal）。设置较大的数值以确保没有层留在 CPU 上。 |
|
||
| `-c 131072` | 上下文窗口大小（128K token）。内存不足时可减小此值。 |
|
||
| `-np 1` | 并行槽数量。单用户使用时保持为 1——更多槽会分摊内存预算。 |
|
||
| `-fa on` | Flash attention。减少内存占用并加速长上下文推理。 |
|
||
| `--cache-type-k q4_0` | 将 key 缓存量化为 4-bit。**这是最大的内存节省手段。** |
|
||
| `--cache-type-v q4_0` | 将 value 缓存量化为 4-bit。与上一项合用，相比 f16 可将 KV 缓存内存减少约 75%。 |
|
||
| `--host 0.0.0.0` | 监听所有网络接口。若不需要网络访问，可改为 `127.0.0.1`。 |
|
||
|
||
当你看到以下输出时，服务器已就绪：
|
||
|
||
```
|
||
main: server is listening on http://0.0.0.0:8080
|
||
srv update_slots: all slots are idle
|
||
```
|
||
|
||
### 内存受限系统的优化
|
||
|
||
`--cache-type-k q4_0 --cache-type-v q4_0` 参数是内存有限系统最重要的优化手段。以下是 128K 上下文下的影响对比：
|
||
|
||
| KV 缓存类型 | KV 缓存内存（128K 上下文，9B 模型） |
|
||
|---------------|--------------------------------------|
|
||
| f16（默认） | ~16 GB |
|
||
| q8_0 | ~8 GB |
|
||
| **q4_0** | **~4 GB** |
|
||
|
||
在 8 GB Mac 上，使用 `q4_0` KV 缓存并将上下文缩减为 `-c 32768`（32K）。在 16 GB 上，可以轻松使用 128K 上下文。在 32 GB+ 上，可以运行更大的模型或多个并行槽。
|
||
|
||
如果仍然内存不足，优先减小上下文大小（`-c`），然后尝试更小的量化级别（Q3_K_M 代替 Q4_K_M）。
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/v1/chat/completions \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "Qwen3.5-9B-Q4_K_M.gguf",
|
||
"messages": [{"role": "user", "content": "Hello!"}],
|
||
"max_tokens": 50
|
||
}' | jq .choices[0].message.content
|
||
```
|
||
|
||
### 获取模型名称
|
||
|
||
如果忘记了模型名称，可查询 models 端点：
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/v1/models | jq '.data[].id'
|
||
```
|
||
|
||
---
|
||
|
||
## 方案 B：通过 omlx 使用 MLX
|
||
|
||
[omlx](https://omlx.ai) 是一款 macOS 原生应用，用于管理和提供 MLX 模型服务。MLX 是 Apple 自研的机器学习框架，专为 Apple Silicon 统一内存架构优化。
|
||
|
||
### 安装
|
||
|
||
从 [omlx.ai](https://omlx.ai) 下载并安装。它提供图形界面用于模型管理，并内置服务器。
|
||
|
||
### 下载模型
|
||
|
||
使用 omlx 应用浏览并下载模型。搜索 `Qwen3.5-9B-mlx-lm-mxfp4` 并下载。模型存储在本地（通常位于 `~/.omlx/models/`）。
|
||
|
||
### 启动服务器
|
||
|
||
omlx 默认在 `http://127.0.0.1:8000` 上提供服务。通过应用 UI 启动服务，或在可用时使用 CLI。
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8000/v1/chat/completions \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "Qwen3.5-9B-mlx-lm-mxfp4",
|
||
"messages": [{"role": "user", "content": "Hello!"}],
|
||
"max_tokens": 50
|
||
}' | jq .choices[0].message.content
|
||
```
|
||
|
||
### 列出可用模型
|
||
|
||
omlx 可同时提供多个模型的服务：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8000/v1/models | jq '.data[].id'
|
||
```
|
||
|
||
---
|
||
|
||
## 基准测试：llama.cpp vs MLX
|
||
|
||
两个后端在同一台机器（Apple M5 Max，128 GB 统一内存）上测试，使用相同模型（Qwen3.5-9B），量化级别相当（GGUF 使用 Q4_K_M，MLX 使用 mxfp4）。五个不同 prompt，每个运行三次，后端顺序测试以避免资源竞争。
|
||
|
||
### 结果
|
||
|
||
| 指标 | llama.cpp (Q4_K_M) | MLX (mxfp4) | 胜者 |
|
||
|--------|-------------------|-------------|--------|
|
||
| **TTFT（首 token 延迟，均值）** | **67 ms** | 289 ms | llama.cpp（快 4.3 倍） |
|
||
| **TTFT（p50）** | **66 ms** | 286 ms | llama.cpp（快 4.3 倍） |
|
||
| **生成速度（均值）** | 70 tok/s | **96 tok/s** | MLX（快 37%） |
|
||
| **生成速度（p50）** | 70 tok/s | **96 tok/s** | MLX（快 37%） |
|
||
| **总耗时（512 token）** | 7.3s | **5.5s** | MLX（快 25%） |
|
||
|
||
### 含义解读
|
||
|
||
- **llama.cpp** 在 prompt 处理上表现突出——其 flash attention + 量化 KV 缓存流水线可在约 66ms 内返回第一个 token。如果你在构建对响应速度敏感的交互式应用（聊天机器人、自动补全），这是显著优势。
|
||
|
||
- **MLX** 一旦开始生成，token 速度快约 37%。对于批量任务、长文本生成，或任何更关注总完成时间而非初始延迟的场景，MLX 完成得更快。
|
||
|
||
- 两个后端都**极为稳定**——多次运行间的方差可忽略不计。这些数据可作为可靠参考。
|
||
|
||
### 如何选择？
|
||
|
||
| 使用场景 | 推荐 |
|
||
|----------|---------------|
|
||
| 交互式聊天、低延迟工具 | llama.cpp |
|
||
| 长文本生成、批量处理 | MLX (omlx) |
|
||
| 内存受限（8–16 GB） | llama.cpp（量化 KV 缓存无可匹敌） |
|
||
| 同时提供多个模型服务 | omlx（内置多模型支持） |
|
||
| 最大兼容性（含 Linux） | llama.cpp |
|
||
|
||
---
|
||
|
||
## 连接 Hermes
|
||
|
||
本地服务器启动后：
|
||
|
||
```bash
|
||
hermes model
|
||
```
|
||
|
||
选择 **Custom endpoint**，按提示操作。系统会询问 base URL 和模型名称——使用你所配置的后端对应的值即可。
|
||
|
||
---
|
||
|
||
## 超时设置
|
||
|
||
Hermes 会自动检测本地端点（localhost、局域网 IP）并放宽其流式传输超时限制。大多数情况下无需额外配置。
|
||
|
||
如果仍然遇到超时错误（例如在慢速硬件上使用超大上下文），可以覆盖流式读取超时：
|
||
|
||
```bash
|
||
# 在 .env 中——将默认的 120s 提高到 30 分钟
|
||
HERMES_STREAM_READ_TIMEOUT=1800
|
||
```
|
||
|
||
| 超时类型 | 默认值 | 本地自动调整 | 环境变量覆盖 |
|
||
|---------|---------|----------------------|------------------|
|
||
| 流式读取（socket 级别） | 120s | 提升至 1800s | `HERMES_STREAM_READ_TIMEOUT` |
|
||
| 停滞流检测 | 180s | 完全禁用 | `HERMES_STREAM_STALE_TIMEOUT` |
|
||
| API 调用（非流式） | 1800s | 无需调整 | `HERMES_API_TIMEOUT` |
|
||
|
||
流式读取超时最容易引发问题——它是接收下一个数据块的 socket 级别截止时间。在大上下文的预填充（prefill）阶段，本地模型可能在处理 prompt 时数分钟内没有任何输出。自动检测机制会透明地处理这一情况。 |