명령줄 인터페이스¶

mlxcel은 19개의 서브명령어를 제공합니다. run과 generate는 모델 출력을 만들고 generate-image는 이미지를 렌더링하며 embed는 밀집·다중 벡터 표현을 생성하고 rerank는 질의-문서 쌍의 점수를 계산합니다. detect는 객체를 찾고 predict는 밀집 맵과 키포인트를 쓰며, tag와 extract는 고정 레이블 토큰 분류와 요청 시점 스팬 추출을 실행합니다. inspect는 로드 전 메모리를 산정하고 serve는 HTTP 서버를 시작합니다. list, arch, download, rm은 모델 가용성을 관리하거나 확인하고 tune은 커널 실행 설정을 측정하여 캐시하며, split-mtp는 원본 GLM-4.7-Flash 체크포인트에서 독립 MTP 초안 모델을 만듭니다. prepare-external-ple과 prepare-expert-stream은 qwen4_exp가 MLX 파라미터 밖에서 읽는 디스크 구조를 만듭니다. generate에는 gen, list에는 ls, arch에는 supported 별칭이 있습니다.

목차¶

• 환경 변수
• mlxcel run
• mlxcel generate
• 모델 옵션
• 생성 옵션
• KV 캐시 옵션
• 샘플링 옵션
• 프롬프트 조회 옵션
• 디퓨전 옵션
• 파이프라인 병렬 옵션
• Tensor Parallel 옵션
• 런타임 모델 변환 옵션
• 언어 바이어스 옵션
• 예시
• mlxcel inspect
• mlxcel detect
• mlxcel predict
• mlxcel generate-image
• mlxcel embed
• mlxcel rerank
• mlxcel tag
• mlxcel extract
• mlxcel serve
• 네트워크 및 인증
• 동시성 및 배칭
• 임베딩 및 재순위화 작업자
• 투기적 디코딩
• 엔드포인트 토글
• 모델 해석과 저장소
• 라우터 모드
• WebUI
• LoRA 어댑터
• 구조적 출력 기본값
• 기본 샘플링 파라미터
• 분산 추론
• 예시
• mlxcel list
• mlxcel arch
• mlxcel download
• mlxcel rm
• mlxcel tune
• mlxcel split-mtp
• mlxcel prepare-external-ple
• mlxcel prepare-expert-stream

환경 변수¶

이 변수들은 플래그 처리 전에 시작 시점에 읽힙니다.

MLXCEL_WIRED_LIMIT=max로 설정하면 대형 모델의 처리량을 향상시킬 수 있지만 모델과 작업 텐서를 합친 크기가 물리적 메모리를 초과하는 경우 메모리 부족이 발생할 수 있습니다.

mlxcel run¶

mlxcel run [OPTIONS] [MODEL_OR_REPO_ID]

ollama 스타일의 위치 기반 모델 인자로 모델을 실행합니다. -p/--prompt가 없으면 대화형 다중 턴 chat REPL을 열고 -p가 있으면 한 번 생성하고 종료합니다. 모델 인자를 생략하면 기본값 mlx-community/gemma-4-e2b-it-4bit를 사용합니다.

MODEL_OR_REPO_ID는 generate -m과 같은 resolver 입력을 받습니다. 기존 로컬 경로, HuggingFace owner/name repo-id, 또는 ${MLXCEL_DEFAULT_ORG:-mlx-community}/<name>으로 해석되는 bare 이름을 사용할 수 있습니다. repo-id가 캐시에 없으면 mlxcel model store에 다운로드되고 이후 어느 디렉터리에서나 재사용됩니다.

예시:

# 대화형 채팅. 첫 사용 시 자동 다운로드합니다.
mlxcel run Qwen3.5-0.8B-4bit

# 일회성 생성.
mlxcel run Qwen3.5-0.8B-4bit -p "Hello" -n 100

# bare 이름에 사용할 기본 owner 재정의.
MLXCEL_DEFAULT_ORG=my-org mlxcel run My-Model-4bit

run의 실행 방식¶

run과 REPL은 mlxcel-server 모델 워커의 클라이언트입니다. 워커는 같은 프로세스 안에서 슬롯 하나(--parallel 1, --max-batch-size 1)로 시작하고 HTTP 리스너는 열지 않으며, 각 턴은 /v1/chat/completions 요청 경로를 거칩니다. 이 경로가 채팅 템플릿 렌더링, reasoning과 본문 분리, 도구 호출 파싱, stop 문자열 적용을 맡습니다. 같은 요청이면 mlxcel run -p와 mlxcel-server는 같은 토큰을 만들고, MLXCEL_SDPA_DETERMINISTIC=1에서는 run -p --temp 0과 서버의 탐욕적 출력이 완전히 같습니다. CLI와 서버 사이의 토큰 일치를 참조하십시오.

run -p는 프롬프트를 다시 출력하지 않고 응답만 출력한 뒤 [Generated N tokens ...] 요약 줄을 찍으며, 초안 모델이 동작했다면 [Speculative ...] 수락 통계 줄도 출력합니다. 프롬프트 캐시는 run -p에서는 꺼져 있고 REPL에서는 켜져 있습니다. REPL의 대화마다 고유한 prompt_cache_key가 붙으므로 후속 턴은 새 메시지만 prefill합니다.

채팅 템플릿이 없는 체크포인트는 서버의 범용 채팅 형식으로 렌더링하고, base 모델일 가능성이 높다는 안내를 출력합니다. --no-chat-template을 주면 원문 텍스트를 /v1/completions 경로로 보냅니다.

채팅 서버가 처리하지 않는 일회성 모드는 generate 흐름에서 실행됩니다. block-diffusion, Florence-2, Nemotron-Parse, Nemotron VoiceChat 체크포인트와 --output-audio, --layout-detections, --audio, --video, --profile, --estimate-memory, --recommend-quant 플래그가 여기에 해당하고, --no-chat-template과 --image를 함께 줄 때도 generate에 남습니다. 그 밖의 --image는 채팅 클라이언트의 image_url 파트처럼 서버를 거칩니다.

run이 받는 플래그 그룹¶

