jundot/omlx

당신의 Mac에 최적화된 LLM 추론 (inference)

메뉴 바에서 직접 관리하는 연속 배치 (Continuous batching) 및 계층형 KV 캐싱 (tiered KV caching).

junkim.dot@gmail.com · https://omlx.ai/me

설치 · 빠른 시작 · 기능 · 모델 · CLI 설정 · 벤치마크 · oMLX.ai

내가 시도해 본 모든 LLM 서버는 편의성과 제어권 사이에서 하나를 선택하게 만들었습니다. 나는 일상적인 모델들을 메모리에 고정하고, 더 무거운 모델들은 필요에 따라 자동으로 스왑(swap)하며, 컨텍스트 제한(context limits)을 설정하고, 이 모든 것을 메뉴 바에서 관리하고 싶었습니다.

oMLX는 핫 인메모리 계층 (hot in-memory tier)과 콜드 SSD 계층 (cold SSD tier)에 걸쳐 KV 캐시 (KV cache)를 유지합니다. 대화 중간에 컨텍스트가 변경되더라도 이전의 모든 컨텍스트가 캐시되어 요청 간에 재사용될 수 있으므로, Claude Code와 같은 도구를 사용하는 실제 코딩 작업에서 로컬 LLM을 실용적으로 사용할 수 있게 해줍니다. 이것이 제가 이를 만든 이유입니다.

.dmg 다운로드

Releases에서 다운로드하여 Applications 폴더로 드래그하면 끝입니다. 앱에는 앱 내 자동 업데이트 기능이 포함되어 있어 향후 업그레이드는 클릭 한 번으로 가능합니다. macOS 앱은 omlx CLI 명령어를 설치하지 않는다는 점에 유의하세요. 터미널 사용을 위해서는 Homebrew 또는 소스(source)를 통해 설치하십시오.

brew tap jundot/omlx https://github.com/jundot/omlx
brew install omlx
# 최신 버전으로 업그레이드
...

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e . # Core 전용
...

macOS 15.0+ (Sequoia), Python 3.10+, 그리고 Apple Silicon (M1/M2/M3/M4)이 필요합니다.

Applications 폴더에서 oMLX를 실행하십시오. Welcome 화면에서 모델 디렉토리, 서버 시작, 첫 번째 모델 다운로드의 세 단계를 안내합니다. 그게 전부입니다. OpenClaw, OpenCode, Codex 또는 Copilot에 연결하려면 Integrations를 참조하십시오.

omlx serve --model-dir ~/models

서버는 하위 디렉토리에서 LLM, VLM, 임베딩 모델 (embedding models), 그리고 리랭커 (rerankers)를 자동으로 탐색합니다. 어떤 OpenAI 호환 클라이언트도 http://localhost:8000/v1에 연결할 수 있습니다. 내장된 채팅 UI는 http://localhost:8000/admin/chat에서도 사용할 수 있습니다.

Homebrew를 통해 설치했다면, oMLX를 관리형 백그라운드 서비스 (managed background service)로 실행할 수 있습니다:

brew services start omlx # 시작 (충돌 시 자동 재시작)
brew services stop omlx # 중지
brew services restart omlx # 재시작
...

해당 서비스는 별도의 설정이 필요 없는 기본값(~/.omlx/models, 포트 8000)으로 omlx serve를 실행합니다. 설정을 사용자 정의하려면 환경 변수(OMLX_MODEL_DIR, OMLX_PORT 등)를 설정하거나, omlx serve --model-dir /your/path를 한 번 실행하여 ~/.omlx/settings.json에 설정을 저장하십시오.

로그는 다음 두 위치에 기록됩니다:

서비스 로그 (Service log): $(brew --prefix)/var/log/omlx.log (stdout/stderr)
서버 로그 (Server log): ~/.omlx/logs/server.log (구조화된 애플리케이션 로그)

Apple Silicon에서 텍스트 LLM, 시각-언어 모델 (VLM), OCR 모델, 임베딩 (embeddings), 그리고 리랭커 (rerankers)를 지원합니다.

/admin에서 제공되는 웹 UI를 통해 실시간 모니터링, 모델 관리, 채팅, 벤치마크 (benchmark), 그리고 모델별 설정을 수행할 수 있습니다. 영어, 한국어, 일본어, 중국어, 프랑스어, 러시아어를 지원합니다. 모든 CDN 의존성은 완전히 오프라인으로 작동할 수 있도록 벤더링 (vendored)되었습니다.

텍스트 LLM과 동일한 연속 배치 (continuous batching) 및 계층형 KV 캐시 (tiered KV cache) 스택을 사용하여 VLM을 실행합니다. 멀티 이미지 채팅, base64/URL/파일 이미지 입력, 그리고 시각적 컨텍스트를 활용한 도구 호출 (tool calling)을 지원합니다. OCR 모델 (DeepSeek-OCR, DOTS-OCR, GLM-OCR)은 최적화된 프롬프트와 함께 자동으로 감지됩니다.

