README.md

metadata

language: ko
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
tags:
  - korean
  - rag
  - small-language-model
  - scratch-pretrained

kjh-model

Scratch pretrained. Llama-style architecture. No Meta weights used.

김재현이 개인적으로 연구·학습 목적으로 개발한 로컬 한국어 언어모델이다. RAG(검색 증강 생성) 환경에서, 찾아온 자료를 근거로 답하도록 만들어졌다.

---

1. 이 모델의 출처 — 왜 랜덤 초기화부터 학습했나

이 모델의 가중치는 랜덤 초기화에서 직접 사전학습(scratch pretrained) 한 것이다. Meta 의 Llama 체크포인트를 내려받아 파인튜닝하거나 이어 학습한 것이 아니고, 어떤 형태로도 Llama 가중치를 포함하지 않는다.

architectures / model_type 이 "llama" 인 이유

config.json 의

"architectures": ["LlamaForCausalLM"],
"model_type": "llama"

는 출처 표기가 아니라 구조 표기다. transformers 라이브러리가 이 가중치 텐서를 어떤 forward 코드로 돌릴지 고르는 로더 지시자일 뿐, "이 모델이 Meta 에서 왔다"는 뜻이 아니다.

Pre-norm Transformer + RMSNorm + SwiGLU + RoPE + GQA 라는 공개된(누구나 쓸 수 있는) 설계 조합을 쓰면, transformers 안에서의 구현 이름이 llama 가 된다. 이 조합 자체는 Meta 의 전유물이 아니라 여러 논문에서 조합해 쓰는 표준 구성이다. 그래서 TinyLlama, OpenLLaMA, SmolLM 처럼 완전히 자체적으로 사전학습한 모델들도 같은 이유로 LlamaForCausalLM 을 그대로 쓴다 — 이 프로젝트만의 예외적인 표기가 아니다.

이 표기를 커스텀 클래스 이름으로 바꾸려면 auto_map + modeling_*.py 를 직접 작성해 넣고 trust_remote_code=True 로 불러야 하는데, 그러면 vLLM · llama.cpp · GGUF 변환 같은 외부 도구와의 호환이 대부분 끊긴다. 그래서 의도적으로 표준 표기를 유지했다. (architectures, model_type 은 변경하지 않는다.)

---

2. 사양

항목	값
총 파라미터	약 172M (본체 107M + 임베딩/출력층 66M)
레이어	12
hidden / intermediate	1024 / 2048
attention head	16 (KV head 4, GQA)
head_dim	64
컨텍스트 길이	4096
vocab	32,001 (자체 토크나이저 + 특수토큰 1)
dtype	float16
학습 방식	랜덤 초기화 → scratch pretraining → RAG 형식 SFT

크기부터가 Meta Llama 계열(최소 1B)에 존재하지 않는 구성이다. 참고로 파라미터를 0.1B 급으로 줄여 부르는 경우, 임베딩/출력층을 제외한 본체(107M) 기준이다 — 정확한 총량은 172M 이다.

---

3. 쓰는 법 — 반드시 [자료] / [질문] 형식으로 물을 것

이 모델은 근거 문서와 질문을 아래 형식으로 감싸 주는 것을 전제로 SFT 되었다. 이 형식을 지키지 않으면 아는 것도 지어내는 빈도가 크게 늘어난다.

[자료]
(검색해 왔거나 손으로 넣은 근거 문장들)

[질문] (사용자의 질문)

Transformers 로 직접 불러 쓰기

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

token = "hf_xxxxxxxxxxxx"  # 본인 토큰
MODEL = "coderecode95/KJH"   # 실제 리포지토리 경로로 바꿀 것
tok = AutoTokenizer.from_pretrained(MODEL, token=token)
model = AutoModelForCausalLM.from_pretrained(MODEL, token=token, dtype=torch.float16).to("cuda").eval()

# context = "" 참고자료를 넣을 경우 자료를 기반하여 답변합니다.
question = "건강을 위해서는 어떻게 해야할까?"

# prompt = f"[자료]\n{context}\n\n[질문] {question}"
prompt = f"{question}"

messages = [{"role": "user", "content": prompt}]

inputs = tok.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    return_dict=True,   # 명시적으로 dict(BatchEncoding) 반환하도록
).to("cuda")

output = model.generate(
    **inputs,
    max_new_tokens=200,
    do_sample=True,
    temperature=0.55,
    top_p=0.85,
    repetition_penalty=1.15,
    no_repeat_ngram_size=4,
    pad_token_id=tok.pad_token_id or tok.eos_token_id,
)