run은 generate의 생성, 미디어, KV 캐시, 디퓨전, 샘플링 옵션과 아래 서버 샘플링 옵션, 위 표의 투기적 디코딩 플래그를 받습니다. 파이프라인 병렬, 텐서 병렬, 언어 바이어스, 모델 변환, 프롬프트 조회 그룹은 받지 않습니다. 전체 목록은 mlxcel run --help를 기준으로 하십시오.

샘플링 플래그는 이름이 같은 mlxcel-server 옵션으로 그대로 전달됩니다. 지정하지 않은 플래그는 서버 기본값을 따르는데, 예외가 하나 있습니다. 체크포인트의 generation_config.json이 temperature를 정하지 않으면 기본 샘플러는 탐욕적 디코딩으로 남습니다. --repeat-last-n과 --dry-penalty-last-n은 지정했을 때만 전달되므로, 지정하지 않은 run은 서버의 64토큰 윈도를 쓰고(페널티가 꺼져 있으면 효과 없음) generate는 -1(전체 이력)을 씁니다.

대화형 명령¶

이미지를 포함한 transcript 전체가 턴마다 다시 전송됩니다. 그래서 /image와 --image는 대화가 서버의 요청당 이미지 상한(기본 16장)을 넘게 만드는 이미지를 거절하고, /clear로 개수를 초기화할 수 있습니다. raw 모드(--no-chat-template)의 턴에는 미디어가 실리지 않으므로 REPL은 /image를 거절하고 --image는 안내와 함께 무시합니다.

mlxcel generate¶

mlxcel generate [OPTIONS] --model <PATH_OR_REPO_ID> [--prompt <TEXT>]
mlxcel gen [OPTIONS] --model <PATH_OR_REPO_ID> [--prompt <TEXT>]   # alias

모델을 로드하고 프롬프트가 제공된 경우 이를 적용한 뒤 생성된 토큰을 stdout으로 스트리밍하고 요약 줄을 출력합니다. --prompt를 생략하면 generate는 mlxcel run과 같은 대화형 다중 턴 REPL로 진입합니다.

generate -p는 raw completion 클라이언트입니다. 엔진의 직접 클라이언트(mlxcel_core::engine::DirectEngine)에서 디코딩하며, 서버의 단일 시퀀스 행과 같은 샘플러, finish 단계, B=1 lookahead 파이프라인을 씁니다. MLXCEL_FORCE_SYNC는 이 파이프라인을 끕니다. 채팅 프롬프트는 서버와 같은 방식으로 체크포인트 템플릿을 렌더링합니다. --profile의 [TTFT] 줄은 샘플러 구성 시간을 eval에 포함하므로 sample=0으로 표시합니다.

모델 옵션¶

생성 옵션¶

KV 캐시 옵션¶

호환성과 품질 지침은 TurboQuant KV 캐시를 참조하십시오.

샘플링 옵션¶

이 플래그들은 모델의 확률 분포에서 다음 토큰을 선택하는 방식을 제어합니다.

프롬프트 조회 옵션¶

프롬프트 조회는 초안 모델 없이 n-gram으로 하는 투기적 디코딩입니다. 라운드마다 시퀀스의 마지막 몇 토큰이 앞서 나타났던 위치를 찾아 그 뒤에 이어졌던 토큰을 제안하고, 대상 모델 forward 한 번으로 검증합니다. 프롬프트를 베껴 쓰는 응답(수정, 다시 쓰기, 형식 변환)에서 효과가 있고, 그 밖의 응답에서는 제안을 줄이거나 멈춰 일반 디코딩에 가까운 속도를 유지합니다. 수락 규칙은 샘플러 일치(sampler-match) 방식이라 one-hot 제안에 대해 손실이 없으며, 탐욕적 출력은 logit이 거의 같은 지점에서만 일반 디코딩과 달라질 수 있습니다. 서버 형태(--draft-kind prompt-lookup)는 투기적 디코딩을 참조하십시오.

튜닝 플래그는 --prompt-lookup이 있어야 합니다. mlxcel generate --draft-kind prompt-lookup은 --prompt-lookup을 안내하는 파싱 오류가 납니다. --prompt-lookup 실행은 대화형 채팅(-p 없음), 이미지·오디오·비디오 입력, 파이프라인 병렬, 그리고 캐시 trim으로 상태를 되돌릴 수 없는 대상 모델에서 거절됩니다. 마지막 경우는 recurrent·hybrid 모델과 어텐션 캐시를 모델이 직접 소유하는 모델(Qwen 3.5, Gemma 3과 4, Llama 4)입니다. 첫 실행은 측정 대상 생성 전에 모든 검증 폭을 예열합니다. GB10에서 수정형 응답은 일반 디코딩보다 1.10배에서 1.94배 빨랐고, 자유 서술은 gated 정책에서 약 0.98배에서 1.00배를 유지했습니다.

디퓨전 옵션¶

블록 디퓨전 생성을 제어하는 플래그로, DiffusionGemma 같은 디퓨전 모델에만 적용되며 자기회귀 모델은 무시합니다. 생성 메커니즘과 튜닝 지침은 블록 디퓨전을 참조하십시오.

파이프라인 병렬 옵션¶

이 플래그들은 mlxcel generate에서 단일 프로세스 내 파이프라인 경로를 활성화합니다.

현재 CLI 파이프라인 참고 사항:

• 이 경로는 Llama만이 아니라 파이프라인 병렬화에 나열된 stage-executor family에서 사용할 수 있습니다.
• Text-only이며 speculative decoding과 VLM input은 지원하지 않습니다. 현재 Llama stage executor에서는 load-time adapter 하나를 stage별로 fuse할 수 있고 다른 family는 명시적으로 실패합니다.
• 지원되는 dense runtime에서는 in-process CLI PP×TP 조합을 사용할 수 있지만 TP×LoRA는 지원하지 않습니다. Remote pipeline serving은 제한이 더 엄격하여 현재 adapter와 TP 조합을 거부합니다.

Tensor Parallel 옵션¶

이 플래그들은 지원되는 dense 텍스트 모델 계열에서 현재 단일 프로세스 tensor-parallel 런타임을 활성화합니다.

지원되는 tp_size > 1 계열은 dense Llama, Qwen2/2.5, Qwen3, Qwen3.5 text, Gemma 3 text, Gemma 4 text, ERNIE 4.5, Hunyuan v1 Dense입니다. LoRA 어댑터는 TP와 함께 사용할 수 없습니다.

