이 페이지는 Ostris AI Toolkit으로 LoRA 파인튜닝을 시작하기 위한 개요입니다. 특정 모델 레시피가 필요하다면 아래 가이드로 바로 이동하세요:

• AI Toolkit으로 FLUX.2 Dev LoRA 학습하기
• AI Toolkit으로 LTX-2 LoRA 학습하기
• AI Toolkit으로 Z‑Image Turbo LoRA 학습하기
• AI Toolkit으로 Qwen Image 2512 LoRA 학습하기
• AI Toolkit으로 Qwen‑Image‑Edit‑2511 LoRA 학습하기
• AI Toolkit으로 Qwen‑Image‑Edit‑2509 LoRA 학습하기
• AI Toolkit으로 Wan 2.2 I2V 14B LoRA 학습하기
• AI Toolkit으로 Wan 2.2 T2V 14B LoRA 학습하기

이 가이드를 끝내면 다음을 할 수 있어야 합니다:

• LoRA 학습의 핵심 아이디어(파인튜닝 중 실제로 무엇이 바뀌는지)를 이해한다.
• AI Toolkit의 구성과 각 패널이 무엇을 제어하는지 안다.
• 핵심 파라미터(learning rate, rank, steps, noise schedule, DOP 등)가 무엇을 의미하고 어떤 영향을 주는지 이해해 의도적으로 튜닝할 수 있다.
• 로컬 환경 또는 RunComfy Cloud AI Toolkit에서 LoRA를 학습하고, 이후 일반적인 생성 워크플로에 재사용할 수 있다.

---

목차

• 1. Ostris AI Toolkit이란? (확산 모델용 LoRA 트레이너)
• 2. Ostris AI Toolkit 지원 모델 (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)
• 3. Ostris AI Toolkit 로컬 설치 및 RunComfy Cloud AI Toolkit 사용
• 4. Ostris AI Toolkit Web UI 개요 (Dashboard, Datasets, New LoRA Job)
• 5. AI Toolkit의 LoRA 학습 기초와 핵심 하이퍼파라미터
• 6. LoRA 개념을 AI Toolkit 파라미터로 매핑하기
• 7. 빠른 시작: AI Toolkit에서 “쓸 만한” LoRA 학습하기
• 8. AI Toolkit LoRA 학습 트러블슈팅: 흔한 오류와 해결책

1. Ostris AI Toolkit이란? (확산 모델용 LoRA 트레이너)

Ostris AI Toolkit은 이미지·비디오 확산 모델에 초점을 둔 트레이닝 스위트입니다. 언어 모델이나 오디오 모델은 다루지 않으며, 지원 범위는 전통적인 DDPM 계열 확산 모델(SD 1.5, SDXL 등) 또는 Flux, Wan, Qwen‑Image, Z‑Image, OmniGen2 같은 최신 diffusion‑transformer 계열 모델입니다. AI Toolkit은 LoRA 계열 어댑터 중심으로 설계되어 있어, 실제로는 네트워크 전체를 재학습하는 것이 아니라 고정된 베이스 모델 위에 작은 LoRA(또는 유사한 경량 어댑터)를 학습합니다.

LoRA 학습을 위한 Ostris AI Toolkit의 핵심 특징

AI Toolkit은 지원 모델 패밀리 전반에 공통으로 적용되는 트레이닝 엔진과 설정 시스템을 제공합니다. Flux, Z‑Image Turbo, Wan 2.2, Qwen‑Image, SDXL 등 각 모델 패밀리는 자체 프리셋을 갖지만, 모두 동일한 구조(모델 로딩, 양자화, LoRA/LoKr 정의, 학습 하이퍼파라미터, 데이터셋 처리, 샘플링 규칙)에 “꽂혀” 동작합니다. 그래서 Flux LoRA를 학습하든, Z‑Image Turbo LoRA를 학습하든, Wan 비디오 LoRA를 학습하든 Web UI의 흐름이 일관됩니다.