vLLM에서 영감을 받은 블록 기반 KV 캐시 관리 방식을 사용하며, 접두사 공유 (prefix sharing) 및 쓰기 시 복사 (Copy-on-Write)를 지원합니다. 캐시는 다음 두 계층에 걸쳐 작동합니다:

핫 티어 (Hot tier, RAM): 자주 액세스하는 블록은 빠른 액세스를 위해 메모리에 유지됩니다.
콜드 티어 (Cold tier, SSD): 핫 캐시가 가득 차면 블록은 safetensors 형식으로 SSD에 오프로드 (offloaded)됩니다. 일치하는 접두사가 있는 다음 요청 시, 서버 재시작 후에도 처음부터 다시 계산하는 대신 디스크에서 복구됩니다.

mlx-lm의 BatchGenerator를 통해 동시 요청을 처리합니다. 최대 동시 요청 수는 CLI 또는 관리 패널을 통해 구성할 수 있습니다.

Claude Code와 함께 더 작은 컨텍스트 모델을 실행하기 위한 컨텍스트 스케일링 (Context scaling) 지원을 제공합니다. 보고된 토큰 수를 스케일링하여 자동 압축 (auto-compact)이 적절한 타이밍에 트리거되도록 하며, SSE keep-alive를 통해 긴 프리필 (prefill) 과정 중 읽기 타임아웃을 방지합니다.

동일한 서버 내에서 LLM, VLM, 임베딩 모델 (embedding models), 그리고 리랭커 (rerankers)를 로드합니다. 모델은 자동 제어와 수동 제어의 조합을 통해 관리됩니다:

LRU eviction: 메모리가 부족해지면 가장 최근에 사용되지 않은 (Least-recently-used) 모델이 자동으로 제거됩니다.
수동 로드/언로드 (Manual load/unload): 관리 패널의 대화형 상태 배지를 통해 필요에 따라 모델을 로드하거나 언로드할 수 있습니다.
모델 고정 (Model pinning): 자주 사용하는 모델을 고정하여 항상 로드된 상태를 유지합니다.
모델별 TTL (Per-model TTL): 모델별로 유휴 타임아웃 (idle timeout)을 설정하여 일정 기간 활동이 없으면 자동으로 언로드합니다.
프로세스 메모리 강제 적용 (Process memory enforcement): 전체 메모리 제한 (기본값: 시스템 RAM - 8GB)을 통해 시스템 전체의 OOM (Out-of-Memory)을 방지합니다.

관리 패널에서 모델별로 샘플링 파라미터 (sampling parameters), 채팅 템플릿 kwargs, TTL, 모델 별칭 (model alias), 모델 유형 재정의 (model type override) 등을 직접 구성할 수 있습니다. 변경 사항은 서버 재시작 없이 즉시 적용됩니다.

모델 별칭 (Model alias): API에 노출될 사용자 정의 이름을 설정합니다. /v1/models는 별칭을 반환하며, 요청 시 별칭과 디렉토리 이름을 모두 사용할 수 있습니다.
모델 유형 재정의 (Model type override): 자동 감지 결과와 상관없이 모델을 LLM 또는 VLM으로 수동 설정합니다.

관리 패널에서 로드된 모든 모델과 직접 채팅할 수 있습니다. 대화 기록 (conversation history), 모델 전환, 다크 모드, 추론 모델 (reasoning model) 출력, 그리고 VLM/OCR 모델을 위한 이미지 업로드를 지원합니다.

관리 대시보드에서 HuggingFace의 MLX 모델을 직접 검색하고 다운로드할 수 있습니다. 모델 카드 (model cards)를 살펴보고, 파일 크기를 확인하며, 클릭 한 번으로 다운로드하세요.

관리 대시보드에서 클릭 한 번으로 OpenClaw, OpenCode, Codex, Copilot, Pi를 설정할 수 있습니다. 수동으로 설정 파일을 편집할 필요가 없습니다.

관리 패널에서 클릭 한 번으로 벤치마킹을 수행합니다. 실제 성능 수치를 위해 부분적 접두사 캐시 히트 (partial prefix cache hit) 테스트를 포함하여, 초당 프리필 (prefill, PP) 및 텍스트 생성 (text generation, TG) 토큰 수를 측정합니다.

네이티브 PyObjC 메뉴바 앱 (Electron 아님)을 제공합니다. 터미널을 열지 않고도 서버를 시작, 중지 및 모니터링할 수 있습니다. 지속적인 서빙 통계 (재시작 후에도 유지), 충돌 시 자동 재시작, 앱 내 자동 업데이트 기능을 포함합니다.

