빠른 시작¶

이 가이드는 Homebrew로 mlxcel을 설치하고 모델을 실행한 뒤, 서버를 시작하고 REST API로 요청을 보내는 흐름을 안내합니다. 예제는 repo-id를 이해하는 새 모델 resolver를 사용하므로 명시적인 다운로드 단계가 필수는 아닙니다. mlxcel은 HuggingFace MLX 체크포인트를 첫 사용 시 자동으로 다운로드하고 이후에는 어느 작업 디렉터리에서나 재사용합니다.

사전 요구사항¶

진행하기 전에 다음 사항을 확인하십시오.

Apple Silicon Mac에 Homebrew가 설치되어 있습니다. tap은 macOS Apple Silicon 빌드만 배포합니다. Linux에서는 GitHub 릴리스 페이지의 mlxcel-linux-*-cuda13 아카이브를 사용하거나 소스에서 빌드하십시오.
mlxcel 및 mlxcel-server 명령이 PATH에 등록되어 있습니다. Homebrew 포뮬러는 두 명령을 모두 설치합니다.

0단계: Homebrew로 설치¶

Homebrew 포뮬러는 macOS Apple Silicon에서 mlxcel CLI와 독립 실행형 mlxcel-server 바이너리를 모두 설치합니다.

brew tap lablup/tap
brew install lablup/tap/mlxcel

Linux 빌드는 CUDA 전용이며 tap에 포함되지 않습니다. GitHub 릴리스 페이지에서 mlxcel-linux-*-cuda13 아카이브로 제공되며, 소스에서 빌드할 수도 있습니다. Windows 빌드는 소스 빌드만 지원하며, NVIDIA CUDA는 실험 단계이고 AMD ROCm은 0.8부터 지원합니다.

v0.8.0은 프리릴리스입니다

v0.8.0 릴리스는 프리릴리스로 표시되어 있고 첨부된 사전 빌드 아카이브가 없습니다. Homebrew formula와 releases/latest 페이지는 이전 안정 릴리스를 제공하므로 둘 다 v0.8.0을 설치하지 않습니다. v0.8.0을 실행하려면 git clone --branch v0.8.0 https://github.com/lablup/mlxcel.git으로 태그를 받아 소스에서 빌드하십시오.

두 명령이 사용 가능한지 확인합니다.

mlxcel --help
mlxcel-server --help

소스에서 빌드한 경우에는 아래 예제의 mlxcel과 mlxcel-server 대신 ./target/release/mlxcel, ./target/release/mlxcel-server를 사용하십시오. 소스 빌드 사전 요구사항은 소스에서 빌드하기를 참조하십시오.

1단계: 모델 실행¶

mlxcel은 MLX 형식의 HuggingFace 체크포인트와 직접 호환됩니다. 가장 빠른 시작 경로는 mlxcel run입니다. HuggingFace owner/name repo-id, MLX Community의 bare 모델 이름, 또는 로컬 모델 디렉터리를 전달할 수 있습니다.

이 가이드에서는 4비트 양자화된 Qwen3.5 0.8B를 예시로 사용합니다. 첫 실행에 적합할 만큼 작지만 더 큰 모델과 같은 resolver, downloader, 생성, 서버 실행 경로를 그대로 확인할 수 있습니다.

# 대화형 chat REPL. 첫 사용 시 mlxcel store에 자동 다운로드합니다.
mlxcel run mlx-community/Qwen3.5-0.8B-4bit

# bare 이름은 기본적으로 mlx-community/<name>으로 해석됩니다.
mlxcel run Qwen3.5-0.8B-4bit

# -p를 전달하면 한 번만 생성하고 종료합니다.
mlxcel run Qwen3.5-0.8B-4bit -p "Explain attention in one sentence." -n 100

# 모델 인자를 생략하면 mlx-community/gemma-4-e2b-it-4bit를 기본값으로 사용합니다.
mlxcel run

mlxcel run은 서버 엔진의 클라이언트입니다. mlxcel-server 모델 워커를 프로세스 안에서 시작하고(슬롯 1개, HTTP 리스너 없음) 각 턴을 /v1/chat/completions 요청 경로로 보냅니다. 따라서 같은 요청에 대해 mlxcel run -p와 mlxcel-server는 같은 출력을 내며, run -p는 프롬프트를 다시 출력하지 않고 응답만 출력합니다. 자세한 내용은 mlxcel run을 참조하십시오.

더 큰 체크포인트도 같은 한 줄 명령으로 시작할 수 있습니다. 예를 들어 아래 명령은 Gemma 4 chat 세션을 시작하고 아직 없으면 mlx-community/gemma-4-e4b-it-4bit를 store에 다운로드합니다.

mlxcel run gemma-4-e4b-it-4bit

