예제 소스

download_gemma4.py

"""Hugging Face 에서 Gemma 4 (mlx-community 변환본) 모델을 다운로드합니다.

기본은 Apple Silicon 친화적 4bit 양자화본:
    mlx-community/gemma-4-e4b-it-4bit (≈ 6 GB, 멀티모달 추론에 권장)

대안 (가벼움):
    mlx-community/gemma-4-e2b-it-4bit (≈ 1.5 GB, 빠르지만 품질 ↓)

원본 (양자화 없음, 디스크/메모리 큼):
    google/gemma-4-E4B-it
    google/gemma-4-E2B-it

원본 google/gemma-4-* 는 Hugging Face 에서 라이선스 동의 + 로그인 토큰이
필요할 수 있습니다 (`huggingface-cli login`).
"""

from __future__ import annotations

import os
import sys
from pathlib import Path
from typing import Optional


def download(model_id: str, cache_dir: Optional[str] = None) -> str:
    """모델 스냅샷을 다운로드하고 로컬 경로를 반환합니다."""
    try:
        from huggingface_hub import snapshot_download
    except ImportError as e:  # pragma: no cover
        raise SystemExit(
            "huggingface_hub 미설치. `pip install -r vlm_server/requirements.txt` 먼저 실행하세요."
        ) from e

    print(f"[download] model={model_id} cache_dir={cache_dir or '(HF default)'}")
    # mlx-vlm 모델은 대부분 safetensors + tokenizer*.json + config.json 만 필요.
    allow_patterns = [
        "*.json",
        "*.safetensors",
        "*.txt",
        "*.model",
        "tokenizer*",
        "*.png",
        "*.md",
    ]
    local = snapshot_download(
        repo_id=model_id,
        cache_dir=cache_dir,
        allow_patterns=allow_patterns,
        token=os.environ.get("HUGGINGFACE_HUB_TOKEN") or os.environ.get("HF_TOKEN"),
    )
    print(f"[download] OK: {local}")
    return local


def main() -> int:
    import argparse

    p = argparse.ArgumentParser(description="Hugging Face 에서 Gemma 4 모델 다운로드")
    p.add_argument("--model", default="********")
    p.add_argument("--cache-dir", default=None)
    args = p.parse_args()
    path = download(args.model, args.cache_dir)
    print(path)
    return 0


if __name__ == "__main__":
    sys.exit(main())