Запуск локальних агентів кодування на 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, а не лише Command Line Tools, що є найпростішим аргументом на користь використання формату 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 для перших двох та TOML для Codex. Адаптери інтеграції записують дані у цей файл, а вкладка Integrations у панелі керування адміністратора передає одну команду:

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

Pід час запуску 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 його не перевіряє. Додайте завантажену модель у розділ «Custom Models» під її точною назвою з 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