README.md

---
base_model: unsloth/gemma-2-2b-it
tags:
- text-generation-inference
- transformers
- unsloth
- gemma2
- trl
license: openrail
language:
- en
---
# Gemma2 한국어 전용 어댑터 (Gemma2 Korean Adapter)

본 레포지토리는 **unsloth/gemma-2-2b-it** 모델을 기반으로, **한국어 질의 분류 및 검색 쿼리 재작성**을 수행하기 위한 어댑터(Adapter) 예시입니다.  
**비상업적 용도**로 배포되며, 상업적 사용은 제한됩니다. 본 모델 및 어댑터에 대한 저작권은 원 개발자에게 있으며, 무단 전재 및 배포는 금지됩니다.

---

## 주요 기능

1. **질의 분류(Query Classification)**  
   - 사용자의 질의가 인사, 농담, 겉치레 등의 실제 검색이 불필요한 경우, `{"search": ""}`(빈 문자열) 형태로 반환합니다.  
   - 즉, 검색이 전혀 필요하지 않은 상황을 자동으로 분류하여 쿼리를 생성하지 않습니다.
   
2. **검색 쿼리 작성(Search Query Rewriting)**  
   - 실제 검색이 필요한 질문의 경우, **과거 대화(Context)**를 고려하여 불완전한 쿼리를 보완하거나, 불필요한 부분을 제거해 최적화된 검색어를 생성합니다.  
   - 최종 출력은 JSON 형식으로 `{"search": "<검색 쿼리>"}` 형태를 따릅니다.

---

## 학습 데이터 구성

- **대화(Context)**: 사용자와의 과거 대화 기록을 개행(`\n`)으로 구분하여 이어붙인 텍스트
- **지시문(Instruction)**: 모델에게 어떤 작업을 수행해야 하는지 알려주는 텍스트
- **입력(Input)**: 사용자가 마지막으로 입력한 실제 질의
- **응답(Response)**: 최종 JSON 형식(`{"search": "<검색어>"}`)으로 작성된 검색 쿼리 결과

대화와 요청을 하나의 텍스트로 합쳐 학습할 수 있도록, Hugging Face `Dataset`을 활용하여 아래와 같은 템플릿에 맞춰 변환하였습니다.

---

## 프롬프트 템플릿(예시)

본 어댑터는 아래와 같은 템플릿 구조를 사용합니다. 모델에 입력될 최종 문자열은 다음과 같습니다:

```
### Context:
{conversation}

### Instruction:
다음은 대화 기록(Context)와 사용자의 질문(Input)입니다. 사용자의 질문에 답을 제공하기 위해 필요한 단일 문자열 검색 쿼리를 생성하세요. 대화 기록을 고려하여 검색 쿼리를 생성하세요. 검색이 필요하지 않거나 쿼리가 불필요한 경우(인사나, 겉치레, 농담) 빈 문자열을 반환하세요.

최종 출력 형식은 {'search': '<검색 쿼리>'}입니다.

### Input:
{input}

### Response:
{response}
```

- `{conversation}`: 과거 대화 히스토리를 개행(`\n`)으로 구분하여 이어붙인 문자열
- `{instruction}`: 사용자 요청에 대한 지침
- `{input}`: 최종 사용자 질의
- `{response}`: JSON 형식(예: `{"search": "<검색어>"}`)으로 작성된 결과

모델의 EOS 토큰(예: `tokenizer.eos_token`)을 이용해 문장 단위를 구분합니다.

---

## 사용 예시

1. **인사, 농담, 겉치레 질문**  
   - Input: “안녕? 잘 지내?”  
   - 분류 결과: 검색이 불필요하다고 판단 → `{"search": ""}`  

2. **검색 필요한 질문**  
   - Context: 이전 대화에서 “뉴욕 맛집” 이야기를 하고 있었음  
   - Input: “그럼 뉴욕에서 제일 인기 있는 햄버거 가게 찾아줘”  
   - 모델 응답: `{"search": "뉴욕 인기 햄버거 가게"}`  
   - 과거 대화를 고려하여 키워드를 추출 및 재작성

---

## 모델 구조

- **Base Model**: [unsloth/gemma-2-2b-it](https://huggingface.co/unsloth/gemma-2-2b-it)  
- **언어(Language)**: 한국어에 최적화된 어댑터  

---

## 사용 방법

1. **데이터셋 생성**  
   - `merged_dataset.json` 형태로 대화와 질의가 포함된 원본 데이터를 준비합니다.  
   - 위 예시 스크립트처럼, `{"search": "<검색어>"}` 형태의 최종 `Response`를 생성하도록 전처리(토큰 수 제한, 불필요한 대화 제거 등)를 거칩니다.

2. **포맷 변환**  
   - 템플릿(`custom_prompt`)을 사용해 `<conversation>`, `<instruction>`, `<input>`, `<response>`를 하나의 문자열로 합칩니다.
   - Hugging Face `Dataset` 객체에 맵핑(map)하여 `text` 컬럼을 생성합니다.

3. **데이터 분할**  
   - 예시 코드에서처럼 train/val 데이터를 분리한 후, 원하는 미세조정 방법으로 학습합니다.

4. **추론(Inference)**  
   - 학습된 모델 혹은 어댑터를 로드한 뒤, 사용자 입력을 받아 템플릿에 맞춰 모델에 전달합니다.
   - 모델의 최종 출력이 `{"search": "<검색어>"}` 형태인지 확인합니다.
   - `search` 필드가 빈 문자열(`""`)이라면 검색이 필요하지 않음을 의미합니다.

---

## 라이선스

- 본 어댑터는 **비상업적 용도**로만 사용 가능합니다.
- 재배포 및 파생 프로젝트 생성 시, 반드시 비상업적 목적이어야 하며, 2차 창작 시 원작자 표기를 준수해야 합니다.
- 상업적 이용이 필요한 경우 별도의 협의를 통해 허가를 받아야 합니다.

---