자동으로 종료되는 smoke test가 필요하면 프롬프트와 작은 토큰 제한을 함께 전달합니다.

mlxcel run gemma-4-e4b-it-4bit -p "Hello!" -n 8 --temp 0

Apple Silicon 머신에서 모델이 이미 로컬에 있었을 때의 예시 출력은 다음과 같습니다.

Runtime device: Apple GPU (Metal)
Wired memory limit: 107.5 GB
[mlxcel] 'gemma-4-e4b-it-4bit' -> mlx-community/gemma-4-e4b-it-4bit
Loading model from "models/gemma-4-e4b-it-4bit"...
Loaded Gemma4 audio encoder (12 Conformer layers)
Model loaded in 1.440s (resident: 4.83 GB, peak: 4.86 GB).
Generating...
Hello!...

[Generated 8 tokens in 0.17s = 46.62 tok/s]

깨끗한 머신에서는 같은 명령이 Loading model from ... 전에 다운로드 진행률을 출력합니다. 시간과 생성 텍스트는 하드웨어와 캐시 상태에 따라 달라집니다.

-p/--prompt를 생략하면 mlxcel run은 다중 턴 대화형 chat REPL을 엽니다. /bye로 종료하고 /clear로 대화를 초기화하며 /?로 도움말을 볼 수 있습니다. 여러 줄 입력은 triple quote(""")를 사용합니다.

MLX 형식이란? MLX 모델은 아키텍처를 설명하는 config.json, 토크나이저 메타데이터(tokenizer_config.json 등), 그리고 SafeTensors 가중치 파일(.safetensors)로 구성됩니다. mlxcel은 별도의 변환 과정 없이 이 파일들을 직접 로드합니다.

2단계: 생성, 검사, 사전 메모리 점검¶

generate, serve, inspect는 모두 -m/--model에서 동일한 모델 인자 형식을 받습니다.

기존 로컬 경로,
HuggingFace owner/name repo-id,
또는 mlx-community/<name>으로 해석되는 bare 모델 이름.

repo-id 인자가 캐시에 없으면 전역 mlxcel store로 다운로드되고 이후 재사용됩니다.

# 일회성 텍스트 생성.
mlxcel generate \
    --model Qwen3.5-0.8B-4bit \
    --prompt "Explain the concept of attention in transformer models." \
    --max-tokens 200

# 읽기 전용 메모리 예산: 가중치 + KV 캐시 + 런타임 headroom.
mlxcel inspect --model Qwen3.5-0.8B-4bit --max-tokens 32768

# 추정된 모델 + KV 캐시가 메모리에 맞지 않으면 시작을 거부합니다.
mlxcel generate \
    --model Qwen3.5-0.8B-4bit \
    --prompt "Hello, world!" \
    --max-tokens 32768 \
    --estimate-memory

예산 초과 preflight를 확인한 뒤에만 --force(별칭: --no-memory-check)를 사용하십시오. 배포 환경의 soft 예산을 반영하려면 MLXCEL_MEMORY_LIMIT=32GB처럼 설정하여 전체 시스템 메모리 대신 해당 값을 estimator가 사용하도록 할 수 있습니다.

CLI 옵션 요약¶

옵션	단축	설명
`--model PATH_OR_REPO_ID`	`-m`	로컬 모델 경로, HuggingFace `owner/name`, 또는 `MLXCEL_DEFAULT_ORG`를 통해 해석되는 bare 이름
`--models-dir PATH`		repo-id 해석/다운로드에 사용할 mlxcel model-store 루트 재정의
`--prompt TEXT`	`-p`	입력 텍스트. 생략하면 `generate`도 `run`과 같은 대화형 REPL로 진입
`--max-tokens N`	`-n`	최대 생성 토큰 수(기본값 `-1`: EOS 또는 context window가 찰 때까지)
`--temp FLOAT`	`-t`	샘플링 온도(0.0 = 탐욕적/결정론적)
`--top-p FLOAT`		Nucleus 샘플링 임계값
`--no-chat-template`		채팅 템플릿 자동 적용 비활성화
`--adapter PATH`		LoRA 어댑터 디렉터리 경로
`--draft-model PATH`		드래프트 모델을 사용한 투기적 디코딩 활성화

선택 사항: 더 빠른 디코딩 추가¶

먼저 --profile로 target만 실행한 시간을 측정하십시오. target과 토크나이저가 같은 작은 모델이 있다면, 그 모델을 full-model drafter로 지정해 일회성 generation에 투기적 디코딩을 추가할 수 있습니다.

mlxcel generate \
    --model ./models/target-model \
    --draft-model ./models/smaller-compatible-model \
    --draft-kind full-model \
    --draft-block-size 5 \
    --prompt "Explain speculative decoding in three sentences." \
    --max-tokens 200 \
    --profile

두 번째 모델이 없으면 mlxcel generate --prompt-lookup이 컨텍스트의 앞선 텍스트를 draft 토큰으로 복사하고, mlxcel serve --draft-kind prompt-lookup은 서버의 배치 스케줄러 안에서 같은 일을 합니다. 둘 다 프롬프트를 반복하는 응답에서 주로 효과가 있습니다.

Target 전용 assistant는 특화 서버 경로를 사용합니다. 예를 들어 Gemma 4 target을 공개된 assistant와 짝짓고 MTP를 선택합니다.

mlxcel serve \
    --model ./models/gemma-4-target \
    --draft-model ./models/gemma-4-assistant \
    --draft-kind mtp \
    --draft-block-size 4 \
    --max-batch-size 1 \
    --port 8080

지원되는 Qwen 3.5 계열 target과 그에 맞는 DFlash 체크포인트에서는 kind와 width를 바꿉니다.

mlxcel serve \
    --model ./models/qwen3.5-target \
    --draft-model ./models/qwen3.5-dflash \
    --draft-kind dflash \
    --draft-block-size 16 \
    --max-batch-size 1 \
    --port 8080

Target과 drafter는 명시적으로 호환되는 pair여야 하고 두 모델 모두 메모리를 사용하며 요청이 qualification을 통과하지 못하면 설정한 경로가 decline 또는 fallback할 수 있습니다. 설정을 유지하기 전에 target-only latency 및 출력을 비교하십시오. 알고리즘은 투기적 디코딩, 지원 pairing·exactness gate·멀티모달 제한·튜닝은 MTP와 DFlash를 참조하십시오.

3단계: OpenAI 호환 서버 시작¶

serve 서브명령어는 OpenAI 호환 엔드포인트를 제공하는 HTTP 서버를 시작합니다. OpenAI 스타일 API와 함께 동작하는 애플리케이션은 대개 base URL만 바꾸면 mlxcel로 전환할 수 있습니다.

mlxcel serve --model Qwen3.5-0.8B-4bit --port 8080

다음과 유사한 출력이 표시됩니다.

Loading model: mlx-community/Qwen3.5-0.8B-4bit
Warming up model...
Server listening on http://127.0.0.1:8080

서버는 시작 시 웜업 패스를 수행합니다(토큰 하나를 생성하고 버립니다). Metal 파이프라인을 사전 컴파일하기 때문에 시작 시간이 몇 초 더 걸리지만 첫 번째 요청의 지연 시간 급증이 사라집니다.

또는 llama.cpp의 llama-server 드롭인 대체용으로 설계된 독립 실행형 mlxcel-server 바이너리를 사용할 수도 있습니다. -m/--model 인자는 mlxcel serve와 동일하게 로컬 경로, repo-id, bare 이름을 받습니다.

mlxcel-server -m Qwen3.5-0.8B-4bit --port 8080

4단계: 서버에 요청 보내기¶

서버가 실행 중이면 curl 또는 임의의 HTTP 클라이언트를 사용하여 요청을 보낼 수 있습니다. 서버는 OpenAI 형식의 채팅 완성 요청을 받습니다.

비스트리밍 요청¶

curl http://localhost:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen3.5-0.8B-4bit",
        "messages": [
            {"role": "user", "content": "What is the capital of France?"}
        ],
        "max_tokens": 100,
        "temperature": 0.7
    }'

응답:

{
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "model": "Qwen3.5-0.8B-4bit",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "The capital of France is Paris."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 8,
        "total_tokens": 23
    }
}

스트리밍 요청¶

실시간 토큰 스트리밍을 사용하려면 "stream": true를 설정하십시오. 서버는 Server-Sent Events(SSE) 방식으로 응답합니다.

curl http://localhost:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen3.5-0.8B-4bit",
        "messages": [
            {"role": "user", "content": "Write a haiku about Rust programming."}
        ],
        "stream": true
    }'

응답의 각 줄은 JSON 델타를 담은 data: 이벤트입니다.

data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":"Memory"},"index":0}]}
data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":" safe"},"index":0}]}
...
data: [DONE]

서버는 OpenAI Responses API용 /v1/responses, Anthropic Messages API용 /v1/messages, /v1/embeddings, /v1/rerank, 고유 /completion과 /embedding, 그리고 /v1/audio 아래의 OpenAI 호환 음성 합성 및 전사 경로도 제공합니다. 정확한 형식은 REST API 레퍼런스, 임베딩 및 재순위화 API, 오디오 API 가이드를 참고하십시오.

5단계: 임베딩과 재순위화¶

임베딩 체크포인트로 오프라인 벡터를 만들고 비교합니다.

mlxcel embed -m sentence-transformers/all-MiniLM-L6-v2 \
    -p "벡터 검색은 가까운 임베딩을 찾는다." \
    -p "컴파일러는 소스 코드를 번역한다."

교차 인코더 재순위화 모델로 한 질의에 대한 후보 문서 점수를 계산합니다.

mlxcel rerank -m BAAI/bge-reranker-v2-m3 \
    -q "벡터 검색이란 무엇인가?" \
    -d "벡터 검색은 가까운 임베딩을 찾는다." \
    -d "컴파일러는 소스 코드를 번역한다." \
    --top-n 1

HTTP로 서빙할 때는 -m에 대화 모델을 두고 두 전용 모델 제공자를 추가합니다. 각 모델은 전용 작업자 스레드를 소유합니다.

mlxcel serve \
    -m mlx-community/Qwen3-4B-4bit \
    --embedding-model Qwen/Qwen3-Embedding-0.6B \
    --reranker-model mlx-community/Qwen3-Reranker-0.6B-4bit \
    --port 8080

OpenAI 응답에는 /v1/embeddings, Jina/Cohere 방식의 결과에는 /v1/rerank를 사용합니다. 고유 /embedding과 /embeddings는 모양이 다른 llama-server 응답을 반환합니다. 접두문, 풀링, 정규화는 모델 계약의 일부이므로 인덱스를 만들기 전에 임베딩과 재순위화를 읽으십시오.

6단계: 다운로드된 모델 관리¶

다운로드된 모델은 위치 독립적인 전역 store에 저장됩니다.

${MLXCEL_CACHE_DIR:-$HOME/.cache/mlxcel}/models/<owner>/<name>

어느 디렉터리에서나 store를 나열하고 정리할 수 있습니다.

# 다운로드된 모델의 디스크 사용량과 절대 경로를 표시합니다.
mlxcel list

# mlxcel store에서 모델을 제거합니다(확인 프롬프트 표시).
mlxcel rm mlx-community/Qwen3.5-0.8B-4bit

# 스크립트용으로 프롬프트 없이 제거합니다.
mlxcel rm mlx-community/Qwen3.5-0.8B-4bit --yes

store 위치를 바꾸려면 MLXCEL_MODELS_DIR을 설정하거나 --models-dir를 전달합니다. 이 override는 <owner>/<name> 스냅샷을 직접 포함하는 디렉터리이며 추가 models/ 컴포넌트를 붙이지 않습니다.

MLXCEL_MODELS_DIR=/data/mlxcel-models mlxcel list
mlxcel download mlx-community/Qwen3.5-0.8B-4bit --models-dir /data/mlxcel-models

전역 store를 사용하지 않고 정확한 한 디렉터리에 스냅샷을 쓰고 싶을 때만 mlxcel download --local-dir를 사용하십시오.

7단계: 비전-언어 모델 사용¶

mlxcel은 텍스트와 이미지를 함께 처리할 수 있는 비전-언어 모델(VLM)을 지원합니다. VLM을 사용하는 방법은 다음과 같습니다.

resolver가 MLX Community의 VLM을 자동 다운로드하게 하거나, 명시적으로 다운로드합니다.

mlxcel download mlx-community/Qwen2-VL-7B-Instruct-4bit

CLI에서 이미지와 함께 텍스트를 생성합니다.

mlxcel generate \
    --model mlx-community/Qwen2-VL-7B-Instruct-4bit \
    --prompt "Describe what you see in this image." \
    --image ./path/to/image.jpg \
    --max-tokens 200

OpenAI 비전 형식(base64 인코딩 이미지 또는 URL)으로 서버에 이미지 요청을 보냅니다.

curl http://localhost:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen2-VL-7B-Instruct-4bit",
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "What is in this image?"},
                    {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
                ]
            }
        ]
    }'

대표적인 VLM 계열에는 Gemma 3/3n/4, LLaVA, Llama Vision/4, Florence-2, Falcon-OCR, Jina VLM, MiniCPM-o/V, Molmo, Muse Glimmer, Phi-3 Vision, Phi-4 Multimodal, Qwen2/2.5/3/3.5-VL, Youtu-VL이 있습니다. 유지 관리되는 전체 목록은 지원 모델에 있습니다.

다음 단계¶

설정 가이드를 읽고 모델 store 경로, 메모리 한도, 디바이스 선택을 조정해 보십시오.
CLI 레퍼런스에서 사용 가능한 모든 옵션을 살펴보십시오.
REST API 레퍼런스에서 전체 엔드포인트 명세를 확인하십시오.
검색 요청과 응답 계약은 임베딩 및 재순위화 API를 확인하십시오.
OpenAI 오디오 API 가이드에서 Whisper 전사/번역과 Kokoro 음성 합성을 알아보십시오.
하드웨어별 paged-decode autotuning이 필요하면 성능 튜닝을 실행하십시오.
분산 추론에서 멀티 GPU 설정 방법을 알아보십시오.