AB
AiBoss
Tutorials

MLX

Tutorials

用 MLX-LM 在 Apple 芯片上加载、生成并转换大模型

面向 Apple 芯片机器的 MLX-LM 实操教程:安装环境、从 Hub 直接加载模型生成文本、用 Python 调用、下载非内置架构的权重、把模型转换并量化成 MLX 格式,以及转换后推送到 Hub 的完整流程。

MLX 是 Apple Machine Learning Research 推出的面向 Apple 芯片的模型训练与推理框架。它本身是一个独立包,而 MLX-LM 是建立在它之上、专门处理大语言模型的子包,并且与 Hugging Face Hub 打通:模型可以直接按仓库名下载、加载、生成文本,也可以把 Hub 上的权重转换、量化成 MLX 格式再推回去。如果你手上是一台 Apple 芯片的 Mac,想跑本地大模型、又不想折腾一整套 CUDA 生态,这套组合是值得先摸清楚的入口。站内也有对应的工具页可以一并参考:MLX。

这篇教程按实际操作顺序展开:先装环境,再用一行命令跑通文本生成,然后换成 Python 代码调用,接着处理 MLX-LM 不内置支持的模型架构,最后走完「转换 → 量化 → 上传」的完整链路。文中出现的模型名、命令与参数都来自可复现的公开用法;至于包版本、模型可用性、存储与配额等易变信息,请以官网当前信息为准。

准备工作

硬件与系统前提

MLX 面向 Apple 芯片设计,因此运行环境是搭载 Apple silicon 的 Mac。素材没有给出具体的 macOS 版本下限,也没有给出最低内存要求,实际能否跑动某个模型,主要取决于模型参数量与你机器的统一内存大小。选模型时先看权重体积,再决定是否量化,这是最稳妥的判断方式。

安装 MLX-LM

处理大语言模型时,装 MLX-LM 就够了。它通过 pip 一行安装:

pip install mlx-lm

关键一点:装了 mlx-lm 就不需要再单独安装 mlx,前者已经包含后者。重复安装不会带来额外好处,反而容易在排查问题时混淆来源。

只装 MLX 本体的情形

如果你的用途不是大语言模型文本生成,而只是用 MLX 做别的计算,可以只装 MLX 本体。pip 方式:

pip install mlx

conda 方式:

conda install -c conda-forge mlx

两种方式选其一即可。conda 渠道走的是 conda-forge,适合已经在用 conda 管理环境的机器。

确认环境可用

安装完成后,最直接的验证方式就是跑一次生成命令(见下一节)。如果命令能正常下载模型并输出文本,说明 Python 环境、MLX 与 MLX-LM 都已就位。若报找不到模块,优先检查当前 shell 激活的是不是安装时所用的那个 Python 环境。

操作步骤

第一步:用一行命令直接生成文本

MLX-LM 自带命令行工具,可以直接指定 Hub 上的模型仓库名,程序会自动下载、加载并开始生成:

python -m mlx_lm.generate --model mistralai/Mistral-7B-Instruct-v0.2 --prompt "hello"

这条命令里有两个参数值得记住:--model 接的是 Hub 上的仓库标识(用户或组织/模型名 的形式),--prompt 接的是输入提示词。首次运行会下载权重,耗时取决于网络与模型大小;之后再运行会复用本地缓存。

想看清楚还有哪些可调项,直接查帮助:

python -m mlx_lm.generate --help

生成相关的选项都在这里列出。不同版本之间选项可能有增减,以你本地实际输出的帮助信息为准。

第二步:改用 Python 代码调用

命令行适合快速验证,真正写程序时用 Python 接口更灵活。MLX-LM 提供 load 与 generate 两个入口:

from mlx_lm import load, generate

model, tokenizer = load("mistralai/Mistral-7B-Instruct-v0.2")
response = generate(model, tokenizer, prompt="hello", verbose=True)

这段代码做了三件事:load 按仓库名取回模型与分词器;generate 传入模型、分词器与提示词完成推理;verbose=True 让生成过程边跑边打印,便于观察输出节奏与是否卡住。返回值 response 即生成的文本结果,可以直接拿去做后续处理。

把这段代码放进脚本或 notebook 里,就可以围绕它做批量提示、结果落盘、接下游逻辑等扩展,而不必每次敲命令行。

第三步:确认模型架构是否被支持

MLX-LM 内置支持一批主流大语言模型架构,素材明确列出的是 LLaMA、Phi-2、Mistral 与 Qwen。也就是说,这几类架构的模型可以直接用上面的命令行或 Python 方式加载。

如果目标模型不属于内置支持的架构,不要硬套 mlx_lm.generate,而是先把权重完整下载到本地目录,再按需处理。下载用 hf 命令行工具:

pip install -U huggingface_hub
export HF_XET_HIGH_PERFORMANCE=1
hf download --local-dir <LOCAL FOLDER PATH> <USER_ID>/<MODEL_NAME>

这里有三点需要说明:

  • 先升级 huggingface_hub,保证 hf 子命令可用且行为与文档一致。
  • HF_XET_HIGH_PERFORMANCE=1 会提高并发上限与缓冲区大小,适用于带宽充足、内存至少 64 GB 的机器。内存不够时不要开这个开关,否则可能因为缓冲过大而适得其反。
  • --local-dir 指定落盘目录,后面跟仓库标识。把这两个占位符换成你自己的路径与模型名即可。

