Blaizzy/mlx-vlm

MLX-VLM is a package for inference and fine-tuning of Vision Language Models (VLMs) on your Mac using MLX.

MLX‑VLM – Apple MLX에서 시각-언어 모델 추론 및 미세조정

무엇인가요 – mlx‑vlm는 Apple의 MLX 프레임워크를 지원하는 맥에서 현대의 시각-언어 모델(VLM)과 다중모달 '오미니' 모델(이미지 + 오디오 + 비디오)을 로컬로 실행하고 미세조정할 수 있는 Python 패키지입니다. CLI, FastAPI 서버, Gradio 채팅 UI를 포함하며, 모델 변환, 양자화, 추측적 디코딩을 위한 도구 모음도 제공합니다.

핵심 기능

기능	세부 사항
추론	`mlx_vlm.generate`는 텍스트 전용, 이미지, 오디오, 또는 이미지+오디오 조합 프롬프트를 지원합니다.
미세조정	Hugging‑Face 체크포인트를 MLX 형식으로 변환하고 저비트 양자화(4비트, 1비트 아핀, KV 캐시 양자화)를 적용하는 도구(`mlx_vlm.convert`, `mlx_vlm.finetune` – 요약에서는 생략됨)
추측적 디코딩	세 가지 유형의 드래프트 모델 기반 가속화: DFlash/DFlash2/DSpark, Gemma‑4 MTP, EAGLE‑3. 사용자는 `--draft-model`, `--draft-kind`, 그리고 선택적 블록 크기를 지정합니다.
사고 예산	'사고' 블록(``)을 출력하는 모델의 경우, 그 안에서 소비되는 토큰 수를 제한할 수 있습니다(`--thinking-budget`).
서버 / API	`mlx_vlm.server`는 연속 배치, 자동 프리픽스 캐싱, KV 캐시 양자화, 다중모달 엔드포인트(LLM, 이미지 생성, TTS, STT)를 옵션으로 제공하는 FastAPI 서비스를 시작합니다.
채팅 UI	1명령어로 실행 가능한 Gradio 인터페이스(`mlx_vlm.chat_ui`)를 통해 인터랙티브한 다중모달 채팅이 가능합니다.
모델 자료관	수십 종의 VLM용 즉시 실행 가능한 래퍼(예: Qwen2‑VL, Gemma‑4, MiniCPM‑o, Moondream 2/3, Granite Vision, LLaVA‑OneVision 등)를 제공하며, 각 모델마다 README 링크가 포함됩니다.
에이전트 스킬 번들	코딩 어시스턴트(Claude Code, Codex, Gemini)를 위한 미리 준비된 프롬프트를 포함하는 `skills/` 디렉터리로, 변환, 벤치마킹, 이슈 생성 등의 자동화 작업을 지원합니다.

빠른 시작 (CLI)

# 핵심 패키지 설치
pip install -U mlx-vlm
# 옵션: Gradio UI용 추가 패키지
pip install -U 'mlx-vlm[ui]'

# 텍스트 생성
mlx_vlm.generate \
  --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
  --prompt "Hello, how are you?" \
  --max-tokens 100

# 이미지 생성
mlx_vlm.generate \
  --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
  --image http://images.cocodataset.org/val2017/000000039769.jpg \
  --prompt "Describe this image." \
  --max-tokens 100

# 오디오 인식 모델
mlx_vlm.generate \
  --model mlx-community/gemma-3n-E2B-it-4bit \
  --audio /path/to/audio.wav \
  --prompt "What do you hear?" \
  --max-tokens 100

추측적 디코딩 예시 (속도 향상)

mlx_vlm.generate \
  --model Qwen/Qwen3.5-4B \
  --draft-model z-lab/Qwen3.5-4B-DFlash \
  --draft-kind dflash \
  --prompt "Write a quicksort in Python." \
  --max-tokens 512 \
  --temperature 0

드래프트 모델이 각 단계에서 여러 토큰을 제안하고, 타겟 모델이 단일 프로퍼게이션으로 검증함으로써 대규모 모델에서 최대 약 4배의 속도 향상이 가능합니다.

Python 사용 예 (최소 예제)

from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template

model, processor = load("mlx-community/Qwen2-VL-2B-Instruct-4bit")
prompt = "Describe this image."
image = ["http://images.cocodataset.org/val2017/000000039769.jpg"]
formatted = apply_chat_template(processor, model.config, prompt, num_images=1)
output = generate(model, processor, formatted, image)
print(output)

동일한 API는 오디오 또는 이미지+오디오 입력에도 동일하게 적용됩니다.

서버 배포

# 간단한 실행 (기본 포트 8080)
mlx_vlm.server

# 특정 모델 사전 로드
mlx_vlm.server --model mlx-community/Qwen2-VL-2B-Instruct-4bit

# 전역적으로 사고 모드 활성화
mlx_vlm.server --model Qwen/Qwen3.5-4B --enable-thinking

서버는 텍스트 생성, 다중모달 생성, 그리고 선택적 TTS/STT 모델용 엔드포인트를 노출합니다.

왜 중요한가

Apple 우선 – CUDA 없이 Apple Silicon GPU에서 효율적으로 작동하는 MLX 런타임을 활용.
광범위한 다중모달 지원 – 시각, 오디오, 비디오 입력을 처리하며, 이미지 생성 출력도 지원.
성능 최적화 기법 – 추측적 디코딩, KV 캐시 양자화, 1비트 아핀 추론으로 장치 내 속도/메모리 성능이 크게 향상.
개발자 친화성 – CLI, Python API, FastAPI 서버, Gradio UI로 워크플로우 전반을 커버.

도움 받기 / 기여하기

리포지토리는 코딩 어시스턴트 플러그인(Claude Code, Codex, Gemini)용 skills 번들을 제공하며, 일반적인 개발 작업을 자동화합니다.
reproducible-github-issues 스킬을 통해 이슈를 재현 가능한 GitHub 리포트로 변환할 수 있습니다.
기여는 contributing 스킬을 통해 안내되며, 프리커밋 훅과 테스트 배치 확인이 이루어집니다.

TL;DR – mlx‑vlm은 Apple의 MLX를 사용하여 맥에서 시각-언어(및 오디오/비디오) 모델의 실행과 미세조정을 위한 포괄적인 툴킷이며, 풍부한 CLI, Python API, 서버, UI, 그리고 추측적 디코딩과 같은 고급 가속 기능을 제공합니다.