런타임 모델 변환 옵션¶

런타임 모델 변환은 체크포인트가 로드되는 동안 YAML로 정의된 가중치 변환을 적용합니다. 디스크의 모델 파일을 수정하지 않고 일시적이고 재현 가능한 가중치 조정을 해야 할 때 사용합니다. 연산 스키마와 제한 사항은 런타임 모델 변환을 참조하십시오.

언어 바이어스 옵션¶

mlxcel generate와 두 서버 진입점은 샘플링 시 특정 문자권을 억제하거나 장려하는 언어 바이어스 제어를 제공합니다. 운영 가이드는 Language Bias를 참조하십시오.

Generate 예시¶

탐욕적 디코딩을 이용한 기본 텍스트 생성:

# Bare 이름은 mlx-community/Qwen2.5-7B-Instruct-4bit로 해석됩니다.
mlxcel generate \
  --model Qwen2.5-7B-Instruct-4bit \
  --prompt "Explain the difference between a mutex and a semaphore." \
  --max-tokens 300

generate에서 대화형 채팅 시작:

mlxcel generate --model Qwen3.5-0.8B-4bit

더 큰 vision token budget을 사용하는 Gemma 4:

mlxcel generate -m ./models/gemma-4-e2b-it-4bit \
  --image page.png --image-soft-tokens 560 \
  -p "Read the small text in this page."

Falcon-OCR region 단위 OCR:

mlxcel detect -m ./models/docling-layout -i page.png --format json > regions.json
mlxcel generate -m ./models/falcon-ocr --image page.png --layout-detections regions.json

Qwen3-Omni 음성 출력:

mlxcel generate -m ./models/qwen3-omni \
  -p "Give a short welcome." --output-audio welcome.wav --speaker chelsie

높은 온도와 핵 샘플링을 이용한 창의적 글쓰기:

mlxcel generate \
  --model ./models/Llama-3.1-8B-Instruct \
  --prompt "Write the opening paragraph of a science fiction novel." \
  --max-tokens 200 \
  --temp 0.8 \
  --top-p 0.95

LoRA 어댑터 사용:

mlxcel generate \
  --model ./models/Mistral-7B-v0.3 \
  --adapter ./adapters/mistral-sql-lora \
  --prompt "Write a SQL query to find the top 10 customers by revenue." \
  --max-tokens 150

런타임 모델 변환 적용:

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct \
  --surgery ./surgery.yaml \
  --prompt "배포 체크리스트를 요약해 주세요." \
  --max-tokens 150

이미지를 이용한 비전-언어 모델:

mlxcel generate \
  --model ./models/Qwen2.5-VL-7B-Instruct \
  --image ./photos/diagram.png \
  --prompt "Describe what you see in this image." \
  --max-tokens 200

Gemma 4 비디오 입력:

mlxcel generate \
  --model ./models/gemma-4-vl \
  --video ./demo.mp4 \
  --fps 2.0 \
  --prompt "Summarize the visible events in this clip." \
  --max-tokens 200

비디오 디코딩은 ffmpeg를 사용합니다. --video를 사용하기 전에 설치되어 있고 PATH에서 찾을 수 있는지 확인하십시오.

--image 플래그를 반복하여 여러 이미지를 지정할 수 있습니다:

mlxcel generate \
  --model ./models/Qwen2.5-VL-7B-Instruct \
  --image ./before.png --image ./after.png \
  --prompt "What changed between these two images?" \
  --max-tokens 200

full-model 투기 디코딩(일반 소형 체크포인트를 초안 모델로 사용):

mlxcel generate \
  --model ./models/Llama-3.1-70B-4bit \
  --draft-model ./models/Llama-3.2-1B \
  --draft-kind full-model \
  --prompt "Summarize the key ideas in the Rust ownership model." \
  --max-tokens 400

--draft-kind full-model은 대상 모델과 토크나이저를 공유하는 소형 체크포인트를 자체 KV 캐시에서 실행하고, 엔진의 토큰 전용 검증 loop가 모든 위치를 결정합니다. MTP도 DFlash도 아닌 읽을 수 있는 모델 디렉터리는 full-model로 자동 감지됩니다. --draft-kind dflash는 Laguna 대상 모델과 그 Laguna DFlash 초안 모델 조합에서만 오프라인으로 실행되며, Qwen 3.5, LFM2 DSpark, Muse Glimmer DFlash 조합은 서버 방식으로 실행됩니다. --draft-kind mtp는 자격을 갖춘 Gemma 4/Unified, Qwen 3.5/Qwen3.8 계열, GLM-4.7-Flash 텍스트 전용 조합에서 지원됩니다.

초안 모델 없이 수정형 요청에 프롬프트 조회 적용:

mlxcel generate \
  --model mlx-community/Qwen3-1.7B-4bit \
  --prompt-lookup \
  --prompt "Fix the typos in this paragraph and return it unchanged otherwise: ..." \
  --max-tokens 400

Nemotron VoiceChat 오프라인 턴(음성 입력, 음성 출력):

mlxcel generate -m models/NemotronLabs-VoiceChat-11B-4bit \
  --audio question.wav --output-audio response.wav \
  -p "Be concise and answer in one sentence."

[user] <전사 결과>, 어시스턴트 텍스트, 그리고 function 채널이 무언가를 만들었다면 [function] <text>를 출력하고 response.wav(22050 Hz mono PCM16)를 씁니다. 출력 길이가 입력 타임라인 길이와 같으므로 -n은 무시되고, 이 계열에서 --seed의 기본값은 0이라 음성이 재현 가능하며, --image와 --video는 거절됩니다. --stream --profile을 더하면 온라인 세션으로 실행하면서 단계별 지연과 실시간 배율을 출력합니다. --audio 없는 대화형 generate는 이 체크포인트를 거절합니다. 서버 형태는 Nemotron VoiceChat Realtime API를 참조하십시오.

모델 로드 전 메모리 preflight:

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct \
  --prompt "Summarize the deployment plan." \
  --max-tokens 1024 \
  --estimate-memory

