콘텐츠로 이동

지원 모델

mlxcel은 체크포인트 메타데이터에서 모델 아키텍처를 자동 감지합니다. config.json의 model_type이 생성 모델 계열의 기본 키이며 architectures, sentence-transformers 풀링 구성, 분류 헤드로 임베딩과 재순위화 체크포인트를 추가로 구분합니다. 특정 바이너리에 들어 있는 정확한 목록은 mlxcel arch로 확인하십시오.

모델별 명령과 하드웨어 지침은 mlxcel 레시피에서 확인할 수 있습니다. 지원하는 각 레지스트리 패밀리의 페이지는 https://mlxcel.ai/ko/recipes/families/<id>/에 있습니다.

현재 Tensor Parallel 런타임

현재 tp_size > 1 런타임은 다음 dense 텍스트 계열에서 사용할 수 있습니다.

계열 model_type 현재 TP 상태 레시피 비고
Llama 계열 llama 지원 레시피 dense Llama-style 경로
Qwen 2 / 2.5 qwen2 지원 레시피 dense Qwen2/Qwen2.5 경로; 가장 작은 tied-embedding 체크포인트는 greedy 24토큰까지 parity 검증
Qwen 3 qwen3 지원 레시피 dense TP 경로; paged 서버 디코드가 기본 활성화
Qwen 3.5 qwen3_5, qwen3.5, 또는 qwen3_5_text 지원 레시피 dense 텍스트 백본만 해당; VLM 패키징 체크포인트도 텍스트 생성에서는 text TP 경로로 로드되며 paged 서버 디코드가 기본 활성화
Gemma 3 gemma3 또는 gemma3_text 지원 레시피 텍스트 전용 Gemma 3 경로; paged 서버 디코드가 기본 활성화
Gemma 4 gemma4 또는 gemma4_text 지원 레시피 텍스트 경로만 해당; dense 31B/E4B와 26B-A4B MoE parity를 검증했고 E2B 계열 VLM 체크포인트는 보수적 TP 폴백으로 처리
ERNIE 4.5 ernie4_5 또는 ernie4.5 지원 레시피 dense ERNIE 4.5만 해당
Hunyuan v1 Dense hunyuan_v1_dense 또는 hunyuan_dense 지원 레시피 dense 경로만 해당

현재 TP 제약:

  • --tp-embedding-mode replicated
  • --tp-lm-head-mode replicated
  • TP + LoRA adapter 미지원
  • dense Llama, Qwen2/2.5, Qwen3, Qwen3.5, Gemma 3 text, Gemma 4 text, ERNIE 4.5, Hunyuan v1 Dense는 TP server batching 활성화
  • 서버 디코드 스토리지는 기본적으로 자동 선택되며 Llama, Qwen 3, Qwen 3.5 text, Gemma 3 text, Llama 4 워커는 기본값으로 paged decode를 사용하고 나머지 계열은 명시적으로 opt-in 하지 않는 한 dense decode를 유지합니다
  • Gemma 4 E2B 계열(num_key_value_heads=1 + per-layer input + KV sharing)은 현재 보수적 폴백을 사용하며 server에서는 sequential 실행으로 강제됩니다

현재 real-model CUDA parity 검증 범위:

  • tp=2: Qwen2.5 0.5B (greedy 24토큰 parity)
  • tp=2: Llama, Qwen 3, Qwen 3.5 0.8B 및 9B, Gemma 3, Gemma 4 E2B (generation smoke), ERNIE 4.5, Hunyuan v1 Dense
  • tp=4: Qwen2.5 7B
  • tp=4: Llama, Qwen 3, Qwen 3.5 4B, 9B, 27B, Gemma 3, Gemma 4 31B / E4B / 26B-A4B, ERNIE 4.5, Hunyuan v1 Dense
  • 추가 Gemma 4 TP smoke 검증: gemma-4-e2b-it-8bit, gemma-4-e4b-it-8bit, gemma-4-31b-it-4bit, gemma-4-31b-it-nvfp4 (F8_E4M3 weight scale은 로드 시 f16으로 변환)

목차

표준 트랜스포머 모델

