Mojo 1.0 на Mac не находит GPU? Устранение неполадок Metal Toolchain 2026

Mojo запускается, но GPU не определяется, либо MAX serve падает на компиляции модели.

Самое быстрое решение: не списывайте проблему на M1 или M2. Сначала проверьте macOS, Xcode или Command Line Tools и Metal Toolchain; если минимальная GPU-программа видит устройство, прекращайте переустановку Mojo и проверяйте модель, ядра и доступную память.

Эта статья для вас, если вы уже можете выполнить команду mojo, но получаете ошибку Apple GPU или Metal. Она также пригодится инженерам, которые оценивают MAX serve на Apple Silicon M1/M2, и руководителям платформенных команд, которым нужна воспроизводимая среда для удалённой проверки.

Последнее обновление — 21 августа 2026 года. Данные сверены с официальными требованиями Mojo 1.0, документацией MAX и релизом MAX 26.5.

Три независимых вывода: Mojo, Metal и MAX

Типичный сбой выглядит так: команда mojo отвечает версией, обычный пример на языке запускается, но при выполнении GPU-примера появляется сообщение о недоступном Metal Toolchain. После этого разработчик переустанавливает весь стек — uv, pixi, Mojo и MAX — хотя неисправен только путь к Xcode.

Разделяйте три утверждения:

1. Mojo работает — исполняемый файл найден, окружение активировано, программа на языке запускается.
2. Metal доступен — система видит Apple GPU, а компилятор может обратиться к нужным инструментам.
3. Модель поддерживается MAX — граф модели, её операции и конкретные ядра доступны на Apple Silicon, а памяти хватает для компиляции и запуска.

Успешный первый пункт не доказывает второй. Успешный второй не доказывает третий.

Не удаляйте окружение до сохранения лога. В нём часто есть точное имя отсутствующего инструмента или операции, и это быстрее отделяет системную ошибку от несовместимой модели.

Важное различие: встроенный Metal Framework — часть macOS. Metal Toolchain — дополнительный набор инструментов для разработки и компиляции. Наличие первого не означает, что установлен второй.

Шаг 1. Сначала исключите неподдерживаемую систему

На момент проверки Mojo 1.0 официально требует macOS 15 или новее, Apple Silicon от M1 до M5 и Xcode либо Command Line Tools версии 16 или новее. Эти границы указаны в системных требованиях Mojo.

Это означает, что Apple Silicon M1/M2 входит в заявленный диапазон. Сообщение «GPU не найден» нельзя автоматически трактовать как отказ от старого чипа. Сначала проверьте фактическую конфигурацию:

sw_vers
uname -m
system_profiler SPHardwareDataType
xcodebuild -version
xcode-select --print-path

Что должно вас насторожить:

• uname -m возвращает не arm64, если терминал запущен через неподходящую архитектуру или используется не Apple Silicon;
• macOS ниже 15;
• xcodebuild не найден;
• Xcode установлен, но xcode-select --print-path указывает на удалённый или старый каталог;
• версия Command Line Tools ниже 16.

Если система не проходит эту проверку, не переходите к переменным Python и не меняйте модель. На неподдерживаемой базе дальнейшая диагностика создаёт ложные симптомы.

Поддерживают ли M1 и M2 программирование GPU в Mojo? Да, они находятся в официальном диапазоне Apple Silicon M1–M5 для Mojo 1.0. При этом поддержка языка и Metal не обещает, что любая модель MAX будет успешно скомпилирована или обслужена.

Шаг 2. Отделите Metal Toolchain от самого Metal

Сбой в этой точке обычно относится к одному из трёх сценариев:

• инструмент Metal не установлен;
• после обновления macOS или Xcode путь к инструменту стал недействительным;
• компиляция GPU начинается, но завершается ошибкой уже внутри toolchain.

Для установки дополнительного компонента используется команда:

xcodebuild -downloadComponent MetalToolchain

Запускайте её в терминале с выбранным актуальным Xcode. После выполнения проверьте код завершения:

echo $?

Нулевой код показывает, что команда завершилась без ошибки. Но это ещё не доказательство работоспособности Mojo. Сразу после загрузки снова выполните минимальный GPU-пример из официального руководства Mojo по GPU.

Сохраняйте оба вывода:

xcodebuild -downloadComponent MetalToolchain > metal-download.log 2>&1
status=$?
printf 'MetalToolchain exit status: %s\n' "$status"

Если загрузка завершилась успешно, а тест всё равно не видит GPU, ищите проблему в выбранном Xcode, архитектуре процесса или версии пакета. Если тест доходит до компиляции и падает с сообщением о конкретном Metal-инструменте, полезно сопоставить ошибку с текущим каталогом разработчика.

Нужно ли заново устанавливать Metal Toolchain после обновления macOS или Xcode? Не всегда. Но после обновления нужно повторно проверить выбранный developer directory и заново выполнить официальный шаг загрузки, если инструмент отсутствует или старый путь больше не работает. Ориентируйтесь на результат минимального GPU-теста, а не на сообщение «загрузка завершена».

Шаг 3. Проверьте, какой Xcode действительно использует терминал

Несколько версий Xcode — частый источник расхождения. Приложение может находиться в одном каталоге, а xcode-select указывать на другой. В результате интерфейс Xcode выглядит исправным, но Mojo вызывает инструменты из старой установки.

Проверьте активный путь:

xcode-select --print-path
xcodebuild -version
xcrun --find metal
xcrun --find metallib

Если путь не соответствует нужной установке, выберите каталог явно:

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

Путь должен соответствовать реально существующему приложению. Если используется другое имя Xcode, подставьте его каталог. После переключения повторите:

xcodebuild -version
xcrun --find metal
xcodebuild -downloadComponent MetalToolchain

Документация Apple объясняет, как проверять и менять активные Command Line Tools в настройках инструментов командной строки Xcode. Это особенно важно после удаления старого Xcode, установки бета-версии или обновления macOS.

Плюсы проверки пути:

• вы меняете только системный выбор инструментов;
• ошибка становится воспроизводимой;
• не затрагиваются остальные Python-проекты.

Минусы:

• sudo требует административных прав;
• смена пути может повлиять на другие проекты, если команда использует другой Xcode;
• наличие metal в PATH не заменяет проверку версии и developer directory.

Не подменяйте диагностику переустановкой всех компонентов. Сначала установите, какой бинарный файл вызывается и откуда он загружает инструменты.

Шаг 4. Сравните uv, pixi и старое окружение

После системной проверки перейдите к пользовательскому слою. На одном Mac нередко одновременно существуют:

• глобальный mojo;
• окружение pixi с MAX;
• проект на uv;
• старая установка modular;
• стабильная и ночная версии пакетов.

Проверьте реальные пути:

which mojo
which python
python -c "import sys; print(sys.executable)"
python -m pip show max
pixi list

Если команда mojo берётся из одного окружения, а Python-пакет MAX — из другого, вы сравниваете несовместимые компоненты. В таком случае очистите и пересоздайте только проблемное окружение. Не удаляйте рабочую среду соседнего проекта, пока не установили её путь и владельца.

MAX 26.5 изменил структуру пакетов. В зависимости от задачи могут понадобиться отдельные компоненты:

• max[serve] — запуск сервера вывода;
• max[benchmark] — сценарии измерений;
• max[all] — полный набор компонентов;
• базовый пакет — для задач, которым не нужны серверные функции.

Описание раздельных пакетов есть на странице пакетов MAX. Отсутствие serve не является ошибкой Metal. Если GPU-тест проходит, а команда запуска сервера не найдена, сначала исправьте состав окружения.

Сначала зафиксируйте версии и пути. Затем пересоздайте среду с одной выбранной схемой. Смешивание uv и pixi само по себе не запрещено, но для воспроизводимой диагностики команда должна однозначно знать, какой менеджер владеет окружением.

Шаг 5. Минимальный GPU-тест важнее запуска большой модели

Не начинайте с Llama, Gemma или другой тяжёлой модели. Сначала запустите минимальный пример из GPU-учебника Mojo. Его цель — проверить обращение Mojo к GPU, а не доказать совместимость MAX serve.

Порядок действий:

1. Активируйте только нужное окружение.
2. Сохраните вывод which mojo и версии.
3. Выполните минимальную GPU-программу.
4. Проверьте, есть ли в логе имя устройства или успешный запуск kernel.
5. Повторите тест после исправления Xcode или Metal Toolchain.
6. Только после успешного результата запускайте MAX.
7. Сохраняйте полный лог компиляции модели, включая первую ошибку, а не только последнюю строку.