OpenAI 및 Anthropic API를 즉시 대체할 수 있는 솔루션입니다. 스트리밍 사용 통계 (stream_options.include_usage), Anthropic adaptive thinking, 그리고 비전 입력 (base64, URL)을 지원합니다.

엔드포인트 (Endpoint)	설명
POST /v1/chat/completions	채팅 완성 (Chat completions, 스트리밍)
POST /v1/completions	텍스트 완성 (Text completions, 스트리밍)
POST /v1/messages	Anthropic Messages API
POST /v1/embeddings	텍스트 임베딩 (Text embeddings)
POST /v1/rerank	문서 재순위화 (Document reranking)
GET /v1/models	사용 가능한 모델 목록

mlx-lm에서 사용 가능한 모든 함수 호출 (function calling) 형식을 지원하며, JSON 스키마 검증 (JSON schema validation) 및 MCP 도구 통합 (MCP tool integration)을 지원합니다. 도구 호출 (Tool calling)을 위해서는 모델의 채팅 템플릿 (chat template)이 tools 파라미터를 지원해야 합니다. 다음 모델 제품군 (model families)은 mlx-lm의 내장 도구 파서 (tool parsers)를 통해 자동으로 감지됩니다:

모델 제품군 (Model Family)	형식 (Format)
Llama, Qwen, DeepSeek 등	JSON <tool_call>
...

위에 나열되지 않은 모델이라도 채팅 템플릿이 tools를 수용하고 출력이 인식 가능한 <tool_call> XML 형식을 사용한다면 여전히 작동할 수 있습니다. 도구가 활성화된 스트리밍 (tool-enabled streaming)의 경우, 알려진 도구 호출 제어 마크업 (tool-call control markup)은 가시적인 콘텐츠에서 억제되는 동안 어시스턴트 텍스트가 점진적으로 방출됩니다. 구조화된 도구 호출은 완료된 턴 (turn)을 파싱한 후에 방출됩니다.

--model-dir 포인터를 MLX 형식의 모델 하위 디렉토리를 포함하는 디렉토리로 지정하십시오. 2단계 계층 구조 폴더 (예: mlx-community/model-name/)도 지원됩니다.

~/models/
├── Step-3.5-Flash-8bit/
├── Qwen3-Coder-Next-8bit/
...

모델은 유형별로 자동 감지됩니다. 관리자 대시보드 (admin dashboard)에서 모델을 직접 다운로드할 수도 있습니다.

유형 (Type)	모델 (Models)
LLM	mlx-lm에서 지원하는 모든 모델
...

# 로드된 모델에 대한 메모리 제한
omlx serve --model-dir ~/models --max-model-memory 32GB
# 프로세스 수준 메모리 제한 (기본값: auto = RAM - 8GB)
...

모든 설정은 /admin에 있는 웹 관리자 패널 (web admin panel)에서도 구성할 수 있습니다. 설정은 ~/.omlx/settings.json에 저장되며, CLI 플래그 (CLI flags)가 우선권을 갖습니다.

아키텍처 (Architecture)

FastAPI Server (OpenAI / Anthropic API)
│
├── EnginePool (multi-model, LRU eviction, TTL, manual load/unload)
...

git clone https://github.com/jundot/omlx.git
cd omlx
pip install -e ".[dev]"
...

Python 3.11+ 및 venvstacks (pip install venvstacks)가 필요합니다.

cd packaging
# Full build (venvstacks + app bundle + DMG)
python build.py
...

앱 번들 (app bundle) 구조 및 레이어 설정에 대한 자세한 내용은 packaging/README.md를 참조하세요.

기여(Contributions)를 환영합니다! 자세한 내용은 기여 가이드 (Contributing Guide)를 참조하세요.

• 버그 수정 및 개선

• 성능 최적화

• 문서 개선

• MLX 및 mlx-lm (Apple 제작)

• mlx-vlm - Apple Silicon에서의 시각-언어 모델 (Vision-language model) 추론

• vllm-mlx - oMLX는 vllm-mlx v0.1.0에서 시작되었으며, 멀티 모델 서빙 (multi-model serving), 계층형 KV 캐싱 (tiered KV caching), 전체 페이지 캐시 (paged cache)를 지원하는 VLM, 관리자 패널, 그리고 macOS 메뉴 바 앱과 함께 크게 발전했습니다.

• venvstacks - macOS 앱 번들을 위한 휴대 가능한 Python 환경 레이어링 (layering)

• mlx-embeddings - Apple Silicon을 위한 임베딩 모델 (Embedding model) 지원

• dflash-mlx - Apple Silicon에서의 블록 확산 투기적 디코딩 (Block diffusion speculative decoding)