建置與安裝

建置與安裝#

Python 安裝#

MLX 可在 PyPI 取得。要在自己的 Apple 晶片電腦上使用 MLX，只需：

pip install mlx

要從 PyPI 安裝，你的系統必須符合下列需求：

  • Using Apple silicon

  • 使用原生的 Python >= 3.10

  • macOS >= 14.0

備註

MLX 僅支援執行 macOS >= 14.0 的裝置。

CUDA#

MLX 提供 CUDA 後端，可使用以下命令安裝：

pip install mlx[cuda12]

要從 PyPI 安裝 CUDA 軟體包，你的系統必須符合下列需求：

  • Nvidia 架構 >= SM 7.5

  • Nvidia 驅動程式 >= 550.54.14

  • CUDA Toolkit >= 12.0

  • glibc >= 2.35 的 Linux 發行版

  • Python >= 3.10

CUDA 13 請使用 pip install mlx[cuda13]。CUDA 13 軟體包需要 Nvidia 驅動>= 580 或適當的 CUDA 相容性軟體包。

僅 CPU（Linux）#

在 Linux 上使用僅 CPU 版本的 MLX：

pip install mlx[cpu]

要從 PyPI 安裝僅 CPU 軟體包，你的系統必須符合下列需求：

  • glibc >= 2.35 的 Linux 發行版

  • Python >= 3.10

疑難排解#

我的 OS 與 Python 版本符合需求，但 pip 仍找不到相符的發行版。

你可能使用了非原生的 Python。以下命令的輸出：

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

應該是 arm。若顯示為 ``i386``（且你使用 M 系列機器），代表你在使用非原生的 Python。請切換到原生 Python。可使用 Conda 來達成。

從來源碼建置#

建置需求#

  • libblas-dev, liblapack-dev, and liblapacke-dev (Linux)

  • A C++ compiler with C++20 support (e.g. Clang >= 15.0)

  • cmake 版本 3.25 以上，以及 make

  • Xcode >= 15.0 與 macOS SDK >= 14.0

備註

請確保你的 shell 環境是原生 arm，不是透過 Rosetta 的 x86。若 uname -p 輸出為 x86，請參考下方的疑難排解。

Python API#

要從來源碼建置與安裝 MLX Python 程式庫，先從其 GitHub 專案複製：

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

接著使用 pip 建置並安裝 MLX：

pip install .

進行開發時，請安裝含開發相依性的軟體包，並使用可編輯安裝：

pip install -e ".[dev]"

安裝開發相依性後，可用以下命令加速建置：

python setup.py build_ext --inplace

使用以下命令執行測試：

python -m unittest discover python/tests

C++ API#

目前 MLX 必須從來源碼建置與安裝。

與 Python 程式庫相同，要建置並安裝 MLX C++ 程式庫，先從 其 GitHub 專案 複製：

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 程式庫大小。它會在特定機器上首次使用內核時進行即時編譯，從而大幅減少 Metal 程式庫大小。請注意，即時編譯會產生冷啟動成本，視應用程式而定可能從數百毫秒到數秒不等。內核一旦編譯完成，會被系統快取，且 Metal 內核快取會在重開機後保留。

Linux#

在 Linux 上從來源碼建置（僅 CPU）時，請安裝 BLAS 與 LAPACK 標頭。以 Ubuntu 為例，可執行：

apt-get update -y
apt-get install libblas-dev liblapack-dev liblapacke-dev -y

接著依照指示安裝 Python 或 C++ API。

CUDA#

在 Linux 上以 CUDA 從來源碼建置時，請安裝 BLAS 與 LAPACK 標頭以及 CUDA Toolkit。以 Ubuntu 為例，可執行：

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
dpkg -i cuda-keyring_1.1-1_all.deb
apt-get update -y
apt-get -y install cuda-toolkit-12-9
apt-get install libblas-dev liblapack-dev liblapacke-dev libcudnn9-dev-cuda-12 -y

建置 Python 或 C++ API 時，請務必加入 cmake 旗標 MLX_BUILD_CUDA=ON。例如要建置 Python API，請執行：

CMAKE_ARGS="-DMLX_BUILD_CUDA=ON" pip install -e ".[dev]"

要建置 C++ 軟體包，請執行：

mkdir -p build && cd build
cmake .. -DMLX_BUILD_CUDA=ON && make -jmkdir -p build && cd build
cmake .. -DMLX_BUILD_CUDA=ON && make -j

疑難排解#

找不到 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/ 清除建置快取後再試一次。

目錄