README.md

---
license: cc-by-nc-4.0
tags:
- translation
- korean
- english
- ko-en
- en-ko
- kanana
- kanana-1.5
- lora
- peft
- unsloth
language:
- ko
- en
library_name: peft
pipeline_tag: translation
base_model: kakaocorp/kanana-1.5-2.1b-base
datasets:
- AI-Hub-126-korean-english-parallel
model-index:
- name: kanana-1.5-2.1b-aihub-ko-en-lora
  results:
  - task:
      type: translation
    dataset:
      name: AI Hub #126 — 한국어-영어 병렬 말뭉치 (균형 검증셋 200쌍)
      type: AI-Hub-126
    metrics:
    - type: bleu
      value: 32.04
      name: BLEU
    - type: chrf
      value: 57.26
      name: chrF++
---

# kanana-1.5-2.1b-aihub-ko-en-lora

> **Kanana 1.5 2.1B base** (카카오)를 **AI Hub 한-영 병렬 말뭉치 (#126)** 로 QLoRA 파인튜닝한 **한↔영 번역 어댑터**입니다.

코드·문서 전체 리포지토리: [github.com/DeepMav/on-device-translation](https://github.com/DeepMav/on-device-translation)
자매 모델: [`harveykim/gemma-3-1b-aihub-ko-en-lora`](https://huggingface.co/harveykim/gemma-3-1b-aihub-ko-en-lora) — 동일 데이터·동일 평가 프로토콜로 학습된 Gemma 3 1B 버전.

---

## 모델 정보

| 항목 | 값 |
|---|---|
| 베이스 모델 | [`kakaocorp/kanana-1.5-2.1b-base`](https://huggingface.co/kakaocorp/kanana-1.5-2.1b-base) (Apache-2.0) |
| 어댑터 | LoRA (PEFT 0.19.1), r = 32, α = 64, dropout = 0 |
| 타겟 모듈 | 언어 레이어 전체 선형 계층 (attn q/k/v/o + mlp gate/up/down) |
| 어댑터 크기 | 약 184 MB (`safetensors`) — 토크나이저 포함 총 약 201 MB |
| 시퀀스 길이 | 1,024 |
| 학습 데이터 | AI Hub #126 — 한국어-영어 병렬 말뭉치 |
| 학습 쌍 수 | 988,003 (양방향, 균형 샘플링) |
| 지원 언어 | 한국어 ↔ 영어 |
| 라이선스 (어댑터) | CC BY-NC 4.0 — 비영리 용도 한정 |
| 라이선스 (베이스 모델) | Apache 2.0 |

> **베이스 모델 자체는 Apache 2.0**이라 상용 가능하지만, 본 어댑터는 학습 데이터(AI Hub #126)의 비영리·연구 목적 정신에 맞춰 **CC BY-NC 4.0**으로 배포합니다. 상용 사용을 원한다면 자체 데이터로 재학습하세요.

---

## 성능 (균형 검증셋 200쌍, AI Hub #126 12개 카테고리 × 양방향)

| 모델 | BLEU | chrF++ |
|---|---:|---:|
| Kanana 1.5 2.1B base (베이스) | 13.78 | 38.11 |
| **+ LoRA (988K, 1 epoch)** | **32.04** | **57.26** |
| Δ | **+18.26** | **+19.15** |

### 자매 Gemma 모델과의 비교 (동일 데이터·동일 평가)

| 모델 | 베이스 BLEU | 베이스 chrF++ | Post-SFT BLEU | Post-SFT chrF++ |
|---|---:|---:|---:|---:|
| Gemma 3 1B-IT + LoRA | 1.88 | 23.07 | 25.13 | 49.64 |
| **Kanana 1.5 2.1B base + LoRA** | **13.78** | **38.11** | **32.04** | **57.26** |
| 차이 | +11.90 | +15.04 | **+6.91** | **+7.62** |

- Kanana base의 출발선(13.78 BLEU)이 Gemma-IT 베이스(1.88)보다 월등히 높음 — 카카오의 한국어 사전학습 우위
- Post-SFT 절대 점수도 Kanana 우위 (+6.91 BLEU, +7.62 chrF++)
- SFT 게인(Δ)은 출발선이 낮았던 Gemma가 더 큼 — 베이스 자체의 한국어 능력 차이가 반영됨

---

## 파일 목록

| 파일 | 크기 | 형식 |
|---|---:|---|
| `adapter_model.safetensors` | 184 MB | PEFT LoRA 가중치 |
| `adapter_config.json` | 1.4 KB | PEFT 설정 (r=32, α=64, target_modules) |
| `tokenizer.json` | 17 MB | Kanana 토크나이저 (LFS) |
| `tokenizer_config.json` / `special_tokens_map.json` / `chat_template.jinja` | ~70 KB | 토크나이저 메타데이터 |
| `eval_result.json` | < 1 KB | 200쌍 BLEU/chrF 결과 |

---

## 사용법

### 입력 포맷 (중요)

본 어댑터는 **base 모델** 위에 학습되었으므로 chat template을 사용하지 않고 raw Instruction/Response 포맷을 따릅니다:

```
### Instruction:
{지시문}

### Input:
{입력 문장 — 옵션}

### Response:
{출력}
```

### PyTorch + PEFT

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
import torch

base = AutoModelForCausalLM.from_pretrained(
    "kakaocorp/kanana-1.5-2.1b-base",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)
model = PeftModel.from_pretrained(base, "harveykim/kanana-1.5-2.1b-aihub-ko-en-lora")
tok = AutoTokenizer.from_pretrained("harveykim/kanana-1.5-2.1b-aihub-ko-en-lora")

prompt = (
    "### Instruction:\n다음 한국어 문장을 영어로 번역하세요.\n\n"
    "### Input:\n오늘 점심은 김치찌개 어때요?\n\n"
    "### Response:\n"
)
inputs = tok(prompt, return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=128, do_sample=False)
print(tok.decode(out[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))
# → "How about kimchi stew for lunch today?"
```

### Unsloth (학습·평가에 권장, 더 빠름)

```python
from unsloth import FastModel
model, tok = FastModel.from_pretrained(
    model_name="harveykim/kanana-1.5-2.1b-aihub-ko-en-lora",
    max_seq_length=1024,
    load_in_4bit=True,
)
```

---

## 학습 정보

| 항목 | 값 |
|---|---|
| 프레임워크 | Unsloth + PEFT 0.19.1 + TRL 0.19.1 |
| 정밀도 | bfloat16 (Unsloth 4-bit 베이스) |
| 배치 | device당 16 × grad-accum 2 (effective 32) |
| 시퀀스 길이 | 1,024 |
| 옵티마이저 | AdamW 8-bit |
| 학습률 / 스케줄 | 7e-5, cosine, 2% warmup |
| Weight decay | 0.01 |
| 스텝 수 | 30,876 (988K / 32, 1 epoch) |
| 총 학습 시간 | 5.88 시간 (RTX 3090) |
| Train loss (최종) | 1.377 |
| Eval loss | 1.413 → 1.299 (15회 평가, 단조 감소, 과적합 없음) |
| Seed | 42 |

전체 학습 스크립트: [`training/train_kanana.py`](https://github.com/DeepMav/on-device-translation/blob/main/training/train_kanana.py)
4단계 자동화 파이프라인: [`training/run_pipeline_kanana.sh`](https://github.com/DeepMav/on-device-translation/blob/main/training/run_pipeline_kanana.sh)
Gemma와의 상세 비교 리포트: [`docs/COMPARISON_REPORT.md`](https://github.com/DeepMav/on-device-translation/blob/main/docs/COMPARISON_REPORT.md)

> Gemma 모델 대비 LR을 7e-5로 보수적으로 설정한 이유: Kanana 2.1B base는 **instruct-tuned가 아닌 raw base** 모델이라, 강한 LR이 사전학습된 한국어 표현 능력을 손상시킬 위험이 더 큽니다.

---

## 한계점

- **도메인 분포 편향** — AI Hub #126 분포 (대화체·구어체 중심)에 맞춰져 있어 시·문학·전문 분야는 보장 없음
- **1 epoch 단방향 학습** — Eval loss가 단조 감소 중이며 plateau 미도달. 추가 학습 여지 있음
- **Base 모델 출력 형식 의존** — Instruction/Response 포맷을 정확히 따르지 않으면 품질 저하

---

## 라이선스

- **어댑터 가중치 (이 레포)** — **CC BY-NC 4.0** (비영리·연구 목적). 출처 표기 시 자유롭게 사용 가능
- **베이스 모델** — Apache 2.0 ([`kakaocorp/kanana-1.5-2.1b-base`](https://huggingface.co/kakaocorp/kanana-1.5-2.1b-base))
- **데이터셋** — AI Hub #126은 NIA(한국지능정보사회진흥원)가 연구 목적으로 제공하며 재배포 금지. 원본 데이터는 본 레포에 포함되지 않음

### 상용 사용을 원한다면

베이스 모델 자체는 Apache 2.0이므로, 본인 데이터로 별도 LoRA를 재학습하면 상용 가능합니다. AI Hub #126 학습 결과물인 이 어댑터는 비영리 용도로만 사용 가능합니다.

---

## 인용

```bibtex
@misc{kanana_aihub_ko_en_lora_2026,
  title  = {kanana-1.5-2.1b-aihub-ko-en-lora: Korean-English Translation LoRA for Kanana 1.5},
  author = {Kim, Harvey},
  year   = {2026},
  url    = {https://huggingface.co/harveykim/kanana-1.5-2.1b-aihub-ko-en-lora}
}
```

## 감사의 글

- 베이스 모델: [Kanana 1.5 2.1B base](https://huggingface.co/kakaocorp/kanana-1.5-2.1b-base) — 카카오 (Apache 2.0)
- 학습 프레임워크: [Unsloth](https://github.com/unslothai/unsloth)
- 데이터셋: [AI Hub #126 한국어-영어 번역(병렬) 말뭉치](https://www.aihub.or.kr/aihubdata/data/view.do?dataSetSn=126) — 연구 목적 한정, 원본 데이터는 본 레포에 미포함

본 모델은 과학기술정보통신부의 재원으로 한국지능정보사회진흥원의 지원을 받아 구축된 "한국어-영어 번역(병렬) 말뭉치"(AI Hub, 데이터셋 번호 126)를 활용하여 학습되었습니다.