AI 튜토리얼

Google Colab에서 MiniMax H3 Ref2VA LoRA 학습하기

이 튜토리얼에서는 Codex 스킬 설치, 학습 대상 이미지와 참조 이미지 선별, 재현 가능한 캡션과 페어링 생성, Google Colab에서 Ostris AI Toolkit을 사용한 MiniMax H3 Ref2VA LoRA 학습 실행, 그리고 생성된 safetensors 어댑터 다운로드 방법을 설명합니다.

2026년 9월 29일약 14분 소요

Google Colab에서 MiniMax H3 Ref2VA LoRA 학습하기

이 프로젝트가 하는 일

MiniMax H3 Ref2VA LoRA Colab Skill은 이미지 쌍 데이터셋을 준비하고 Google Colab에서 MiniMax H3 Ref2VA LoRA를 학습하기 위한 설치 가능한 Codex 스킬입니다. 이 실행기는 로컬 이미지를 정리하고, 데이터셋을 패키징하며, 포함된 Colab 노트북을 시작하고, 체크포인트와 실행 산출물을 Google Drive에 저장한 뒤, 최종 .safetensors 어댑터를 컴퓨터로 다운로드합니다.

이 워크플로는 MiniMax H3 트랜스포머를 대상으로 합니다. H3는 이미지 이해 파이프라인에서 Qwen3-VL을 사용하지만, Qwen Image는 별도의 모델입니다. Qwen Image LoRA는 H3 어댑터와 호환되지 않습니다.

주요 기능

타깃 이미지와 참조/제어 이미지로 구성된 이미지 쌍 데이터셋을 생성합니다.
사용 가능한 경우 동일한 기본 이름의 캡션 파일을 사용합니다.
재현 가능한 캡션과 참조 이미지 선택을 위한 JSON 데이터셋 계획을 지원합니다.
Google Colab에서 Ostris AI Toolkit을 통해 MiniMax H3 Ref2VA LoRA 학습을 실행합니다.
학습 스텝, LoRA rank, alpha, 학습률, GPU 유형 및 고메모리 요청을 설정할 수 있습니다.
체크포인트, 샘플, 구성 및 실행 요약을 Google Drive에 동기화합니다.
최종 .safetensors 어댑터를 로컬 출력 디렉터리로 다운로드합니다.
Colab 컴퓨팅 잔액을 확인하고 원격 런타임 연결을 테스트하는 명령을 제공합니다.

사전 요구 사항

스킬을 설치하기 전에 로컬 시스템에 다음이 갖춰져 있는지 확인하세요.

Python 3.10 이상.
원격 명령을 실행하기 전에 설치 및 인증된 Google Colab CLI.
GPU 하드웨어에 액세스할 수 있는 Colab 계정.
해당 라이선스의 동의를 포함하여 필요한 H3 모델 및 학습 어댑터 리소스에 대한 액세스 권한.
예정된 학습 실행에 충분한 Colab 컴퓨팅 리소스.

포함된 노트북은 최소 60 GiB의 여유 디스크 공간을 확인하고 GPU VRAM이 48 GiB 미만이면 경고합니다. 이 프로젝트는 고메모리 A100을 권장하지만, 공식적인 최소 VRAM 보장은 없습니다.

Codex 스킬 설치

저장소를 복제하고 설치 프로그램을 실행하세요.

git clone https://github.com/killkli/minimax-h3-lora-colab-skill.git
cd minimax-h3-lora-colab-skill
./install.sh

CODEX_HOME이 설정되어 있으면 설치 프로그램은 $CODEX_HOME/skills 아래에 스킬을 배치합니다. 그렇지 않으면 ~/.codex/skills를 사용합니다.

다른 스킬 디렉터리에 설치하려면 --dest를 지정하세요.

./install.sh --dest /path/to/skills

기존 설치는 기본적으로 보존됩니다. 기존 설치를 의도적으로 교체하려면 --force를 사용하세요. 설치 프로그램은 이전 복사본을 조용히 삭제하지 않고 타임스탬프가 포함된 백업으로 이동합니다.

설치 확인

Colab 작업을 시작하지 않고 실행기 도움말을 표시하세요.

python3 ~/.codex/skills/minimax-h3-lora-colab/scripts/runner.py --help

CODEX_HOME이 구성되어 있다면 ~/.codex/skills를 $CODEX_HOME/skills로 바꾸세요. 로컬 설치 및 도움말 확인은 학습을 시작하거나 Colab GPU 시간을 사용하지 않습니다.

학습 이미지 준비

타깃 사진을 하나의 디렉터리에 배치하세요. 사진에는 동일한 사람 또는 피사체가 나와야 합니다. 선택적으로 동일한 기본 이름의 텍스트 파일로 캡션을 추가할 수 있습니다. 예를 들어 photo01.jpg의 캡션은 photo01.txt에 작성할 수 있습니다.

