Запуск локальных агентов кодирования на Mac с oMLX: объяснение кэша KV с хранением на диске

Через двенадцать минут работы сессии программирования локальная модель перестаёт вести себя как агент и начинает вести себя как факс-аппарат. Ранее запросы к инструментам возвращались за две секунды. Теперь каждый этап обработки занимает тридцать, а иногда и девяносто секунд. Задача не изменилась — просто контекст стал длиннее, и локальный сервер с каждым запросом заново вычисляет всю конверсацию с нуля.

Именно эту проблему — медленный старт, а не медленная обработка токенов — было предусмотрено устранить в небольшом проекте на базе Apple Silicon под названием oMLX. Это не модель и не агент; это сервер инференса с одним чётким обещанием: всё, что агент уже прочитал, остаётся в кэше, даже по мере увеличения длины сессии, так что двенадцатый этап кажется таким же, как и первый. Настоящий тест — это не красивая демонстрация, а то, как программа справляется с сороковым этапом реальной рабочей сессии на оборудовании, которое у вас действительно есть.

Почему Mac имеют трудности с агентами для программирования

На бумаге Apple Silicon представляет собой мощную платформу для локальной обработки данных. Единая память обеспечивает CPU и GPU общий ресурс, поэтому квантизированная модель хранится в RAM без необходимости использования шины передачи данных, а фреймворк MLX от Apple разработан именно для таких задач.

Проблемы начинаются, когда чат превращается в работу агента. Агент-программист практически при каждом шаге перечитывает большую часть своего предыдущего контекста, вызывает инструмент, получает результат, добавляемый к запросу, и повторяет этот процесс десятки раз. Префикс, то есть общая часть запроса, почти полностью совпадает с предыдущим запросом, за исключением одного нового результата от инструмента в конце.

Большинство локальных серверов воспринимают такое косвенное совпадение как полное несоответствие, удаляют кэш в формате «ключ-значение» и пересчитывают данные заново, начиная с нуля. При коротких запросах этого никто не замечает. Однако в сессии длиной 20 000 токенов это приводит к тому, что ответ длительностью две секунды отличается от ответа длительностью девяносто секунд. Создатель проекта именно это и назвал причиной своего решения на форуме обсуждений Apple MLX: агенты-программы отправляют запросы с меняющимися префиксами, и каждый существующий сервер MLX аннулирует кэш и пересчитывает всё заново при таких ситуациях.

Что такое oMLX

oMLX — это сервер инференса с открытым исходным кодом, построенный на технологиях Apple MLX и mlx-lm. Он поставляется как нативное приложение для панели меню macOS, а также как инструмент командной строки на Python. Его создал разработчик по имени Jun Kim; проект хранится на GitHub под названием jundot/omlx под лицензией Apache 2.0. На момент написания статьи у него было около 18 600 звёзд, 1 600 копий и более двух тысяч коммитов.

Ничто из этого не доказывает надежности. Звезды отражают уровень внимания, а не зрелость, а проект, выпускающий несколько кандидатов на релиз в месяц, все еще находится в стадии становления. Популярность — это повод для тестирования, но не замена ему.

Один процесс обслуживает два стиля API: чат-функции, совместимые с OpenAI, и нативный маршрут Anthropic вида /v1/messages вместе с функциями завершения запросов, генерации эмбеддингов и переранжирования. Он позволяет одновременно использовать языковые модели, модели визуального понимания языка, модели OCR и инструменты переранжирования, применяя механизмы удаления по принципу LRU и фиксации моделей. Для агентов важно то, что происходит за этой поверхностью.

Префиксы сохраняются на диске, а не в буфере

В обычном режиме инференса MLX хранит кэш разговора только в памяти GPU до тех пор, пока совпадение префикса сохраняется. Основная идея oMLX — двухуровневый кэш, способный выдерживать как смещение префиксов, так и перезапуск системы. Часто используемые блоки остаются в быстродоступном уровне памяти. Когда он заполняется, блоки записываются на медленный уровень в SSD в формате safetensors; управление происходит по отдельным блокам с использованием механизмов общего использования префиксов и копирования при записи. Если последующий запрос совпадает с префиксом, который был сохранен на диске, эти блоки считываются обратно, а не пересчитываются.

Хорошей аналогией может служить библиотекарь, который никогда не перемещает книгу, которую вы недавно взяли в аренду. Если спросить о ней снова позже, даже после возобновления работы библиотеки, книга уже будет на стойке.