모델 계열 변형 아키텍처 키 (model_type) 비고
Llama Llama ½/3 및 Mistral ½ llama 또는 mistral 공유 dense runtime
Llama Llama 4 llama4 MoE 변형; VLM 자동 감지
Qwen Qwen 2 / 2.5 qwen2
Qwen Qwen 3 qwen3
Qwen Qwen 3.5 qwen3_5 하이브리드 Transformer + GatedDeltaNet; VLM 자동 감지. Qwen3.8-27B 체크포인트도 이 키를 선언하므로 같은 경로로 로드됩니다. 공급사의 fine-grained FP8 체크포인트(quant_method: fp8, E4M3 가중치와 128x128 블록마다 bf16 역스케일)는 로드 시 텐서 하나씩 MLX mxfp8로 재양자화하며, 다른 FP8 레이아웃은 이름을 밝혀 거부합니다
Gemma Gemma 1 gemma
Gemma Gemma 2 gemma2
Gemma Gemma 3 gemma3 또는 gemma3_text 텍스트 전용 또는 VLM 자동 감지
Gemma Gemma 4 gemma4 또는 gemma4_text 텍스트 전용 또는 VLM 자동 감지
Gemma DiffusionGemma diffusion_gemma 또는 diffusion_gemma_text Gemma 4 MoE 백본 위의 블록 디퓨전 캔버스 디코더; 이미지 입력 지원. 블록 디퓨전 참조
Gemma Gemma 3n gemma3n 또는 gemma3n_text MatMul-Free 변형; VLM 자동 감지
Phi Phi ½ phi 또는 phi-msft
Phi Phi 3 phi3
Phi Phi 3 Small phi3small
Mistral Mistral 3 mistral3 텍스트 전용 또는 VLM 자동 감지
Mistral Mistral 4 mistral4 MLA 텍스트 모델
Youtu Youtu-LLM youtu 또는 youtu_llm DeepSeek-V2 배치의 Multi-head Latent Attention 텍스트 전용 디코더이며, 같은 디코더가 Youtu-VL의 텍스트 타워로도 쓰입니다. rope_interleave가 회전 쌍 배치를 고르고, rope_scaling은 항등 YaRN 블록(factor: 1.0)만 받으며, q_lora_rank는 없어도 됩니다
Ministral Ministral 3 ministral3
Nemotron Nemotron nemotron
DeepSeek DeepSeek (v1) deepseek
DeepSeek DeepSeek V2 deepseek_v2 MoE
DeepSeek DeepSeek V3 deepseek_v3 MoE
DeepSeek DeepSeek V3.2 deepseek_v32 또는 deepseek_v3.2 MoE
DeepSeek DeepSeek V4 deepseek_v4 텍스트 모델. HyperConnections가 일반 잔차 스트림을 대신하고, 어텐션은 64개 쿼리 헤드가 공유하는 512 폭 KV 헤드 하나를 128토큰 회전 윈도 안에서 헤드별 softmax sink와 함께 사용합니다. compress_ratios가 레이어마다 로컬, 풀링, 희소 압축 어텐션을 고르며 희소 레이어에는 top-k 인덱서가 있습니다. 처음 세 MoE 레이어는 토큰 ID 해시(tid2eid)로 라우팅합니다. mlx-community/DeepSeek-V4-Flash-4bit로 검증했습니다
Cohere Command-R cohere
Cohere Command-R v2 cohere2
InternLM InternLM 2 internlm2
InternLM InternLM 3 internlm3
OLMo OLMo 1 olmo
OLMo OLMo 2 olmo2
OLMo OLMo 3 olmo3
SmolLM SmolLM 3 smollm3
MiniCPM MiniCPM minicpm
MiniCPM MiniCPM 3 minicpm3
StableLM StableLM stablelm
Solar Solar Open solar_open
MiMo MiMo mimo
Step Step 3.5 step3p5
GPT GPT-2 gpt2 학습된 절대 위치 임베딩, Conv1D 레이아웃 weight
GPT GPT-BigCode gpt_bigcode multi-query 어텐션 코드 모델
GPT GPT-NeoX gpt_neox 어텐션과 MLP를 병렬 residual로 연결
Kyutai Helium helium
Apple OpenELM openelm 레이어마다 어텐션과 FFN 폭이 달라지는 layer-wise scaling
TeleAI TeleChat3 telechat3
IBM Granite granite Dense Granite text model
Swiss AI Apertus apertus Dense text model
ByteDance Seed-OSS seed_oss Dense text model
BitNet BitNet b1.58 bitnet Ternary-weight architecture
nanochat nanochat d20 / d32 nanochat 가중치 없는 RMSNorm, 미러링된 RoPE, relu(x)^2 MLP, 15로 soft-cap한 logit을 쓰는 GPT-2 형태 디코더. 로드 시 가중치를 bf16으로 유지합니다(f16 변환 없음). 프롬프트는 <\|bos\|>로 시작해야 하며, 동봉된 chat template이 이를 붙이고 --no-chat-template에서는 직접 써야 합니다. <\|assistant_end\|>에서 생성을 멈춥니다. madmag77/nanochat-d20-q8-mlx와 dnakov/nanochat-d20-mlx로 검증했습니다. tensor parallel은 지원하지 않습니다

Mixture-of-Experts(MoE) 모델

모델 계열 변형 아키텍처 키 (model_type) MoE 세부 사항
Mixtral Mixtral 8x7B / 8x22B mixtral Sparse MoE
Qwen Qwen 2 MoE qwen2_moe Sparse MoE
Qwen Qwen 3 MoE qwen3_moe Sparse MoE
Qwen Qwen 3.5 MoE qwen3_5_moe 하이브리드 MoE + GatedDeltaNet; VLM 자동 감지
GPT-OSS GPT-OSS MoE gpt_oss
MiniMax MiniMax minimax Sparse MoE
OLMoE OLMoE olmoe Sparse MoE
Phi Phi MoE phimoe
GLM GLM 4 MoE glm4_moe
GLM GLM 4 MoE Lite glm4_moe_lite GLM-4.7-Flash. next-token-prediction 계층은 mlxcel split-mtp로 만든 별도 MTP 초안 모델로 실행합니다. MTP와 DFlash를 참조하십시오
GLM GLM MoE DSA glm_moe_dsa 이중 희소 어텐션
ERNIE ERNIE 4.5 MoE ernie4_5_moe 또는 ernie4.5_moe
Hunyuan Hunyuan MoE hunyuan (num_experts > 1인 경우) 설정에서 자동 감지
ExaOne ExaOne MoE exaone_moe
Mellum Mellum / Mellum 2 mellum JetBrains 코드 모델. 슬라이딩/풀 하이브리드 어텐션에 레이어마다 sparse softmax-routed MoE와 QK-RMSNorm을 적용
LLaDA-2 LLaDA-2 MoE llada2_moe DeepSeek-V3 스타일 MoE FFN을 갖춘 masked-diffusion LLM. 블록 디퓨전 참조
Cohere Command MoE cohere2_moe Command-R v2 백본 위의 sparse MoE
Databricks DBRX dbrx Sparse MoE
Dots dots.llm1 dots1 Sparse MoE
Ant Group Ling / Bailing MoE bailing_moe Sparse MoE
Arcee AFMoE afmoe Sparse MoE
Kuaishou Klear Klear Sparse MoE. 공개 체크포인트는 키를 대문자로 적는데, 탐지 단계에서 model_type을 소문자로 바꾸므로 Klear와 klear 모두 로드됩니다
MiniMax MiniMax-M3 minimax_m3 block-sparse 어텐션을 쓰는 dense/MoE 하이브리드. VLM 자동 감지
Poolside Laguna XS 2.1 / XS.2 / S 2.1 laguna 코드 모델. full-attention 계층(YaRN, partial rotary)과 512토큰 sliding-window 계층이 번갈아 나오고, 헤드별 softplus 어텐션 출력 게이트와 shared expert를 갖춘 sigmoid 라우팅 top-k MoE를 사용합니다. 공개 NVFP4 체크포인트는 expert를 compressed-tensors nvfp4-pack-quantized 레이아웃으로 저장하며 로드 시 MLX NVFP4로 변환합니다. 미리 쌓은 MLX 변환본과 expert별 bf16 내보내기도 같은 경로로 로드됩니다. 텐서 병렬화는 없습니다. Laguna DFlash 초안 모델을 지원합니다
Phi Phixtral num_local_experts > 1인 phi-msft Phi-2 parallel-residual 백본 위의 Mixtral 스타일 sparse MoE. phixtral 키는 없습니다. dense Phi-2도 같은 phi-msft를 선언하므로 num_local_experts로 구분합니다. 어텐션은 float32로 실행됩니다
Xiaomi MiMo v2 Flash mimo_v2_flash 슬라이딩 어텐션과 full 어텐션을 섞은 sparse 디코더. 48개 레이어, top-8 선택을 쓰는 256개 routed expert, 선택에만 보정 편향을 적용하는 noaux_tc sigmoid 라우터, Q/K(192)와 V(128)의 서로 다른 헤드 폭, 레이어별 partial RoPE, 슬라이딩 레이어의 learned 어텐션 싱크로 구성됩니다. mlx-community/MiMo-V2-Flash-4bit로 검증했고 512 GB M3 Ultra에서 상주 161.8 GiB로 로드됩니다