AI Toolkit에는 CLI와 완전한 Web UI가 함께 제공됩니다. CLI는 YAML 설정으로 직접 잡을 실행하고, Web UI는 그 YAML을 그래픽으로 다루는 레이어입니다. UI에서 보통 “AI Toolkit”이라고 말할 때는 New Job 화면(모델 패밀리 선택, LoRA 타입/Rank, learning rate/steps 설정, 데이터셋 연결, 샘플 이미지/비디오 생성 주기 설정 등)을 가리킵니다. Job, Model, Quantization, Target, Training, Regularization, Datasets, Sample 패널이 분리되어 있어 YAML을 직접 만질 일이 거의 없습니다. 로컬이든 RunComfy Cloud AI Toolkit 같은 클라우드든 워크플로는 같습니다.

---

Ostris AI Toolkit에 내장된 LoRA 학습 기능

AI Toolkit에는 보통 직접 스크립팅해야 하는 기능들이 기본 탑재되어 있습니다:

• 양자화 및 Low‑VRAM 모드 – 8/6/4‑bit(3‑bit은 recovery adapter 포함) transformer 양자화와 레이어 오프로딩을 통해 Flux/Wan 같은 대형 모델도 24–48GB GPU에서 학습 가능하게 합니다(품질/속도 트레이드오프 조절 가능).
• LoRA / LoKr 어댑터 – 표준 LoRA와 LoKr(더 작지만 범용 지원은 떨어질 수 있는 변형)를 Target Type으로 선택해, 호환성 우선 또는 더 작고 “용량 큰” 어댑터 우선 중 선택할 수 있습니다.
• Differential Output Preservation(DOP) – 정규화 이미지에서 베이스 모델 출력과 LoRA 적용 출력의 차이를 비교하고 원치 않는 변화를 벌점으로 주는 정규화 손실로, LoRA가 “새는” 현상을 줄이는 데 도움 됩니다.
• 터보 계열용 Differential Guidance – 주로 Z‑Image Turbo에서 쓰이는 옵션으로, 베이스 대비 “무엇이 바뀌어야 하는지”에 업데이트를 집중시켜 few‑step/turbo 모델에서도 적응을 깊게 하면서 속도 장점을 망가뜨리지 않게 돕습니다.
• 멀티 스테이지 노이즈 트레이닝 – high‑noise 단계와 low‑noise 단계를 분리해, 큰 구조(구도/포즈)와 미세 디테일(텍스처/엣지)의 균형을 잡습니다.
• Latent 및 텍스트 임베딩 캐시 – Cache Latents, Cache Text Embeddings로 디스크 공간을 쓰는 대신 속도/VRAM을 개선합니다.
• EMA(Exponential Moving Average) – LoRA 가중치의 평활화 복사본을 유지해 수렴 안정성을 높이는 옵션입니다(특히 작은 데이터셋에서 도움 될 수 있음).

Web UI는 이 기능들을 일관된 컨트롤로 노출하며, 한 모델(예: Flux)에서의 이해를 Z‑Image Turbo/Wan/Qwen‑Image 등으로 쉽게 확장할 수 있습니다.

---

2. Ostris AI Toolkit 지원 모델 (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)

AI Toolkit은 현재 다음 모델 패밀리를 지원합니다:

• IMAGE 모델 – 단일 이미지(Flux, Z‑Image Turbo, Qwen‑Image, SD 등)
• INSTRUCTION / EDIT 모델 – 이미지 편집/지시 추종(Qwen‑Image‑Edit, Flux Kontext, HiDream E1)
• VIDEO 모델 – 텍스트‑투‑비디오 및 이미지‑투‑비디오(Wan 2.x 시리즈)

---

2. Ostris AI Toolkit 지원 모델 (Flux, Wan, Z‑Image, Qwen‑Image, SDXL)

AI Toolkit은 현재 다음 모델 패밀리를 지원합니다:

• IMAGE 모델 – 단일 이미지(Flux, Z‑Image Turbo, Qwen‑Image, SD 등)
• INSTRUCTION / EDIT 모델 – 이미지 편집/지시 추종(Qwen‑Image‑Edit, Flux Kontext, HiDream E1)
• VIDEO 모델 – 텍스트‑투‑비디오 및 이미지‑투‑비디오(Wan 2.x 시리즈)

---

3. Ostris AI Toolkit 로컬 설치 및 RunComfy Cloud AI Toolkit 사용

