개요

로컬 LLM 서버를 써본 사람이라면 대부분 같은 불만에 맞닥뜨린다. 편하거나 제어하거나, 둘 중 하나만 된다. oMLX는 이 선택지를 거부한다. Apple Silicon Mac에 최적화된 추론 서버로, RAM과 SSD를 2계층 KV 캐시로 쓰고, 연속 배칭으로 동시 요청을 처리하고, macOS 메뉴바 앱으로 전부 제어한다. GitHub 스타 1.4만, 릴리스 71개. 실사용 기반이 탄탄하다. Llama, Qwen, Mistral, Gemma 계열 등 mlx-lm이 지원하는 모델이라면 대부분 올릴 수 있다.

핵심 요약

  • 계층형 KV 캐시: RAM(핫 블록) + SSD(콜드 블록) 2계층 구조. 서버 재시작 후에도 캐시가 살아남아 재계산 없이 재사용 가능
  • 연속 배칭: mlx-lm의 BatchGenerator로 동시 요청 처리. 최대 동시 요청 수를 직접 설정
  • 멀티모델 서빙: 텍스트 LLM·VLM·임베딩·리랭커를 동시에 올린다. LRU 퇴거, 핀고정, 아이들 타임아웃 지원
  • OpenAI·Anthropic API 호환: Claude Code 등 기존 도구의 엔드포인트를 그대로 oMLX로 교체 가능
  • 어드민 대시보드: 실시간 모니터링, 통합 채팅, 성능 벤치마크를 웹 UI로 제공

계층형 KV 캐시: 왜 SSD까지 쓰나

문제: 컨텍스트가 사라진다

코딩 작업에서 LLM 서버를 쓸 때 가장 아픈 지점은 컨텍스트 손실이다. 대화를 바꾸거나 서버를 재시작하면 이전에 처리한 프롬프트를 처음부터 다시 계산한다. 긴 코드베이스를 반복 참조하는 Claude Code 같은 도구에서 이 비용은 크다.

oMLX의 답: 2계층 캐시

oMLX는 KV 캐시를 두 층으로 나눈다.

  • GPU 기반 핫 캐시: 자주 쓰는 블록. 페이지드 캐시 관리, 블록 단위 Copy-on-Write, 프리픽스 공유를 지원한다
  • SSD 콜드 스토리지: 덜 쓰는 블록을 safetensors 포맷으로 SSD에 내린다. 서버를 껐다 켜도 캐시가 남는다

이 캐시는 대화 전환과 서버 재시작을 가로질러 살아남는다. 같은 코드베이스를 다음 날 다시 참조해도 재계산 없이 바로 불러온다. RAM이 부족해도 SSD로 블록을 내리면서 전체 캐시 용량은 디스크 크기에 가까워진다. 맥에 SSD가 넉넉하다면 실질적으로 대용량 KV 캐시를 운영할 수 있다.

연속 배칭과 멀티모델 서빙

연속 배칭

mlx-lm의 BatchGenerator를 기반으로 동시 요청을 처리한다. 최대 동시 요청 수는 설정에서 조정한다. 단일 요청을 순서대로 처리하던 방식과 달리, 배치 안에서 새 요청이 들어오는 대로 계속 합류시켜 GPU 활용률을 높인다. Apple Silicon의 통합 메모리 구조 덕분에 GPU와 CPU가 같은 메모리 풀을 공유한다. 배치 전송 오버헤드가 낮아 연속 배칭의 효과가 일반 dGPU보다 더 일관되게 나온다.

멀티모델 서빙

텍스트 LLM, 비전-언어 모델(VLM), 임베딩 모델, 리랭커를 동시에 올린다. 모델 관리 정책은 이렇다.

  • LRU 퇴거: 오래 쓰지 않은 모델부터 내린다
  • 핀고정: 자주 쓰는 모델은 퇴거 대상에서 뺀다
  • 아이들 타임아웃: 일정 시간 요청이 없으면 자동 언로드
  • 프로세스 메모리 한도: 기본값은 시스템 RAM에서 8GB를 뺀 값. 시스템 전체 메모리 부족을 막는다

VLM도 텍스트 모델과 같은 연속 배칭·캐시 스택을 쓴다. 멀티 이미지 채팅, 다양한 이미지 입력 포맷, 비전 어웨어 툴 콜링을 지원한다. DeepSeek-OCR, DOTS-OCR, GLM-OCR 같은 OCR 특화 모델은 자동 감지 후 최적화된 프롬프트를 적용한다. 어드민 대시보드는 6개 언어를 지원하며, CDN 의존성을 내장해 완전 오프라인 환경에서도 동작한다.

API 호환성과 설치

OpenAI·Anthropic API 드롭인 교체

oMLX는 OpenAI API와 Anthropic Messages API를 모두 구현한다. 지원 엔드포인트는 채팅 컴플리션, 텍스트 컴플리션, 임베딩, 문서 리랭킹이며 스트리밍과 사용량 통계도 제공한다. Claude Code나 Continue 같은 도구의 엔드포인트 URL만 바꾸면 로컬 모델로 붙는다.

설치 방법

  • macOS 앱: Releases에서 다운로드. 자동 업데이트 내장
  • Homebrew: brew install omlx. 백그라운드 서비스 지원
  • 소스 설치: git clone 후 pip install. MCP(Model Context Protocol) 지원 옵션 포함

요구 사항은 macOS 15.0+(Sequoia), Python 3.10+, Apple Silicon이다. MCP 지원을 켜면 Claude Desktop이나 다른 MCP 클라이언트에서 oMLX가 서빙하는 로컬 모델에 바로 붙는다. 성능 벤치마크는 어드민 대시보드에서 원클릭으로 돌린다. 프리픽스 캐시 히트를 포함한 현실적인 성능 수치를 prefill 속도와 생성 토큰/초로 보여준다.

실무자가 볼 핵심 포인트

  1. SSD KV 캐시가 핵심 차별점이다 — 서버 재시작 후에도 캐시가 살아있다는 건 코딩 워크플로우에서 실질적인 시간 절약이다. 특히 동일한 코드베이스를 반복 참조하는 에이전트 도구와 궁합이 좋다
  2. Claude Code 연동에 바로 쓴다 — Anthropic API 호환이라 엔드포인트만 교체하면 된다. 비용 없이 로컬 모델로 Claude Code를 돌리는 가장 빠른 경로다
  3. 멀티모델 서빙이 RAM 관리를 대신 해준다 — LRU·핀고정·아이들 타임아웃 조합이면 8GB Mac에서도 여러 모델을 교대로 쓴다. 수동으로 모델을 껐다 켜는 번거로움이 없어진다
  4. 메뉴바 앱 + 어드민 대시보드 — 설정 파일을 건드리지 않아도 UI에서 모델 로드·언로드, 벤치마크 실행, 실시간 모니터링이 된다. 개발자가 아닌 사용자도 쓴다
  5. Apache 2.0 오픈소스 — 14,200 스타, 71개 릴리스. 빠른 업데이트 주기와 이슈 대응 속도가 실사용 기반을 보여준다

원문 출처

원문: oMLX — GitHub jundot/omlx