SSM 및 RNN 모델

모델 계열 변형 아키텍처 키 (model_type) 비고
Mamba Mamba 1 mamba 또는 falcon_mamba State Space Model
Mamba Mamba 2 mamba2 Structured SSM
RWKV RWKV 7 rwkv7 선형 시간 RNN
RecurrentGemma Griffin recurrent_gemma 또는 griffin Recurrent + MLP 레이어

하이브리드 모델

하이브리드 모델은 여러 아키텍처 패러다임을 결합합니다(예: 트랜스포머 어텐션 레이어와 SSM 또는 선형 어텐션 레이어).

모델 계열 변형 아키텍처 키 (model_type) 하이브리드 타입
Jamba Jamba, AI21 Jamba-Reasoning jamba Transformer + Mamba 블록. AI21-Jamba-Reasoning-3B는 항상 <think>를 미리 열므로 max_tokens를 1024 이상으로 설정하십시오. 아래 설명 참고
Nemotron-H Nemotron-H nemotron_h Transformer + SSM
Nemotron-NAS Nemotron-NAS nemotron-nas 신경 아키텍처 탐색 하이브리드
Qwen 3 Next Qwen 3 Next qwen3_next 또는 qwen3next Transformer + GatedDeltaNet
Ling / Ring Bailing linear-attention MoE bailing_moe_linear Transformer + gated linear attention에 sparse MoE FFN. 청크 closed-form prefill이 기본값입니다. MLXCEL_BAILING_LINEAR_CHUNKED_PREFILL 참조
Kimi-Linear Kimi-Linear kimi_linear 선형 트랜스포머
Kimi K3 Kimi K3 kimi_k3 (text_config.model_type: kimi_linear) Kimi Delta Attention 계층과 네 번째 계층마다 NoPE MLA, latent MoE(expert 896개와 shared expert 2개), Attention Residual 블록으로 구성됩니다. compressed-tensors mxfp4 expert는 로드 시 MLX mxfp4로 쌓습니다. 단일 프로세스 전용입니다. 93계층 전체 체크포인트는 4비트에서 약 1.4 TB이고 --pp-size / --pp-layers는 이 계열을 거부합니다. chunked prefill은 이 계열에서 꺼져 있습니다. 토크나이저는 tiktoken 어휘이며, 체크포인트에 Jinja 템플릿이 없어 XTML 채팅 형식을 코드로 렌더링합니다. 비전 타워도 담은 체크포인트는 Kimi K3 VLM으로 로드됩니다
Longcat Flash Longcat Flash longcat_flash 장문 컨텍스트 플래시 어텐션 하이브리드
Longcat Flash Ngram Longcat Flash Ngram longcat_flash_ngram n-gram 투기적 디코딩 포함
Falcon Falcon-H1 falcon_h1 Parallel Mamba2 + attention hybrid
Liquid AI LFM2 lfm2 Short convolution + attention hybrid
Liquid AI LFM2-MoE lfm2_moe Sigmoid-gated expert를 가진 LFM2 hybrid
Preferred Networks PLaMo 2 plamo2 Mamba + attention hybrid
IBM Granite 4 granitemoehybrid Mamba2 + attention interleaved hybrid

AI21-Jamba-Reasoning-3B는 모든 응답을 reasoning_content에서 시작하고, 모델이 </think>를 쓴 뒤에야 답이 content에 들어갑니다. 그 전에 max_tokens 예산이 끝나면 content는 비어 있고 finish_reason은 "length"입니다. 짧은 사실형 답변도 temperature 0에서 completion 토큰 150~450개를 씁니다. 여러 턴 대화에서는 assistant 턴마다 reasoning_content를 다시 보내거나, 프롬프트 캐시가 켜져 있을 때 서버의 reasoning 재삽입에 맡기십시오. 그렇지 않으면 chat template이 이전 턴을 다르게 렌더링해 프롬프트 캐시가 맞지 않습니다.

비전-언어 모델(VLM)

VLM은 config.json에 vision_config 섹션이 있는지 여부로 텍스트 전용 모델과 자동으로 구별됩니다.

VLM model_type을 가진 체크포인트라도 vision_config가 없거나 null 또는 {}이면, language_model_only가 true이면, 혹은 가중치에 vision tower(vision_tower.*, model.visual.* 등의 prefix)가 없으면 텍스트 전용으로 로드합니다. 텍스트 요청은 그대로 실행되고 이미지·비디오 요청은 실패하며, Qwen-VL 계열에서는 model <path> was loaded without a vision tower (text-only checkpoint) 오류를 냅니다. Qwen 3.5에서는 vision 가중치가 있어도 language_model_only: true가 우선하고(stderr에 안내 출력), 불리언이 아닌 값은 로드 시 거부합니다.

