hushpond/llama-3-seoul-culture-lora-rag

<h1>🎭 Seoul Culture Event Recommendation RAG System (LoRA Adapter)</h1>

<div align="center"> <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/peft/lora_diagram.png" alt="LoRA Architecture" width="600"/> </div>

<h2>📖 Model Overview</h2> <p> 이 모델은 <strong>서울시 문화 행사 정보</strong>를 기반으로 사용자에게 맞춤형 답변을 제공하는 <strong>RAG(Retrieval-Augmented Generation)</strong> 시스템을 위해 미세조정(Fine-tuning)된 Llama-3 기반의 <strong>LoRA Adapter</strong>입니다. </p> <p> 사용자의 질문에 대해 단순히 LLM의 내부 지식으로 답변하는 것이 아니라, 외부 데이터베이스(<code>culture.csv</code>)에서 실시간으로 검색된(Retrieved) 정확한 행사 정보를 바탕으로 답변을 생성합니다. </p>

<ul> <li><strong>Base Model:</strong> <code>beomi/Llama-3-Open-Ko-8B</code></li> <li><strong>Fine-tuning Method:</strong> QLoRA (4-bit quantization + LoRA)</li> <li><strong>Target Task:</strong> 서울 문화 행사 추천 및 정보 안내 (Instruction Following)</li> <li><strong>Dataset Source:</strong> 서울시 문화 행사 정보 (4,275개 데이터)</li> </ul>

<hr>

<h2>🛠️ How to Use</h2> <p>이 모델은 <strong>LoRA Adapter</strong>이므로, 반드시 베이스 모델과 함께 로드해야 합니다.</p>

<h3>1. Install Dependencies</h3> <pre><code>pip install torch transformers peft bitsandbytes pandas accelerate</code></pre>

<h3>2. Run Inference Code</h3> <pre><code class="language-python">import torch from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig from peft import PeftModel

1. Base Model Load (4-bit Quantization for efficiency)

basemodelid = "beomi/Llama-3-Open-Ko-8B" bnbconfig = BitsAndBytesConfig( loadin4bit=True, bnb4bitquanttype="nf4", bnb4bitcompute_dtype=torch.float16 )

basemodel = AutoModelForCausalLM.frompretrained( basemodelid, quantizationconfig=bnbconfig, devicemap="auto" ) tokenizer = AutoTokenizer.frompretrained(basemodelid)

2. Load LoRA Adapter

⚠️ [YOURHUGGINGFACEID/YOURMODELNAME] 부분을 본인 모델 ID로 수정하세요!

adaptermodelid = "YOURHUGGINGFACEID/YOURMODELNAME" model = PeftModel.frompretrained(basemodel, adaptermodelid)

3. Define Inference Function

def generateresponse(context, persona, query): inputtext = f"Context: {context} Persona: [{persona}] 질문: [{query}]" prompt = f"""### Instruction: {persona} 톤으로 답변해 주세요.

Input:

{input_text}

Output:

""" inputs = tokenizer(prompt, returntensors="pt").to(model.device) with torch.nograd(): outputs = model.generate( **inputs, maxnewtokens=300, temperature=0.7, topp=0.9, eostokenid=tokenizer.eostokenid ) return tokenizer.decode(outputs, skipspecial_tokens=True).split("### Output:")[-1].strip()

4. Test

contextdata = "[서울 핸드 메이드 페어 2025, 사전 예매: 8,000원, 서울 삼성동 코엑스 1층 B홀]" print(generateresponse(context_data, "친절한 문화 가이드", "강남구에서 열리는 핸드메이드 행사 알려줘.")) </code></pre>

<hr>

<h2>📊 Training Details</h2>

<h3>Dataset</h3> <ul> <li><strong>Source:</strong> 서울열린데이터광장 (문화 행사 정보)</li> <li><strong>Size:</strong> 4,275 rows (Original CSV), Augmented for training</li> <li><strong>Format:</strong> <code>Instruction</code> (페르소나 지시), <code>Input</code> (Context + Question), <code>Output</code> (Answer)</li> <li><strong>Preprocessing:</strong> UTF-8 / CP949 인코딩 자동 처리, 결측치 제거, 512 토큰 길이 제한</li> </ul>

