ml-explore/mlx-lm
GitHub: ml-explore/mlx-lm
Apple 官方推出的 Python 工具包，让开发者能够在 Apple Silicon 上高效运行、量化和微调各类大语言模型。
Stars: 4418 | Forks: 532
## MLX LM
MLX LM 是一个 Python 包，用于在 Apple silicon 上利用 MLX 生成文本和微调大语言模型。
一些关键功能包括：
* 与 Hugging Face Hub 集成，通过单个命令即可轻松使用数千个 LLM。
* 支持量化模型并将其上传到 Hugging Face Hub。
* [低秩和全模型微调](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/LORA.md)，并支持量化模型。
* 使用 `mx.distributed` 进行分布式推理和微调
最简单的入门方法是安装 `mlx-lm` 包：
**使用 `pip`**:
```
pip install mlx-lm
```
**使用 `conda`**:
```
conda install -c conda-forge mlx-lm
```
### 快速开始
要使用 LLM 生成文本，请使用：
```
mlx_lm.generate --prompt "How tall is Mt Everest?"
```
要与 LLM 进行聊天，请使用：
```
mlx_lm.chat
```
这将为你提供一个聊天 REPL，你可以用它来与 LLM 互动。在 REPL 的生命周期内，聊天上下文会被保留。
`mlx-lm` 中的命令通常带有命令行选项，允许你指定模型、采样参数等。使用 `-h` 查看命令的可用选项列表，例如：
```
mlx_lm.generate -h
```
用于生成和聊天的默认模型是 `mlx-community/Llama-3.2-3B-Instruct-4bit`。你可以使用 `--model` 标志指定任何兼容 MLX 的模型。[MLX Community](https://huggingface.co/mlx-community) Hugging Face 组织中提供了数千个可用模型。
### 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)
```
查看[生成示例](https://github.com/ml-explore/mlx-lm/tree/main/mlx_lm/examples/generate_response.py)以了解如何更详细地使用 API。查看[批量生成示例](https://github.com/ml-explore/mlx-lm/tree/main/mlx_lm/examples/batch_generate_response.py)以了解如何为一批提示高效地生成续写内容。
`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-bit 量化的 Mistral 7B，并将其上传到仓库 `mlx-community/My-Mistral-7B-Instruct-v0.3-4bit`。默认情况下，它还会将转换后的模型保存在路径 `mlx_model` 中。
要查看所有参数的描述，你可以执行：
```
>>> help(convert)
```
#### 流式传输
对于流式生成，请使用 `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 数组并返回一个采样 token 数组。`logits_processors` 必须是一个可调用对象列表，这些对象接受 token 历史记录和当前 logits 作为输入，并返回处理后的 logits。logits 处理器按顺序应用。
`mlx_lm.sample_utils` 中提供了一些标准的采样函数和 logits 处理器。
### 命令行
你也可以通过命令行使用 `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 --model mistralai/Mistral-7B-Instruct-v0.3 -q
```
要获取更多选项，请运行：
```
mlx_lm.convert --help
```
你可以通过向 `convert` 指定 `--upload-repo` 将新模型上传到 Hugging Face。例如，要将量化的 Mistral-7B 模型上传到 [MLX Hugging Face 社区](https://huggingface.co/mlx-community)，你可以执行：
```
mlx_lm.convert \
--model mistralai/Mistral-7B-Instruct-v0.3 \
-q \
--upload-repo mlx-community/my-4bit-mistral
```
模型也可以直接在 [mlx-my-repo](https://huggingface.co/spaces/mlx-community/mlx-my-repo) Hugging Face Space 中进行转换和量化。
### 长提示和生成
`mlx-lm` 拥有一些工具可以高效扩展到长提示和生成：
- 一个旋转的固定大小 key-value cache。
- 提示缓存
要使用旋转 key-value cache，请传递参数 `--max-kv-size n`，其中 `n` 可以是任何整数。较小的值（如 `512`）会占用很少的 RAM，但会导致质量较差。较大的值（如 `4096` 或更高）会使用更多的 RAM，但质量更好。
缓存提示可以显著加快在不同查询中重用相同长上下文的速度。要缓存提示，请使用 `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 中使用，以避免重新计算提示。这在多轮对话或使用相同上下文的跨请求中非常有用。有关更多用法详细信息，请参阅[示例](https://github.com/ml-explore/mlx-lm/blob/main/mlx_lm/examples/chat.py)。
### 支持的模型
`mlx-lm` 支持 Hugging Face Hub 上可用的数千个 LLM。如果你想要运行的模型不受支持，请提交[问题](https://github.com/ml-explore/mlx-lm/issues/new)，或者更好的是提交 pull request。[MLX Community](https://huggingface.co/mlx-community) Hugging Face 组织中以各种量化格式提供了许多受支持的模型。
对于某些模型，tokenizer 可能要求你启用 `trust_remote_code` 选项。你可以通过在命令行中传递 `--trust-remote-code` 来实现这一点。
如果你没有显式指定该标志，则在运行模型时，系统会提示你在终端中信任远程代码。
Tokenizer 选项也可以在 Python API 中设置。例如：
```
model, tokenizer = load(
"qwen/Qwen-7B",
tokenizer_config={"eos_token": "<|endoftext|>", "trust_remote_code": True},
)
```
### 大型模型
相对于机器上可用总 RAM 较大的模型可能会运行缓慢。`mlx-lm` 将尝试通过锁定模型和缓存占用的内存来加快速度。这需要 macOS 15 或更高版本才能工作。
如果你看到以下警告消息：
那么该模型在给定机器上可能会很慢。如果模型可以装入 RAM，则通常可以通过增加系统锁定内存限制来加速。
要增加限制，请设置以下 `sysctl`：
```
sudo sysctl iogpu.wired_limit_mb=N
```
值 `N` 应大于模型大小（以兆字节为单位），但小于机器的内存大小。
标签：4bit, AI开发框架, Apex, Apple Silicon, DNS解析, Hugging Face, LLM, LoRA, MLX, NLP, Python, PyTorch替代, Unmanaged PE, 分布式计算, 大型语言模型, 开源项目, 异常处理, 推理引擎, 无后门, 本地部署, 机器学习, 模型微调, 深度学习, 生成式AI, 索引, 逆向工具, 量化