MLX LM - 在Apple芯片上运行大语言模型的Python工具包

一、关于MLX LM

1、项目概览

MLX LM是一个Python工具包，支持在Apple芯片上使用MLX进行文本生成和大语言模型微调。

2、相关链接资源

• GitHub：https://github.com/ml-explore/mlx-lm
• Hugging Face社区：https://huggingface.co/mlx-community
• Hugging Face Space：https://huggingface.co/spaces/mlx-community/mlx-my-repo

3、功能特性

1. Hugging Face Hub集成

   • 支持数千种LLM模型的单命令调用
   • 支持模型量化和上传到Hugging Face Hub

2. 模型微调

   • 支持 低秩适配(LoRA)和全模型微调
   • 支持量化模型微调
   • 通过 mx.distributed 实现分布式推理和微调

二、安装配置

# pip安装
pip install mlx-lm

# conda安装
conda install -c conda-forge mlx-lm

三、使用指南

1、快速开始

文本生成

mlx_lm.generate --prompt "How tall is Mt Everest?"

交互式聊天

mlx_lm.chat

这将为你提供一个可与大语言模型(LLM)交互的聊天REPL环境。在REPL会话持续期间，聊天上下文会被保留。

mlx-lm中的命令通常支持命令行选项，用于指定模型、采样参数等配置。使用-h参数可以查看某个命令的可用选项列表，例如：

mlx_lm.generate -h

2、Python API

可以将 mlx-lm 作为模块使用：

from mlx_lm import load, generate

model, tokenizer = load("mlx-community/Mistral-7B-Instruct-v0.3-4bit")

prompt = "Write a story about Einstein"

messages = [{"role": "user", "content": prompt}]
prompt = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True
)

text = generate(model, tokenizer, prompt=prompt, verbose=True)

要查看所有参数的描述，您可以执行：

>>> help(generate)

查看生成示例了解如何更详细地使用该API。

3、量化模型，上传HF

mlx-lm包还提供了量化模型及可选上传至Hugging Face Hub的功能。

您可以通过Python API转换模型：

from mlx_lm import convert

repo = "mistralai/Mistral-7B-Instruct-v0.3"
upload_repo = "mlx-community/My-Mistral-7B-Instruct-v0.3-4bit"

convert(repo, quantize=True, upload_repo=upload_repo)

这将生成一个4位量化的Mistral 7B模型，并上传到代码库 mlx-community/My-Mistral-7B-Instruct-v0.3-4bit。

默认情况下，转换后的模型还会保存在路径mlx_model中。

要查看所有参数的描述，您可以执行：

>>> help(convert)

4、流式生成

对于流式生成场景，请使用 stream_generate 函数。该函数会返回一个生成响应对象。例如：

from mlx_lm import load, stream_generate

repo = "mlx-community/Mistral-7B-Instruct-v0.3-4bit"
model, tokenizer = load(repo)

prompt = "Write a story about Einstein"

messages = [{"role": "user", "content": prompt}]
prompt = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True
)

for response in stream_generate(model, tokenizer, prompt, max_tokens=512):
    print(response.text, end="", flush=True)
print()

采样

generate 和 stream_generate 函数接受 sampler 和 logits_processors 关键字参数。

采样器可以是任何可调用对象，它接收一个可能批处理的 logits 数组并返回采样后的令牌数组。logits_processors 必须是一个可调用对象列表，这些对象以令牌历史和当前 logits 作为输入，并返回处理后的 logits。logits 处理器会按顺序应用。

mlx_lm.sample_utils 中提供了一些标准的采样函数和 logits 处理器。

5、命令行

你也可以通过以下方式在命令行中使用 mlx-lm：

mlx_lm.generate --model mistralai/Mistral-7B-Instruct-v0.3 --prompt "hello"

这将从Hugging Face Hub下载Mistral 7B模型，并使用给定的提示生成文本。

要查看完整选项列表，请运行：

mlx_lm.generate --help

要通过命令行量化模型，请运行：

mlx_lm.convert --hf-path mistralai/Mistral-7B-Instruct-v0.3 -q

运行以下命令获取更多选项：