3.1 Linux/Windows에 Ostris AI Toolkit 로컬 설치

공식 설치 방법은 GitHub README를 참고하세요.

Linux:

git clone https://github.com/ostris/ai-toolkit.git
cd ai-toolkit

python3 -m venv venv
source venv/bin/activate

# CUDA 버전 PyTorch 설치(필요시 버전 조정)
pip3 install --no-cache-dir torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 \
  --index-url https://download.pytorch.org/whl/cu126

pip3 install -r requirements.txt

Windows는 python -m venv venv 및 .\venv\Scripts\activate로 동일하게 진행하거나, 커뮤니티의 AI‑Toolkit Easy Install 배치 스크립트를 사용해 한 번에 설치/실행할 수도 있습니다.

의존성이 설치되면 Web UI는 다음으로 실행합니다:

cd ui
npm run build_and_start

UI는 http://localhost:8675에서 열립니다. 원격 머신에서 실행한다면 외부 접근을 막기 위해 AI_TOOLKIT_AUTH를 비밀번호로 설정하세요(보안 관련 내용은 AI Toolkit GitHub 저장소 참고).

---

3.2 RunComfy Cloud AI Toolkit로 LoRA 학습(로컬 설치 없음)

드라이버/CUDA/로컬 설치를 건드리고 싶지 않다면 RunComfy Cloud AI Toolkit을 사용할 수 있습니다:

• AI Toolkit이 클라우드에서 실행되며, 브라우저만 열면 됩니다.
• 80GB/141GB VRAM GPU로 Flux/Qwen‑Image/Z‑Image Turbo/Wan 같은 무거운 LoRA 학습에 적합합니다.
• 데이터셋/설정/체크포인트/과거 작업이 RunComfy 계정에 연결된 영속 워크스페이스에 저장됩니다.
• 학습, 플레이그라운드 테스트, ComfyUI 워크플로가 한 곳에 통합됩니다.

바로 열기: RunComfy Cloud AI Toolkit

---

4. Ostris AI Toolkit Web UI 개요 (Dashboard, Datasets, New LoRA Job)

Web UI(로컬/클라우드)를 열면 좌측 사이드바에 핵심 페이지가 있습니다.

4.1 Dashboard와 Training Queue

Dashboard는 실행 중/최근 작업을 빠르게 확인하는 상태 페이지입니다.

Training Queue에서는:

• 잡 상태(queued, running, finished, failed) 확인
• 로그 열기/디버그
• 잡 중지/삭제
• 출력 체크포인트 및 샘플 다운로드

를 할 수 있습니다. 모든 LoRA 학습 결과는 여기서 관리합니다.

---

4.2 Dataset 관리자

Datasets 페이지는 잡에 연결할 “이름 있는” 데이터셋을 만드는 곳입니다:

• 이미지 폴더/비디오 클립을 선택하거나 업로드
• UI가 스캔해 해상도/개수/caption·metadata 존재 여부를 표시
• 데이터셋 내부 이름이 생성되어 Target Dataset 드롭다운에 표시

여기서:

• 메인 학습 데이터셋(캐릭터, 스타일, 제품 사진)
• 필요 시 정규화 데이터셋(다른 사람/다른 트럭/일반 배경 등)

을 준비합니다.

---

4.3 New Job: LoRA 설정의 핵심 화면

New Job은 AI Toolkit의 중심입니다. 잡은 본질적으로 다음 의미입니다:

모델 Y에 대해, 데이터셋 Z로, 타입 X의 LoRA를 이 하이퍼파라미터로 학습한다.

화면은 패널로 나뉩니다:

• JOB – 이름과 GPU 선택
• MODEL – 베이스 모델 선택
• QUANTIZATION – 베이스 모델 압축
• TARGET – LoRA/LoKr 및 rank
• SAVE – 저장 형식/주기
• TRAINING – learning rate, steps, optimizer, timestep schedule
• ADVANCED / Regularization – EMA, Differential Guidance, DOP
• DATASETS – 어떤 데이터셋을 어떻게 학습할지
• SAMPLE – 학습 중 샘플 생성 규칙