SSD — это не RAM, поэтому восстановление большого кэша всё равно занимает реальное время, хотя это гораздо дешевле, чем пересчёт каждого токена. Наибольшая польза от этого видна при использовании описанного ранее паттерна агента: длинных, в основном повторяющихся префиксов с небольшим изменением в конце. Сервер также осуществляет непрерывную группировку запросов с помощью BatchGenerator из mlx-lm, обрабатывая их одновременно вместо того, чтобы ставить в очередь; уровень группировки можно настроить из командной строки или панели администрирования.

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

Установка на Apple Silicon

Требования: macOS 15 (Sequoia) или новее, Python версии от 3.11 до 3.13, а также чип из семейств M1, M2, M3 или M4. Существует три способа, причем первый подходит большинству пользователей.

Рекомендуемый способ — использование приложения для macOS. Скачайте подписанный и нотариально заверенный файл .dmg с страницы GitHub Releases, перетащите его в папку Applications и запустите. На экране приветствия будет показано, как выбрать каталог модели, запустится сервер и произойдет первое загрузчение; приложение также установит небольшой инструмент командной строки.

С помощью Homebrew:

brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx
omlx start

Из исходного текста:

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e .            # core
pip install -e ".[mcp]"     # optional MCP support

Те, кто планирует использовать GLM-5.2, MiniMax M3 или Qwen3.5, должны знать, что простая команда pip install игнорирует их собственные пользовательские ядра, в результате чего соответствующие модели автоматически используют гораздо более медленный способ работы. В отчетах проекта говорится, что его объединенное ядро prefill на устройстве M3 Ultra делает работу моделей примерно в 30 раз быстрее. Для сборки таких ядер требуется полная версия Xcode, а не только инструменты командной строки, что является главным аргументом в пользу использования формата DMG.

Перед подключением чего-либо убедитесь, что сервер работает:

curl -s http://localhost:8000/v1/models

Пустой список подходит, если папка с моделями ещё не указана.

Загрузка первой модели

oMLX автоматически находит языковые модели, модели визуального понимания языка, модели эмбеддингов и инструменты для переранжирования в указанной папке. Он также напрямую читает существующую кэш-папку Hugging Face и папку LM Studio, поэтому ничего не нужно загружать дважды.

omlx serve --model-dir ~/models

Размер модели должен соответствовать объему памяти устройства, а не размеру самого большого доступного файла. Оставьте четыре-пять гигабайт свободной памяти для macOS, а остальное выделите на веса модели и рост кэша. Модель размером 9 миллиардов параметров в формате 4 бита подходит для устройств с 16–32 ГБ памяти. Модели класса 30–40 миллиардов параметров требуют 64 ГБ и более. Самые крупные модели, протестированные в собственных тестах проекта, нуждаются в памяти Mac Studio объемом свыше 400 ГБ.

Модели можно загрузить с браузера Hugging Face, встроенного в панель управления, по адресу http://localhost:8000/admin, или с помощью любой существующей процедуры загрузки из библиотеки hf, направленной на каталог моделей. Простой запрос выглядит как обычное завершение чата в OpenAI:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "your-model-name", "messages": [{"role": "user", "content": "Say hi in five words."}]}'

Если возвращается результат завершения, значит, конечная точка работает.

Подключение Claude Code, Codex, Cursor и OpenCode

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

Инструменты с файлом конфигурации

OpenClaw, OpenCode, Codex и Pi читают файл конфигурации, к которому oMLX может получить прямой доступ: для первых двух — в формате JSON, а для Codex — в формате TOML. Адаптеры интеграции записывают данные в этот файл, а вкладка «Интеграции» на панели управления администратора передаёт одну команду:

omlx-cli launch codex --model your-model-name --api-key your-key
omlx-cli launch opencode --model your-model-name --api-key your-key
omlx-cli launch pi --model your-model-name --api-key your-key

При запуске происходит обновление конфигурации инструмента и одновременный запуск агента. Любая существующая конфигурация сначала резервируется в виде файла с расширением .bak и временной меткой, чтобы в случае проблем было возможно откатить изменения.

Hermes Agent и пункт Copilot

Оба указаны в списке для однокликового запуска в README, причем собственная документация Hermes Agent отдельно подтверждает его использование: мастер настройки предоставляет опцию настройки собственного конечного точка, совместимого с OpenAI, для указания любого локального сервера, включая oMLX. Чтобы пропустить панель управления, вручную укажите адрес http://localhost:8000/v1.

