gemma-mud-colab-starter/README.md

gemma-mud-colab-starter

작고 조용한 불씨 하나를 코랩 위에 올려 두는 패키지다.
이 묶음은 MUD 문체·NPC 대화·방 분위기를 위한 Gemma 4 + Unsloth LoRA 첫 실험용 최소 패키지다.

이 패키지는 완성형 대규모 학습 시스템이 아니다.
100개 샘플 데이터로 흐름을 익히고, 노트북이 실제로 한 번 돌아가게 만드는 데 목적이 있다.

---

1. 무엇이 들어 있나

• README.md
  전체 흐름 안내
• requirements_colab.txt
  코랩 설치 패키지 목록
• run_instructions.md
  정말 쉬운 실행 순서
• troubleshooting.md
  자주 막히는 문제와 해결
• dataset/gemma4_mud_alpaca_100.jsonl
  학습 데이터셋
• notebooks/Gemma4_MUD_QLoRA_Colab_Notebook.ipynb
  코랩 실행 노트북
• examples/sample_prompts.md
  테스트용 명령 예시
• examples/lmstudio_system_prompt_ko.txt
  LM Studio 붙여 넣기용 시스템 프롬프트
• examples/lmstudio_system_prompt_npc_ko.txt
  LM Studio 짧은 NPC 대화용 프롬프트
• examples/lmstudio_system_prompt_lore_ko.txt
  LM Studio 세계관 설명용 프롬프트
• examples/lmstudio_test_prompts.md
  LM Studio 확인용 테스트 문장
• examples/expected_outputs.md
  정상 출력의 결을 읽는 기준
• output/.gitkeep
  결과 폴더 자리 보존용
• package_manifest.md
  파일 역할 요약

---

2. 이 패키지의 목적

이 패키지는 아래 셋을 빠르게 시험하는 데 맞춰져 있다.

1. MUD 명령어에 대한 문체 학습
2. NPC 대화 반응 미세조정
3. 로컬 추론 서버나 MUD 엔진에 붙일 수 있는 LoRA 어댑터 생성

즉,
게임 판정 전체를 AI에게 맡기는 것이 아니라
말투, 분위기, 짧은 서사, 힌트성 응답을 다듬는 방향에 맞다.

---

3. 준비물

• Google 계정
• Google Colab
• 선택: Hugging Face 계정
• 선택: Hugging Face 토큰
• 이 패키지 zip 파일

---

4. Hugging Face 로그인은 언제 필요한가

이번 노트북 기본 경로는 unsloth/gemma-4-E2B-it 를 사용한다.
로컬 저장만 할 때는 Hugging Face 로그인이 없어도 시작할 수 있다.

아래 경우에는 로그인해 두는 편이 좋다.

1. Hugging Face Hub로 LoRA 어댑터를 올리고 싶을 때
2. 다른 gated Gemma 체크포인트를 직접 불러오고 싶을 때
3. 모델/결과를 Hub에서 관리하고 싶을 때

중요:

• 비밀번호를 문서에 적지 않는다.
• 토큰을 코드에 하드코딩하지 않는다.
• 토큰이 필요할 때만 노트북의 로그인 셀 주석을 풀어 직접 입력한다.

---

5. 가장 쉬운 실행 순서

방법 A — 가장 쉬운 길

1. zip을 푼다.
2. notebooks/Gemma4_MUD_QLoRA_Colab_Notebook.ipynb 를 Colab에서 연다.
3. 런타임을 GPU로 바꾼다.
4. dataset/gemma4_mud_alpaca_100.jsonl 파일을 Colab 파일 패널에 업로드한다.
5. 셀을 위에서부터 차례대로 실행한다.
6. 설치 셀 뒤에 import 오류가 났다면 런타임 재시작 후 2번 셀부터 다시 실행한다.
7. 필요할 때만 Hugging Face 로그인 셀의 주석을 풀어 실행한다.
8. 학습이 끝나면 /content/output/gemma_mud_lora_out 폴더를 확인한다.

방법 B — 드라이브에 두고 쓰기

1. zip을 구글 드라이브에 올린다.
2. 드라이브에서 압축을 푼다.
3. 노트북에서 경로 설정 셀만 바꿔 드라이브 경로를 잡는다.
4. 나머지는 같은 순서로 실행한다.