이후 섹션은 이 패널들이 LoRA 개념과 어떻게 연결되는지 설명합니다.

---

5. AI Toolkit의 LoRA 학습 기초와 핵심 하이퍼파라미터

5.1 확산 모델에서 LoRA가 동작하는 방식

현대 확산 모델은 대형 가중치 행렬을 가진 transformer 블록의 스택입니다. 전체를 파인튜닝하면 비싸고 과적합도 쉬워집니다.

Flux/Z‑Image Turbo/Wan/Qwen‑Image 같은 모델은 거대한 diffusion‑transformer 백본을 쓰며, LoRA는 원래 가중치 W를 바꾸지 않고 저랭크 업데이트를 더합니다: W_new = W + alpha A B. 여기서 W는 고정된 원본, A/B는 작은 학습 행렬, alpha는 추론 시 LoRA 강도를 제어하는 스케일입니다.

rank는 A/B의 폭을 결정해 LoRA 용량을 좌우합니다. rank가 높을수록 표현력은 늘지만 VRAM/계산량/과적합 위험도 커집니다. rank가 낮으면 더 작고 일반화가 쉬운 LoRA가 되기 쉽습니다.

---

5.2 핵심 하이퍼파라미터

Learning Rate (Learning Rate)

• LoRA를 업데이트할 때의 스텝 크기입니다.
• 너무 낮으면 학습이 느리고 잘 맞지 않을 수 있습니다.
• 너무 높으면 불안정/노이즈/과적합이 빠르게 나타날 수 있습니다.

확산 LoRA에서는 0.0001이 매우 합리적인 기본값이며, 많은 Wan/Flux 설정이 0.0001 – 0.0002에 있습니다.

---

Batch Size와 Gradient Accumulation

• Batch Size는 동시에 처리하는 이미지/클립 수입니다.
• Gradient Accumulation은 N번 누적 후 1번 업데이트해 큰 배치를 흉내 냅니다.

유효 배치: Batch Size × Gradient Accumulation

24GB GPU에서는 Batch Size = 1, Gradient Accumulation = 2–4가 흔합니다.

---

Steps (Steps)

옵티마이저 업데이트 횟수입니다.

• 너무 적으면 underfitting
• 너무 많으면 overfitting/“누수”

일반적으로 20–50장 규모의 캐릭터 LoRA라면 2,000–3,000 steps가 좋은 시작점입니다.

---

Rank (Linear Rank)

LoRA 용량을 결정합니다.

• 대형 모델(Flux/Wan 등)은 16–32가 자주 쓰입니다.
• 데이터가 작으면 높은 rank일수록 과적합이 쉬워집니다.

---

Weight Decay (Weight Decay)

표준 정규화로, 0.0001이 흔한 안전값입니다.

---

Timestep schedule

• high noise: 큰 구조/구도
• low noise: 디테일/텍스처
• mid noise: 얼굴/캐릭터에 유리

Timestep Type과 Timestep Bias가 이를 UI로 제어합니다.

---

데이터셋 구성과 captions

좋은 LoRA는 데이터 품질에서 시작합니다: 깨끗하고 다양한 이미지, 그리고 고유 트리거 토큰을 captions에 명확히 연결하세요.

---

6. LoRA 개념을 AI Toolkit 파라미터로 매핑하기

6.1 JOB 패널: 이름, GPU, 트리거

Training Name은 잡 이름이며 출력 파일명에도 반영됩니다.

GPU ID는 로컬에서 GPU 선택, RunComfy 클라우드에서는 기본값 유지.

Trigger Word는 학습 시 captions 앞에 자동으로 붙는 트리거이며, 의미 충돌을 피하기 위해 “헛단어” 토큰을 권장합니다.

---

6.2 MODEL 패널: 베이스 모델 로딩

Model Architecture를 고르면 모델별 프리셋이 적용됩니다.

Name or Path는 Hugging Face repo id이며, 기본 자동입력을 유지하는 것이 보통 안전합니다.

gated 모델은 라이선스 승인과 HF_TOKEN 설정이 필요합니다.

Low VRAM/Layer Offloading은 “무엇을 학습하느냐”가 아니라 “메모리에 어떻게 올리느냐”를 바꾸는 옵션입니다.

