mlx-vlm — MLX 의 Vision-Language Model

MLX 의 Vision-Language Model

mlx-vlm 이 vision-language 모델용 MLX-native 패키지 — 이미지 (또는 video frame) 와 텍스트 prompt 받아 텍스트 만드는 모델. Apple-Silicon-친화 tier 의 현재 best-of-class 가 Qwen-VL 가족 모델, LLaVA 파생물, 더 작은 multimodal Llama 들.

모양이 mlx-lm 의 거와 평행 — load 가 model + processor 돌려줌; generate 가 prompt + 이미지 받고 텍스트 돌려줌. 유일한 진짜 새 조각은 이미지 전처리, 대부분 VLM 튜토리얼이 첫 시도에 잘못하는 부분.

설치 + 최소 loop

mlx env 의 pip install mlx-vlm. CLI 가 python -m mlx_vlm.generate; Python API 가 이미지 처리하는 processor 객체로 mlx_lm 의 모양 mirror.

모두가 잘못하는 이미지 전처리 디테일

VLM 이 specific 이미지 해상도와 specific normalization (mean/std) 에 학습됨. 잘못된 해상도로 이미지 전달하거나 normalization 건너뛰면, 모델이 여전히 출력 만들어 — 보통 그럴듯하게 worded, 완전 환각. mlx-vlm 이 load() 에서 돌려주는 processor 객체가 너 위해 이 모든 거 처리 — 그 API 사용할 때. 사람들이 자기가 이미지 전처리하고 processor 우회할 때 버그 나타나.

항상 processor 통해 이미지 먹여. PIL 또는 torchvision transform 으로 똑똑하려 하지 마 — processor 가 모델의 기대 알아.

VLM 이 (오늘) 잘하는 것

OCR-같은 작업 — 이미지의 텍스트 읽기, 손글씨와 표 포함.
차트와 도표 해석 — "이 그래프의 trend 가 뭐?" 가 놀라울 만큼 잘 동작.
Visual question answering — "이 사진에 사람 몇 명?" "부서진 부분이 뭐?" — 빵-과-버터.
UI screenshot reasoning — "이 앱이 뭐 해?" "이 버튼 활성?" — agentic UI 워크플로 발전하면서 점점 강해짐.

여전히 약한 것

공간 정밀도 — "이 두 객체가 픽셀로 얼마나 떨어져?" 또는 정확한 geometry 요구하는 무엇이든. VLM 은 이미지를 묘사, 측정 안 해.
많은 객체 카운팅 — ~5 instance 까지 잘 동작, 그 너머 빠르게 degrade.
큰 이미지의 작은 텍스트 — 해상도 중요; 모델의 입력 해상도에서 텍스트가 글자 당 ~10 픽셀 아래면 OCR 실패.

Code

mlx-vlm 설치·bash

conda activate mlx
pip install mlx-vlm

# Verify
python -c "import mlx_vlm; print('mlx_vlm:', mlx_vlm.__version__)"
# As of 2026-05-03: mlx_vlm 0.4.4

이미지에 대한 질문 — 최소 API 표면·python

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

# Load a small VLM (under ~5 GB on disk)
model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit"
model, processor = load(model_path)
config = load_config(model_path)

# Image path or URL
image = ["path/to/your/image.jpg"]
prompt = "What's in this image? Be concise."

# Apply the chat template (includes the image placeholder)
formatted_prompt = apply_chat_template(processor, config, prompt, num_images=len(image))

output = generate(model, processor, formatted_prompt, image, max_tokens=120, verbose=False)
print(output)

같은 호출의 CLI 변형·bash

python -m mlx_vlm.generate \
  --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
  --image path/to/your/image.jpg \
  --prompt "What's in this image? Be concise." \
  --max-tokens 120

Exercise

다른 VLM capability 테스트하는 세 이미지 골라 — UI 의 screenshot 하나, 차트 또는 도표 하나, 여러 객체의 사진 하나. 같은 VLM 에 각각 같은 질문 ("두 문장으로 보이는 거 묘사"). 모델이 sharp 한 곳, 모호한 곳, 거기 없는 디테일 자신 있게 발명하는 곳 알아채. 가장 놀라운 실패 모드 두 문장.