모델 계열 변형 아키텍처 키 (model_type) 비전 인코더
Gemma 3 VLM Gemma 3 Vision vision_config가 있는 gemma3 SigLIP 2
Gemma 3n VLM Gemma 3n Vision vision_config가 있는 gemma3n MobileNetV5
Gemma 4 VLM Gemma 4 Vision vision_config가 있는 gemma4 Gemma 4 ViT
Gemma 4 Unified Gemma 4 Unified gemma4_unified Text + vision + audio용 encoder-free patch projection. 한 프롬프트에 비디오와 오디오를 함께 받는 유일한 계열입니다
Llama 4 VLM Llama 4 Scout / Maverick vision_config가 있는 llama4 Llama 4 ViT
Qwen2-VL Qwen2-VL qwen2_vl MRoPE를 사용한 Custom ViT
Qwen2.5-VL Qwen2.5-VL qwen2_5_vl MRoPE를 사용한 Windowed ViT
Qwen3-VL Qwen3-VL qwen3_vl ViT + DeepStack 인터리브 MRoPE
Qwen3-VL-MoE Qwen3-VL-MoE qwen3_vl_moe Qwen3-VL + MoE 텍스트 백본
Qwen 3.5 VLM Qwen 3.5 VLM vision_config가 있는 qwen3_5 Qwen3-VL 인코더. MTP 투기적 디코딩은 텍스트 전용 요청에 적용되며, 이미지나 비디오가 있는 요청은 MTP를 쓰지 않고 일반 디코딩으로 처리합니다
Qwen 3.5 MoE VLM Qwen 3.5 MoE VLM vision_config가 있는 qwen3_5_moe Qwen3-VL 인코더 + MoE
MiMo-V2 MiMo-V2 / V2.5 / V2.6 mimo_v2 MiMo v2 Flash 텍스트 디코더에 mimovl 비전 타워를 얹은 구성. 샤드별 FP8 스케일 그리드를 쓰는 fused QKV, MXFP4 routed expert, 윈도우 블록의 learned per-head 싱크, 공유 Qwen2.5-VL 이미지·비디오 런타임을 사용합니다. 오디오는 지원하지 않습니다. 공개 체크포인트가 개발 장비에 들어가지 않아 실체크포인트 검증은 남아 있고, 로더와 fixture 패리티 테스트로 레이아웃을 검증합니다
Qwen3.8-Flash-Next Qwen 3.8 Flash-Next (Qwen4-Exp) qwen4_exp Qwen 3.5 스타일 GatedDeltaNet 하이브리드 텍스트 스택 위에 얹은 Qwen4-Exp 비전 타워. sigmoid 게이트를 쓰는 shared expert가 있는 512-expert top-10 MoE, 0을 중심으로 둔 RMSNorm 가중치, 저랭크 gated hyper-connection, 인터리브 MRoPE. Qwen Sparse Attention을 네이티브 Metal 프리필과 희소 디코드로 실행합니다. 텍스트, 이미지, 비디오 입력을 받습니다. 외부 n-gram table(text_config.ple_storage)은 유한한 row cache 뒤에서 디스크에 두고, routed expert는 Metal에서 SSD에서 스트리밍하며, 프롬프트 캐시 snapshot은 sequence별 상태 전체를 복원합니다. 대상 변환에 포함했거나 따로 분리한 native MTP head를 drafter로 짝지을 수 있습니다. FP8 체크포인트는 로드에서 거부합니다
Cohere Compass North-Micro-Vision cohere_compass DeepStack merger를 쓰는 Qwen3-VL 타워 + Command 계열 parallel decoder
Youtu-VL Youtu-VL youtu_vl SigLIP2 windowed-attention 인코더 + DeepSeek-V3 스타일 MLA
InternVL InternVL Chat internvl_chat InternViT + pixel-shuffle connector + Qwen2 text
LLM-jp-VL LLM-jp-4 VL / Jagle-VL llmjpvl SigLIP2-so400m + InternVL 방식 dynamic tiling + pixel-shuffle connector. 텍스트 백본은 Llama 또는 Qwen3
LLaVA LLaVA / LLaVA-Next llava 또는 llava_next CLIP 또는 SigLIP + Llama/Qwen2
LLaVA-Bunny LLaVA-Bunny llava_bunny, bunny-llama, llava-qwen2 SigLIP + Qwen2
Aya Vision Aya Vision aya_vision SigLIP + Cohere2
PaliGemma PaliGemma ½ paligemma SigLIP + Gemma
Pixtral Pixtral pixtral 2D RoPE를 사용한 ViT + Mistral
Mistral 3 VLM Mistral 3 Vision vision_config가 있는 mistral3 Pixtral ViT + PatchMerger
Phi 3.5 Vision Phi 3.5 Vision phi3_v CLIP + Phi 3
Phi 4 MM Phi 4 Multimodal phi4mm SigLIP2 NaFlex + Phi4 (이미지 전용)
Phi 4 SigLIP Phi 4 Reasoning Vision phi4-siglip SigLIP2 NaFlex + Phi3 스타일 텍스트
Molmo Molmo v1 molmo CLIP ViT + attention pooling + OLMo-style text
Molmo2 Molmo2 molmo2 Custom ViT + 어텐션 풀링
Molmo-Point Molmo-Point molmo_point point-prediction head를 갖춘 Molmo2 스타일 비전 스택
MiniCPM-o MiniCPM-o minicpmo Dynamic SigLIP + 리샘플러 + Qwen3-VL 텍스트
MiniCPM-V 4.6 MiniCPM-V 4.6 minicpmv4_6 SigLIP + VitMerger + Merger + Qwen3.5 텍스트
Moondream3 Moondream3 moondream3 Custom ViT + 커스텀 텍스트 디코더
Moondream2 Moondream2 moondream2 (moondream1도 동일) Moondream3 ViT + dense Phi 텍스트
Nemotron H Nano Omni Nemotron H Nano Omni nemotron_h_nano_omni 또는 nemotronh_nano_omni_reasoning_v3 비전 지원 Nemotron-H 변형. 오디오 경로가 있으면 함께 로드됩니다.
Llama 3.2 Vision mllama mllama 게이트형 크로스어텐션 레이어를 Llama-3 텍스트 백본에 끼워 넣은 타일형 ViT
GLM-4V GLM-4V glm4v GLM-4V ViT(3D 패치 임베딩 + SwiGLU 머저) + 섹션형 even/odd MRoPE를 쓰는 GLM-4 텍스트
GLM-4V MoE GLM-4.5V 계열 glm4v_moe GLM-4V ViT + 섹션형 half-split MRoPE를 쓰는 GLM-4 MoE 텍스트
GLM-OCR GLM-OCR glm_ocr GLM-4V 스타일 ViT(OCR 특화) + GLM-4 텍스트
SmolVLM / SmolVLM2 / Idefics3 SmolVLM 계열 smolvlm, smolvlm2, 또는 idefics3 SigLIP + 픽셀 셔플 토큰 압축 + Llama/SmolLM2 텍스트. 두 온디스크 레이아웃을 하나의 런타임으로 처리
Idefics2 Idefics2 idefics2 SigLIP + perceiver-resampler 커넥터 + Mistral 텍스트
PaddleOCR-VL PaddleOCR-VL paddleocr_vl NaViT 동적 해상도 SigLIP 스타일 인코더 + MRoPE를 쓰는 ERNIE-4.5 텍스트
dots.ocr dots.ocr dots_ocr dots_vit 동적 해상도 ViT + Qwen2 텍스트 디코더
Kimi-VL / Kimi-VL 2.5 Kimi-VL kimi_vl (kimi_k25도 동일) MoonViT native-resolution 인코더 + DeepSeek-V3 스타일 MoE 텍스트. 3D MoonViT patch embedding이 이미지와 비디오를 함께 처리하므로 비디오 입력도 받습니다
Kimi K3 VLM Kimi K3 vision_config와 vision_tower.* 텐서가 있는 kimi_k3 Kimi K3 텍스트 백본 앞에 놓인 MoonViT3D native-resolution 타워 + patchmergerv2 프로젝터. 고유 비디오 경로가 없어 클립은 비디오 프레임 대체 경로를 거쳐 순서가 있는 이미지로 들어갑니다. 한 요청의 이미지는 합쳐서 media token 32768개까지 쓸 수 있습니다(MLXCEL_KIMI_K3_MAX_MEDIA_TOKENS)
LFM2-VL LFM2-VL lfm2_vl 또는 lfm2-vl 패치 패킹 SigLIP2 ViT + 픽셀 언셔플 프로젝터 + LFM2 하이브리드 텍스트
Granite Vision Granite Vision granite_vision (또는 Granite 텍스트 설정을 가진 llava_next) 중간 특징 4개 지점을 뽑는 SigLIP + Granite 텍스트
Granite 4 Vision Granite 4 Vision granite4_vision SigLIP + 8개의 window-QFormer 프로젝터를 Granite 4 하이브리드 텍스트 백본에 주입
DeepSeek-OCR DeepSeek-OCR deepseekocr SAM 스타일 ViT-B + CLIP 스타일 ViT-L + DeepSeek MoE 디코더
DeepSeek-OCR 2 DeepSeek-OCR 2 deepseekocr_2 SAM 스타일 ViT-B + Qwen2 형태 쿼리 리샘플러 + DeepSeek MoE 디코더
GOT-OCR 2.0 GOT-OCR2_0 GOT 고정 1024x1024 캔버스의 SAM 스타일 ViT-B(페이지당 특징 행 256개) + Qwen2-0.5B 디코더. 요청당 이미지 한 장만 받습니다. 체크포인트에 채팅 템플릿이 없어 mlxcel이 고정 OCR 대화를 제공하며, 지시문이 모드를 정합니다(OCR:, OCR with format:, [x1,y1,x2,y2] 영역, [red] 색 표시 영역)
DeepSeek-VL2 DeepSeek-VL2 deepseek_vl_v2 (deepseek_vl2도 동일) SigLIP 스타일 ViT + DeepSeek-V2 MoE(MLA) 디코더
FastVLM FastVLM fastvlm 또는 llava_qwen2 FastViTHD 하이브리드 인코더 + Qwen2 텍스트
ERNIE-4.5 MoE VL ERNIE-4.5 MoE VL ernie4_5_moe_vl 또는 ernie4.5_moe_vl DFNRope ViT + 가변 해상도 리샘플러 + 3D MRoPE를 쓰는 modality-split MoE 텍스트
Hunyuan-VL Hunyuan-VL(예: HunyuanOCR) hunyuan_vl perceive 머저를 가진 ViT + XD-RoPE를 쓰는 Hunyuan dense 텍스트
Qwen3-Omni MoE Qwen3-Omni(thinker + talker) qwen3_omni_moe Qwen3-VL-MoE 비전/텍스트 스택 + 오디오 타워. --output-audio로 talker + code2wav 보코더 음성 출력도 선택 가능
MiniMax-M3-VL MiniMax-M3-VL minimax_m3_vl ViT + block-sparse 어텐션을 쓰는 MiniMax-M3 dense/MoE 하이브리드 텍스트
Unlimited-OCR Unlimited-OCR unlimited_ocr (unlimited-ocr도 동일) OCR 지향 인코더 + ring sliding 디코드 캐시
Florence-2 Florence-2 base-ft florence2 DaViT 타워 + BART 인코더-디코더. 자기회귀가 아니라 seq2seq입니다. 비전-언어 모델 참조
LocateAnything LocateAnything 3B locateanything MoonViT native-resolution 타워 + Qwen2 텍스트. 생성형 그라운딩이라 박스가 <box>와 좌표 토큰 형태로 일반 텍스트 스트림에 실려 나옵니다
Falcon-OCR Falcon-OCR 300M falcon_ocr 비전 타워가 없습니다. 16x16 패치를 선형 프로젝터 하나로 통과시켜 곧바로 토큰 스트림에 넣고, 하이브리드 마스크 디코더 하나가 이미지와 텍스트를 함께 읽습니다
Jina VLM jina-vlm jvlm (jina_vlm도 동일) SigLIP-so400m 계열 ViT + Molmo 스타일 풀링 커넥터 + OLMo 텐서 레이아웃의 Qwen2 계열 텍스트
Muse Glimmer Meta Muse Glimmer 30B muse_glimmer dense BF16과 고정(pinned) affine Q4 체크포인트를 모두 지원합니다. 단일 프로세스 전용이라 TP와 PP가 없습니다. 투기적 디코딩은 mlxcel-server에서 전용 DFlash 보조 초안 모델로, 텍스트 전용 요청에만 동작합니다
Step Step-3.7 step3p7 Perception encoder ViT + Step-3.5 MoE text
Mage-VL Mage-VL 4B mage_vl (MageVLForConditionalGeneration) Qwen2-VL smart_resize(patch 16, 2x2 merge)를 쓰는 Mage-ViT tower + 1-D RoPE Qwen3-4B 디코더. 이미지 입력만 지원합니다. microsoft/Mage-VL과 mlx-community/Mage-VL-8bit로 검증했습니다. codec-native 비디오, 프레임 샘플링 비디오, LoRA, tensor parallel은 지원하지 않습니다
Inkling Inkling(텍스트) / Inkling VLM inkling_mm_model 또는 inkling 슬라이딩과 전역 NoPE 어텐션을 섞은 하이브리드 구조에, 학습된 밴드형 상대 위치 로짓과 라우팅 및 공유 전문가를 갖춥니다. bf16/f32 가중치, ModelOpt NVFP4 전문가 평면, 변환된 affine 4비트 전문가를 로드합니다. VLM 형태(vision_config와 비전 가중치로 감지)는 이미지, 비디오, 오디오(dMel) 입력을 받습니다. 두 형태 모두 네이티브 체인형 MTP 드래프터가 있습니다(MTP와 DFlash 참조)
Nemotron-Parse Nemotron-Parse 2.0 nemotron_parse C-RADIOv2-H tower + mBART 디코더. Florence-2처럼 자체 CLI driver와 단일 스트림 서버 worker를 쓰는 인코더-디코더(seq2seq) 문서 OCR·레이아웃 모델입니다. 요청당 이미지 하나. 비전-언어 모델 참고