Прежде чем полагаться на Copilot, стоит внимательно его рассмотреть. Настоящий Copilot Chat от GitHub аутентифицируется с помощью OAuth по адресу api.githubcopilot.com и не предназначен для работы с произвольным локальным базовым URL. Поэтому однокликовая интеграция Copilot либо предназначена для другого инструмента с таким же названием, либо использует механизм, который не подтверждается в официальной документации. Обязательно проверьте вкладку «Интеграции», прежде чем считать, что он выполняет то, что указано в названии.

Claude Code

При запуске Claude Code берет свой серверный адрес из переменной окружения ANTHROPIC_BASE_URL, а не из файла, который может редактироваться oMLX, поэтому настройка остается ручной. Поскольку oMLX обслуживает встроенный маршрут /v1/messages, прокси для перевода не требуется:

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_AUTH_TOKEN="local"
export ANTHROPIC_DEFAULT_SONNET_MODEL="your-model-name"
export ANTHROPIC_DEFAULT_OPUS_MODEL="your-model-name"
claude

oMLX также включает функции, предназначенные специально для Claude Code. Отчёты о масштабировании контекста показывают количество токенов, что позволяет функции автоматического сжатия корректно работать при меньшем размере локального окна контекста, а механизм SSE keep-alive предотвращает прерывания при длительной загрузке предварительных данных. Это реальные детали, связанные непосредственно с агентом, а не общий флаг совместимости.

Курсор

Настройки локальной модели в Cursor находятся в его графическом интерфейсе, поэтому для записи данных в формате oMLX файл не существует. В разделе «Настройки» → «Модели» найдите раздел OpenAI API и включите переключатель «Override Base URL». Ранее Cursor менял название этого переключателя, поэтому его метка может отличаться в зависимости от версии. Введите http://localhost:8000/v1, а в поле API key укажите любую ненулевую строку, поскольку сервер на localhost её не проверяет. Добавьте загруженную модель в раздел «Собственные модели» под её точным именем из oMLX, а также отключите стандартные модели Cursor, чтобы он не пытался их верифицировать на серверах OpenAI.

Проверка корректной работы

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

Оценка горячей и холодной кэши

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

Согласно официально опубликованным данным проекта, полученным на устройстве M3 Ultra с объемом памяти 512 ГБ, скорость генерации составляет примерно от 45 до 59 токенов в секунду для модели Qwen3-Coder-Next с 8 битами при длине контекста от 1 к до 32 к токенов. При одновременной обработке восьми запросов скорость генерации увеличивается примерно в 4,14 раза по сравнению с одним запросом. Это верхняя граница для высокопроизводительного оборудования, и это не то, что можно ожидать от MacBook Air с 16 ГБ памяти.

В одном независимом отчете говорится, что обработка контекста объемом 8 700 токенов с использованием стандартного MLX заняла примерно двадцать секунд, в то время как ответ из кэша был получен настолько быстро, что автор повторил тест, чтобы убедиться. Это отчет от третьей стороны, а не контролируемое тестирование, поэтому перед тем, как верить этим данным, их стоит повторить.

Время запуска до первого токена практически не отличается от времени работы с необработанным MLX, поскольку пока нет ничего, что можно было бы повторно использовать. Вся польза заключается в работе с уже знакомыми префиксами во время многократных запросов, которые составляют большую часть сессии кодингового агента.

Управление сервером

Запуск, остановка и перезапуск с использованием варианта в фоновом режиме, подключенного к терминалу:

omlx start          # background service, auto-restarts on crash
omlx stop
omlx restart
omlx serve --model-dir ~/models   # foreground, attached to this terminal

Подтвердите, что он запущен и обслуживает модель:

curl -s http://localhost:8000/v1/models

Не допускайте конфликтов между использованием памяти и остальной частью системы:

omlx serve --model-dir ~/models --memory-guard safe
omlx serve --model-dir ~/models --memory-guard-gb 48

Настраивайте двухуровневую кэш-память напрямую:

omlx serve --model-dir ~/models --paged-ssd-cache-dir ~/.omlx/cache
omlx serve --model-dir ~/models --hot-cache-max-size 20%

Повысьте конкурентоспособность, когда несколько агентов одновременно обращаются к серверу:

omlx serve --model-dir ~/models --max-concurrent-requests 16

Установки через Homebrew проходят тот же жизненный цикл с помощью brew services:

brew services start omlx
brew services stop omlx
brew services info omlx