构建和安装

构建和安装#

Python 安装#

MLX 在 PyPI 上可用。要在您的 Apple 芯片电脑上使用 MLX，只需执行以下操作：

pip install mlx

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

  • 使用 M 系列芯片 (Apple 芯片)

  • 使用原生 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。使用 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

可选：安装 stubs 以在您的 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，并且它应指向构建生成的 Metal 库的路径。

构建选项#

选项

默认值

MLX_BUILD_TESTS

ON

MLX_BUILD_EXAMPLES

OFF

MLX_BUILD_BENCHMARKS

OFF

MLX_BUILD_METAL

ON

MLX_BUILD_CPU

ON

MLX_BUILD_PYTHON_BINDINGS

OFF

MLX_METAL_DEBUG

OFF

MLX_BUILD_SAFETENSORS

ON

MLX_BUILD_GGUF

ON

MLX_METAL_JIT

OFF

注意

如果您有多个 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

MLX_METAL_JIT 标志可以最小化包含预构建 GPU 内核的 MLX Metal 库的大小。通过在给定机器上首次使用 MLX 中的内核时进行运行时编译，这可以显著减小 Metal 库的大小。请注意，运行时编译会产生冷启动成本，根据应用程序的不同，可能从几百毫秒到几秒不等。内核一旦编译，将由系统缓存。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" 但构建出现错误，提示“Building for x86_64 on macOS is not supported.”，请使用 rm -rf build/ 清除构建缓存并重试。

目录