print(tok.decode(output[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))

위 디코딩 파라미터(temperature=0.55, repetition_penalty=1.15, no_repeat_ngram_size=4)는 generation_config.json 에도 기본값으로 들어 있으므로, 별도로 지정하지 않고 model.generate(input_ids, attention_mask=...) 만 호출해도 같은 값이 적용된다.

근거 없이 물으면 어떻게 되나

[자료] 블록 없이 질문만 던지면("[질문] 세종대왕은 누구야?" 또는 그냥 평문 질문) 모델이 갖고 있는 얕은 지식으로 답을 시도하며, 이 경우 사실 관계를 지어낼 확률이 뚜렷이 올라간다. 정확한 답이 필요한 질문은 반드시 근거를 함께 준다.

채팅 템플릿

<|im_start|>{role}
{content}<|endoftext|>
<|im_start|>assistant

ChatML 과 유사한 형식이며, tokenizer_config.json 에 chat_template.jinja 로 등록되어 있어 apply_chat_template() 을 그대로 쓰면 된다.

---

4. 무엇을 잘하고, 무엇을 못하는가 (실측 기준)

작은 모델이라는 점을 숨기지 않는다. 수백 개의 질문을 직접 돌려 확인한 결과다.

잘하는 것

• 근거를 그대로 옮겨 짧게 답하기 — [자료] 에 실제 답이 있는 사실형 질문 ("OO 테이블에 어떤 컬럼이 있어?", "설립년도가 언제야?")
• 정해진 형식의 반복 작업 — 인사, 자기소개, 정형화된 문서 요약
• 한국어 문장 생성 — 학습 데이터가 한국어 위주라 이 범위에서는 자연스럽다

못하는 것

• 영어 질문 — 한국어 전용 데이터로 학습되어 영어로 물으면 답이 무너진다 (문법이 깨지거나 관련 없는 토큰을 늘어놓는다).
• 긴 절차형 답변 — 레시피, 설치 순서처럼 단계 순서를 지켜야 하는 답변은 순서가 뒤섞이거나 없는 단계를 지어낸다.
• 멀티턴 맥락 유지 — 몇 턴만 지나도 이전 대화 내용을 엉뚱하게 되짚어 답이 무너지는 경향이 뚜렷하다. 매 질문에 필요한 정보(주어 등)를 다시 넣는 것을 권장한다.
• 고유명사·숫자를 정확히 그대로 베끼기 — 근거에 있는 이름이나 숫자를 비슷하지만 틀린 값으로 바꿔 쓰는 경우가 있다 (예: 회사명의 음절이 하나 빠짐, 연도가 한두 자리 바뀜). 법적·재무적으로 정확해야 하는 숫자·고유명사는 모델 출력을 그대로 신뢰하지 말고 원문 대조를 권장한다.
• SQL·코드 생성 — 학습 범위 밖이라 문법이 깨진 코드를 낸다. (참고: 이 모델을 실제로 서비스에 얹을 때는 SQL 생성을 모델에 맡기지 않고, 스키마 정보를 코드로 파싱해 규칙 기반으로 조립하는 방식을 함께 썼다.)

요약

이 모델 단독으로는 "무엇이든 잘 답하는 어시스턴트"가 아니다. 근거를 붙여 좁은 질문에 짧게 답하게 하는 용도로 설계되었고, 그 범위를 벗어나면 성능이 급격히 떨어진다. 정확도가 중요한 부분(숫자 계산, SQL, 스키마 조회 등)은 모델이 아니라 주변 코드가 담당하고, 모델은 "찾아온 문장을 자연스러운 한국어로 풀어 설명하는" 역할에 집중시키는 것을 권장한다.

---

5. 학습 개요

• 1단계 — 사전학습(pretraining): 랜덤 초기화 가중치에서 시작해 한국어 텍스트로 처음부터 학습.
• 2단계 — RAG 형식 SFT: [자료]\n(근거)\n\n[질문] (질문) 형식의 대화 데이터로 지도 미세조정. 근거 없이 묻는 일반 대화·인사·자기소개도 일부 포함.

6. 라이선스

Apache License 2.0. 상업적 이용을 포함해 자유롭게 사용·수정·재배포할 수 있으며, 원저작자 표시를 남겨야 한다. 자세한 조건은 리포지토리의 LICENSE 파일을 참고할 것.

7. 인용

@misc{kjh-model,
  title  = {kjh-model: A Scratch-Pretrained Korean Small Language Model for RAG},
  author = {Kim, Jaehyeon},
  year   = {2026}
}

8. 실제 사용 예시

이 모델을 RAG 파이프라인에 적용해 성능을 확인한 데모 영상입니다.

• A에서 Z까지 직접 만든 지시기반 모델 — RAG 적용하여 성능 확인하기