복제한 저장소에서 다음 명령으로 데이터셋을 준비하세요.

python3 scripts/runner.py prepare \
  --input-dir /path/to/target_photos \
  --name studio_subject \
  --trigger "studio_subject person" \
  --output-dir ./prepared_dataset

준비된 디렉터리에는 다음이 포함됩니다.

prepared_dataset/
├── targets/
├── references/
└── dataset_manifest.json

targets/에는 타깃 이미지와 동일한 기본 이름의 캡션 파일이 들어 있습니다.
references/에는 타깃과 기본 이름이 일치하는 참조 또는 제어 이미지가 들어 있습니다.
dataset_manifest.json에는 모든 샘플의 소스, 타깃, 참조 이미지 및 캡션이 기록됩니다.

데이터셋 준비는 로컬에서 수행됩니다. 원본 사진을 준비된 데이터셋에 복사하지만 Colab으로 업로드하지는 않습니다.

참조 이미지 자동 선택

별도의 참조 폴더를 제공하지 않으면 실행기는 최소 두 장의 타깃 사진을 필요로 합니다. 실행기는 해당 사진들을 순환하여 참조 이미지 쌍을 생성합니다.

가능하면 동일한 피사체를 다양한 각도에서 촬영한 유용한 이미지를 사용하세요. 타깃은 자기 자신을 참조 이미지로 사용해서는 안 됩니다.

별도의 참조 폴더 사용

다른 디렉터리에서 참조 이미지를 선택하려면 --reference-dir를 추가하세요.

python3 scripts/runner.py prepare \
  --input-dir /path/to/target_photos \
  --reference-dir /path/to/reference_photos \
  --name studio_subject \
  --trigger "studio_subject person" \
  --output-dir ./prepared_dataset

선택한 모든 참조 이미지에는 타깃 세트와 동일한 피사체가 나와야 합니다. 더 큰 컬렉션의 일부만 선별하는 경우에는 선택한 타깃과 참조 이미지를 스테이징 폴더에 배치하고 원본 이미지 컬렉션은 그대로 두세요.

재현 가능한 데이터셋 계획 만들기

데이터셋 계획에는 이미지별 캡션과 선택적인 타깃-참조 이미지 선택 정보가 기록됩니다. 이를 통해 수동 또는 에이전트 지원 큐레이션을 재현할 수 있습니다.

{
  "captions": {
    "photo01.jpg": "studio_subject person, 허리 위로 보이는 파란 재킷 차림의 인물, 부드러운 자연광 아래 야외",
    "photo02.jpg": "studio_subject person, 창가 실내에서 흰 셔츠를 입은 인물의 측면 프로필"
  },
  "references": {
    "photo01.jpg": "front_reference.png",
    "photo02.jpg": "side_reference.png"
  }
}

captions 객체에는 모든 대상 이미지의 베이스네임이 포함되어야 합니다. 선택 사항인 references 객체가 있는 경우, 모든 대상 베이스네임을 후보 참조 디렉터리의 이미지 베이스네임에 매핑해야 합니다.

캡션에는 눈에 보이는 세부 정보만 설명해야 합니다. 관련 없는 사람이나 피사체는 별도의 데이터셋으로 분리하고, 대상 이미지를 자기 자신에게 매핑하지 마세요.

다음 계획을 사용하여 데이터셋을 준비하세요.

python3 scripts/runner.py prepare \
  --input-dir /path/to/target_photos \
  --reference-dir /path/to/reference_photos \
  --dataset-plan /path/to/dataset-plan.json \
  --name studio_subject \
  --trigger "studio_subject person" \
  --output-dir ./prepared_dataset

--dataset-plan을 생략하면 러너는 기존 사이드카 캡션을 사용하고, 캡션이 없는 경우 간단한 기본 캡션을 제공합니다.

업로드 전 검토

학습을 시작하기 전에 dataset_manifest.json을 열고 각 소스, 대상, 참조, 캡션을 확인하세요. 잘못된 페어링, 누락된 설명 또는 다른 피사체에 해당하는 이미지가 있는지 확인하기에 가장 좋은 시점입니다. 준비된 이미지를 Colab 런타임에 업로드하는 단계는 학습 단계입니다.

Google Colab에서 LoRA 학습

준비된 데이터셋을 검토한 후 학습을 시작하세요.

python3 scripts/runner.py train \
  --dataset-dir ./prepared_dataset \
  --name studio_subject \
  --trigger "studio_subject person" \
  --steps 1000 \
  --rank 16 \
  --alpha 16 \
  --gpu A100 \
  --output-dir ./outputs

기본 학습 설정은 다음과 같습니다.

학습 스텝 1,000회
LoRA rank 16
Alpha 16
학습률 1e-4
A100 고메모리 Colab 세션