Это разделяет две часто смешиваемые ситуации: «Mojo 1.0 Mac не видит Apple GPU» и «конкретный граф MAX не может быть собран».

Опыт диагностики: если ошибка появляется только после перехода от минимального kernel к модели, повторная установка Metal Toolchain обычно не меняет причину. С этого момента полезнее анализировать имя операции, формат весов и целевой backend.

Почему GPU виден, а MAX serve всё равно не стартует

MAX на Apple Silicon поддерживает не весь каталог моделей, доступный на других ускорителях. Актуальный перечень нужно сверять с официальной страницей поддерживаемых моделей MAX, а изменения — с журналом обновлений MAX.

Релиз MAX 26.5 отдельно важен для M1 и M2: в нём поддержку GPU Apple Silicon расширили обратно на M1. Это подтверждено в официальном объявлении MAX 26.5 и Mojo 1.0. Но «поддерживается Apple GPU» не означает «поддерживается каждая архитектура модели».

После успешного GPU-теста проверьте:

• есть ли целевая модель в официальном списке;
• совпадает ли архитектура графа с поддерживаемым backend;
• не используется ли операция, для которой нет ядра Apple Silicon;
• хватает ли unified memory одновременно для весов, runtime и компилятора;
• установлен ли именно max[serve], если вы запускаете сервер;
• не занимает ли память другой процесс.

Ошибки компиляции графа и ошибки нехватки памяти могут выглядеть похоже. Поэтому сохраняйте участок лога с названием операции и первым сообщением о memory allocation. Не делайте вывод «M1 не поддерживается», если сбой связан с неподдерживаемым слоем конкретной модели.

Почему минимальная GPU-программа работает, а MAX serve падает? Потому что эти проверки имеют разный охват. Минимальный пример доказывает доступность Metal и базового kernel. MAX serve дополнительно проверяет модельный граф, набор ядер, формат данных, серверные зависимости и память. Исправление системного toolchain не добавит отсутствующую операцию в модель.

Как выбрать следующий шаг

Для команды полезно передавать не фразу «MAX не работает», а пакет воспроизведения: версию macOS, чип, вывод xcode-select, версию Xcode, версии Mojo и MAX, команду запуска и полный лог первой ошибки. Такой набор позволяет отличить системный дефект от ограничения модели без повторения всей установки.

Что выбрать: чинить Mac, менять модель или переносить среду

Если у вас не проходит минимальный GPU-тест, чините текущую среду по слоям. Начните с официальных требований, затем проверьте путь Xcode и загрузите Metal Toolchain. Пересоздание uv или pixi оправдано только после подтверждения, что проблема находится в пакетах.

Если GPU виден, но не собирается одна модель, сначала смените модель или проверьте её архитектуру. MAX 26.5 расширяет поддержку Apple Silicon, но не превращает Mac в универсальную замену всех платформ. Особенно осторожно оценивайте проекты, где модельный граф содержит нестандартные операции.

Если ошибка зависит от свободной памяти, одновременных процессов или необходимости повторяемого стенда, разумнее перенести тест на удалённый Apple Silicon Mac. В консоли MacHTML можно использовать единый набор команд и логов для проверки среды, а требования к окружению заранее зафиксировать в справочном разделе MacHTML.

Собственный Mac остаётся удобнее, когда вам нужны постоянная локальная разработка, физические интерфейсы или длительная стабильная нагрузка. Удалённый вариант полезнее, когда требуется временный стенд, параллельная проверка чипов или воспроизводимый доступ для нескольких участников без переноса всей конфигурации на рабочие ноутбуки.

После завершения минимального GPU-теста сравните текущую схему с Mac-средой для аренды не по рекламному обещанию, а по журналу воспроизведения. Локальная машина может быть занята, иметь неподходящую версию Xcode и ограниченную unified memory; облачная среда добавляет сетевую задержку, зависит от доступности удалённого подключения и не заменяет Mac с физическим оборудованием. Но для временного MAX serve, проверки совместимости модели и командной диагностики аренда MacHTML даёт более управляемый сценарий: вы передаёте один и тот же лог, повторяете команды на выделенной Apple Silicon-среде и быстрее понимаете, проблема в Metal Toolchain или в самой модели.