mlx_lm.convert — Hugging Face 모델을 MLX에 맞게 · MLX Quest

언제 직접 변환하나

Hugging Face의 많은 LLM은 PyTorch 방식의 가중치 이름을 쓰는 safetensors로 저장돼. MLX는 같은 가중치를 MLX가 기대하는 이름으로 바꾸고, 흔히 양자화까지 적용해야 해. mlx_lm.convert는 원본 모델을 읽어 mlx_lm.load가 바로 쓸 폴더로 만드는 도구야.

mlx-community에는 이미 변환한 인기 모델이 많아서 보통 직접 할 필요는 없어. 원하는 모델이 없거나, 남들이 올리지 않은 양자화가 필요하거나, 직접 파인튜닝한 결과를 배포할 때 변환해.

명령 하나로 끝나

명령줄에서 Hugging Face 모델을 받고, 필요하면 양자화하면서 변환해 디스크에 쓰면 돼.

알아둘 선택지

--hf-path 또는 --model — meta-llama/Llama-3.2-1B-Instruct 같은 Hugging Face 저장소 ID나 로컬 폴더를 지정해.
--mlx-path — MLX 형식 결과를 쓸 곳이야. 기본값은 현재 폴더 아래의 알맞은 경로야.
-q / --quantize — 변환 중 가중치를 양자화해. 빼면 보통 bf16이나 fp16인 원래 정밀도를 지켜.
--q-bits — 가중치 하나의 비트 수야. 보통 4나 8을 쓰고 -q의 기본은 4야.
--q-group-size — 양자화 묶음의 크기야. 작은 값은 품질이 좋고 파일이 커져. 흔한 값은 32, 64, 128이야.
--q-mode — 전통적인 affine 또는 맞는 칩에서 가속되는 mxfp4, nvfp4, mxfp8 같은 MX 형식을 골라.
--quant-predicate — 레슨 4의 혼합 정밀도 방식을 고르는 값이야. mixed_3_4라면 어떤 층은 3비트, 나머지는 4비트로 둬.
--dtype — 양자화하지 않은 가중치를 float16, bfloat16, float32 가운데 무엇으로 저장할지 정해.
--upload-repo — 변환 결과를 Hugging Face 저장소에 올려. 먼저 huggingface-cli login이 필요해.
-d / --dequantize — 반대로 양자화한 MLX 모델을 전체 정밀도 가중치로 되돌려.
--trust-remote-code — 별도 모델링 코드를 가진 일부 모델에 필요하지만 신중히 써.

조용히 실패하는 함정을 막아

원본 config.json에 특이한 rope-scaling 설정이나 비표준 model_type처럼 mlx-lm이 필요한 값이 빠졌다면 변환은 끝나도 나중에 알 수 없는 키 오류로 불러오지 못할 수 있어. 결과를 믿기 전에 python -c "from mlx_lm import load, generate; m, t = load('./my-converted'); print(generate(m, t, prompt='hi', max_tokens=5))"로 시험해. 5초로 한 시간을 아껴.

Code

Hugging Face의 작은 Llama 모델을 변환하고 Q4로 양자화하기(실행 가능한 예시지만 mlx-quest 시연에서는 건너뛰어)·bash

# This downloads the original model from meta-llama (requires HF auth + license accept)
# and writes a Q4 MLX-format copy locally. Don't run unless you actually want to convert.
python -m mlx_lm convert \
  --hf-path meta-llama/Llama-3.2-1B-Instruct \
  --mlx-path ./Llama-3.2-1B-Instruct-MLX-Q4 \
  --quantize \
  --q-bits 4 \
  --q-group-size 64

# After conversion, the local directory looks just like the inspected files in lesson 1:
ls ./Llama-3.2-1B-Instruct-MLX-Q4/
# config.json  model.safetensors  tokenizer.json  tokenizer_config.json  ...

빠른 동작 확인 — 실제로 불러와 생성할 수 있나?·python

# Always test-load before trusting a freshly converted model.
from mlx_lm import load, generate

model, tok = load("./Llama-3.2-1B-Instruct-MLX-Q4")
print(generate(model, tok, prompt="Hi.", max_tokens=10, verbose=False))

# If this raises a key error, the conversion's config.json is missing something
# the loader expects — diff against a known-working mlx-community config.

선택 사항 — 변환한 모델을 자신의 Hugging Face 저장소에 올리기·bash

# Requires `huggingface-cli login` first.
python -m mlx_lm convert \
  --hf-path meta-llama/Llama-3.2-1B-Instruct \
  --mlx-path ./Llama-3.2-1B-Instruct-MLX-Q4 \
  --quantize --q-bits 4 \
  --upload-repo your-username/Llama-3.2-1B-Instruct-MLX-Q4

# The upload includes a generated README with the source repo,
# the conversion command, and the quantization config — so others
# can reproduce or audit the conversion.

Exercise

mlx-community에 없는 작은 지시 학습 모델이나 직접 양자화하고 싶은 모델을 골라. mlx_lm.convert로 Q4와 Q8 결과 폴더를 각각 만들어. 디스크 크기를 비교하고 같은 프롬프트로 짧게 생성해. Q8이 Q4보다 디스크에서 약 두 배 큰지, 출력 품질은 알아볼 만큼 다른지 확인하고 두 문장으로 적어.

mlx_lm.convert — Hugging Face 모델을 MLX에 맞게