mlx-vlm: M5와 같은 Apple Silicon에 최적화된 MLX 기반 시각-언어 모델(VLM) 추론 및 파인튜닝 도구

읽을거리&정보공유
, , , , , , ,
1

mlx-vlm: M5와 같은 Apple Silicon에 최적화된 MLX 기반 시각-언어 모델(VLM) 추론 및 파인튜닝 도구
mlx-vlm: M5와 같은 Apple Silicon에 최적화된 MLX 기반 시각-언어 모델(VLM) 추론 및 파인튜닝 도구1024×572 110 KB

mlx-vlm 소개

mlx-vlm은 Apple의 자체 실리콘(Apple Silicon) 칩셋에 최적화된 머신러닝 프레임워크인 MLX를 기반으로 구축된, Vision Language Model(VLM) 및 Omni Model 전용 툴킷입니다. 오늘날의 AI 트렌드는 단순히 텍스트만을 처리하는 LLM(Large Language Model)을 넘어, 이미지와 오디오, 비디오까지 동시에 이해하고 처리하는 멀티모달(Multi-modal) 모델로 진화하고 있습니다. 하지만 이러한 멀티모달 모델들은 방대한 연산량과 메모리를 요구하기 때문에, 고성능 NVIDIA GPU가 없는 로컬 환경, 특히 Mac 사용자들에게는 접근 장벽이 높았습니다.

이러한 배경에서 등장한 mlx-vlm은 Mac 개발자들이 로컬 환경에서 최신 고성능 모델을 효율적으로 구동할 수 있도록 돕습니다. 이 라이브러리는 단순히 모델을 실행하는 추론(Inference) 기능뿐만 아니라, 사용자의 데이터셋을 이용해 모델을 재학습시키는 파인튜닝(Fine-tuning) 기능까지 포괄적으로 제공합니다. 특히 Apple Silicon의 통합 메모리 구조를 활용하여 4-bit 또는 8-bit 양자화된 모델을 구동함으로써, 제한된 하드웨어 자원 내에서도 놀라운 속도와 성능을 보여줍니다. 개발자는 복잡한 환경 설정 없이도 이 패키지를 통해 이미지 분석, 문서 OCR, 비디오 캡셔닝, 오디오 이해와 같은 작업을 자신의 Mac에서 즉시 수행할 수 있습니다.

mlx-vlm의 주요 특징

Apple Silicon에 최적화된 멀티모달 환경

mlx-vlm의 가장 큰 특징은 Apple이 직접 개발한 MLX 프레임워크 위에서 동작한다는 점입니다. 이는 기존의 PyTorch 기반 모델들을 Apple의 하드웨어 가속기(Metal)에 맞춰 변환하고 최적화하는 과정을 자동화해 줍니다. 사용자는 Hugging Face Hub에 업로드된 mlx-community 버전의 모델들을 별도의 복잡한 변환 과정 없이 바로 다운로드하여 사용할 수 있습니다.

이 과정에서 mlx-vlm은 텍스트 처리와 이미지/오디오 처리를 위한 프로세서를 자동으로 연결하고, 채팅 템플릿을 적용하여 모델이 이해할 수 있는 형태의 입력으로 변환해 줍니다. 결과적으로 개발자는 하드웨어 최적화에 대한 깊은 지식 없이도, Python 코드 몇 줄만으로 상용 수준의 멀티모달 AI 기능을 구현할 수 있게 됩니다.

특히, 최근 공개된 DeepSeek-OCR, DeepSeek-OCR2, GLM-OCR 등의 모델들을 Apple Silicon에 최적화하여 실행할 수 있습니다.

이미지부터 오디오, 비디오까지: 확장된 입력 지원

초기의 VLM들이 단순히 한 장의 이미지를 보고 텍스트로 설명하는 데 그쳤다면, mlx-vlm은 이를 훨씬 확장된 형태로 지원합니다:

먼저, 다중 이미지(Multi-Image) 분석 기능이 있습니다. 사용자는 모델에게 여러 장의 이미지를 동시에 입력으로 제공하고, "이 두 이미지의 차이점을 설명해 줘"라거나 "연속된 이미지들의 상황을 요약해 줘"와 같은 복잡한 추론을 요청할 수 있습니다.

또한, 최근 추가된 Omni Model 지원을 통해 오디오 입력도 처리가 가능해졌습니다. 예를 들어 Gemma-3n과 같은 모델을 활용하면, 오디오 파일을 입력받아 그 소리가 무엇인지 설명하거나, 오디오와 이미지를 동시에 입력받아 "이 사진의 상황과 들리는 소리를 종합해서 설명해 줘"와 같은 복합적인 명령을 수행할 수 있습니다.

더 나아가 비디오 이해(Video Understanding) 기능도 지원합니다. 비디오 파일을 입력하면 프레임 단위로 정보를 분석하여 비디오의 내용을 텍스트로 요약하거나 특정 장면에 대한 질문에 답변할 수 있습니다. 이는 Qwen2-VL이나 LLaVA 시리즈와 같은 모델에서 특히 강력한 성능을 발휘합니다.

로컬 파인튜닝을 통한 모델 최적화

단순히 공개된 모델을 사용하는 것을 넘어, mlx-vlm은 사용자의 독자적인 데이터를 모델에 학습시키는 파인튜닝 기능도 강력하게 지원합니다. 특히 거대 모델의 모든 파라미터를 학습시키는 대신, 핵심적인 일부 파라미터만 학습하는 LoRA(Low-Rank Adaptation) 및 QLoRA 기법을 적용할 수 있습니다.

