gemma-mud-colab-starter/troubleshooting.md

문제 해결

1. Hugging Face 인증 실패

증상

• 로그인 셀에서 오류가 난다.
• 토큰 입력 후에도 인증 실패 메시지가 뜬다.

원인

• 토큰이 틀렸거나 만료되었을 수 있다.
• 토큰 권한이 부족할 수 있다.
• 붙여 넣는 과정에서 공백이 섞였을 수 있다.

해결 방법

• Hugging Face에서 새 토큰을 다시 발급한다.
• 복사할 때 앞뒤 공백을 제거한다.
• 노트북을 재시작한 뒤 다시 로그인한다.

---

2. Gemma 모델 접근 권한 오류

증상

• from_pretrained 단계에서 접근 거부가 뜬다.
• gated model 관련 메시지가 나온다.

원인

• Gemma 모델 사용 조건을 아직 승인하지 않았다.
• 승인 후에도 로그인 상태가 반영되지 않았을 수 있다.

해결 방법

• Hugging Face에서 원하는 Gemma 모델 카드로 이동한다.
• 사용 조건을 승인한다.
• 다시 로그인한다.
• 계속 막히면 기본값인 unsloth/gemma-4-E2B-it 경로로 먼저 시험한다.

---

3. Colab GPU가 안 잡히는 경우

증상

• torch.cuda.is_available() 가 False로 나온다.
• import unsloth 에서 Unsloth cannot find any torch accelerator 오류가 난다.

원인

• 런타임이 CPU로 열렸을 수 있다.
• 무료 Colab 자원이 잠시 부족할 수 있다.

해결 방법

• 런타임 → 런타임 유형 변경 → GPU 로 다시 설정한다.
• 새 세션을 다시 열어 본다.
• GPU로 바꾼 뒤에는 설치 셀부터 다시 실행한다.
• 계속 안 되면 잠시 후 다시 시도한다.

---

4. bitsandbytes / quantization 관련 오류

증상

• 4bit 양자화 설정 셀에서 오류가 난다.
• bitsandbytes import 오류가 난다.

원인

• 패키지 설치가 덜 끝났을 수 있다.
• GPU 세션이 아닌 상태일 수 있다.
• 설치 후 런타임 재시작이 필요할 수 있다.

해결 방법

• 설치 셀을 다시 실행한다.
• 런타임을 재시작한다.
• GPU가 실제로 잡혔는지 다시 확인한다.
• LOAD_IN_4BIT = True / False 를 바꿔 어느 쪽이 현재 세션에서 안정적인지 확인한다.

---

4-1. import 단계에서 바로 깨지는 경우

증상

• from transformers import ... 단계에서 바로 오류가 난다.
• ModuleNotFoundError: No module named 'unsloth' 가 뜬다.
• from unsloth import FastModel 단계에서 import error 가 난다.
• from trl import SFTTrainer 에서 import error 가 난다.
• 설치 셀은 끝났지만 다음 셀에서 패키지 충돌 메시지가 이어진다.

원인

• Colab 기본 torch 와 Unsloth 쪽 패키지 버전이 중간에 섞였을 수 있다.
• transformers==5.5.0 이전 조합이나 누락된 timm / torchcodec 때문에 Gemma 4 import 가 깨질 수 있다.
• 설치 직후 재시작 없이 이전 런타임 상태가 남아 있을 수 있다.

해결 방법

• 노트북 설치 셀을 그대로 다시 실행한다.
• 설치 뒤 바로 깨졌다면 런타임을 재시작한 다음 2번 셀부터 다시 실행한다.
• 설치 셀 마지막의 pip show unsloth 출력이 실제로 보이는지 확인한다.
• 버전 출력에서 unsloth, transformers, trl 이 정상적으로 찍히는지 확인한다.

---

5. 메모리 부족

증상

• 학습 중간에 out of memory 오류가 난다.
• 세션이 갑자기 죽는다.

원인

• 모델이 너무 크다.
• MAX_SEQ_LENGTH 가 너무 길다.
• 배치 크기 또는 누적 스텝 조합이 현재 GPU에 무겁다.

해결 방법

• LOAD_IN_4BIT = True 로 바꾼다.
• MAX_SEQ_LENGTH 를 1024 → 512 로 줄인다.
• batch size는 1로 유지하고, 필요하면 데이터 수를 줄여 흐름만 먼저 확인한다.

---

6. dataset 파일 경로 오류

증상

• FileNotFoundError 가 뜬다.
• 노트북이 dataset 파일을 찾지 못한다.

원인

• 파일 업로드 위치가 노트북 설정과 다르다.
• zip은 풀었지만 Colab 경로가 달라졌다.

해결 방법

• 파일 패널에서 실제 경로를 확인한다.
• 설정 셀의 DATA_CANDIDATES 목록에 현재 경로를 추가한다.
• 가장 쉬운 방법은 dataset 파일을 /content/ 에 직접 올리는 것이다.

---

7. 세션 종료 또는 런타임 초기화

증상

• 코랩이 갑자기 다시 시작된다.
• 학습 로그가 사라진다.

원인

• 무료 Colab 세션 제한
• 메모리 초과
• 장시간 유휴 상태

해결 방법

• 먼저 작은 모델과 짧은 설정으로 한 번 성공시킨다.
• 저장 셀이 끝났는지 수시로 확인한다.
• 결과는 가능한 빨리 Drive나 로컬에 백업한다.

---

8. 출력 품질이 이상한 경우

증상

• 말투가 흔들린다.
• 세계관 밖 설명이 나온다.
• 너무 길거나 건조한 답이 나온다.

원인

• 데이터 수가 적다.
• instruction이 충분히 구체적이지 않다.
• 문체는 익혔지만 규칙까지 자동으로 배우지 못했다.

해결 방법

• 데이터 수를 300개 이상으로 늘린다.
• NPC별, 명령어별 데이터를 나눈다.
• instruction 문장을 더 또렷하게 쓴다.
• 실제 게임 판정은 엔진이 맡고, AI는 대화/분위기/서사 보조에 쓰는 편이 안전하다.

---

9. 저장 파일이 안 보이는 경우

증상

• 학습은 끝났는데 출력 폴더가 비어 보인다.
• 파일 패널에서 결과가 잘 안 보인다.

원인

• 저장 경로를 잘못 보았을 수 있다.
• 세션 재시작 전 저장이 끝나지 않았을 수 있다.

해결 방법

• /content/output/gemma_mud_lora_out 경로를 직접 확인한다.
• os.listdir() 로 폴더 내용을 출력해 본다.
• Drive 복사 셀을 사용해 별도 위치에 백업한다.