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/ 폴더에는 다음이 포함되어 있다.

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

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

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

DATASET_GUIDE.md

모델 개요

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

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

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

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

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

기반 모델과 구조

이 저장소의 기반은 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 안에 있다.

권장 시작 프롬프트

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/ 폴더는 모델을 다시 학습하거나 변형해 보고 싶은 사용자를 위한 구성이다.

주요 파일:

포함된 예시 데이터셋:

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

중요:

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

응답 품질을 볼 때 좋은 기준

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

좋은 신호:

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

경계 신호:

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

한계와 주의사항

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

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

권장 사용 패턴

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

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

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

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

라이선스와 출처

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

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

한 줄 요약

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