---

6. 데이터셋 위치와 형식

기본 데이터셋은 여기에 있다.

• dataset/gemma4_mud_alpaca_100.jsonl

형식은 다음 필드를 가진 Alpaca 계열 JSONL이다.

• instruction
• input
• output
• text

노트북은 이 파일을 먼저 읽고, instruction/input/output 를 Gemma 4용 user/assistant 대화로 다시 감싼 뒤, 최종 text 컬럼을 만들어 Unsloth SFTTrainer 에 넘긴다.

---

7. 노트북 기본 설정

노트북은 처음 성공 확률을 높이기 위해 Unsloth의 Gemma 4 E2B instruct 체크포인트를 기본값으로 둔다.
왜냐하면 무료 Colab T4에서도 비교적 현실적으로 한 번 돌아가게 만들기 좋기 때문이다.

기본값 예시:

• per_device_train_batch_size = 1
• gradient_accumulation_steps = 4
• num_train_epochs = 1
• learning_rate = 2e-4
• MAX_SEQ_LENGTH = 1024
• LOAD_IN_4BIT = False

VRAM이 부족하면 설정 셀에서 LOAD_IN_4BIT = True 또는 MAX_SEQ_LENGTH = 512 로 낮춘다.
핵심은 Gemma 4를 그냥 Alpaca 문자열로 넣지 않고, Gemma 4 채팅 템플릿으로 다시 감싼 뒤 Unsloth LoRA로 학습하는 점이다.

---

8. 학습 후 결과는 어디에 저장되나

기본 저장 위치:

• /content/output/gemma_mud_lora_out

여기에는 보통 아래가 생긴다.

• LoRA adapter 가중치
• 토크나이저 파일
• 설정 파일 일부
• 체크포인트 폴더

이 폴더를 Google Drive로 복사하거나, Colab에서 직접 내려받으면 된다.

---

9. 로컬 MUD 실험에 붙이는 큰 흐름

학습이 끝나면 보통 이렇게 이어진다.

1. LoRA 어댑터 저장
2. 로컬 또는 서버 추론 환경에 로드
3. MUD 명령 입력을 프롬프트로 변환
4. talk oracle, look, rumor 같은 응답 생성
5. 게임 엔진은 여전히 판정을 맡고, AI는 말과 분위기를 맡음

핵심은 이 선을 지키는 것이다.

• 엔진: 이동, 전투 판정, 보상, 퀘스트 상태
• AI: 대화, 분위기, 전승, 짧은 힌트

---

10. 한계와 주의사항

이 패키지는 첫 실험용이다.

• 데이터가 100개뿐이라 품질이 흔들릴 수 있다.
• 문체는 배워도, 세계 규칙 전체를 자동으로 이해하지는 않는다.
• 큰 모델은 무료 Colab에서 실패할 수 있다.
• 긴 시퀀스 길이는 메모리를 빠르게 잡아먹는다.
• 세션이 끊기면 저장 전까지 작업이 사라질 수 있다.

또한 이런 문장은 AI가 임의로 내면 안 된다.

• “너는 퀘스트를 완료했다”
• “너는 500 골드를 얻었다”
• “문이 열렸다”

이것은 게임 엔진 판정 영역이다.

---

11. 권장 테스트 명령

학습 직후에는 아래 다섯 개를 먼저 넣어 보는 편이 좋다.

• talk oracle
• ask oracle about first fire
• look
• rumor
• scan signal

좋은 출력은 짧고, 세계관 안에 머물고, 과장된 메타 발언이 적다.

LM Studio 에서 테스트할 때는 아래 파일도 같이 보면 편하다.

• examples/lmstudio_system_prompt_ko.txt
• examples/lmstudio_system_prompt_npc_ko.txt
• examples/lmstudio_system_prompt_lore_ko.txt
• examples/lmstudio_test_prompts.md

---

12. 다음 확장 단계

1. 100개 → 300개 데이터 확장
2. chat/messages 형식 데이터셋 실험
3. NPC별 전용 데이터셋 분리
4. 로컬 추론 서버 연동
5. MUD 명령어별 응답 품질 비교

처음에는 한 명의 NPC만 살아나도 충분하다.
그 뒤에 세계를 넓히면 된다.