MLX-LM 在本地运行大模型

MLX-LM 在本地运行大模型

[TOC]

MLX-LM 运行大模型

基础知识

什么是MLX-XL

mlx-lm 是一个强大且易用的工具包，它将 Apple Silicon 硬件的潜力充分释放出来，让你能在个人电脑上完成从模型实验、量化压缩、高效推理到本地微调的全流程工作。无论是 AI 爱好者、研究者还是开发者，都能通过它更方便地探索和使用最前沿的大型语言模型。

分组大小在量化中做什么？

在进行 4-bit 或 8-bit 量化时，为了减小误差，通常不会把整个权重矩阵作为一个整体粗暴地压缩，而是将权重划分为若干小组，对每个小组分别计算自己的缩放因子和零点偏移，然后再进行压缩。这样每个小组内的权重都能在有限的比特数内更准确地还原出原始数值。

  • 分组大小 = 64：意味着每 64 个权重值组成一个小组，共享一组量化参数。
  • 分组大小 = 32：每 32 个权重组成一组，更细的粒度。
  • 分组大小 = 128：每 128 个权重组成一组，更粗的粒度。

分组大小对模型的影响

影响主要体现在三个方面：量化误差（模型质量）、模型体积、计算速度。

分组大小 对模型质量的影响 对模型体积的影响 对推理速度的影响
调小（如 32） 质量更高。因为每个小组能更精确地拟合原始权重的分布，量化误差更小，模型输出更接近原始模型。 体积略微增大。因为需要保存更多的缩放因子和零点（每个小组一套），所以整体模型文件会稍稍变大（通常可以忽略不计）。 推理速度可能略慢。计算时需要频繁切换缩放因子，增加了内存访问开销。但在实践中，这种差异通常微乎其微，很多情况下感觉不到。
默认（64） 平衡点。官方推荐的默认值，在大多数模型上都能在质量和效率之间取得良好平衡。 标准大小。 正常速度。
调大（如 128） 质量可能下降。如果权重分布不均匀，较大的分组可能无法很好拟合局部特征，导致量化误差累积，模型回答可能出现更明显的退化（如逻辑错误、流畅度下降）。 体积略微缩小。因为保存的缩放因子更少，模型文件会再小一点点（通常只有几MB的差异）。 推理速度可能稍快。减少了缩放因子的读取次数，对内存访问更友好，但实际提升有限。

安装

pipx install mlx-lm -i https://pypi.tuna.tsinghua.edu.cn/simple --verbose
pipx inject mlx-lm socksio -i https://pypi.tuna.tsinghua.edu.cn/simple --verbose --force

模型转换

使用国内镜像源加速下载

解决下载慢最直接有效的方法。通过更换下载源到国内镜像，下载速度可以从“KB/s”级别提升到“MB/s”级别。

你只需要在运行转换命令前，设置一个环境变量即可：

# 设置环境变量，将Hugging Face的默认源替换为国内镜像站
export HF_ENDPOINT=https://hf-mirror.com

实现断点续传

针对下载容易中断的问题，我们可以利用Hugging Face Hub下载工具本身的功能来解决。

你可以在运行命令前，启用断点续传模式。具体的操作方式如下：

# 启用HF Hub的断点续传功能
export HF_HUB_ENABLE_HF_TRANSFER=1

或者，你也可以在Python代码中这样设置：

import os
os.environ['HF_HUB_ENABLE_HF_TRANSFER'] = '1'

通过这个设置，下载过程就具备了断点续传能力，即使网络中断，恢复后也能从中断处继续，无需从头再来。

# 模型转换
mlx_lm.convert --hf-path MiniMaxAI/MiniMax-M2.5 -q --q-bits 6 --q-group-size 32 --mlx-path ./MiniMax-M2.5-6bit

在 mlx-lm 的语境下，“模型量化与转换” 通常是指将 Hugging Face 上的 PyTorch 或 TensorFlow 格式的模型，转换为能在 Apple Silicon 上高效运行的 MLX 格式，并在转换过程中对模型权重进行量化（例如从 32 位浮点数压缩到 4 位整数），从而大幅减小模型体积、降低内存占用并提升推理速度。

简单来说，这个工具的作用是 “从 HF 到 MLX”，而不是 “从 GGUF 到 MLX”。

GGUF 格式呢？