preflight는 렌더링된 prompt token 수와 --max-tokens를 더한 길이를 사용하고 정확한 가중치 크기, KV 캐시, runtime headroom을 사용 가능 메모리와 비교합니다. 자세한 내용과 override 기준은 메모리 추정을 참조하십시오.

성능 측정을 위한 프로파일링 모드:

mlxcel generate \
  --model ./models/Gemma-3-4B-Instruct \
  --prompt "What is photosynthesis?" \
  --max-tokens 200 \
  --profile

--profile 사용 시 타이밍 단계별 상세 정보가 출력됩니다:

[Profile Results]
  Prompt tokens:    12
  Generated tokens: 148
  Prefill:          84.3 ms (142.3 tok/s)
  Decode:           3241.7 ms (45.6 tok/s)

--profile 없이 실행하면 간단한 요약이 출력됩니다:

[Generated 148 tokens in 3.24s = 45.6 tok/s]

원시 프롬프트 주입을 위한 채팅 템플릿 비활성화:

mlxcel generate \
  --model ./models/Qwen2.5-7B-Instruct \
  --prompt "<|im_start|>user\nHello<|im_end|>\n<|im_start|>assistant\n" \
  --no-chat-template \
  --max-tokens 50

지원되는 텍스트 모델의 단일 머신 파이프라인 generate:

mlxcel generate \
  --model ./models/llama-3.2-1b-4bit \
  --prompt "Hello" \
  --max-tokens 64 \
  --temp 0 \
  --no-chat-template \
  --pp-size 2

mlxcel inspect¶

mlxcel inspect --model <PATH_OR_REPO_ID> [OPTIONS]

모델을 로드하지 않고 로드 전 메모리 breakdown을 출력합니다. 출력에는 가중치, KV 캐시, runtime headroom, 총 byte, 사용 가능 byte, 해당 구성이 들어맞을지 여부가 포함됩니다. 이 명령은 --estimate-memory와 --recommend-quant가 사용하는 것과 같은 추정기를 사용합니다. 자세한 내용은 메모리 추정을 참조하십시오.

예시:

mlxcel inspect -m ./models/Qwen2.5-7B-Instruct-4bit
mlxcel inspect -m ./models/Qwen2.5-7B-Instruct-4bit --max-tokens 32768
mlxcel inspect -m ./models/Qwen2.5-7B-Instruct-4bit --batch 4 --kv-cache-mode int8
mlxcel inspect --json -m mlx-community/Qwen3-4B-4bit | python3 -m json.tool

JSON 형식은 recipe builder와 scheduler가 hardware-fit 입력값을 읽기 위한 표면입니다. 출력 field는 mlxcel_version, model, model_type, family, inputs, weights_bytes, weights_source, kv_bytes_per_token, kv_bytes_total, kv_detail, per_slot_overhead_bytes, activation_bytes, backend_inflight_bytes(ROCm 빌드에서만 0이 아니며 headroom_bytes에 포함), headroom_bytes, headroom_factor, budget_bytes, total_bytes, fits입니다. 추정기가 제공할 수 없는 값은 추측하지 않고 null로 둡니다.

mlxcel detect¶

mlxcel detect --model <PATH> --image <PATH> [OPTIONS]

이미지에서 객체 검출을 수행하고 원본 이미지 픽셀 좌표로 바운딩 박스를 출력합니다. 검출 모델은 토큰 스트림이 아니라 클래스 레이블과 신뢰도가 포함된 박스(l, t, r, b)를 출력하므로 generate/serve와는 별도의 명령어입니다.

config.json과 model.safetensors가 있는 디렉터리에서 RT-DETRv2, PP-DocLayoutV3, YOLO11, RF-DETR 체크포인트를 로드합니다. 사전 변환된 MLX 체크포인트(예: mlx-community/docling-layout-heron-mlx-bf16)와 원본 HuggingFace 체크포인트를 모두 받고, HF 가중치는 로드 시 MLX 레이아웃으로 변환합니다.

클래스 이름은 체크포인트의 config.json::id2label에서 해석하고, YOLO11은 config.json의 클래스 목록을 씁니다. 없으면 숫자 클래스 id가 표시됩니다. PP-DocLayoutV3 검출에는 모델이 매긴 전역 읽기 순서도 함께 실립니다.

예시:

# 페이지 이미지에 대한 문서 레이아웃 검출(17개 클래스 docling 모델).
mlxcel detect -m ./models/docling-layout-heron-mlx-bf16 -i page.png

# 더 높은 임계값, 다운스트림 도구용 JSON 출력.
mlxcel detect -m ./models/rt-detr-v2 -i photo.jpg --threshold 0.5 --format json

# 가장 긴 변을 줄여서 수행하는 OmniParser v2 아이콘 검출.
mlxcel detect -m axiom-of-choice/OmniParser-v2-icon-detect -i ui.png --size 1280 --format json

JSON 출력 스키마:

{
  "image": "page.png",
  "threshold": 0.3,
  "detections": [
    { "label": "section_header", "label_id": 7, "confidence": 0.89,
      "box": { "l": 390.3, "t": 21.7, "r": 738.5, "b": 41.4 } }
  ]
}

mlxcel predict¶

mlxcel predict --model <PATH> (--image <PATH> | --video <PATH>) --output <DIR> [OPTIONS]

박스보다 많은 것을 반환하는 체크포인트를 위한 밀집 태스크 출력을 기록합니다. 깊이, 표면 노멀, 세그멘테이션, 포인트 맵, 키포인트, 인스턴스별 마스크, 메시, 가우시안 스플랫이 여기에 해당합니다. 모든 실행은 출력 디렉터리에 result.safetensors와 meta.json을 쓰고, 그 밖에 keypoints.json, depth.png, normal.png, segmentation.png, instances.json, masks/ 같은 태스크별 파일을 씁니다.

# Image-encoder features from DINOv2.
mlxcel predict -m ./models/dinov2-small -i input.png -o features --task features

# Pose from Sapiens2 with an explicit box.
mlxcel predict -m ./models/sapiens2-pose -i person.png -o pose \
  --opts '{"boxes":[[140,90,920,700]],"flip_test":true}'

# Depth over a video.
mlxcel predict -m ./models/video-depth -v clip.mp4 -o depth --max-frames 32