이를 통해 수십 기가바이트에 달하는 VRAM이 없는 일반적인 Mac 환경에서도 효율적인 학습이 가능합니다. 사용자는 자신의 도메인에 특화된 이미지-텍스트 쌍 데이터셋을 준비하고, 제공되는 학습 스크립트를 실행함으로써 자신만의 시각 지능 모델을 구축할 수 있습니다. 이는 의료 영상 분석, 특정 양식의 문서 OCR, 혹은 회사 내부의 디자인 가이드라인 준수 여부 판단 등 특수한 목적의 AI를 개발하는 데 필수적인 기능입니다.

LoRA 및 QLoRA 기법을 활용한 파인튜닝을 위한 상세한 방법은 GitHub 저장소의 문서를 참고해주세요:

mlx-vlm 설치 및 사용

mlx-vlm 설치

mlx-vlm은 Python 환경에서 pip를 사용하여 간단하게 설치할 수 있습니다.

pip install -U mlx-vlm

유연한 개발 인터페이스: CLI, Python, API Server

mlx-vlm은 개발자의 숙련도와 사용 목적에 따라 세 가지의 다른 인터페이스를 제공합니다.

가장 먼저, 빠른 테스트를 위한 **명령줄 인터페이스(CLI)**가 있습니다. 터미널에서 mlx_vlm.generate 명령어를 입력하고 모델 경로와 이미지 URL, 혹은 오디오 경로를 옵션으로 전달하면 즉시 결과를 확인할 수 있습니다. 예를 들어 --image 옵션으로 이미지 주소를, --prompt로 질문을 던지면 모델이 이미지를 분석해 답변을 출력합니다.

다음은 CLI 사용 예시입니다:

# 이미지 분석
mlx_vlm.generate --model mlx-community/Qwen2-VL-2B-Instruct-4bit \
                 --max-tokens 100 \
                 --temperature 0.0 \
                 --image http://images.cocodataset.org/val2017/000000039769.jpg

# 오디오 분석
mlx_vlm.generate --model mlx-community/gemma-3n-E2B-it-4bit \
                 --max-tokens 100 \
                 --prompt "Describe what you hear" \
                 --audio /path/to/audio.wav


본격적인 애플리케이션 개발을 위해서는 Python API를 사용할 수 있습니다. load 함수를 통해 모델과 프로세서를 메모리에 적재하고, apply_chat_template 함수를 사용하여 텍스트, 이미지, 오디오가 혼합된 복잡한 프롬프트를 모델이 처리 가능한 텐서 형태로 변환합니다. 이후 generate 함수를 호출하여 결과를 얻는 구조입니다. 이 방식은 세밀한 제어가 가능하여 커스텀 챗봇이나 분석 도구를 만들 때 유용합니다.

다음은 Python 코드 내에서 모델을 로드하고 이미지를 처리하는 예시 코드입니다:

import mlx.core as mx
from mlx_vlm import load, generate
from mlx_vlm.prompt_utils import apply_chat_template
from mlx_vlm.utils import load_config

# 1. 모델 및 프로세서 로드
model_path = "mlx-community/Qwen2-VL-2B-Instruct-4bit"
model, processor = load(model_path)
config = load_config(model_path)

# 2. 입력 데이터 준비 (이미지 URL 또는 로컬 경로)
image = ["http://images.cocodataset.org/val2017/000000039769.jpg"]
prompt = "Describe this image."

# 3. 채팅 템플릿 적용
formatted_prompt = apply_chat_template(
    processor, config, prompt, num_images=len(image)
)

# 4. 결과 생성
output = generate(model, processor, formatted_prompt, image, verbose=False)
print(output)


마지막으로, OpenAI 호환 API 서버 기능입니다. mlx_vlm.server 명령어를 실행하면 로컬 호스트(기본 8080 포트)에 웹 서버가 구동됩니다. 이 서버는 OpenAI의 Chat Completion API 규격을 따르기 때문에, 기존에 OpenAI API를 사용하던 애플리케이션의 엔드포인트 URL만 변경하면 즉시 로컬 모델로 교체하여 사용할 수 있습니다.

다음은 CLI에서 OpenAI 호환 API 서버 실행을 위한 명령어입니다. 이 서버는 텍스트뿐만 아니라 이미지 및 오디오 입력도 표준적인 JSON 요청 본문을 통해 처리할 수 있어 확장성이 매우 뛰어납니다.

# 서버 시작 (기본 포트: 8080)
mlx_vlm.server --model mlx-community/Qwen2-VL-2B-Instruct-4bit

서버가 실행되면 curl 또는 OpenAI Client SDK 등을 이용해 요청을 보낼 수 있습니다:

curl -X POST "http://localhost:8080/chat/completions" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "mlx-community/Qwen2-VL-2B-Instruct-4bit",
       "messages": [
         {
           "role": "user",
           "content": [
             {"type": "text", "text": "What is in this image?"},
             {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
           ]
         }
       ]
     }'


그 외에도 별도의 코드 작성 없이 웹 브라우저에서 모델과 대화할 수 있는 Gradio 인터페이스도 내장되어 있습니다. 다음은 CLI 실행 명령 예시입니다:

mlx_vlm.chat_ui --model mlx-community/Qwen2-VL-2B-Instruct-4bit

라이선스

mlx-vlm 프로젝트는 MIT License로 배포되고 있어, 상업적 이용을 포함하여 자유롭게 수정 및 배포가 가능합니다.

단, mlx-vlm을 통해 구동되는 개별 모델(예: Qwen, Llama 등)은 각 모델 제작사의 라이선스 정책(예: Apache 2.0, Llama Community License 등)을 따르므로, 실제 서비스 적용 시에는 사용하는 모델의 라이선스를 별도로 확인해야 합니다.

:github: mlx-vlm 프로젝트 GitHub 저장소



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck: