README.md

---
license: apache-2.0
language:
  - ko
library_name: transformers
pipeline_tag: text-generation
base_model:
  - google/gemma-4-E2B-it
tags:
  - gemma
  - gemma4
  - korean
  - roleplay
  - mud
  - lore
  - gguf
  - llama.cpp
  - lmstudio
  - transformers
---

# gemma4-e2b-mud

`gemma4-e2b-mud` 는 **Gemma 4 E2B 계열을 기반으로 한 한국어 우주항행 텍스트 MUD 스타일 모델**이다.  
짧은 명령 반응, NPC 대사, 방 분위기 묘사, 전승 설명, 항로 힌트 같은 **게임 서사 레이어**를 다루기 좋게 정리한 체크포인트와, 이를 재현하거나 확장할 수 있는 **Colab 스타터 패키지**, 그리고 **LM Studio용 GGUF**를 함께 제공한다.

이 저장소의 핵심 방향은 “게임 엔진의 판정”이 아니라, **말투, 분위기, 짧은 세계관 응답**을 AI가 맡도록 만드는 것이다.

## TL;DR

- 기반 모델: `google/gemma-4-E2B-it`
- 주 사용 언어: 한국어
- 주 사용 영역: 텍스트 MUD, NPC 대화, 룸 묘사, 전승/로어 설명
- 포함 형식:
  - Transformers 체크포인트
  - LM Studio / llama.cpp 용 `GGUF`
  - Colab / Unsloth 재현용 스타터 패키지
- 가장 잘 맞는 입력:
  - `talk oracle`
  - `look`
  - `rumor`
  - `scan signal`
  - `First Fire Horizon이 어떤 곳인지 설명해줘.`

## 이 저장소에 들어 있는 것

### 1. Transformers 체크포인트

루트에는 병합된 Hugging Face 형식 모델 가중치가 들어 있다.

- `model-00001-of-00005.safetensors`
- `model-00002-of-00005.safetensors`
- `model-00003-of-00005.safetensors`
- `model-00004-of-00005.safetensors`
- `model-00005-of-00005.safetensors`
- `config.json`
- `processor_config.json`
- `tokenizer.json`
- `tokenizer_config.json`
- `chat_template.jinja`

### 2. GGUF

LM Studio / llama.cpp 에 바로 가져갈 수 있도록 다음 GGUF 파일을 함께 제공한다.

- `gemma4-e2b-mud-Q4_K_M.gguf`

이 파일은 로컬 추론, LM Studio 테스트, 빠른 배포에 적합한 시작점이다.

### 3. Companion starter package

저장소 안의 [`gemma-mud-colab-starter/`](./gemma-mud-colab-starter) 폴더에는 다음이 포함되어 있다.

- Colab 노트북
- E2B / E4B 실험용 노트북 변형
- 예시 데이터셋
- LM Studio 시스템 프롬프트
- 테스트 프롬프트
- 실행 안내와 트러블슈팅 문서

즉 이 저장소는 “모델만 던져 놓은 형태”가 아니라, **실험과 배포까지 이어지는 패키지형 저장소**를 목표로 한다.

데이터셋 구조와 제작 방법은 별도 문서에 정리해 두었다.

- [`DATASET_GUIDE.md`](./DATASET_GUIDE.md)

## 모델 개요

이 모델은 **Gemma 4 E2B instruct 계열을 텍스트 MUD 톤에 맞게 다듬은 파생 모델**이다.

지향하는 응답은 아래와 같다.

- 짧고 선명한 NPC 대사
- 분위기가 살아 있는 방/장면 설명
- 세계관 고유명사를 중심으로 한 전승/로어 안내
- 플레이를 돕는 짧은 힌트
- 범용 비서형 답변보다, **세계 안에 머무르는 반응**

반대로 아래와 같은 방향은 피하도록 설계했다.

- 현실 기업/DB/상식 설명으로 새는 답변
- `AI로서...` 같은 메타 발언
- 장황한 백과사전식 설명
- 게임 상태를 모델이 임의로 확정하는 발화

## 기반 모델과 구조

이 저장소의 기반은 [`google/gemma-4-E2B-it`](https://huggingface.co/google/gemma-4-E2B-it) 이다.  
Gemma 4 E2B는 Google의 작은 Gemma 4 계열 모델이며, 공식 카드 기준으로 **Apache 2.0** 라이선스를 사용한다.

주의:

- **이 저장소 루트에 올라온 실제 가중치와 GGUF는 E2B 기반이다.**
- starter package 안에 들어 있는 `E4B` 노트북은 **E4B 실험/재학습용 companion notebook** 이며, 루트 체크포인트가 E4B라는 뜻은 아니다.

이 저장소의 로컬 `config.json` 기준 주요 텍스트 설정은 다음과 같다.

- 아키텍처: `Gemma4ForConditionalGeneration`
- `model_type`: `gemma4`
- 텍스트 hidden size: `1536`
- 텍스트 레이어 수: `35`
- attention heads: `8`
- key/value heads: `1`
- intermediate size: `6144`
- vocab size: `262144`
- sliding window: `512`

중요:

- **이 파생 모델의 실제 사용 초점은 텍스트 생성**이다.
- Gemma 4 E2B 계열 자체는 작은 멀티모달 계열이지만, 이 저장소의 스타터 패키지와 예시 프롬프트는 **텍스트 MUD 사용 시나리오**에 맞춰져 있다.
- 함께 들어 있는 GGUF 파일 역시 LM Studio에서 **텍스트 대화 중심**으로 바로 테스트하는 용도에 맞다.

## 어떤 작업에 잘 맞는가

### 잘 맞는 작업

- 텍스트 MUD NPC 대화
- 룸/장면 분위기 묘사
- 짧은 rumor / lore / signal 응답
- 로컬 스토리텔링 테스트
- 한국어 세계관 프로토타이핑
- MUD 엔진의 “서사 레이어” 분리 실험

### 특히 잘 맞는 입력 스타일

- 한두 단어 명령형
  - `talk oracle`
  - `look`
  - `rumor`
  - `scan signal`
- 짧은 설명 요청형
  - `First Fire Horizon이 어떤 곳인지 설명해줘.`
  - `Helios Verge의 의미와 중요성을 설명해줘.`

## 어떤 작업에는 맞지 않는가

이 모델은 아래 역할을 **직접 담당하지 않는 편이 안전하다.**

- 퀘스트 완료 판정
- 보상 지급
- 아이템/골드 정산
- 문 열림/잠금 등 상태 변경 확정
- 전투 승패 계산
- 법률, 의료, 금융 같은 고신뢰 정보 제공

즉, 추천 사용 구조는 다음과 같다.

- **엔진**: 이동, 전투, 상태, 보상, 퀘스트 로직
- **모델**: 대사, 분위기, 전승, 짧은 힌트, 묘사

## 빠른 시작

### Transformers 로 바로 쓰기

Gemma 4 공식 문서의 사용 방식에 맞춰 `AutoProcessor` + `AutoModelForImageTextToText` 경로로 시작할 수 있다.

```python
from transformers import AutoProcessor, AutoModelForImageTextToText
import torch

MODEL_ID = "sangwon1472/gemma4-e2b-mud"

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForImageTextToText.from_pretrained(
    MODEL_ID,
    dtype="auto",
    device_map="auto",
)

messages = [
    {
        "role": "system",
        "content": "당신은 우주항행 텍스트 MUD의 항로 안내자이자 세계관 해설자다. 답변은 한국어로 한다."
    },
    {
        "role": "user",
        "content": "talk oracle"
    },
]

text = processor.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=False,
)

inputs = processor(text=text, return_tensors="pt").to(model.device)
input_len = inputs["input_ids"].shape[-1]

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=128,
        temperature=1.0,
        top_p=0.95,
        top_k=64,
    )

response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
print(processor.parse_response(response))
```

## LM Studio / llama.cpp 사용

이 저장소에는 바로 import 가능한 GGUF 파일이 포함되어 있다.

- `gemma4-e2b-mud-Q4_K_M.gguf`

LM Studio 에서는 이 GGUF를 가져와서 바로 테스트할 수 있다.  
함께 제공하는 시스템 프롬프트와 테스트 문장은 starter package 안에 있다.

- [`lmstudio_system_prompt_ko.txt`](./gemma-mud-colab-starter/examples/lmstudio_system_prompt_ko.txt)
- [`lmstudio_system_prompt_npc_ko.txt`](./gemma-mud-colab-starter/examples/lmstudio_system_prompt_npc_ko.txt)
- [`lmstudio_system_prompt_lore_ko.txt`](./gemma-mud-colab-starter/examples/lmstudio_system_prompt_lore_ko.txt)
- [`lmstudio_test_prompts.md`](./gemma-mud-colab-starter/examples/lmstudio_test_prompts.md)

### 권장 시작 프롬프트

- `talk oracle`
- `look`
- `rumor`
- `scan signal`
- `First Fire Horizon이 어떤 곳인지 설명해줘.`

### 권장 생성 설정

Gemma 4 계열은 공식/실전 사용에서 아래 값이 무난한 출발점이다.

- `temperature = 1.0`
- `top_p = 0.95`
- `top_k = 64`

보다 짧고 안정적인 NPC 답변이 필요하면 아래처럼 조금 보수적으로 시작해도 좋다.

- `temperature = 0.7`
- `max tokens = 96 ~ 128`

위의 “더 짧게” 설정은 이 저장소의 MUD 용도에 맞춘 실전 권장값이다.

## Companion starter package 안내

함께 제공하는 [`gemma-mud-colab-starter/`](./gemma-mud-colab-starter) 폴더는 모델을 다시 학습하거나 변형해 보고 싶은 사용자를 위한 구성이다.

주요 파일:

- [`README.md`](./gemma-mud-colab-starter/README.md)
- [`run_instructions.md`](./gemma-mud-colab-starter/run_instructions.md)
- [`troubleshooting.md`](./gemma-mud-colab-starter/troubleshooting.md)
- [`Gemma4_MUD_QLoRA_Colab_Notebook-E2B.ipynb`](./gemma-mud-colab-starter/notebooks/Gemma4_MUD_QLoRA_Colab_Notebook-E2B.ipynb)
- [`Gemma4_MUD_QLoRA_Colab_Notebook-E4B.ipynb`](./gemma-mud-colab-starter/notebooks/Gemma4_MUD_QLoRA_Colab_Notebook-E4B.ipynb)

포함된 예시 데이터셋:

- `combined_1000.jsonl` : 1000행 원본
- `combined_1000.unsloth_chatml_dedup.jsonl` : 963행 정리본
- `combined_1000.unsloth_gemma4_messages_dedup.jsonl` : 963행 Gemma 4 messages 정리본
- `gemma4_mud_alpaca_100.jsonl` : 100행 소형 예시

데이터셋의 구조, 분포, 정제 방식, 새 샘플 작성 규칙은 별도 문서에서 자세히 다룬다.

- [`DATASET_GUIDE.md`](./DATASET_GUIDE.md)

중요:

- 위 데이터셋은 **starter/retraining/example 용도**로 함께 넣어 둔 것이다.
- 이 저장소의 체크포인트를 이해하거나 확장하는 데 도움을 주는 자료이며, 재현 실험을 위한 출발점으로 보는 편이 좋다.

## 응답 품질을 볼 때 좋은 기준

정답 문장을 외워 내는지가 핵심은 아니다.  
더 중요한 것은 **응답의 결**이다.

좋은 신호:

- 한국어로 답한다
- 세계관 안에 머문다
- 짧고 분위기가 있다
- 명령어별 반응 결이 다르다
- 현실 일반 상식 강의로 새지 않는다

경계 신호:

- `Hello!` 로 시작하는 범용 챗봇 톤
- `Oracle Database` 같은 현실 상식 반응
- `AI로서` 같은 메타 발언
- 엔진이 해야 할 상태 판정을 모델이 직접 선언

## 한계와 주의사항

이 모델은 특정 스타일과 용도에 맞춘 **도메인 적응형 모델**이다. 따라서 아래 한계를 이해하고 쓰는 것이 좋다.

- 세계관 톤은 강화되지만, 작은 도메인 적응 모델 특성상 **고유명사를 과장되게 이어붙이거나 분위기를 과생성**할 수 있다.
- 텍스트 MUD 서사에는 잘 맞지만, 일반 비서형 질의응답의 정확도를 목표로 하지는 않았다.
- 장황한 설명을 줄이기 위해 프롬프트와 시스템 메시지를 짧고 명확하게 유지하는 편이 좋다.
- 공식 벤치마크 기반 재평가나 별도 안전성 평가를 이 카드에서 제공하지는 않는다.

## 권장 사용 패턴

이 모델은 아래처럼 붙이면 가장 자연스럽다.

1. 플레이어 입력을 짧은 텍스트 프롬프트로 정리한다.
2. 엔진은 상태/판정을 처리한다.
3. 모델은 대사, 묘사, 힌트, 전승 설명을 생성한다.
4. 엔진은 모델 출력을 그대로 쓰기보다, 필요하면 후처리 규칙을 둔다.

특히 아래 선은 지키는 편이 좋다.

- **엔진이 결정해야 할 것**: 퀘스트 성공, 보상, 전투 판정, 문 상태
- **모델이 표현해도 좋은 것**: 분위기, 목소리, 여운, 단서, 문화, 신화

## 라이선스와 출처

- 파생 기반 모델: [`google/gemma-4-E2B-it`](https://huggingface.co/google/gemma-4-E2B-it)
- 라이선스 표기: `Apache-2.0`
- GGUF 및 starter package 는 이 저장소 배포 편의를 위해 함께 포함했다.

Gemma 4 자체의 구조와 기본 사용 방식은 공식 Gemma 4 카드와 Unsloth Gemma 4 문서를 참고하면 좋다.

- [Google Gemma 4 E2B model card](https://huggingface.co/google/gemma-4-E2B-it)
- [Unsloth Gemma 4 docs](https://unsloth.ai/docs/models/gemma-4)

## 한 줄 요약

`gemma4-e2b-mud` 는 **한국어 우주항행 텍스트 MUD의 분위기, NPC 대사, 전승 설명을 로컬에서도 빠르게 시험할 수 있게 만든 Gemma 4 E2B 파생 모델 + GGUF + Colab starter package 묶음**이다.