오디오 모델

오디오 전용 체크포인트는 text-generation worker를 사용하지 않습니다. 전용 서버를 시작하고 OpenAI 오디오 API를, Nemotron VoiceChat이라면 Realtime VoiceChat API를 사용하십시오.

모델 감지 방향 현재 제한
Whisper model_type: whisper (whisper) 음성 전사와 영어 번역 WAV 입력, fp16/f32 가중치, greedy decoding
Kokoro-82M istftnet 설정 또는 kokoro-v1_0.safetensors 음성 합성 미국 영어 G2P, WAV 출력, voices/ 아래 voice pack
Nemotron VoiceChat model_type: nemotron_voicechat 전이중 음성 대 음성(16 kHz 입력, 22.05 kHz 출력, 80 ms 프레임) 내장 Aria 음성만 지원, 배치 1. 오프라인은 mlxcel generate --audio로 실행하고, 서버에서는 /v1/realtime WebSocket으로만 한 번에 한 세션씩 서비스

지역 및 특수 목적 모델

모델 계열 변형 아키텍처 키 (model_type) 비고
Baichuan Baichuan M1 baichuan_m1
GLM GLM 4 glm4
ERNIE ERNIE 4.5 ernie4_5 또는 ernie4.5
Hunyuan Hunyuan Dense hunyuan_v1_dense 또는 hunyuan_dense
Hunyuan Hunyuan (자동) num_experts == 1인 경우 hunyuan Dense 자동 감지
ExaOne ExaOne exaone 한국어 LLM
ExaOne ExaOne 4 exaone4