GGUF 是另一个非常流行的模型格式，主要用于 llama.cpp 项目，它同样支持量化，并且在 CPU 上运行得很好。

  • mlx-lm 本身并不直接支持将 GGUF 转换为 MLX 格式。 它的转换工具 mlx_lm.convert 的输入源主要是 Hugging Face 模型仓库（--hf-path）或本地保存的原始模型权重（通常是 config.json 和 *.safetensors 文件）。
  • 如果你想在 MLX 上运行一个只有 GGUF 格式的模型，通常需要先找到它的 Hugging Face 源模型（很多 GGUF 模型都是从 HF 模型量化来的），然后用 mlx_lm.convert 重新量化为 MLX 格式。
  • 当然，社区里可能有一些爱好者写的脚本可以实现 GGUF 到 MLX 的转换，但这并非官方支持的功能，使用起来可能会有兼容性问题。

量化与转换的具体过程

mlx_lm.convert 命令背后大致做了这几件事：

  1. 下载或读取原始模型：从 Hugging Face 或本地路径获取模型的配置和权重文件。
  2. 加载模型：在内存中重建原始模型的计算图（通常是用 PyTorch）。
  3. 量化权重：按照你指定的位数（如 4-bit、6-bit 或 8-bit）将模型的权重从高精度浮点数（如 float32）转换为低精度整数（如 int4 或 int8），并计算缩放因子等参数。这一步是关键，能有效压缩模型。
  4. 转换为 MLX 格式：将量化后的权重以 MLX 框架可以高效加载和计算的格式重新保存下来，通常也是一系列 .safetensors 文件和一个 config.json 配置文件。
  5. 可选的上传：如果你指定了，它还可以将转换好的模型推送到 Hugging Face 仓库。

如果不转换，下载直接支持MLX的模型，也可以使用下面命令

hf download spicyneuron/Kimi-K2.5-MLX-mixed-2.8-bit \
  --local-dir ./Kimi-K2.5-MLX-mixed-2.8-bit

如何清理下载过的模型?

缓存目录位置

~/.cache/huggingface/hub

在这个目录下，你下载的每个模型都会以 models--组织名--模型名 的格式保存在一个单独的文件夹中

  1. 清理特定模型：
    如果你想删除某个已转换或下载的特定模型，可以直接删除对应的缓存文件夹。例如，要删除 Qwen/Qwen2.5-7B-Instruct 的缓存，可以执行：

    bash

    # 先查看该目录下的内容，确认模型对应的文件夹名
ls ~/.cache/huggingface/hub | grep "models--"

# 然后删除特定模型的缓存，例如：
rm -rf ~/.cache/huggingface/hub/models--Qwen--Qwen2.5-7B-Instruct
  2. 完全清空缓存：
    如果你想释放所有磁盘空间，可以删除整个 hub 目录：

    bash

    rm -rf ~/.cache/huggingface/hub

    请注意：执行此操作后，所有之前下载过的模型都需要重新下载。

清理前，建议先用 du -sh ~/.cache/huggingface/hub 命令查看一下缓存目录当前占用的总磁盘空间，做到心中有数。

清理完缓存后，如果需要重新下载，可以参考我之前提到的设置镜像源的方法来加速。

启动命令

运行 GLM‑4.7-Flash-MLX-8bit 模型

mlx_lm.server \
  --model ./GLM-4.7-Flash-MLX-8bit \
  --port 9000 \
  --host 0.0.0.0 \
  --temp 0.7 \
  --top-p 0.9 \
  --max-tokens 202752 \
  --decode-concurrency 2 \
  --prompt-concurrency 2 \
  --use-default-chat-template

如果与OpenClaw配合使用，指定模型的目录一定是要用./模型名称，否则会出现404找不到模型名称。

查看模型支持的最大上下文：打开config.json文件，查找关键字段：”max_position_embeddings” 或 “max_sequence_length”。

特点：

  • decode-concurrency 2 + prompt-concurrency 2 可以充分利用 M3 多核心
  • temp 0.7 + top-p 0.9 给自然文本生成比较合理的随机性
  • max-tokens 1024 支持中等长度生成
  • 内部 MLX 自动处理 Metal / KV cache / batch，不需要手动设置线程或 GPU 层

测试模型

curl localhost:9000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
     "messages": [{"role": "user", "content": "你好，请介绍一下你自己。"}],
     "temperature": 0.7
   }'
Comments are closed.