文章目录
一、关于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、功能特性
Hugging Face Hub集成
- 支持数千种LLM模型的单命令调用
- 支持模型量化和上传到Hugging Face Hub
模型微调
- 支持 低秩适配(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（二）