构建和安装

构建和安装#

Python 安装#

MLX 可在 PyPI 上获取。要在您自己的 Apple Silicon 电脑上使用 MLX，您只需

pip install mlx

要从PyPI安装，您必须满足以下要求：

  • 使用M系列芯片（苹果硅）

  • 使用原生Python版本大于等于3.9

  • macOS >= 13.5

注意

MLX 仅在运行 macOS >= 13.5 的设备上可用 强烈建议使用 macOS 14 (Sonoma)

MLX 也可以在 conda-forge 上获取。要使用 conda 安装 MLX，请执行以下操作：

conda install conda-forge::mlx

故障排除#

我的操作系统和Python版本都在要求的范围内，但pip仍然找不到匹配的发行版。

你可能正在使用非原生的Python。输出

python -c "import platform; print(platform.processor())"

应该是 arm。如果是 i386（并且你使用的是 M 系列机器），那么你正在使用非本地的 Python。将你的 Python 切换到本地 Python。一个好的方法是使用 Conda。

从源代码构建#

构建要求#

  • 支持C++17的C++编译器（例如Clang >= 5.0）

  • cmake – 版本 3.25 或更高，以及 make

  • Xcode >= 15.0 和 macOS SDK >= 14.0

注意

确保您的shell环境是本地的arm，而不是通过Rosetta的x86。如果uname -p的输出是x86，请参阅下面的故障排除部分。

Python API#

要从源代码构建并安装MLX Python库，首先从其GitHub仓库克隆MLX：

git clone git@github.com:ml-explore/mlx.git mlx && cd mlx

然后只需使用 pip 构建并安装 MLX：

CMAKE_BUILD_PARALLEL_LEVEL=8 pip install .

为了开发，请安装带有开发依赖项的包，并使用可编辑安装：

CMAKE_BUILD_PARALLEL_LEVEL=8 pip install -e ".[dev]"

一旦安装了开发依赖项，您可以使用以下命令更快地构建：

CMAKE_BUILD_PARALLEL_LEVEL=8 python setup.py build_ext --inplace

运行测试使用：

python -m unittest discover python/tests

可选：安装存根以启用IDE中的自动补全和类型检查：

python setup.py generate_stubs

C++ API#

目前，MLX 必须从源代码构建和安装。

与Python库类似，要构建和安装MLX C++库，首先从其GitHub仓库克隆MLX：

git clone git@github.com:ml-explore/mlx.git mlx && cd mlx

创建一个构建目录并运行CMake和make：

mkdir -p build && cd build
cmake .. && make -j

运行测试使用：

make test

安装方法：

make install

请注意，构建的mlx.metallib文件应该与静态链接到libmlx.a的可执行文件位于同一目录中，或者在构建时应定义预处理器常量METAL_PATH，并且它应指向构建的金属库的路径。

构建选项#

选项

默认值

MLX_BUILD_TESTS

开启

MLX_BUILD_EXAMPLES

关闭

MLX_BUILD_BENCHMARKS

关闭

MLX_BUILD_METAL

开启

MLX_BUILD_CPU

开启

MLX_BUILD_PYTHON_BINDINGS

关闭

MLX_METAL_DEBUG

关闭

MLX_BUILD_SAFETENSORS

开启

MLX_BUILD_GGUF

开启

MLX_METAL_JIT

关闭

注意

如果您安装了多个Xcode并希望在构建时使用特定的一个，您可以通过在构建前添加以下环境变量来实现

export DEVELOPER_DIR="/path/to/Xcode.app/Contents/Developer/"

此外，您可以使用以下命令来找出将使用哪个macOS SDK

xcrun -sdk macosx --show-sdk-version

二进制大小最小化#

要生成较小的二进制文件，请使用CMake标志CMAKE_BUILD_TYPE=MinSizeRel 和BUILD_SHARED_LIBS=ON。

MLX CMake 构建有几个额外的选项可以生成更小的二进制文件。 例如，如果您不需要 CPU 后端或对 safetensors 和 GGUF 的支持，您可以这样做：

cmake .. \
  -DCMAKE_BUILD_TYPE=MinSizeRel \
  -DBUILD_SHARED_LIBS=ON \
  -DMLX_BUILD_CPU=OFF \
  -DMLX_BUILD_SAFETENSORS=OFF \
  -DMLX_BUILD_GGUF=OFF \
  -DMLX_METAL_JIT=ON

THE MLX_METAL_JIT 标志最小化了包含预构建GPU内核的MLX Metal库的大小。通过在给定机器上首次在MLX中使用时运行时编译内核，这大大减少了Metal库的大小。请注意，运行时编译会产生冷启动成本，这可能在几百毫秒到几秒之间，具体取决于应用程序。一旦内核被编译，它将被系统缓存。Metal内核缓存在重启后仍然存在。

故障排除#

未找到金属#

当你尝试构建时，你会看到以下错误：

error: unable to find utility "metal", not a developer tool or in PATH

要解决这个问题，首先确保你已经安装了Xcode：

xcode-select --install

然后设置活动的开发者目录：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

x86 Shell#

如果 uname -p 的输出是 x86，那么你的 shell 是通过 Rosetta 以 x86 模式运行，而不是原生运行。

要解决这个问题，请在Finder中找到应用程序（对于iTerm是/Applications， 对于Terminal是/Applications/Utilities），右键点击，然后点击“获取信息”。 取消勾选“使用Rosetta打开”，关闭“获取信息”窗口，并重新启动你的终端。

验证终端现在是否原生运行以下命令：

$ uname -p
arm

同时检查cmake是否使用了正确的架构：

$ cmake --system-information | grep CMAKE_HOST_SYSTEM_PROCESSOR
CMAKE_HOST_SYSTEM_PROCESSOR "arm64"

如果你看到"x86_64"，尝试重新安装cmake。如果你看到"arm64" 但构建时出现错误“不支持在macOS上为x86_64构建。” 使用rm -rf build/清除你的构建缓存，然后重试。