임베딩 모델

임베딩 체크포인트는 텍스트 생성이 아니라 mlxcel embed 또는 임베딩 서버 경로로 실행합니다. 인코더 전용 model_type, 알려진 임베딩 아키텍처, sentence-transformers 풀링 모듈, 1_Pooling/config.json을 검사하여 감지합니다. 서빙 방법은 임베딩 및 재순위화 API, 모델 계약은 임베딩과 재순위화를 참고하십시오.

밀집 텍스트 임베딩

계열 감지 키 풀링 검증한 체크포인트 레시피
BERT / MiniLM bert 체크포인트 지정, 주로 평균 sentence-transformers/all-MiniLM-L6-v2; intfloat/multilingual-e5-small 레시피
XLM-RoBERTa xlm-roberta 체크포인트 지정, 주로 CLS BAAI/bge-m3 레시피
ModernBERT modernbert 체크포인트 지정 또는 평균 기본값 nomic-ai/modernbert-embed-base 레시피
SigLIP 텍스트 타워 siglip 고정된 마지막 위치 google/siglip-base-patch16-224; 텍스트 전용 레시피
EmbeddingGemma gemma3_text 또는 양방향 gemma3 아키텍처 평균 뒤 밀집 사영 두 번 mlx-community/embeddinggemma-300m-4bit 레시피
Qwen3-Embedding qwen3 임베딩 아키텍처·레이아웃 마지막 토큰 Qwen/Qwen3-Embedding-0.6B 레시피
양방향 Llama / LLM2Vec llama_bidirec 또는 LlamaBidirectionalModel 평균 nvidia/llama-nemotron-embed-1b-v2 레시피
Nemotron-3-Embed 비인과적 ministral3 평균 nvidia/Nemotron-3-Embed-1B-BF16 레시피
LFM2.5-Embedding Lfm2BidirectionalModel을 쓰는 lfm2 CLS LiquidAI/LFM2.5-Embedding-350M 레시피

멀티모달 및 후기 상호작용 임베딩

계열 감지 키 출력 검증한 체크포인트 레시피
Qwen3-VL-Embedding qwen3_vl 임베딩 아키텍처 텍스트·이미지마다 풀링 벡터 하나 Qwen/Qwen3-VL-Embedding-2B 레시피
Llama-Nemotron-VL-Embed llama_nemotron_vl 텍스트·이미지마다 풀링 벡터 하나 nvidia/llama-nemotron-embed-vl-1b-v2 레시피
EmbeddingGemma 2 embedding_gemma2, embedding_gemma2_text, 또는 EmbeddingGemma2Model 텍스트마다 풀링 벡터 하나. 체크포인트에 vision tower가 있으면 이미지 벡터도 반환. 모델 내부 projection 512에서 768, mean pooling, L2 정규화, Matryoshka 768 / 512 / 256 / 128 google/embeddinggemma-2, mlx-community/embeddinggemma-2-bf16(로드 시 bf16 유지) 레시피
ColIdefics3 idefics3, ColIdefics3 토큰마다 정규화한 128차원 벡터 검색 가중치를 병합한 vidore/ColSmolVLM-Instruct-256M-base 레시피
ColQwen2.5 qwen2_5_vl 또는 colqwen2 검색 아키텍처 토큰마다 정규화한 128차원 벡터 검색 가중치를 병합한 vidore/colqwen2.5-base 레시피

