비전-언어 SFT
이 스킬은 finetuning-method-selection이
이미 여기로 라우팅되었다고 가정합니다. 즉, 데이터 형태가
선호도 쌍이나 검증 가능한 보상 신호가 아닌
이미지+텍스트 시연(demonstration)이며, 기본 모델이
텍스트 전용 모델이 아닌 비전-언어 모델(VLM)입니다.
lora-qlora-recipes는 텍스트 전용
LoRA/QLoRA 레시피를 다루며, 이 스킬은 그것을 비전
타워와 프로젝터에 특화합니다. LoRA 기본 개념(rank, alpha, target
modules)이 이미 익숙하지 않다면 먼저 해당 스킬을 읽으십시오.
입력: 이미지+텍스트 데이터셋과 모델 카탈로그에서
이미 선택된 VLM 기본 모델입니다.
출력 형식: 동결할 구성 요소, LoRA 대상 모듈,
그리고 min_pixels/max_pixels 예산이 포함된 검증된 어댑터 구성입니다.
이 구성은 llm-finetuning-training-engineer가
실행 가능한 스크립트를 생성할 때 직접 사용합니다.
빠른 참조
| 상황 | 기본값 |
|---|---|
| 익숙한 이미지에서 동작 조정 | 타워+프로젝터 동결, LoRA r=8–16, α=16–32 |
| 시각적 도메인 이동 | 마지막 6개 ViT 레이어 동결 해제, 비전 LR 5–10배 낮춤 |
| 대상 rank에서 bf16에 맞지 않음 | QLoRA — 비전 타워만 동결 |
fast_inference=True | finetune_vision_layers=False |
| 손실 정상, 평가 개선 없음 | 먼저 아래 '두 가지 침묵하는 킬러' 확인 |
합의된 레시피
비전 타워와 프로젝터를 동결합니다.
LLM에만 LoRA를 적용하며, 모든 선형(attention + MLP 대상 목록은 텍스트 전용 SFT와 동일 —
lora-qlora-recipes 참조)에 대해
r=8–16, α=16–32를 사용합니다.
이는 VLM의 동작 방식을 방해하지 않고 적응시키기 위한
정착된 기본 설정입니다.
- 비전 타워와 프로젝터는 기본적으로 동결 상태를 유지합니다. 이들은 이미 일반적인 시각 표현을 인코딩하고 있습니다. 재훈련은 거의 필요하지 않으며, 대부분의 작업에서 기능 추가 없이 위험만 증가시킵니다.
- LoRA rank는 텍스트 전용 일반 기본값보다 낮게 실행됩니다. (여기서는 r=8–16, 텍스트 전용 SFT는 r=16–32) LLM 전용 어댑터는 새로운 시각 지식을 주입하는 것이 아니라 동작을 조정하는 것이기 때문입니다.
- QLoRA는 비전 타워가 동결된 경우에만 허용됩니다. 기본 모델을 양자화하면서 비전 레이어를 동결 해제하고 훈련하는 것은 지원되지 않으며 불안정합니다. 이는 조정 가능한 옵션이 아닌 강력한 페어링 규칙으로 취급하십시오. 비전 타워를 동결 해제해야 한다면 QLoRA를 포기하고 대신 bf16 LoRA를 사용하십시오.
# 타워 + 프로젝터 동결; LLM에만 LoRA 적용
for name, param in model.named_parameters():
if "vision_tower" in name or "projector" in name:
param.requires_grad = False
target_modules = [
"q_proj", "k_proj", "v_proj", "o_proj",
"gate_proj", "up_proj", "down_proj",
] # LLM 전용, 모든 선형 — r=8-16, alpha=16-32
동결 해제 시기
비전 레이어 동결 해제는 기본 결정이 아니라 의도적인 확장입니다. 도메인 이동이 텍스트가 아닌 시각적인 경우에만 사용하십시오.
- 시각적 도메인 이동이 있는 경우에만 동결 해제하십시오. 작업이 타워가 이미 이해하는 이미지(차트, 일상적인 사진)에서 새로운 동작을 가르치는 것이라면 위의 동결 타워 레시피로 충분합니다. 타워가 익숙하지 않은 시각적 도메인(위성 이미지, 의료 스캔, 복잡한 기술 다이어그램)이고 동결 타워 레시피가 정체 상태일 때 동결 해제하십시오.
- 마지막 6개 ViT 레이어가 최적 지점입니다. 전체 타워가 아닌 최종 6개의 비전 트랜스포머 레이어를 동결 해제하면 동결 기준선 대비 약 1.75배 훈련 비용으로 DocVQA +1.7포인트 향상이 측정되었습니다. 여섯 개 레이어를 지불할 가치가 있는 상한선으로 취급하고, 그 이상은 일치하는 결과 없이 계산만 낭비합니다.
- 비전 LR은 동결 해제 시 LLM LR보다 5–10배 낮게 설정되어야 합니다. 비전 타워의 사전 훈련된 표현은 LLM의 어댑터보다 더 취약합니다. 둘에 동일한 LR을 사용하면 LLM 어댑터가 보상할 수 있는 것보다 빠르게 시각 표현을 덮어쓸 위험이 있습니다.
- 패치 임베딩 레이어에 높은 LoRA rank를 적용하면 NaN 위험이 있습니다. 패치 임베딩이 동결 해제된 세트에 포함된 경우, rank를 낮게 유지하고 초기 단계 손실을 면밀히 관찰하십시오. VLM에서 LoRA를 적용하기 가장 취약한 위치 중 하나입니다.
두 가지 침묵하는 킬러
둘 다 오류 없이 훈련되지만 학습되지는 않는 실행을 만듭니다: 손실 곡선은 정상으로 보이지만 모델은 개선되지 않으며, 어떤 예외도 발생하지 않습니다. 둘 다 깨끗한 훈련 로그만으로는 충분하지 않고 명시적인 훈련 전 검사가 필요합니다.
- 이미지 태그/개수 불일치. 템플릿 텍스트의 모든 이미지
플레이스홀더 토큰은 콜레이터에 실제로 전달되는 미디어 항목과
1:1로 매핑되어야 합니다. 불일치(플레이스홀더 하나에
이미지 없음 또는 두 개 연결, 또는 이미지에 플레이스홀더 없음)는
대부분의 콜레이터에서 오류를 발생시키지 않습니다.
이미지와 텍스트를 조용히 잘못 정렬하고,
모델은 "훈련되지만 아무것도 배우지 않습니다."
훈련 시작 전에 모든 예제에 대해 샘플이 아닌
1:1 플레이스홀더-미디어 매핑을 검증하십시오.
전체 검증 체크리스트 세부 사항:
references/collators-and-pitfalls.md. min_pixels/max_pixels해상도 예산. 이 쌍은 VLM SFT에서 품질과 메모리에 가장 중요한 단일 하이퍼파라미터입니다 — rank, alpha, LR보다 더 중요합니다. 너무 낮으면 작업에 필요한 것보다 이미지를 조용히 다운샘플링합니다(작은 문서 텍스트를 읽을 수 없게 만들지만 훈련은 "성공"합니다); 너무 높으면 활성화 메모리 예산을 초과하거나 안정적인 훈련을 위해 배치 크기를 너무 작게 강제합니다. 데이터셋별로 의도적으로 설정하고, 프레임워크 기본값에 맡기지 마십시오.
Unsloth 세부 사항
- **
UnslothVisionDataCollator**는 Unsloth가 VLM SFT에서 기대하는 콜레이터입니다.references/collators-and-pitfalls.md에 설명된 이미지-태그 정렬 및 아키텍처별 프로세서 계약을 처리합니다. VLM 데이터에 텍스트 전용 콜레이터를 대체하지 마십시오. fast_inference=True인 경우finetune_vision_layers=False가 필수입니다. vLLM은 비전 레이어에 LoRA 어댑터를 제공할 수 없으므로, fast-inference 설정이면서 비전 레이어를 동결 해제하면 훈련이 성공하더라도 서빙 시점에 실패합니다. 레시피가 마지막 6개 ViT 레이어 동결 해제를 요구한다면 (위의 '동결 해제 시기' 참조), 해당 실행에서는 fast inference를 사용할 수 없습니다. 둘 중 하나를 선택하고, 둘 다 선택하지 마십시오.
모델 선택
기본 VLM 선택은 이 스킬의 범위를 벗어납니다.
이는 finetuning-method-selection의
references/model-catalog.md에 있는 모델 카탈로그에서
한 곳에서 관리됩니다. 이 스킬과 그 참조 자료는
아키텍처 패밀리별로 레시피만 설명하며,
어느 한 모델을 다른 모델보다 추천하지 않습니다.
VLM 강화 학습(VLM-GRPO)은 이 플러그인에서
참조 전용입니다. VLM-RL에 특화된
단편화된 도구와 보상 해킹 실패 모드는
grpo-rlvr-training에서 다루며, 여기서 다루지 않습니다.
이 스킬의 범위는 지도 학습 파인튜닝에서 끝납니다.
실패 모드
위의 모든 섹션에서 반복되는 실수는 깨끗한 손실 곡선을
실행이 건강하다는 증거로 취급하는 것입니다.
정상적으로 보이는 곡선은 작동하는 실행과 두 킬러 중 하나
모두와 일관성이 있습니다. 킬러가 있는 경우 모델이
정렬된 이미지-텍스트 신호가 아닌 무언가를 기반으로 훈련되기
때문입니다. 정상 손실 곡선 옆에 평평한 평가 점수는
하이퍼파라미터를 건드리기 전에
references/collators-and-pitfalls.md의 체크리스트를
다시 실행해야 함을 의미합니다.
참조
references/collators-and-pitfalls.md— 아키텍처별 콜레이터 테이블, 이미지 플레이스홀더가 포함된 데이터셋 형식 예제, 훈련 전 검증 체크리스트, 고급 패턴으로서의 2단계 프로젝터 정렬 레시피.
관련 스킬: finetuning-method-selection이 여기로
라우팅합니다. lora-qlora-recipes는 이 스킬이 특화하는
텍스트 전용 LoRA 기본 개념을 다룹니다.
grpo-rlvr-training은 VLM-RL을 다룹니다(참조 전용).
dataset-curation은 이 스킬이 다루지 않는
이미지+텍스트 데이터셋 준비를 다룹니다.