---

6.3 QUANTIZATION 패널: 정밀도 vs VRAM

대부분 Transformer(float8/6-bit/4-bit/3-bit ARA)와 Text Encoder(대개 float8)가 있습니다.

24GB에서 Flux/Wan은 Transformer = 6-bit, Text Encoder = float8이 좋은 시작점입니다.

---

6.4 TARGET 패널: LoRA 타입과 rank

Target Type은 보통 LoRA(호환성 우선).

Linear Rank는 용량이며, 8–16/16–32가 흔한 범위입니다.

---

6.5 SAVE 패널: 저장 형식/주기

BF16이 기본 권장.

Save Every는 Sample Every와 맞추면 체크포인트와 프리뷰 비교가 쉬워집니다.

---

6.6 TRAINING 패널: optimizer/steps/schedule

AdamW8Bit이 일반적으로 가장 무난합니다.

learning rate는 보통 0.0001에서 시작해, 너무 약하면 올리고 과적합/노이즈면 내립니다.

Cache Text Embeddings는 captions가 “정적으로” 유지될 때만 켜는 것이 안전하며, DOP처럼 매 스텝 텍스트가 변하면 꺼야 합니다.

---

6.7 ADVANCED / Regularization: DOP와 Differential Guidance

DOP는 정규화 데이터셋(Is Regularization)이 있어야 하며, 정규화 captions에는 트리거를 넣지 않습니다.

Differential Guidance는 주로 Z‑Image Turbo에서 사용합니다.

---

6.8 DATASETS 패널

핵심은 LoRA Weight, Default Caption, Caption Dropout Rate, Cache Latents, Is Regularization, Resolutions(bucket)입니다.

Caption Dropout Rate가 낮으면 “트리거 있을 때만”에 가깝고, 높으면 “항상 스타일”에 가까워집니다.

---

6.9 SAMPLE 패널

Save Every = Sample Every를 권장합니다.

고정 seed 프롬프트를 하나 두면 체크포인트 비교가 쉬워집니다.

---

7. 빠른 시작: AI Toolkit에서 “쓸 만한” LoRA 학습하기

7.1 데이터 준비

• 작은 깨끗한 데이터셋으로 시작
• 고유 트리거 토큰(헛단어) 사용
• 다양성(각도/조명/배경) 확보

필요하면 정규화 데이터셋을 준비해 이후 DOP에서 사용합니다.

---

7.2 데이터셋 생성

Datasets → New Dataset에서 업로드 후, 개수·captions·해상도를 빠르게 점검하세요.

---

7.3 잡 생성: 5가지만 바꾸기

트리거, rank(16 시작), steps(2k–3k), learning rate(0.0001), bucket(768/1024 중 하나)만 먼저 맞추세요.

---

7.4 샘플 프롬프트 3개로 진단

• 트리거 포함(활성 확인)
• 트리거 포함(일반화 확인)
• 트리거 없음(누수 확인)

---

7.5 한 번에 하나만 조정

약하면 steps→rank, 강하면 체크포인트를 앞당기고 steps/rank 감소, OOM이면 해상도→rank 순으로 내립니다.

---

7.6 LoRA 내보내기

.safetensors 체크포인트를 다운로드해 사용합니다. RunComfy Cloud에서는 Custom Models에도 저장됩니다.

---

8. AI Toolkit LoRA 학습 트러블슈팅: 흔한 오류와 해결책

Dataset이 없거나 비어 있음

Datasets에서 개수 확인, 잡의 Target Dataset 확인, JSONL 형식 확인.

---

Hugging Face 다운로드 오류

gated 모델 라이선스 승인 후 .env에 HF_TOKEN 설정.

---

CUDA OOM

bucket/해상도 낮추기 → rank 낮추기 → Low VRAM/양자화 강화 → 배치/샘플링 줄이기.

RunComfy Cloud에서는 더 큰 VRAM GPU로 올리는 것이 가장 빠른 해결책인 경우가 많습니다.

---

LoRA가 과적합되어 베이스를 “하이재킹”

rank/steps 낮추기, 더 이른 체크포인트 사용, weight decay 증가, 정규화 데이터셋 + DOP 적용.