--- 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 묶음**이다.