노트북은 H3 모델과 필요한 학습 어댑터 자산을 다운로드합니다. 최종 어댑터는 ./outputs/에 .safetensors 파일로 저장됩니다.

실행 결과물은 다음 경로에도 동기화됩니다.

MyDrive/MiniMax_H3_LoRAs/<name>/<run-id>/

Drive 디렉터리에는 체크포인트, 생성된 샘플, 구성 데이터 및 실행 요약이 포함됩니다.

학습 매개변수는 신중하게 변경

스텝, rank, alpha, GPU 및 출력 디렉터리의 예시 값을 변경할 수 있습니다. 지원되는 모든 학습 옵션을 확인하려면 다음을 실행하세요.

python3 scripts/runner.py train --help

기본적으로 고메모리 모드가 요청됩니다. 선택한 Colab GPU 할당에서 해당 요청을 생략해야 할 때만 --no-high-mem을 추가하세요.

Colab 사용량 및 연결 상태 확인

현재 Colab 컴퓨팅 잔액을 JSON 형식으로 확인하려면 다음을 사용하세요.

python3 scripts/runner.py usage --json

원격 GPU 런타임을 준비하고 프로브, 파일 전송 및 Google Drive 경로를 확인하려면 다음을 실행하세요.

python3 scripts/runner.py test

test 명령은 학습 검증 명령이 아닙니다. 사용 가능한 VRAM에서 MiniMax H3 학습이 실행될 수 있거나 성공적으로 완료된다는 것을 입증하지 않습니다.

고급 팁 및 운영 지침

피사체 데이터셋을 집중적으로 구성

각 데이터셋에는 한 사람 또는 한 피사체의 이미지만 사용하세요. 관련 없는 피사체를 분리하면 캡션과 참조 매핑이 더 명확해지고 러너가 예상하는 작업 흐름을 따를 수 있습니다.

이미지별 캡션 사용

일반적인 캡션에만 의존하지 말고 포즈, 의상, 구도, 환경 및 조명과 같이 눈에 보이는 특성을 설명하세요. 선택한 트리거를 일관되게 포함하되, 이미지에서 볼 수 없는 세부 정보는 추가하지 마세요.

유용한 참조 다양성 우선

같은 피사체를 묘사하면서도 다양한 시점을 제공하는 참조 이미지를 선택하세요. 예를 들어 적절한 경우 정면 모습과 측면 프로필을 짝지을 수 있습니다. 대상 이미지를 자기 자신과 짝짓지 마세요.

검토 가능한 기록 보존

데이터셋 계획과 생성된 매니페스트를 프로젝트와 함께 보관하세요. 두 파일은 실행에 사용된 캡션과 페어링을 문서화하며, 준비 과정을 감사하거나 반복하기 쉽게 해줍니다.

로컬 및 클라우드 출력 모니터링

로컬 출력 디렉터리에는 다운로드된 최종 어댑터가 포함되고, Google Drive에는 더 광범위한 실행 결과물이 보관됩니다. 학습 실행이 예기치 않게 중단되면 Drive 사본에서 체크포인트, 샘플, 구성 및 실행 요약을 확인하세요.

하드웨어 적합성은 런타임에 따라 달라짐

권장되는 고메모리 A100이 성공을 보장하는 것은 아닙니다. 실제 메모리 적합성은 Colab 런타임과 학습 구성에 따라 달라집니다. 노트북은 VRAM이 48 GiB 미만이면 경고하고 여유 디스크 공간이 60 GiB인지 확인하지만, 이러한 검사는 공식적인 하드웨어 보장이 아닙니다.

검증 상태 이해

업스트림 AI Toolkit Ref2VA 예시 구성은 검증되지 않음으로 표시되어 있습니다. 따라서 저장소는 모든 클라우드 학습 실행이 성공한다고 주장하지 않습니다. 재현성을 위해 노트북은 검사한 AI Toolkit 소스 커밋을 고정하지만, 설치 성공이나 원격 프로브 성공을 엔드투엔드 학습 완료의 증거로 해석해서는 안 됩니다.

추가 자료

결론

MiniMax H3 Ref2VA LoRA Colab Skill은 로컬 이미지 큐레이션부터 다운로드 가능한 H3 어댑터 생성까지 반복 가능한 경로를 제공합니다. 로컬에서 대상 이미지와 참조 이미지 쌍을 준비하고 검토하며, 재현 가능한 캡션과 매핑이 필요할 때는 데이터셋 계획을 사용하고, Colab 리소스와 라이선스를 확인한 다음 학습을 시작하세요. 업스트림 구성은 아직 검증되지 않았으며 Qwen Image LoRA와 MiniMax H3 어댑터는 서로 호환되지 않는다는 점을 기억하세요.