TRELLIS 2.0 от Microsoft на Mac без CUDA: как я запустил 3D-нейросеть Microsoft на Apple Silicon

TRELLIS.2 — это свежий image-to-3D генератор от Microsoft Research: одна фотография на входе, готовый меш с физически корректными материалами (PBR) на выходе. Официально он работает только на Linux с видеокартой NVIDIA от 24 ГБ видеопамяти. Я перенёс его на Mac (чипы M1–M4), под графический движок Apple Metal через вычислительный бэкенд MPS (Metal Performance Shaders). Никаких облаков, никакой аренды графических процессоров (GPU) — всё считается локально на ноутбуке.

Дальше — как это устроено внутри и что пришлось сломать, чтобы оно поехало.

Если вы хоть раз пытались запустить свежую ИИ-модель на Mac, вы знаете это чувство. pip install, десять минут компиляции, и в конце — стена из красного текста про CUDA error или nvcc not found.

Причина системная. Почти вся современная инфраструктура машинного обучения исторически выросла вокруг вычислительной платформы NVIDIA CUDA. Под неё пишут кастомные вычислительные ядра, под неё оптимизируют библиотеки, под неё затачивают примеры в каждой второй научной статье. Apple Silicon с его быстрой объединённой памятью существует как будто в параллельной вселенной: «железо» мощное, а софт его в упор не видит.

TRELLIS.2 — образцовый пример. В официальной карточке модели прямым текстом: протестировано только на Linux, нужна видеокарта NVIDIA минимум на 24 ГБ, код проверялся на A100 и H100, для сборки части пакетов требуется CUDA Toolkit. Для владельца MacBook Pro или Mac Studio это приговор: у тебя на столе машина с 24, 48, а то и 128 ГБ объединённой памяти, но запустить на ней топовый 3D-генератор ты не можешь. Ирония в том, что памяти под модель у Mac хватает с запасом — не хватает только совместимого кода.

Хорошая новость: сам TRELLIS.2 выпущен под свободной лицензией MIT, то есть его разрешено модифицировать и использовать в том числе коммерчески. Значит, преграда не юридическая, а чисто инженерная. А инженерные преграды на то и существуют, чтобы их ломать.

Это большая 3D-генеративная модель Microsoft Research (совместно с Университетом Цинхуа), 4 миллиарда параметров. Её фишка — представление сцены через O-Voxel («омни-воксели»): структуру разреженных вокселей, которая хранит и геометрию, и внешний вид объекта одновременно. В отличие от старых подходов на основе неявных поверхностей (вроде SDF), O-Voxel спокойно переваривает сложную топологию — открытые поверхности, тонкие стенки, внутренние полости.

Дальше эти воксели сжимает SC-VAE (Sparse Compression VAE — разреженный вариационный автокодировщик) с 16-кратным уменьшением разрешения, упаковывая ассет 1024³ примерно в 9,6 тысячи латентных токенов. На этом сжатом пространстве уже работает генеративный трансформер. Результат — текстурированный меш с полным набором PBR-материалов (базовый цвет, металличность, шероховатость, прозрачность) и экспортом в .glb, .obj, .ply.

Если коротко: это не игрушка, а production-ready инструмент. За такое стоит повоевать.

Технический хардкор: как именно я обманул систему

Оригинальный код падал на Mac буквально на каждом шагу. Я не стал переписывать его форком (это путь в ад поддержки) — вместо этого написал проактивный лаунчер setup_mac.sh, который разворачивает изолированное окружение .venv и хирургически правит проблемные места на лету. Вот три ключевых патча.

Патч №1. Эмуляция FlashAttention через нативный SDPA

flash_attn — это библиотека сверхбыстрого механизма внимания, написанная под кастомные ядра CUDA. На macOS она физически не собирается: компилировать нечем и не для чего, там нет CUDA в принципе.

Грубое решение — просто выпилить её — не работает: модель внутри вызывает функции варьируемой длины (Varlen QKV), которые принимают упакованные тензоры «запрос-ключ-значение» переменной длины с массивом смещений cu_seqlens. Это не обычный плотный attention, его так просто не подменишь.

Я внедрил динамический Mock-эмулятор. Он перехватывает вызовы FlashAttention, на лету распаковывает варьируемые последовательности обратно в формат, понятный PyTorch, и перенаправляет вычисления на встроенный механизм SDPA (scaled_dot_product_attention — масштабированное скалярное произведение внимания). А SDPA на Apple Silicon уже умеет уходить на ускорение через Metal Performance Shaders. Снаружи код думает, что вызывает FlashAttention; на деле под капотом считает нативный механизм Apple. Математика та же — бэкенд другой.

Схематично подмена выглядит так (упрощено для читаемости):

Ключевой момент — не потерять семантику cu_seqlens: в varlen-формате несколько последовательностей разной длины лежат одним плоским тензором, и если просто скормить их в SDPA как один батч, внимание «перетечёт» между соседними последовательностями. Поэтому распаковываем по смещениям.

nvdiffrast — это растеризатор NVIDIA, который TRELLIS.2 использует для отрисовки превью сгенерированной модели. На Mac он наглухо блокирует запуск: тоже завязан на CUDA.

Тут важно было не отрезать лишнего. Превью и финальный экспорт меша — это разные стадии: превью нужно только чтобы показать картинку в веб-интерфейсе, а реальная ценность (кнопка Extract GLB) живёт в другом месте пайплайна. Я расцепил эти стадии: вызовы nvdiffrast заблокированы, а генерация snapshot-превью в render_utils.py подменена кастомным гибридным классом-заглушкой MagicDict. В результате веб-интерфейс на Gradio больше не падает на этапе превью, а экспорт финального .glb остаётся полностью рабочим.

Хитрость заглушки в том, что она «магически» отвечает на любой паттерн доступа — атрибут, вызов, индексацию — и возвращает себя же. Код превью получает «как бы валидный» объект, тихо отрабатывает вхолостую и не валит интерфейс. А путь экспорта меша устроен иначе и идёт мимо nvdiffrast — поэтому он остаётся живым.

Приятный побочный эффект — юридический. nvdiffrast распространяется не под MIT, а под лицензией NVIDIA, ограничивающей использование некоммерческими исследованиями. Вырезав его из сборки, я заодно убрал из дистрибутива главный «коммерческий» камень преткновения. Решение получилось чище не только технически, но и по лицензиям.

Самый въедливый баг. На стыке центрального процессора (CPU) и графического чипа (GPU) выскакивал рантайм:

Источник — модуль metal_remeshing.py из библиотеки cumesh. Там скалярный коэффициент (float scale) пытался принудительно вызвать у себя метод .to(coords.device) — ровно так же, как это делают для тензоров координат, чтобы перекинуть их на нужное устройство. Но обычное число с плавающей точкой никакого .to() не имеет: метод переноса между устройствами есть только у тензоров. На NVIDIA-стеке это, видимо, проскакивало незаметно из-за неявных приведений; на границе CPU/MPS — мгновенный вылет.

Лечение — защитные проверки hasattr(…, «to») перед переносом. Скалярные числа остаются на CPU как есть, тензоры аккуратно уезжают на устройство. Тупо, надёжно, работает.

Баг показательный: на стеке NVIDIA подобные шероховатости часто маскируются неявными приведениями типов, и код «случайно работает». Стоит сменить бэкенд на MPS — и каждая такая мелочь всплывает наружу честным исключением. Половина работы порта — это вот такие точечные разводки CPU-скаляров и GPU-тензоров.

Голый скрипт в терминале — это для нас, инженеров. Конечному пользователю нужен двойной клик. Поэтому запуск двухфазный.

Фаза 1, однократно. Пользователь один раз запускает setup_mac.sh: тот разворачивает изолированное окружение .venv (никаких глобальных pip install — на свежей macOS с Python 3.14+ это всё равно заблокировано стандартом PEP 668 с ошибкой externally-managed-environment), накатывает все MPS-патчи, проходит авторизацию на Hugging Face и на финальном шаге сам компилирует AppleScript-обёртку в полноценное приложение TRELLIS 3D.app, кладя иконку в «Документы».

Фаза 2, повседневно. Дальше терминал не нужен вообще. По клику .app открывает Терминал уже сам, выставляет флаг PYTORCH_ENABLE_MPS_FALLBACK=1 (он разрешает «провалить» неподдерживаемые на MPS операции обратно на CPU, чтобы пайплайн не падал), дёргает изолированный интерпретатор из .venv и автоматически открывает вкладку с веб-интерфейсом в браузере ровно в тот момент, когда локальный сервер готов.

Разделение «болезненная установка один раз — лёгкий запуск всегда» — то, что отличает продукт от папки со скриптами.

Я инженер, а не продавец воздуха, поэтому скажу прямо.

Скорость. В официальных бенчмарках TRELLIS.2 выдаёт ~3 секунды на 512³ и ~60 секунд на 1536³ — но это на серверной видеокарте NVIDIA H100 за десятки тысяч долларов. На ноутбучном чипе через MPS, да ещё с откатами части операций на CPU (тот самый PYTORCH_ENABLE_MPS_FALLBACK), будет ощутимо медленнее. Это локальный инференс на ноутбуке, а не дата-центр. Зато — ноль платежей за облако и полная приватность: картинки никуда не уходят.

Память и разрешение. Объединённая память — реальный потолок. На MacBook Pro с 24 ГБ стабильно идёт генерация в разрешении 512 (это базовое разрешение модели, его хватает на аккуратные текстурированные ассеты). Разрешения выше (1024, 1536) требуют больше памяти и на 24 ГБ уже не умещаются. Так что «запустилось» и «запустилось на максималках» — разные вещи; я честно называю 512 рабочим режимом для типичного ноутбука с 24 ГБ.

Это порт, а не магия. Я не ускорил модель и не переобучил её. Я сделал ровно одно: заставил её честно работать на «железе», под которое её не задумывали. Для большинства задач — концепты, ассеты для прототипов, эксперименты — этого более чем достаточно.

Справедливый вопрос, отвечаю честно. Модель бесплатная и лежит в открытом доступе под MIT — это правда, и я её не прячу. Но между «модель бесплатна» и «ты можешь её запустить» лежит как раз тот овраг, который я описал выше: несобираемый flash_attn, падающий nvdiffrast, баги типов на границе устройств, пара зависимостей-моделей за закрытым (gated) доступом, который надо запрашивать заранее и ждать одобрения, и общие танцы с зависимостями и окружением.

Я этот овраг уже перешёл. И собрал из своего опыта коробочную сборку под Mac: двойной клик — и работает. Платите вы не за модель Microsoft, а за сэкономленный вечер (а у кого-то и неделю) возни и за то, что всё уже отлажено. Не хотите платить — весь путь открыт, репозиторий публичный, патчи я описал прямо в этой статье. Это абсолютно нормально.

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

👉 Забрать готовый билд для Mac (Apple Silicon) → готовая сборка TRELLIS 2.0 на Boosty — установка в один клик, без CUDA и без облака.

Если статья зашла — задавайте вопросы по реализации в комментариях, разберу любой из патчей подробнее. И напишите, какие ещё NVIDIA-only модели вы мечтаете увидеть нативно на Mac — следующий порт выберу по вашим заявкам.