Qwen3-VL-Embedding, Llama-Nemotron-VL-Embed, EmbeddingGemma 2는 이미지마다 벡터 하나를 반환하며, embedding_gemma2_text처럼 vision tower가 없는 EmbeddingGemma 2 체크포인트는 이미지 입력을 거부합니다. ColIdefics3와 ColQwen2.5는 토큰 벡터 행렬을 반환하므로 최대 유사도 합산으로 순위를 매겨야 합니다. LoRA 어댑터만 있는 후기 상호작용 저장소는 거부되며 완전한 체크포인트로 먼저 병합해야 합니다. SigLIP 임베딩 계열은 텍스트 타워만 제공합니다.

재순위화 모델

재순위화 모델은 mlxcel rerank 또는 재순위화 서버 경로로 실행합니다. 지원하는 모든 종류는 [0, 1] 범위의 관련도 점수를 반환합니다.

계열 선택 방법 점수 검증한 체크포인트 레시피
BERT 교차 인코더 레이블 하나짜리 BertForSequenceClassification; -m에서 자동 감지 sigmoid(logit) cross-encoder/ms-marco-MiniLM-L6-v2 레시피
XLM-RoBERTa 교차 인코더 레이블 하나짜리 XLMRobertaForSequenceClassification; -m에서 자동 감지 sigmoid(logit) BAAI/bge-reranker-v2-m3 레시피
ModernBERT 교차 인코더 레이블 하나짜리 ModernBertForSequenceClassification; -m에서 자동 감지 sigmoid(logit) Alibaba-NLP/gte-reranker-modernbert-base 레시피
Qwen3 생성형 재순위화 명시적인 --reranker-model sigmoid(logit("yes") - logit("no")) mlx-community/Qwen3-Reranker-0.6B-4bit 레시피
Qwen3-VL 멀티모달 재순위화 명시적인 --reranker-model 텍스트·이미지에서 같은 예·아니요 점수 Qwen/Qwen3-VL-Reranker-2B 레시피

레이블 하나짜리 시퀀스 분류기만 -m에서 재순위화 모델로 자동 감지할 수 있습니다. 생성형 체크포인트는 감지 시점에 일반 생성 모델과 구분할 수 없으므로 명시적인 보조 옵션으로 순위화 의미를 선택합니다. Qwen3-VL은 이미지가 든 질의와 문서를 지원하고 이미지 행을 하나씩 처리하며 비디오는 재순위화하지 않습니다.

객체 검출 모델

객체 검출 모델은 토큰 스트림을 내보내지 않습니다. 전용 mlxcel detect 명령을 사용하면 체크포인트를 로드하고 이미지 processor를 실행한 뒤 바운딩 박스를 text 또는 JSON 형식으로 출력합니다.

모델 계열 변형 감지 키 비고
RT-DETRv2 RT-DETRv2 / Docling layout 체크포인트 architectures: ["RTDetrV2ForObjectDetection"] 또는 호환 RT-DETRv2 설정 사전 변환된 MLX 체크포인트와 원본 HuggingFace RT-DETRv2 가중치를 모두 지원하며 HF 가중치는 로드 시 MLX 레이아웃으로 변환됩니다.
YOLO11 OmniParser v2 아이콘 검출 model_type: yolo11 OmniParser v2 icon_detect 고정 토폴로지. C3k2 백본, SPPF, C2PSA 넥, stride 8·16·32의 anchor-free DFL 헤드를 씁니다. ch와 stride가 토폴로지와 일치하는 변환 MLX 체크포인트를 받고, --threshold 기본값은 0.05, --size는 letterbox 전 가장 긴 변, --iou는 NMS 임계값(기본 0.1, 최대 300개 박스)입니다. axiom-of-choice/OmniParser-v2-icon-detect로 검증했습니다

예시:

mlxcel detect -m mlx-community/docling-layout-heron-mlx-bf16 -i page.png --format json
mlxcel detect -m axiom-of-choice/OmniParser-v2-icon-detect -i ui.png --size 1280 --format json

고밀도 예측과 토큰 단위 모델

체크포인트 계열 셋이 더 있으며, 이들은 채팅 토큰 스트림을 만들지 않고 각자 전용 서브명령어를 가집니다.

표면 서브명령어 패밀리 안내
깊이, 노멀, 세그멘테이션, 포인트 맵, 키포인트, 마스크, 메시 mlxcel predict DINOv2, Sapiens2, SAM 3와 SAM 3.1, Video Depth Anything, MoGe3, SAM 3D Objects, SAM 3D Body 고밀도 예측과 비전 태스크
객체 박스, 선택적으로 인스턴스 마스크 포함 mlxcel detect RT-DETRv2, PP-DocLayoutV3, RF-DETR Base와 Seg Small(--masks-dir) CLI 레퍼런스
고정 레이블 토큰 분류와 요청 시점 스팬 추출 mlxcel tag, mlxcel extract BERT / XLM-RoBERTa ForTokenClassification, OpenAI Privacy Filter, GLiNER2.5 토큰 분류와 스팬 추출

이미지 생성 체크포인트는 네 번째 표면(mlxcel generate-image, 그리고 --image-model로 켜는 /v1/images/generations, /v1/images/edits)입니다. 패밀리는 FLUX.2 Klein(flux2), Z-Image(z_image), Prism Bonsai 삼진 FLUX.2 Klein(bonsai), ERNIE-Image(ernie_image), Mage-Flow(mage_flow), Qwen-Image-2.1(qwen_image), Ideogram 4(ideogram4), Ming-Image-0.1-Design(ming_image), LLaDA-Image(llada_image)입니다. 체크포인트, 작업, 기본 단계 수는 이미지 생성에 있습니다.