mlx_lm.convert --help

你可以通过为convert指定--upload-repo来上传新模型到Hugging Face。例如，要将量化后的Mistral-7B模型上传到MLX Hugging Face社区，可以执行以下操作：

mlx_lm.convert \
    --hf-path mistralai/Mistral-7B-Instruct-v0.3 \
    -q \
    --upload-repo mlx-community/my-4bit-mistral

模型也可以直接在 mlx-my-repo Hugging Face Space 中进行转换和量化处理。

6、长提示词与生成

mlx-lm 提供了一些工具来高效处理长提示词和生成内容：

• 采用固定大小的旋转键值缓存机制
• 支持提示词缓存功能

要使用旋转键值缓存，需传入参数 --max-kv-size n（其中 n 可为任意整数值）。

较小数值如 512 会显著减少内存占用，但会降低生成质量；

较大数值如 4096 或更高会占用更多内存，但能获得更好的生成质量。

通过缓存提示词可大幅加速相同长上下文在不同查询中的复用。

使用 mlx_lm.cache_prompt 方法即可缓存提示词，例如：

cat prompt.txt | mlx_lm.cache_prompt \
  --model mistralai/Mistral-7B-Instruct-v0.3 \
  --prompt - \
  --prompt-cache-file mistral_prompt.safetensors

然后使用缓存的提示词配合 mlx_lm.generate：

mlx_lm.generate \
    --prompt-cache-file mistral_prompt.safetensors \
    --prompt "\nSummarize the above text."

缓存的提示词会被视为所提供提示词的前缀。还需注意，当使用缓存的提示词时，模型会从缓存中读取，因此无需显式指定模型。

提示词缓存功能也可在Python API中使用，以避免重复计算提示词。这在多轮对话或使用相同上下文的多次请求中非常有用。更多使用细节请参阅示例。

四、支持模型

mlx-lm 支持数千种 Hugging Face 格式的大语言模型。

如果您想运行的模型不在支持列表中，请提交一个issue，或者更棒的是，直接提交一个 pull request。

以下是与此示例兼容的部分 Hugging Face 模型示例：

• mistralai/Mistral-7B-v0.1
• meta-llama/Llama-2-7b-hf
• deepseek-ai/deepseek-coder-6.7b-instruct
• 01-ai/Yi-6B-Chat
• microsoft/phi-2
• mistralai/Mixtral-8x7B-Instruct-v0.1
• Qwen/Qwen-7B
• pfnet/plamo-13b
• pfnet/plamo-13b-instruct
• stabilityai/stablelm-2-zephyr-1_6b
• internlm/internlm2-7b
• tiiuae/falcon-mamba-7b-instruct

大多数 Mistral、Llama、Phi-2 和 Mixtral 类型的模型应该可以直接运行。

对于某些模型（如 Qwen 和 plamo），分词器需要启用 trust_remote_code 选项。您可以通过在命令行中传递 --trust-remote-code 来实现这一点。如果没有明确指定该标志，运行模型时终端会提示您是否信任远程代码。

对于 Qwen 模型，您还必须指定 eos_token。您可以通过在命令行中传递 --eos-token "<|endoftext|>" 来实现这一点。

这些选项也可以在 Python API 中设置。例如：

model, tokenizer = load(
    "qwen/Qwen-7B",
    tokenizer_config={"eos_token": "<|endoftext|>", "trust_remote_code": True},
)

大模型

注意事项： 此功能需要 macOS 15.0 或更高版本支持。

若模型体积相对于机器可用内存较大，运行速度可能会变慢。mlx-lm 会尝试通过固定模型及缓存所占用的内存来提升速度，但此功能需 macOS 15 或更高版本才能生效。

如果看到如下警告信息：

[WARNING] Generating with a model that requires …

则说明该模型在当前机器上运行可能较慢。若模型可完整载入内存，通常可通过提高系统固定内存上限来加速。要调整该限制，请设置以下 sysctl 参数：

sudo sysctl iogpu.wired_limit_mb=N

值 N 应大于模型大小的兆字节数，但小于机器的内存容量。

伊织 xAI 2025-06-24（二）