v3.x로의 업그레이드 핵심 요약
kohya_ss는 Stable Diffusion 기반 모델을 위한 대표적인 훈련 도구로, v2.x에서 v3.x로의 전환은 아키텍처 차원의 중대한 변화를 포함합니다. 이 버전에서는 최신 생성 모델에 대한 네이티브 지원과 더 안정적인 인터페이스가 도입되어 사용자 경험과 훈련 효율성이 크게 개선되었습니다.
주요 향상 기능
- SD3 및 flux.1 호환성: 새로운 확산 모델 구조를 위한 전용 설정 제공
- Gradio 5.14+ 채택: 성능 향상과 UI 반응성 개선
- uv 기반 설치 시스템: 의존성 충돌 감소 및 패키지 관리 용이성
- 고급 훈련 파라미터 추가: 세밀한 제어 가능 항목 확대
업그레이드 사전 준비
백업 필수 항목
버전 전환 전 반드시 다음을 백업하세요:
- 설정 파일 (예:
config_example.toml) - 훈련 데이터셋 폴더 (이미지 + 캡션)
- 생성된 LoRA 또는 Dreambooth 체크포인트
- 사용자 정의 프리셋 (
presets/디렉토리)
시스템 요구사항
- Python 3.8 이상
- NVIDIA GPU (8GB VRAM 권장)
- 최소 20GB 여유 디스크 공간
설치 및 마이그레이션 절차
기존 Git 저장소 업데이트
# 현재 작업 상태 임시 보관
git stash
# 최신 커밋 풀링
git pull origin main
# 특정 릴리스 태그 체크아웃 (예시)
git checkout tags/v25.0.3 -b v3_upgrade_branch
신규 설치 추천 방법
# 저장소 복제
git clone https://gitcode.com/GitHub_Trending/ko/kohya_ss
cd kohya_ss
# uv를 활용한 의존성 설치 (권장)
./gui-uv.sh # Linux/macOS
gui-uv.bat # Windows
# 전통적 pip 설치 (보조 수단)
./setup.sh
주요 변경 사항 및 주의점
설정 파일 재작성 필요
v3.x는 구성 형식을 일부 수정했습니다:
- 모든 경로에서
/사용 (Windows 포함) - flux.1 전용 파라미터 추가 (예:
flow_matching_loss_weight) - 일부 v2 파라미터 삭제됨
→ 기존 설정보다 새 config_example.toml을 기준으로 재작성하는 것이 안전합니다.
훈련 스크립트 변경
- GUI 관련 로직이
kohya_gui/내 새 모듈로 분리 - SD3 전용 훈련 플로우 추가
- 파라미터 명칭 표준화 (예:
batch_size→train_batch_size)
의존성 버전 업데이트
# 필수 패키지 업그레이드 목록
gradio >= 5.14.0
diffusers >= 0.25.0
torch >= 2.0.0
transformers >= 4.36.0
uv는 격리된 환경에서 의존성을 처리하므로 충돌 가능성 낮춤.
흔히 발생하는 문제 해결법
GUI 시작 실패
- 파이썬 캐시 제거:
find . -name "__pycache__" -exec rm -rf {} + - uv로 재설치 실행
- 포트 확인: 기본 7860번 포트 사용 여부 검사
VRAM 부족 오류
- 배치 크기 감소
- Gradient Checkpointing 활성화
- 해상도 조정 (예: 512 → 448)
--mixed_precision=fp16적용
모델 로드 실패
- 확장자 확인 (.ckpt, .safetensors)
- 경로 절대/상대 지정 일관성 유지
- Hugging Face 캐시 삭제 후 재다운로드 시도
버전 비교 요약표
| 기능 | v2.x | v3.x | 비고 |
|---|---|---|---|
| SD3 지원 | 미지원 | 지원 | 전용 학습 옵션 제공 |
| flux.1 통합 | 불가 | 가능 | FM-Loss 기반 훈련 |
| Gradio 버전 | 4.x | 5.14+ | 속도 및 안정성 향상 |
| 설치 방식 | pip만 지원 | uv + pip | uv 권장 |
| 훈련 속도 | 기본 수준 | 15~30% 향상 | 최적화 알고리즘 개선 |
고급 마이그레이션 전략
Docker 기반 테스트
FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime
WORKDIR /kohya_ss
RUN git clone https://gitcode.com/GitHub_Trending/ko/kohya_ss . && \
pip install uv && \
uv pip install -r requirements.txt
EXPOSE 7860
CMD ["python", "kohya_gui.py"]
단계별 전환 접근법
- 검증 환경 구축: 별도 디렉토리에 v3 설치
- 병렬 운영: v2와 v3 동시 실행으로 결과 비교
- 데이터 이관: 점진적으로 데이터셋 이동
- 완전 전환: 모든 테스트 통과 후 본격 사용
핵심 파일 위치 안내
config_example.toml: 새 설정 템플릿kohya_gui/: GUI 핵심 모듈presets/: 훈련 프로필 저장소docs/: 공식 문서 참조 위치tools/: 이미지 전처리 등 유틸리티
업그레이드 후 권장 사항
- 새로운 flux.1 예제 설정 파일로 테스트 실행
- uv를 통해 주기적으로 의존성 업데이트
- SSD에 데이터셋 저장하여 I/O 성능 향상
- 공식 docs/train_README.md 참고하여 최적화
향후 로드맵 전망
다음 버전에서 예상되는 기능:
- 분산 훈련(Distributed Training) 강화
- 자동 하이퍼파라미터 추천 시스템
- 추가 아키텍처(SDXL-Light 등) 지원
- 웹 기반 로깅 및 모니터링 인터페이스
결론
v3.x로의 마이그레이션은 초기 설정 노력이 필요하지만, 장기적으로 향상된 안정성과 신규 모델 지원 덕분에 생산성 향상 효과가 큽니다. 본 가이드를 따르되, 항상 기존 v2 환경을 백업 상태로 유지하여 비상 시 복구할 수 있도록 하는 것이 중요합니다.