--image와 --video 중 정확히 하나가 필요하고 --output은 필수입니다. 선택한 패밀리가 해당 입력의 기본값을 선언하면 --task를 생략할 수 있습니다. --prompt는 반복 지정할 수 있고, --boxes는 픽셀 단위 x1,y1,x2,y2 박스를 받으며(플래그를 반복하거나 ;로 박스를 구분합니다), --mask와 --pointmap은 SAM 3D Objects 입력을 제공하고, --max-frames와 --target-fps는 비디오 샘플링을 제어하며, --opts는 모델별 옵션을 JSON 객체로 전달합니다.

지원 패밀리, 각 태스크, 출력 계약은 고밀도 예측과 비전 태스크를 참조하십시오.

mlxcel generate-image¶

mlxcel generate-image -m <PATH> -p <TEXT> [--task generate|edit] [OPTIONS]

Diffusers 레이아웃의 디퓨전 체크포인트로 프롬프트에서 이미지를 생성하거나 참조 이미지 하나 이상을 편집합니다. 시드는 항상 출력되며, -n이 1보다 크면 이미지 i는 시드 seed + i를 사용하고(FLUX.2 생성은 노이즈 배치 하나를 뽑는 예외) <stem>-01.png, <stem>-02.png 같은 이름으로 기록됩니다.

mlxcel generate-image -m ./models/flux2-klein -p "a watercolor fox"
mlxcel generate-image -m ./models/flux2-klein -p "a fox" --size 768x512 --seed 7 -n 2 -o fox.png
mlxcel generate-image -m ./models/flux2-klein --task edit --image fox.png -p "make it night"

주요 플래그는 --task generate|edit(기본 generate), --image(반복 지정 가능, edit에는 필수이고 generate에는 거부됨), --size WxH(기본 512x512), --negative-prompt, --steps, --guidance, --seed, -n(1~10), -o/--output(기본 outputs/image-<seed>.png), 모델별 옵션을 JSON으로 받는 --gen-kwargs입니다.

패밀리, 기본값, /v1/images 경로는 이미지 생성을 참조하십시오.

mlxcel embed¶

mlxcel embed -m <MODEL_OR_REPO_ID> -p <TEXT> [-p <TEXT> ...] [OPTIONS]

임베딩 체크포인트를 불러와 입력마다 벡터 하나를 출력합니다. 입력이 둘 이상이면 밀집 벡터에는 코사인 유사도 행렬, 후기 상호작용 벡터에는 최대 유사도 합산 행렬도 출력합니다. 서버와 같은 모델 감지, 로더, 풀링, 정규화, 길이 제한, 소규모 배칭을 사용합니다.

mlxcel embed -m nomic-ai/modernbert-embed-base \
  -p "search_query: 벡터 검색이란 무엇인가?" \
  -p "search_document: 벡터 검색은 가까운 임베딩을 찾는다."

mlxcel rerank¶

mlxcel rerank -m <MODEL_OR_REPO_ID> -q <QUERY> -d <DOCUMENT> [-d <DOCUMENT> ...] [OPTIONS]

한 질의에 대한 각 문서의 점수를 계산한 뒤 요청 순서의 점수와 최종 순위를 출력합니다. 교차 인코더, Qwen3 생성형, Qwen3-VL 멀티모달 재순위화 모델을 지원합니다.

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

접두문, 모델 계열, 점수 의미는 임베딩과 재순위화를 참고하십시오.

mlxcel tag¶

mlxcel tag -m <PATH_OR_REPO_ID> [OPTIONS] <TEXT>

텍스트에 고정 레이블 BIO 또는 BIOES 토큰 분류기를 실행하고, 유니코드 문자 오프셋과 마스킹된 사본을 포함한 태깅된 스팬을 출력합니다. 텍스트 인자로 -를 주면 stdin에서 읽습니다. --argmax는 제약된 Viterbi 디코더가 기본인 체크포인트에서 토큰별 디코딩을 강제하고, --replacement는 마스킹 문자열을 정하며, --keep은 마스킹된 텍스트에 남길 레이블을 나열하고, --operating-point는 Viterbi로 디코딩하는 체크포인트의 캘리브레이션 지점을 고릅니다.

mlxcel tag -m nativ-community/rampart-mlx-fp16 --keep CITY,STATE,ZIP_CODE \
  "I'm Sarah Connor, 1984 Cyberdyne Ave, Los Angeles CA 90012, sarah@sky.net"

mlxcel extract¶

mlxcel extract -m <PATH_OR_REPO_ID> (--labels <L1,L2> | --labels-json <JSON> | --classify <JSON>) <TEXT>

스팬 추출 체크포인트에서 요청마다 선택한 레이블의 스팬을 추출하거나 텍스트를 분류합니다. --include-confidence와 --include-spans는 각 스팬의 점수와 오프셋을 더하고, --threshold(기본 0.5)는 최소 엔터티 점수와 기본 다중 레이블 임계값을 정하며, --max-len과 --word-splitter whitespace|char는 GLiNER2.5에 적용됩니다.

mlxcel extract -m fastino/gliner2.5-small-v1 --labels company,person,location \
  --include-confidence --include-spans "Apple hired Sam in New York."

두 명령, 지원 패밀리, 출력 형태는 토큰 분류와 스팬 추출을 참조하십시오.

mlxcel serve¶

mlxcel serve [OPTIONS] --model <PATH_OR_REPO_ID>

OpenAI API 및 llama.cpp 서버 API와 호환되는 지속적인 HTTP 서버를 시작합니다. 서버는 모델을 한 번만 로드하여 메모리에 상주시키고 연속 배칭을 통해 여러 요청을 처리합니다.

여러 플래그는 커맨드라인 인수가 불편한 배포 환경에서 환경 변수로도 설정할 수 있습니다.

네트워크 및 인증¶

동시성 및 배칭¶

--ctx-size C가 0이 아니면 mlxcel은 llama.cpp 서버 의미론을 따릅니다. 이 값은 서버 전체 컨텍스트 예산이며 슬롯별 실제 컨텍스트 윈도우는 floor(C / active_slots)입니다. active_slots는 명시된 --max-batch-size, 없으면 --n-parallel이고 --no-batch는 슬롯 1개를 사용합니다. /health.context_size, /slots[].context_size, 메모리 preflight는 모두 이 슬롯별 값을 보고하고 사용합니다. 명시 예산이 슬롯당 512토큰 미만으로 나뉘면 시작 시 거부합니다.