第四步:转换并量化模型

把 Hub 上的模型转成 MLX 格式,同时做量化,用 mlx_lm.convert:

python -m mlx_lm.convert --hf-path mistralai/Mistral-7B-v0.1 -q

--hf-path 指向源模型仓库,-q 表示执行量化。量化后的权重体积更小、推理更省内存,代价是精度会有一定损失。素材没有给出具体的量化位宽与精度对比数据,实际效果请以你所用版本的默认行为与实测结果为准。

第五步:转换后直接推送到 Hub

如果希望转换结果直接发布出去,加上 --upload-repo 即可,转换完成后会自动推送:

python -m mlx_lm.convert \
  --hf-path mistralai/Mistral-7B-v0.1 \
  -q \
  --upload-repo <USER_ID>/<MODEL_NAME>

多行写法只是为了可读,反斜杠是 shell 的续行符。目标仓库写成 用户或组织/模型名 的形式。推送前需要已经完成 Hub 的登录鉴权,否则上传会失败;鉴权方式与令牌管理请以 Hub 当前文档为准。

一个完整示例

下面把前面的步骤串成一条从零到可用的最小链路。假设你在一台 Apple 芯片的 Mac 上,目标是先跑通生成,再把一个模型量化后发布到自己的账号下。

第 1 步,建环境并安装。

python -m venv mlxenv
source mlxenv/bin/activate
pip install mlx-lm

激活虚拟环境后再安装,可以避免污染系统 Python。装完 mlx-lm 就不必再装 mlx。

第 2 步,验证生成能力。

python -m mlx_lm.generate --model mistralai/Mistral-7B-Instruct-v0.2 --prompt "hello"

首次执行会下载权重。看到模型输出文本,说明环境、下载、加载、推理四个环节都通了。如果这一步就失败,先不要往下走,回到准备工作排查环境。

第 3 步,写一个可复用的 Python 脚本。

from mlx_lm import load, generate

model, tokenizer = load("mistralai/Mistral-7B-Instruct-v0.2")
response = generate(model, tokenizer, prompt="hello", verbose=True)
print(response)

保存为 run.py 后执行 python run.py。这一步的意义在于:模型与分词器只加载一次,后续可以在同一个进程里反复调用 generate,比每次起命令行更省时间。

第 4 步,转换并量化。

python -m mlx_lm.convert --hf-path mistralai/Mistral-7B-v0.1 -q

转换会在本地产出 MLX 格式的权重。先不加 --upload-repo 跑一遍,确认本地能正常产出,再决定是否发布。

第 5 步,发布到 Hub。

python -m mlx_lm.convert \
  --hf-path mistralai/Mistral-7B-v0.1 \
  -q \
  --upload-repo your-username/your-model-name

把 your-username/your-model-name 换成你自己的目标仓库。执行前确认已登录 Hub,并且对该命名空间有写权限。

第 6 步,验证发布结果。

推送完成后,用转换后的仓库名再跑一次生成命令,确认远端权重能被正常加载:

python -m mlx_lm.generate --model your-username/your-model-name --prompt "hello"

能出结果,说明整条链路闭环。若失败,优先检查仓库是否公开、模型文件是否完整上传。

注意事项

安装层面的坑

  • 不要重复装 mlx。 装了 mlx-lm 就已经包含 MLX 本体,额外再装 mlx 没有收益。
  • conda 与 pip 二选一。 只装 MLX 本体时,pip 与 conda-forge 两条路选一条,混用容易产生版本冲突。
  • 环境要对齐。 命令行报找不到模块,多半是当前 shell 用的 Python 与安装时不是同一个。

模型选择与架构支持

  • 内置支持的是 LLaMA、Phi-2、Mistral、Qwen 这几类架构。其他架构的模型不要直接套 mlx_lm.generate,先下载权重再按需处理。
  • 模型能否跑起来,取决于参数量与机器内存的匹配程度。素材没有给出具体的内存门槛,选型时以权重体积为参考自行判断。
  • Hub 上的 MLX 模型可以通过模型页左侧的筛选条件找到,也有一个开放的社区在持续转换并发布 MLX 格式权重。具体有哪些模型、是否可下载,以 Hub 当前页面为准。

下载与网络

  • HF_XET_HIGH_PERFORMANCE=1 只适合带宽高、内存至少 64 GB 的机器。内存不足时开启会放大缓冲占用。
  • 下载大模型前先确认本地磁盘余量。素材没有给出具体的存储配额数字,请以 Hub 与本地磁盘的当前状态为准。
  • 首次运行生成命令会触发下载,耗时较长属于正常现象;后续运行复用缓存,速度会明显不同。

量化与发布

  • -q 会带来精度损失。对输出质量敏感的场景,建议先用未量化的权重做基线对比。
  • --upload-repo 要求已登录且对目标命名空间有写权限。发布前想清楚仓库是公开还是私有。
  • 转换与上传都是一次性动作,但模型体积大,上传耗时会明显长于普通文件,注意保持网络稳定。

版本与信息时效

MLX 与 MLX-LM 仍在持续迭代,命令行选项、默认量化行为、支持的模型架构列表都可能变化。本文涉及的包版本、模型可用性、存储与配额等易变信息,请以官网当前信息为准;执行前用 --help 核对一遍当前版本的参数,是最省事的做法。