Onjeom/writing-ai

Writing AI (온점)

국어 교과 서술형 답안을 채점하고 맞춤형 피드백을 생성하는 LoRA 어댑터입니다.
Meta-Llama-3.1-8B-bnb-4bit를 QLoRA(Unsloth)로 파인튜닝했습니다.

학습 데이터

• AI Hub 서술형 채점 데이터 및 자체 수집 데이터 (1점 ~ 4점 균형)
• 지시문 + 학생 답안 + 피드백 및 최종 점수 형식으로 가공
• 무의미한 단어 반복, 글자 수 늘리기 등 '꼼수(가짜 1점)' 필터링 적용 및 700자 길이 백신 적용 (v2)

성능

지표	수치	비고
인접 정확도 (±1점)	87.5%	인간 채점관 수준의 실무 합격선
1점 적중률	86.0%
Macro F1-Score	0.5348

학습 설정

항목	값
방식	QLoRA (4-bit NF4)
LoRA rank	32
LoRA alpha	32
Epochs	3
Learning rate	3e-5
Optimizer	adamw_8bit
Max length	1536
Framework	unsloth / trl SFTTrainer

사용 방법

  import torch
  import re
  from unsloth import FastLanguageModel
  
  ADAPTER_PATH = "Onjeom/essay_scoring"
  
  tokenizer = FastLanguageModel.from_pretrained(ADAPTER_PATH)[1]
  model, _ = FastLanguageModel.from_pretrained(
      model_name=ADAPTER_PATH,
      max_seq_length=1536,
      load_in_4bit=True,
      device_map="cuda"
  )
  FastLanguageModel.for_inference(model)
  
  RELAXED_INSTRUCTION = """주어진 지시문과 학생의 답안을 분석하여, 부족한 점과 개선 방향을 포함한 피드백을 작성하고 맨 마지막에 1점부터 4점 사이의 최종 점수를 부여하시오.
  
  [유연하고 관대한 채점 기준]
  - 4점: 지시문의 핵심 요구사항을 잘 파악하였고 전반적인 흐름이 우수한 답안 (사소한 결함은 너그럽게 만점 처리)
  - 3점: 지시문은 이해했으나 근거가 다소 평이하거나 논리의 깊이가 아쉬운 일반적인 답안
  - 2점: 지시문의 키워드만 겨우 나열했거나 주장의 근거가 심각하게 부족한 답안
  - 1점 (최하점): 같은 말을 무의미하게 반복하거나 꼼수가 명백한 답안"""
  
  ALPACA_PROMPT = "Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.\n\n### Instruction:\n{}\n\n### Input:\n{}\n\n### Response:\n{}"
  
  student_answer = "선인장은 줄기에 물을 저장해서 사막에서 살 수 있다."
  safe_input = student_answer[:700] # OOM 방지용 700자 제한
  
  prompt = ALPACA_PROMPT.format(RELAXED_INSTRUCTION, safe_input, "")
  inputs = tokenizer([prompt], return_tensors="pt").to("cuda")
  
  with torch.no_grad():
      outputs = model.generate(
          **inputs,
          max_new_tokens=512,
          temperature=0.1,
          top_p=0.9,
          pad_token_id=tokenizer.eos_token_id
      )
  
  response = tokenizer.decode(outputs[0], skip_special_tokens=True).split("### Response:\n")[-1].strip()
  print(response)

프롬프트 형식

지시문: 주어진 지시문과 학생의 답안을 분석하여... [유연하고 관대한 채점 기준] ...

입력:

{학생 답안 텍스트 - 한국어 토큰 폭발 방지를 위해 700자 제한 권장}

출력:

{개선 방향 및 피드백 텍스트}

[최종 점수: 4]

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 테스트

   브라우저에서 http://localhost:8000/docs 접속

   테스트할 엔드포인트 클릭

   Try it out 버튼 클릭

   예시 데이터 붙여넣고 Execute 클릭

3. 주요 엔드포인트 예시

서술형 자동 채점 POST /api/v1/score

  "content": "선인장은 줄기에 물을 저장해서 사막에서 살 수 있다."

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": "running"}

팀원 어댑터 다운로드

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