Выкананне локальных агентаў для кодавання на Mac з oMLX: Адказа пра кэш KV, базаваны на дыску

Чэрвыце хвілін пасля пачатку сесіі кодавання локальны мадэль перастае паводзіцца як агент і пачынае паводзіцца як факсаварка. Ранейі запыты да інструментаў вярталіся за два секунды. Цяпер кожны наступны крок займае трыдцаць, а іноды дажы дзевяносто секунд. Задача не змянілася. Кантэкст проста стаў дужа дзьвігутым, і локальны сервер кожны раз занова вырахоўвае весь дыялог з нуля з кожным запытам.

Гэты сімптам — медленны пачатак, а не медленная апрацоўка токенав — і ўсё тое, што прагледзела стварыць малая праект на базе Apple Silicon пад назвай oMLX. Гэта не мадэль і не агент. Гэта сервер для вырахоўвання выводаў з адной чыстаю задачай: все, што агент вялікі час тады ўжо прачытаў, застаеецца у кэшы, нават калі сесія стае дзьвігутой, таму дванацаты крок здаецца такім жа, як і першы. Адпаведны тэст — не якісь яскравы дэманстрацыйны прыклад, а тое, як праект паводзіцца на сораковым кроцы рэальнай рабочай сесіі на апаратнай частцы, якая належыць вам.

Чаму Mac-камп’ютары маюць труднасці з агентамі для кодавання

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

Проблемы пачынаюцца, калі чат ператвараецца на работу агента. Кодавальны агент практычна ў кожны момент перачытае большую частку свайго пакананага кантэксту, вызывае інструмент, прыме рэзультат, які дадаецца да запіту, і павтарае гэты працэс дзесяткі разоў. Прылагоджанне, тыя ж самыя першыя словы запіту, практычна збігаецца з пакананым запітам, за выключэннем аднаго новага рэзультата ад інструмента ў канцы.

Большасць местных сервераў спрыймае такую частковую падобнасць як абсолютную несувямленасць, выкарыстоўваець кэш з ключамі-значэннямі і перасчыляе усё значэнне з нуля. Пры короткіх запытках ніхто гэтага не зазначае. Але пад час сесіі з 20 000 токенаў гэта прыводзіць да таго, што адпаведны адпаведзень на запыткі трывае два секунды, а іншыя — дзевяносто секунд. Стваральнік праекту самэльва назваў гэта прычыной сваіх дзеянняў на форуме Apple’s MLX: агенты, якія пішу код, апрашваюць даныя, пры чым ўсі ўсноўкі ў іх запытках зменшваюцца, і кожны існуючы сервер MLX анулюе кэш і перасчыляе усё, калі гэта выканаецца.

Што такое oMLX

oMLX — гэта сервер для выканання задач на адкрытым кодзе, створаны на базе тэхналогій Apple’s MLX і mlx-lm. Ён доступны як аплікацыя для паліцы меню у macOS, так і як інструмент у фармаце Python у команднай лініі. Йго стварыў распрацоўшчык пад іменем Jun Kim, і ён знаходзіцца на GitHub пад назвай jundot/omlx пад ліцэнзай Apache 2.0. На момент напісання статты ён меў абоўшы 18 600 “звёзд”, 1 600 копій і паўторы два тысячы змян.

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

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

Прыфіксы зберагаюцца на дыску, а не ў біні

Звычная аптэкстракцыя 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 прахідзяць заўсёды праз стандартныя ядры, і ў такім случае адпаведныя мадэлі тыхо пераходзяць на значна медленнейшы спосаб работы. У праекце паведамляецца, што ўжо створаныя ядры працуюць прыблізна у 30 разоў быстрэй на працоўніку M3 Ultra. Для стварэння такіх ядэр патрэбны ўсе функцыі Xcode, а не толькі Command Line Tools, і гэта ўжо сама простая прычына для выкарыстоўвання фармата DMG.

Перш чым ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо ўжо падключаць што-небудзь, пераканайцеся, што сервер працуе:

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

Якшае, калі спачатку не было задана ніяка дырэктарыя модэляў.

Завантажэнне першага модэля

oMLX аўтаматычна выклікае мовныя модэлі, модэлі візуя-мовы, модэлі імбеддынгу і прыстроі пераранжавання ў дырэктарыі, на якую ён нацэлёван. Ён таксама безпосерэдньа чытае існуючы кэш Hugging Face і папку LM Studio, таму няма прычыны два разы завантажваць даныя.

omlx serve --model-dir ~/models

Размер модэлі павінен падаць па мемарыях апарата, а не па розмеры большага заўважлівага файла. Залішыце чатыры-пяць гігабайта мемарыяў для macOS, а рэшту выдзеліце на вагі модэлі і рост кэша. Модэлі размерам 9B у фармаце 4-біт падыходзяць для апаратаў з 16 да 32 ГБ мемарыяў. Модэлі класу 30-40B выклікаюць патрэбу ў 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 і не прызначаны для вікорыстоўвання будзь-яга локальнага базовага адрэсу. Таму інтэграцыя 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 яго не пераглядае. Дадзіце завантажаную модэлі пад роздзелам «Custom Models» з яе точным назвам з oMLX, а таксама выключыце стандартныя модэлі Cursor, каб яна таксама не намагалася пераверыць іх на серверах OpenAI.

Перакананне, што все працуе

У часах рэальнай сесіі панелі гарачай і холадной кэш-памяці на панелі адміністрацыі должны продовжваць накапліваць блакі, а не перазначальвацца пасля кожнага крока. Перазначальванне пасля кожнага крока зазвычай означае, што контэнт сістэмных запросаў або схемы інструментаў пераранжуецца між вызывамі, што наражае на пагубы працэс апрацоўкі дадзеных.

Аналіз гарачай і холадной кэш-памяці

У змену таму, што проста перакладаць тверджэння праўодавца як факт, можна адразу адрабатваць тэст на сваёй апаратурэ. Выправіце мадэль, параметры квантызацыі, дужыну кантэксту і фармат запросаў у всіх інструментах, а пасля — зазначыце час запуску без поперадней падготовкі, час до першага токена ў рэжыме холадной кэш-памяці, час до першага токена ў рэжыме гарачай кэш-памяці праз паўтарэнне таго ж прафіля, стабільную шыроцу генеравання, максымальную колькасць памяці, прыменшэнне працэсу пасля 15–20 сімуляваных крокаў агента, час на налагоджэнне, а таксама чы правільна інструменты продовжваюць парсаваць даныя працэса ўсю час сесіі.

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

У аднам незалежным аналізе паведамляецца, што для кантэксту з 8 700 токеноў знадобілася прыблізна 20 секунд на звычным 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