페이지 OCR 파이프라인은 별도 하위 명령 대신 mlxcel generate로 문서를 통째로 처리합니다. IndicOCR(indic_ocr)은 PP-DocLayoutV3 레이아웃 단계와 Qwen3.5-0.8B 블록 전사 단계를 조합해 영어와 인도 언어 22종을 읽고, 읽기 순서대로 정리한 Markdown이나 블록 JSON을 반환합니다.

mlxcel generate -m HashNuke/indic-ocr-mlx --image page.png --output-json page.json

--table-format markdown은 표를 HTML 대신 GitHub-flavored Markdown으로 렌더링하고, -n/--max-tokens는 블록당 기본값 2048 토큰을 덮어씁니다. 각 영역의 지시문이 레이아웃 클래스에서 오므로 프롬프트는 쓰지 않습니다. --layout-detections FILE을 주면 레이아웃 단계를 다시 돌리지 않고 mlxcel detect가 출력한 검출 JSON을 재사용합니다.

코드 모델

모델 계열 변형 아키텍처 키 (model_type) 비고
StarCoder StarCoder 2 starcoder2 코드 생성
IQuest IQuest-Coder V1 Loop iquestloopcoder 40B-Loop Instruct와 Thinking 체크포인트이며 architectures: ["IQuestLoopCoderForCausalLM"]으로도 감지됩니다. 같은 토큰에 같은 가중치로 계층을 두 번 실행하는 Llama 형태 디코더입니다. 두 번째 패스에서 각 계층은 첫 번째 패스의 K/V에 대한 어텐션과 자신의 K/V에 대한 64토큰 sliding window 어텐션을 헤드별 sigmoid 게이트로 섞습니다. loop_num: 2만 받습니다. KV 캐시 모드는 FP16만 지원하며 --max-kv-size는 첫 번째 패스 캐시를 제한하지 않습니다
IQuest IQuest-Coder V1 iquestcoder 7B / 14B / 40B Base, Instruct, Thinking 체크포인트가 공유 Llama 디코더를 자체 라벨로 사용합니다. llama로 라벨을 바꾼 체크포인트도 architectures: ["IQuestCoderForCausalLM"]로 감지됩니다. 공유 디코더가 구현하지 않는 non-null clip_qkv나 활성 슬라이딩 윈도는 로드 시 거부합니다. 파이프라인 병렬화는 가능하고 텐서 병렬화는 지원하지 않습니다

모델 감지

아키텍처 감지는 src/models/detection.rs에서 수행합니다. 생성 모델 계열은 주로 config.json::model_type으로 결정하고 과제 종류 감지는 먼저 임베딩 배치와 지원되는 레이블 하나짜리 시퀀스 분류 헤드를 확인하여 생성 경로로 잘못 보내지 않게 합니다.

텍스트 전용 및 비전-언어 변형이 모두 있는 모델(Gemma 3, Llama 4, Qwen 3.5, Mistral 3, Gemma 3n)의 경우 감지가 자동으로 이루어집니다:

if config.json contains "vision_config" key
    => load as VLM
else
    => load as text-only model

Florence-2는 인코더-디코더 계열입니다. 감지는 model_type: florence2로 동일하게 이뤄지지만 공용 자기회귀 루프에는 합류하지 않습니다. mlxcel generate는 전용 seq2seq 파이프라인을 돌리고, mlxcel-server는 배치·paged 스케줄러 대신 전용 단일 스트림 워커로 이 계열을 서빙합니다. Nemotron-Parse(model_type: nemotron_parse)도 같은 방식을 따릅니다.

Hunyuan 계열의 경우 num_experts를 기반으로 감지합니다:

if num_experts > 1  => HunyuanMoe
else                => HunyuanV1Dense

임베딩 감지는 인코더 전용 계열, 알려진 임베딩 아키텍처 이름, sentence-transformers 풀링 모듈, 1_Pooling/config.json도 인식합니다. 지원되는 ForSequenceClassification 아키텍처는 임베딩 규칙보다 먼저 재순위화를 선택합니다. 생성형 Qwen3 및 Qwen3-VL 재순위화 모델의 설정은 일반 생성 설정이므로 --reranker-model이 필요합니다.

양자화 형식

양자화 정보는 config.json의 quantization 블록에서 읽습니다. mlxcel은 affine 4-bit·8-bit와 MXFP4, MXFP8, NVFP4 모드 외에 affine 1-bit 체크포인트(bits: 1, group_size 32·64·128, .scales와 .biases 포함)도 로드합니다. Metal은 전용 1-bit fused kernel로 실행하고, CUDA와 ROCm은 dequantize 그래프로 실행합니다. 1-bit는 dense linear와 embedding에만 허용되며, 1-bit MoE expert stack, 1-bit MLA head별 projection, .biases가 없는 1-bit plane은 로드 시 거부합니다. Metal에서도 MLXCEL_ONE_BIT_KERNEL=0이면 dequantize 그래프를 씁니다. prism-ml/Bonsai-1.7B-mlx-1bit와 prism-ml/Bonsai-8B-mlx-1bit(qwen3)로 검증했습니다. 백엔드별 동작은 양자화 지원을 참고하십시오.

세밀한 FP8 허브 빌드(quantization_config: {"quant_method": "fp8", "fmt": "e4m3", "weight_block_size": [128, 128]})와 llm-compressor의 compressed-tensors float-quantized 내보내기도 로드합니다. mlxcel은 E4M3 원본 바이트를 블록 또는 채널 스케일로 복원한 뒤 텐서 하나씩 MLX 네이티브 mxfp8로 다시 양자화합니다. compressed-tensors는 출력 채널별 스케일과 블록 스케일을 모두 받고, strategy: "tensor"나 "group", 다른 num_bits, 동적 가중치는 이름을 붙인 로드 오류로 거부합니다. RedHatAI/Qwen3.5-4B-FP8-dynamic을 bf16 원본과 대조해 검증했으며, 채널 스케일을 적용하지 않은 추적은 첫 위치에서 non-finite 로짓을 내므로 스케일은 동작에 필수입니다.

새 모델 추가하기

전체 체크리스트는 새 모델 추가하기 가이드를 참조하십시오.