Onjeom/korean_qa

Korean Reading Comprehension QA (온점)

국어 교과 지문형 주관식 문제를 채점하고 해설을 생성하는 LoRA 어댑터입니다.
Qwen2.5-3B-Instruct를 QLoRA로 파인튜닝했습니다.

학습 데이터

• AI Hub 국어 교과 지문형 문제 데이터 (중1 ~ 고3)
• 지문 + 주관식 문제 + 선택지 + 모범답안 + 해설 형식으로 가공
• v1 대비 선택지 포함 재가공 (v2)

성능

버전	정답률	비고
랜덤 기준선	20%	5지선다
v1	41%	선택지 없이 학습
v2 (현재)	95%	선택지 포함 재학습

학습 설정

항목	값
방식	QLoRA (4-bit NF4)
LoRA rank	16
LoRA alpha	32
Epochs	2
Learning rate	1e-4
Optimizer	paged_adamw_8bit
Max length	1024
Framework	trl SFTTrainer / peft 0.17.1

사용 방법

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

BASE_MODEL = "Qwen/Qwen2.5-3B-Instruct"
ADAPTER_PATH = "Onjeom/korean_qa"

tokenizer = AutoTokenizer.from_pretrained(ADAPTER_PATH, trust_remote_code=True)
base_model = AutoModelForCausalLM.from_pretrained(
    BASE_MODEL,
    torch_dtype=torch.float16,
    device_map="auto",
    trust_remote_code=True,
)
model = PeftModel.from_pretrained(base_model, ADAPTER_PATH)
model.eval()

messages = [
    {"role": "system", "content": "다음 지문을 읽고 문항에 답하시오."},
    {"role": "user", "content": "[지문]\n...\n\n[문항]\n...\n① ...\n② ...\n③ ...\n④ ...\n⑤ ..."},
]

text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to(model.device)

with torch.no_grad():
    output_ids = model.generate(
        **inputs,
        max_new_tokens=256,
        do_sample=False,
        repetition_penalty=1.1,
        eos_token_id=tokenizer.eos_token_id,
        pad_token_id=tokenizer.eos_token_id,
    )

new_ids = output_ids[0][inputs["input_ids"].shape[1]:]
print(tokenizer.decode(new_ids, skip_special_tokens=True))

프롬프트 형식

시스템: 다음 지문을 읽고 문항에 답하시오.

입력:

[지문]
{지문 텍스트}

[문항]
{문제}
① ...
② ...
③ ...
④ ...
⑤ ...

출력:

정답: ④ ...
해설: ...

API 테스트 방법

1. 서버 실행

cd onjeom/api
pip install -r requirements.txt
cp .env.example .env

# HuggingFace 로그인 (최초 1회)
huggingface-cli login

# 모델 포함 정상 실행
uvicorn app.main:app --reload

# 빠른 재시작 (라우터/스키마 수정 시, 모델 로딩 생략)
SKIP_MODEL_LOAD=1 uvicorn app.main:app --reload

처음 실행 시 모델 자동 다운로드 (약 5~10분 소요).
모델 로딩 완료! 메시지가 뜨면 준비된 거예요.

2. Swagger UI 테스트

1. 브라우저에서 http://localhost:8000/docs 접속
2. 테스트할 엔드포인트 클릭
3. Try it out 버튼 클릭
4. 예시 데이터 붙여넣고 Execute 클릭

3. 주요 엔드포인트 예시

주관식 자동 채점 POST /api/grading/grade

{
  "passage": "사막은 강수량이 매우 적은 지역으로, 일교차가 크고 식물이 거의 자라지 않는다. 선인장은 두꺼운 줄기에 수분을 저장하여 이런 환경에 적응했다.",
  "question": "선인장이 사막 환경에서 살아남을 수 있는 이유를 서술하시오.",
  "model_answer": "선인장은 두꺼운 줄기에 수분을 저장하는 구조를 가지고 있어 강수량이 적은 사막에서도 생존할 수 있다.",
  "keywords": [
    {"keyword": "수분 저장", "weight": 50},
    {"keyword": "두꺼운 줄기", "weight": 30},
    {"keyword": "사막", "weight": 20}
  ],
  "student_answer": "선인장은 줄기에 물을 저장해서 사막에서 살 수 있다."
}

AI 튜터 질문 POST /api/tutor/ask

{
  "question": "추론적 독해란 무엇인가요?",
  "context": null
}

용어 설명 POST /api/tutor/explain

{
  "term": "역설법",
  "context": "글쓴이는 역설법을 사용하여 주제를 강조했다."
}

커리큘럼 생성 POST /api/curriculum/generate

{
  "theta": -0.5,
  "daily_goal": 10,
  "weak_areas": ["추론적 이해", "비판적 독해"]
}

헬스 체크 GET /health → {"status": "ok"}

팀원 어댑터 다운로드

huggingface-cli download Onjeom/korean_qa --local-dir ./models/korean_qa