mlx-examples — 읽을 가치 있는 reference library

읽을 가치 있는 reference 라이브러리

ml-explore/mlx-examples 가 MLX 의 canonical reference codebase 에 가장 가까운 것. Repo 가 흔한 모델과 패턴의 reference 구현 모음 — minimal, 잘-주석, 일부러 Python 라이브러리로 패키지 안 됨. pip install mlx-examples 안 해; 읽어.

idiomatic MLX 코드가 어떻게 보이는지 배우려면, mlx-examples 가 내가 가리킬 단일 최고 리소스. 이 quest 의 모든 코드 블록 패턴이 이 repo 의 뭔가에 sanity-check 됨.

북마크할 가치 있는 디렉토리

llms/ — MLX 의 transformer 언어 모델용 canonical 패턴. 새 모델 클래스 박거나 specific architecture 가 어떻게 보여야 할지 궁금하면 첫 읽을 곳.
lora/ — reference LoRA / QLoRA fine-tuning loop, 데이터 로딩 패턴 포함. 뭔가 이상할 때 자기 학습 loop 와 비교.
stable_diffusion/ — reference 이미지-생성 파이프라인. FLUX path 보다 더 오래되지만 diffusion 모델 loop 이해에 여전히 유용.
whisper/ — reference STT 구현. "audio in, 텍스트 out" 의 가장 단순한 end-to-end loop.
mnist/ — 절대 최소 end-to-end 학습 loop. MLX 의 학습 모양에 혼란스러우면 여기서 시작 — 전체 패턴 가르치는 명확한 100 줄 코드.
cifar/ — CIFAR 의 이미지 분류; MNIST 에서 복잡성 한 step 위, 여전히 30 분에 end-to-end 읽기 충분히 작음.
bert/ — encoder-only transformer reference. MLX 에서 BERT-class 모델로 작업해야 할 때 유용.

생산적으로 읽는 법

mlx-examples 를 표지에서 표지로 읽지 마. specific 질문 — "sharded safetensors 로 모델 로드하는 canonical 방법?" 또는 "checkpointing 가진 학습 loop 어떻게 구조?" — 가질 때 열고 가장 가까운 매칭 예제 찾아. 코드가 파일 당 몇 분에 skim 충분히 작고, 패턴이 자기 프로젝트 사이 재사용 가능.

mlx-examples 에 없는 것

Production 패턴. Mlx-examples 는 reference 품질이지 production 품질 아냐 — 진짜 서비스가 필요한 에러 처리, 로깅, queueing, 운영 우려 없는 명확한, minimal 예제 찾을 거. Production 패턴 위해선 Ollama-on-MLX 또는 LM Studio 가 mlx-lm wrap 하는 방식 봐. prod.lesson1 이 FastAPI wrapping 패턴 다룸.

Code

Grep 가능 로컬 reference 위해 mlx-examples 클론·bash

# Optional but useful — clone for local browsing.
git clone https://github.com/ml-explore/mlx-examples.git ~/code/mlx-examples
cd ~/code/mlx-examples

# The directory structure (top level):
ls -d */
# bert/  cifar/  cvae/  llms/  lora/  mnist/  music/  stable_diffusion/  whisper/  ...

# When debugging your own MLX code, grep across the examples:
rg "mx.eval" llms/
rg "value_and_grad" lora/

가장 작은 end-to-end 예제 먼저 읽기·bash

# MNIST is ~100 lines and shows the full training loop end-to-end.
# Read this one first if any of MLX's training shape feels unclear.
cat ~/code/mlx-examples/mnist/main.py | head -80

Exercise

안 했으면 mlx-examples 로컬에 클론. mnist/main.py end to end 읽어 (~100 줄). 그 다음 실제로 하고 있는 거에 매핑되는 다른 디렉토리의 main.py 하나 읽어 — fine-tuning 이면 lora/lora.py, 이미지 생성이면 stable_diffusion/main.py 등. 자기 코드 위해 빌리고 싶다고 알아챈 패턴 두 문장.