오디오 worker¶

Whisper와 Kokoro 설정은 OpenAI 오디오 API를 참조하십시오.

임베딩 및 재순위화 작업자¶

-m에 임베딩 또는 시퀀스 분류 체크포인트를 지정하면 대화 모델 없이 해당 전용 작업자를 시작합니다. -m의 대화 모델은 두 보조 제공자와 함께 실행할 수 있습니다. 생성형 재순위화 전용 서버는 같은 체크포인트를 -m과 --reranker-model에 지정하며 모델을 두 번 불러오지 않습니다. 한 프로세스는 임베딩 제공자 하나와 재순위화 제공자 하나까지만 지원합니다. 임베딩 및 재순위화 API를 참고하십시오.

투기적 디코딩 (serve)¶

디퓨전 옵션 (serve)¶

서빙 중인 모델이 DiffusionGemma 같은 디퓨전 모델일 때 블록 디퓨전 생성을 조정하는 플래그입니다. 자기회귀 모델은 무시합니다. 블록 디퓨전을 참조하십시오.

이미지 모델 (serve)¶

채팅 템플릿¶

엔드포인트 토글¶

모델 해석과 저장소¶

--hf-file, --model-url, --docker-repo는 llama-server CLI 호환을 위해 파싱하지만 시작 시 거부합니다. --hf-file은 리포지터리 안의 GGUF 파일 하나를 고르는데 MLX는 SafeTensors 스냅샷 전체를 로드합니다. --model-url은 URL로 해석하는데 mlxcel은 리포지터리 식별자로 해석합니다. Docker Hub 모델 리포지터리는 GGUF 아티팩트를 배포합니다.

라우터 모드¶

서버가 모델을 둘 이상 호스팅할 때 적용되는 플래그입니다.

WebUI¶

보안 규칙과 화면 구성은 WebUI를 참조하십시오. llama-server 자체 브라우저 UI를 설정하는 옵션(--ui-config, --ui-config-file, --path, --tools, --tools-runtime, --mcp-servers-config, --mcp-servers-json, --ui-mcp-proxy, --agent)은 시작 시 거부합니다.

LoRA 어댑터 (serve)¶

구조적 출력 기본값¶

요청이 자체 제약을 담지 않았을 때 적용되는 서버 전역 제약입니다. 요청이 자체 grammar나 스키마를 지정하면 그쪽이 우선합니다.

Responses API 저장소¶

이 플래그들은 OpenAI Responses API의 응답/대화 저장소 크기와 TTL을 제어합니다. 자세한 내용은 REST API를 참조하십시오.

프롬프트 캐시 및 APC¶

프롬프트 프리픽스 KV 캐시는 기본적으로 활성화되어 있습니다. 아래 플래그들은 캐시 용량과 기본 활성화된 APC 블록 해시 계층을 조정합니다. 동작, 지표, 문제 해결은 프롬프트 캐시를 참조하십시오.

기본 샘플링 파라미터¶

이 플래그들은 요청이 자체 샘플링 파라미터를 지정하지 않을 때 사용되는 서버 전체 기본값을 설정합니다. 개별 요청은 이 모든 값을 재정의할 수 있습니다.

--adaptive-target와 --adaptive-decay는 adaptive-p를 제어하며 b10621과 동일하게 샘플러 목록에 adaptive_p가 있을 때만 동작합니다. --ignore-eos는 생성 종료 토큰을 억제해 토큰 예산이나 stop 문자열까지 생성을 이어 갑니다. --logit-bias는 모든 요청에서 특정 토큰 id에 바이어스를 주며(TOKEN_ID(+/-)BIAS, 예: 15043+1) 반복 지정할 수 있습니다. --reverse-prompt는 서버 전역 stop 문자열을 모든 요청의 stop 집합에 병합하며 반복 지정할 수 있습니다. --samplers와 b10621의 단일 문자 형식인 --sampler-seq는 받아들이지만 mlxcel의 체인 순서는 b10621 기본값으로 고정돼 있어 다른 순서는 시작 시 거부됩니다.

분산 추론¶

현재 tp_size > 1 런타임 참고:

• 지원 계열: dense Llama, dense Qwen2/2.5, dense Qwen3, dense Qwen3.5 text, Gemma 3 text, Gemma 4 text, ERNIE 4.5, Hunyuan v1 Dense
• 현재 런타임은 한 머신 내 in-process multi-rank 방식입니다
• LoRA adapter는 TP와 함께 지원하지 않습니다
• mlxcel serve는 현재 지원되는 dense TP 런타임에서 continuous batching을 유지하지만 Gemma 4 E2B 계열 보수적 폴백 체크포인트는 예외입니다
• mlxcel serve는 decode storage 기본값으로 auto를 사용합니다. Llama, Qwen 3, Qwen 3.5 text, Gemma 3 text, Llama 4 워커는 paged decode를 자동 선택합니다. ExaOne4, Ministral3, Gemma 4, Qwen3 Next, GPT-OSS, 그리고 모델별 paged decode dispatch가 없는 표준 외부-KV 계열은 연속 배칭의 paged-default 체크리스트를 충족할 때까지 dense decode를 유지합니다

예시:

mlxcel generate \
  --model ./models/ernie-4.5-0.3b-4bit \
  --prompt "TP에 대해 짧게 한 문장 써 주세요." \
  --tp-size 2

원격 TCP 파이프라인 병렬 예시:

CLUSTER_NAME=studio-pp \
TRANSPORT_BACKEND=tcp \
COORDINATOR_CONTROL_ADDR=192.168.1.22:19000 \
STAGE0_ADDR=192.168.1.22:19001 \
STAGE1_ADDR=192.168.1.24:19001 \
scripts/benchmark_pipeline_remote_rollout.sh write-config \
  examples/distributed/generated_pipeline_remote_2node_tcp.toml

# Machine B
mlxcel serve \
  --model ./models/llama-3.2-1b-4bit \
  --distributed-config examples/distributed/generated_pipeline_remote_2node_tcp.toml \
  --node-id stage-1 \
  --host 0.0.0.0 \
  --port 18081 \
  --no-warmup