<h3>Hyperparameters</h3> <table border="1" cellpadding="5"> <thead> <tr> <th>Parameter</th> <th>Value</th> <th>Reason</th> </tr> </thead> <tbody> <tr> <td><strong>LoRA Rank (r)</strong></td> <td><code>32</code></td> <td>초기 Rank 8/16 실험 결과, Rank 32에서 Loss 1.51로 가장 우수한 성능 기록</td> </tr> <tr> <td><strong>LoRA Alpha</strong></td> <td><code>32</code></td> <td>Scaling factor</td> </tr> <tr> <td><strong>Target Modules</strong></td> <td><code>qproj</code>, <code>kproj</code>, <code>vproj</code>, <code>oproj</code>, <code>gateproj</code>, <code>upproj</code>, <code>downproj</code></td> <td>모든 Linear Layer 학습으로 추론 능력 극대화</td> </tr> <tr> <td><strong>Batch Size</strong></td> <td><code>1</code></td> <td>Colab T4 GPU 메모리 제약 극복</td> </tr> <tr> <td><strong>Gradient Accumulation</strong></td> <td><code>8</code></td> <td>실제 Batch Size 8 효과 (안정적 수렴)</td> </tr> <tr> <td><strong>Learning Rate</strong></td> <td><code>2e-4</code></td> <td>-</td> </tr> <tr> <td><strong>Epochs</strong></td> <td><code>3</code></td> <td>-</td> </tr> <tr> <td><strong>Optimizer</strong></td> <td><code>pagedadamw_8bit</code></td> <td>메모리 효율 최적화</td> </tr> </tbody> </table>

<h3>Performance Metrics</h3> <ul> <li><strong>Validation Loss:</strong> <code>1.5152</code> (Rank 32 기준) <ul> <li>Rank 8 Loss: 2.1565</li> <li>Rank 16 Loss: 1.7950</li> <li><strong>Rank 32 Loss: 1.5152 (Best)</strong></li> </ul> </li> <li><strong>ROUGE-L Score:</strong> <code>0.83</code> (높은 답변 정확도 및 일관성 확인)</li> <li><strong>Temperature Analysis:</strong> Temperature 0.5~0.7 구간에서 ROUGE 점수 최적화 확인 (너무 낮으면 반복, 너무 높으면 환각 발생)</li> </ul>

<div align="center"> <table border="1" cellpadding="5"> <tr> <th>Rank</th> <th>Validation Loss</th> </tr> <tr> <td>8</td> <td>2.1565</td> </tr> <tr> <td>16</td> <td>1.7950</td> </tr> <tr> <td><b>32</b></td> <td><b>1.5152</b></td> </tr> </table> </div>

<hr>

<h2>⚠️ Limitations & Future Work</h2> <ol> <li><strong>Hallucination (환각 현상):</strong> <ul> <li>모델이 학습하지 않은 외부 정보(Unknown Data)에 대해 약 <strong>50%의 환각 발생률</strong>을 보였습니다.</li> <li>RAG 시스템에서 검색되지 않은 정보에 대해 "알 수 없음"이라고 답변하도록 추가 학습(Negative Sampling)이 필요합니다.</li> </ul> </li> <li><strong>Hardware Constraints:</strong> <ul> <li>Colab T4 (free tier) 환경의 제약으로 인해 Batch Size를 1로 설정했습니다. 더 큰 VRAM 환경에서 Full Fine-tuning 시 성능 향상이 기대됩니다.</li> </ul> </li> <li><strong>Scope:</strong> <ul> <li>현재 서울시 데이터에 특화되어 있어, 타 지역 행사나 일반 상식 질문에는 답변 품질이 낮을 수 있습니다.</li> </ul> </li> </ol>

<hr>

<h2>📜 Citation & License</h2> <ul> <li><strong>License:</strong> Llama 3 Community License</li> <li><strong>Base Model:</strong> <a href="https://huggingface.co/beomi/Llama-3-Open-Ko-8B">beomi/Llama-3-Open-Ko-8B</a></li> </ul>