# Machine A
mlxcel serve \
  --model ./models/llama-3.2-1b-4bit \
  --distributed-config examples/distributed/generated_pipeline_remote_2node_tcp.toml \
  --node-id stage-0 \
  --host 0.0.0.0 \
  --port 18081 \
  --no-warmup

# Machine A coordinator
mlxcel serve \
  --model ./models/llama-3.2-1b-4bit \
  --alias llama-remote-pp \
  --distributed-config examples/distributed/generated_pipeline_remote_2node_tcp.toml \
  --node-id coordinator \
  --host 0.0.0.0 \
  --port 18080 \
  --n-parallel 2 \
  --max-batch-size 2 \
  --pp-micro-batch-size 2 \
  --metrics \
  --no-warmup

smoke test:

COORDINATOR_URL=http://192.168.1.22:18080 \
MODEL_ALIAS=llama-remote-pp \
scripts/benchmark_pipeline_remote_rollout.sh smoke

Thunderbolt 모드는 같은 절차를 사용하되 다음만 바꾸면 됩니다.

• TRANSPORT_BACKEND=thunderbolt
• LAN IP 대신 Thunderbolt Bridge IP 사용
• coordinator/stage 역할과 포트 구성은 동일

예시:

CLUSTER_NAME=studio-pp \
TRANSPORT_BACKEND=thunderbolt \
COORDINATOR_CONTROL_ADDR=169.254.20.10:19000 \
STAGE0_ADDR=169.254.20.10:19001 \
STAGE1_ADDR=169.254.20.11:19001 \
scripts/benchmark_pipeline_remote_rollout.sh write-config \
  examples/distributed/generated_pipeline_remote_2node_thunderbolt.toml

로깅¶

Serve 예시¶

로컬호스트에서 최소 서버 실행:

mlxcel serve --model ./models/Qwen2.5-7B-Instruct

서버가 127.0.0.1:8080에서 시작됩니다. curl로 테스트할 수 있습니다:

curl -s http://localhost:8080/health

{"status":"ok"}

채팅 완성 요청:

curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2.5-7B-Instruct",
    "messages": [
      {"role": "user", "content": "What is 2 + 2?"}
    ],
    "max_tokens": 50
  }'

인증 및 공개 바인딩을 사용하는 서버:

mlxcel serve \
  --model ./models/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8080 \
  --api-key "my-secret-key"

인증된 요청:

curl -s http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"Llama-3.1-8B-Instruct","messages":[{"role":"user","content":"Hello"}]}'

배칭 및 메트릭을 사용한 고동시성 서버:

mlxcel serve \
  --model ./models/Qwen2.5-7B-Instruct \
  --max-batch-size 8 \
  --prefill-chunk-size 512 \
  --enable-preemption \
  --metrics

--prefill-chunk-size를 명시하면 두 스케줄러 상태 모두 그 값으로 고정됩니다. 적응형 기본값(디코딩 중인 시퀀스가 없으면 2048, 있으면 512)을 쓰려면 생략하십시오.

DFlash speculative decoding을 사용하는 서버:

mlxcel serve \
  --model ./models/qwen3.5-27b-4bit \
  --draft-model ./models/Qwen3.5-27B-DFlash \
  --draft-kind dflash \
  --draft-block-size 16

Standalone server binary에서는 --model-draft가 primary spelling이며 --draft-model도 허용됩니다.

mlxcel-server \
  --model ./models/qwen3.5-27b-4bit \
  --model-draft ./models/Qwen3.5-27B-DFlash \
  --draft-kind dflash \
  --draft-block-size 16

Unix 소켓 모드(로컬 IPC용):

mlxcel serve \
  --model ./models/Gemma-3-4B-Instruct \
  --host /tmp/mlxcel.sock

환경 변수 사용(배포 패턴):

export LLAMA_ARG_MODEL=./models/Qwen2.5-7B-Instruct
export LLAMA_API_KEY=my-secret-key
export LLAMA_ARG_PORT=9000
mlxcel serve

mlxcel list¶

mlxcel list [OPTIONS]
mlxcel ls               # alias

로컬 mlxcel store에 다운로드된 모델을 한 줄에 하나씩, repo-id와 디스크 사용량, 마지막 수정 시각과 함께 보여줍니다. 모델 로딩은 일어나지 않습니다. 지원하는 모델 아키텍처 목록을 보려면 mlxcel arch를 쓰면 됩니다.

mlxcel list                              # 기본 테이블, repo-id 순 정렬
mlxcel list --sort size                  # 용량 큰 모델부터
mlxcel list -q                           # repo-id만, 파이프용
mlxcel list --json                       # 기계가 읽기 좋은 형식
mlxcel list --models-dir /data/mlxcel-models

mlxcel arch¶

mlxcel arch
mlxcel arch --json
mlxcel supported        # alias

지원하는 모든 모델 아키텍처를 카테고리별로 그룹화하여 출력한 후 종료합니다. --json을 주면 recipe 및 coverage tooling이 읽을 수 있는 동일 registry를 machine-readable JSON object 하나로 출력합니다. 모델 로딩은 발생하지 않습니다.

출력 예시(축약):

Supported Model Architectures:

Llama:
  - Llama 1/2/3
  - Llama 4 (MoE)

Speech-to-text:
  - Whisper (encoder-decoder ASR)

Text-to-speech:
  - Kokoro (StyleTTS2 + iSTFTNet)

Embedding:
  - BERT / MiniLM encoder
  - Qwen3-VL-Embedding

Reranker:
  - SequenceClassifier

Other VLM:
  - Falcon-OCR (early fusion)
  - Florence-2 (DaViT + BART seq2seq, task prompts)
  ...

JSON 형식은 mlxcel_version과 지원하는 각 아키텍처마다 하나씩의 families entry를 담으며, 안정적인 id, display_name, category, model_types, aliases, runtimes, modalities_in, output, backends(Metal, CUDA, ROCm 상태. 백엔드가 실험 단계인 동안 모든 계열의 ROCm 항목은 partial), tensor_parallel, pipeline_parallel, drafters, kv_modes field를 제공합니다. 커밋된 recipes/registry/CURRENT marker는 해당 snapshot 파일을 recipes/registry/ 아래에서 가리킵니다.

정확한 목록은 실행 중인 바이너리의 ALL_MODEL_TYPES에서 생성됩니다. 배포 환경을 확인할 때 복사된 목록 대신 mlxcel arch를 사용하십시오. Architecture key와 capability는 지원 모델을 참조하십시오.

모델 감지는 자동입니다. 생성, 임베딩, 재순위화 로더가 model_type과 아키텍처·체크포인트 배치 메타데이터를 함께 사용하므로 아키텍처를 수동으로 지정하는 옵션은 필요하지 않습니다.

mlxcel download¶

mlxcel download [OPTIONS] <REPO_ID>

Python 의존성 없이 HuggingFace 저장소 스냅샷을 다운로드합니다. 기본적으로 스냅샷은 ${MLXCEL_CACHE_DIR:-$HOME/.cache/mlxcel}/models/<owner>/<name> 전역 mlxcel store에 저장되며 가능한 경우 기존 HuggingFace 캐시 사본을 재사용합니다. 독립 실행형 mlxcel-server 바이너리도 서버 실행 파일만 포함한 배포 이미지에서 사용할 수 있도록 같은 download 하위 명령어를 제공하며, mlxcel-server download --help(-h, --usage도 동일)로 도움말을 볼 수 있습니다.

예시:

# 기본값: 전역 store.
mlxcel download mlx-community/Qwen3-4B-4bit

# store 대신 정확한 디렉터리에 씁니다.
mlxcel download mlx-community/Qwen3-4B-4bit --local-dir /tmp/qwen

# 이 명령에 사용할 store root를 재배치합니다.
mlxcel download mlx-community/Qwen3-4B-4bit --models-dir /data/mlxcel-models

# gated/private 저장소.
mlxcel download meta-llama/Llama-3.1-8B-Instruct --token "$HF_TOKEN"

mlxcel rm¶

mlxcel rm [OPTIONS] <REPO_ID>

mlxcel store에서 다운로드된 모델 스냅샷을 제거합니다. 관리 대상 store root 아래의 스냅샷만 삭제합니다. 읽기 전용 HuggingFace 캐시에만 존재하는 모델은 보고만 하고 삭제하지 않습니다.

예시:

mlxcel rm mlx-community/Qwen3-4B-4bit
mlxcel rm mlx-community/Qwen3-4B-4bit --yes
mlxcel rm mlx-community/Qwen3-4B-4bit --models-dir /data/mlxcel-models

mlxcel tune¶

mlxcel tune [OPTIONS]

지원하는 kernel launch configuration을 profile하고 가장 빠르면서 안정적인 선택을 ${MLXCEL_CACHE_DIR:-$HOME/.cache/mlxcel}/autotune에 기록합니다. MLXCEL_AUTOTUNE=cache 또는 MLXCEL_AUTOTUNE=1을 설정하기 전에는 추론에 영향을 주지 않습니다. 성능 튜닝을 참조하십시오.

mlxcel tune --dry-run
mlxcel tune --op paged-decode-splits -m ./models/qwen3-4b-4bit
MLXCEL_AUTOTUNE=cache mlxcel serve -m ./models/qwen3-4b-4bit

mlxcel split-mtp¶

mlxcel split-mtp -m <RAW_CHECKPOINT> -o <DRAFTER_DIR> [OPTIONS]

원본 zai-org/GLM-4.7-Flash 체크포인트에서 GLM-4.7-Flash의 next-token-prediction 계층을 꺼내 독립 glm4_moe_lite_mtp 초안 모델 디렉터리로 씁니다. 커뮤니티 4비트 변환본은 model.layers.47.* 텐서를 버리므로 원본 체크포인트를 입력으로 써야 하며, 도구는 safetensors 인덱스가 이 계층을 담았다고 밝힌 shard만 읽습니다. 결과 디렉터리는 mlxcel generate --draft-model 또는 mlxcel-server --model-draft로 형상이 같은 모든 glm4_moe_lite 대상 모델과 짝을 이룹니다. 이 명령에는 기본으로 켜져 있는 surgery Cargo feature가 필요합니다.

비트 수, 그룹 크기, 출력 경로는 출력 디렉터리를 건드리기 전에 검증합니다.

mlxcel split-mtp -m models/glm-4.7-flash-bf16 -o models/glm-4.7-flash-mtp-4bit --q-bits 4
mlxcel generate -m models/glm-4.7-flash-4bit --draft-model models/glm-4.7-flash-mtp-4bit -p "Hi"

mlxcel prepare-external-ple¶

mlxcel prepare-external-ple -m <CHECKPOINT> -o <VIEW_DIR> [OPTIONS]

PLE n-gram 테이블을 MLX 파라미터에 들고 있지 않고 text_config.ple_storage를 통해 디스크에서 읽는 qwen4_exp 모델 뷰를 만듭니다. 그러면 로드 메모리에서 약 30 GiB가 빠집니다. Python이 필요 없고 mlx-vlm v2 형식으로 매니페스트를 씁니다. 샤드를 하드 링크하므로 출력 디렉터리는 원본과 같은 파일시스템에 있어야 하고, 원본 밖으로 나가는 이름은 거부합니다.

명령은 대상 경로, 행 수, 테이블 크기, 링크한 샤드 수를 출력합니다. OptiQ 2비트 체크포인트에서 이 뷰를 로드하면 상주 메모리는 45.39 GB입니다. 자세한 내용은 외부 가중치 저장소를 참조하십시오.

mlxcel prepare-expert-stream¶

mlxcel prepare-expert-stream -m <CHECKPOINT>

SSD expert 스트리밍이 파일이 있을 때 자동으로 쓰는 연속 expert 파일을 만들고, 체크포인트와 대조해 검증한 뒤 결과를 보고합니다. 파일은 모델 디렉터리 안에 생성됩니다. 체크포인트는 qwen4_exp여야 합니다. 스트리밍 자체는 실행 시 MLXCEL_EXPERT_STREAM(기본값 auto)이 고르고 MLXCEL_EXPERT_ARENA_BYTES가 크기를 정합니다. 외부 가중치 저장소를 참조하십시오.

mlxcel prepare-expert-stream -m models/Qwen3.8-Flash-Next-OptiQ-2bit