분필 (bunpil)
AI 문항 출제 워크플로
아키텍처 · 핵심 지표 · 평가셋과 Judge 신뢰도 · 설계 결정 · 개발하며 찾은 문제 · 한계 · 빠른 시작 · 문서
예시 문제를 붙여넣으면 유형과 난이도 구성이 비슷한 새 문항 세트를 만드는 LangGraph 평가-수정 루프 워크플로입니다. 흐름은 코드가 고정하고 생성 단계만 도구 호출 루프로 두며, 통과 여부는 코드 게이트와 생성 모델과 분리된 Judge가 판단합니다.
[!NOTE]
포트폴리오 프로젝트이며, 2026-10-22부터 무료 플랜(Render + Vercel)으로 다시 운영하고 있습니다. 지인 교사 1인이 실제 수업에 쓴 이력이 있습니다. 운영 주소는 https://bunpil-eight.vercel.app 입니다.
한동안 아무도 쓰지 않으면 서버가 잠들어 첫 출제가 12분 걸립니다(2026-10-24 실측 104.9초). 깨어난 뒤의 요청은 대략 2045초입니다. 실제 학생 정보는 넣지 마세요. 배포 구성과 실측은 docs/DEPLOY.md에 있습니다.
아키텍처
- 런타임: 모든 텍스트는 모델 호출 전에
mask_pii()로 마스킹합니다. 캡처 이미지만 원본을 마스킹할 수 없어, VLM이 텍스트로 옮긴 뒤 마스킹합니다.
- 생성과 채점 분리: 문항을 쓰는 모델과 채점하는 Judge가 다릅니다. 통과, 재시도, 문항 개수는
validate 노드의 코드가 정합니다.
- 오프라인 평가: 평가 하네스는 운영과 같은 그래프 코드로 문항을 만들고, 그 채점에 쓰는 Judge는 사람 라벨로 먼저 검증합니다.
- 성취기준 검색(RAG)은 검색을 끄고 비교한 실험에서 품질 기여가 없어 2026-10에 생성 경로에서 뺐습니다.
노드 흐름, 도구 4개, RunPod 백엔드 같은 상세 구조는 docs/ARCHITECTURE.md에 있습니다.
핵심 지표
2026-10에 사람 라벨을 다시 달고 모델을 다시 고르면서 잰 최신 값입니다.
읽는 법: κ(카파)는 LLM 채점과 사람 채점이 얼마나 일치하는지를 0~1로 나타낸 값이고, 이 프로젝트의 기준은 0.4입니다. [하한, 상한]은 95% 신뢰구간입니다. 하한까지 기준을 넘으면 "확정", 점추정치만 넘으면 "미확정"으로 적었습니다. CER은 글자 단위 오류율로, 낮을수록 좋습니다.
| 지표 | 결과 | 측정 조건 |
|---|
| Judge 신뢰도 (가중 κ) | 정답유일성 0.86 [0.74, 0.94] 확정오답매력도 0.70 [0.60, 0.77] 확정근거성 0.56 [0.35, 0.73] 미확정 | 실제 생성 문항 91건에 단 사람 라벨, 오프라인 Judge claude-sonnet-5.5 |
| 생성 모델 재선정 | 게이트 통과 12% → 100%세트당 시간 7.2분 → 38초 | 합성 지문 33개, 재시도 최대 5회. Qwen2.5-14B → gpt-6-luna |
| 생성 문항 품질 (사람 채점, 5점 만점) | gpt-6-luna 정답유일성 4.55, 오답매력도 3.76, 근거성 4.79 | 지문 33개에서 뽑은 객관식 33문항 |
| VLM 재선정 | 그림 서술 실패 30% → 0%그림 문항 CER 0.143 → 0.035 | 그림 90건과 텍스트 20건. gpt-4o-mini → gpt-6-luna |
| VLM 그림 서술 Judge 신뢰도 | κ 0.89 [0.82, 0.93] | 사람 라벨 130건(결함을 넣은 서술 40건 포함), gpt-5.6-luna |
| RAG 제거 실험 | 품질 차이 최대 0.07점, 모두 판정 불가 → 생성 경로에서 제거 | 지문 33개 × 검색 켬/끔 × 2회 |
| PII 마스킹 누락률 | 0 | 골든셋 20건, 매 커밋 CI에서 검사 |
- 생성 모델은 gemini-3.8-flash도 게이트를 100% 통과했습니다. 품질 차이는 대부분 판정 불가였고, 정답 오류와 사실 오류가 더 적고(통계적으로 유의하지는 않음) 비용이 6.6배 낮은 gpt-6-luna를 골랐습니다(세트당 $0.0034).
- 재선정 결과를 운영에 적용했습니다(2026-10-18 결정,
render.yaml). 운영은 생성 gpt-6-luna, 런타임 Judge claude-sonnet-5.5, VLM gpt-6-luna이고, 코드 기본값은 로컬 개발용(Ollama Qwen2.5-14B)으로 남아 있습니다.
- 비교 방법과 전체 수치는 MODEL_SELECTION.md, 시간순 원본 기록은 EVAL.md 28~30절에 있습니다.
평가셋과 Judge 신뢰도
위 지표가 어떤 데이터로, 얼마나 믿을 만한 채점기로 나왔는지 정리했습니다.
평가셋
| 평가셋 | 규모 | 구성 | 사람 라벨 | 쓰는 곳 |
|---|
| 문항 품질 | 95문항 (91건 채점, 4건 판단 불가) | 합성 지문 33개(어려운 지문 10개 포함) × 생성 모델 3종에서 객관식 1문항씩 | 정답유일성, 오답매력도, 근거성 (1~5점), 학생 난이도 | 오프라인 Judge 검증, 생성 모델 비교 |
| 구조 유사도 | 45건 | 예시 문제와 생성 문항 세트의 쌍 | 종합 구조 점수 (1~5점), 난이도 일치 여부 | 런타임 Judge 검증 |
| VLM 추출 | 115장 | 그림 90장(선 29, 막대 21, 원 20, 표 20), 텍스트 20장, 적대적 입력 5장 | 그림 서술 점수 130건 (실제 서술 90건, 결함을 넣은 서술 40건) | VLM 비교, 그림 서술 Judge 검증 |
| PII 마스킹 | 20건 | 개인정보 포함 10건, 정상 10건 | 문장별 개인정보 포함 여부와 유형 | CI 하드 게이트 |
문항 품질 라벨은 높은 점수에 몰려 있습니다. 정답유일성은 91건 중 59건(65%)이 5점이고, 학생 기준 난이도는 상 0건, 중 34건, 하 57건입니다. 그래서 아래 κ는 쉬운 문항과 중간 난이도 문항에서 잰 값입니다.
Judge 신뢰도
MAE는 Judge 점수와 사람 점수의 평균 차이(점)이고, 편향은 Judge 점수에서 사람 점수를 뺀 평균입니다. 편향이 양수면 Judge가 사람보다 후하게 준다는 뜻입니다.
| Judge | 과제 | n | κ [95% CI] | MAE | 편향 | 판정 |
|---|
| claude-sonnet-5.5 (오프라인 평가) | 정답유일성 | 91 | 0.86 [0.74, 0.94] | 0.33 | +0.11 | 확정 |
| 〃 | 오답매력도 | 91 | 0.70 [0.60, 0.77] | 0.44 | +0.07 | 확정 |
| 〃 | 근거성 | 91 | 0.56 [0.35, 0.73] | 0.56 | +0.17 | 미확정 |
| gpt-5.6-luna (선정 때 비교한 후보) | 정답유일성 / 오답매력도 / 근거성 | 91 | 0.78 / 0.53 / 0.54 | 0.46 / 0.71 / 0.55 | +0.22 / +0.61 / +0.43 | 정답유일성, 오답매력도는 sonnet보다 유의하게 부정확 |
| claude-sonnet-5.5 (런타임 구조 게이트, 2026-10-18~) | 구조 유사도 | 45 | 해당 없음 | 0.48 [0.32, 0.65] | −0.03 | 난이도 일치 91% |
| gpt-5.6-luna (이전 런타임 구조 게이트, ~2026-10-18) | 구조 유사도 | 45 | 해당 없음 | 0.63 [0.46, 0.84] | +0.23 | 난이도 일치 93% |
| gpt-5.6-luna (VLM 그림 서술) | 그림 서술 | 130 | 0.89 [0.82, 0.93] | 0.27 | +0.12 | 확정 |
| claude-sonnet-5.5 (VLM 비교 후보) | 그림 서술 | 130 | 0.63 [0.48, 0.75] | 0.80 | −0.68 | luna보다 부정확 |
- sonnet 문항 품질 행은 정기 평가 1회 값입니다. 선정 비교(3회 반복)에서는 sonnet 0.87 / 0.67 / 0.58이었습니다.
- 구조 유사도는 점수가 3~4점에 몰려 κ가 의미 있게 나오지 않아, MAE와 난이도 일치율로 봅니다.
- VLM 그림 서술 Judge는 3점 이하를 경보로 쓰면 치명적 결함 20건 중 16건을 잡고, 정상 서술 107건에는 경보를 한 번도 내지 않았습니다.
설계 결정
- LLM은 판단하고 코드가 결정합니다. 유형 비율, 난이도, 종합 품질처럼 의미를 봐야 하는 항목은 Judge가 점수를 매기고, 통과와 재시도, 문항 개수, 언어, 형식은 코드가 판정합니다.
- 생성 모델과 Judge를 런타임까지 분리했습니다. 처음에는 생성 모델이 자기 출력을 채점했고, 오프라인 평가만 외부 Judge를 썼습니다. 지금은 런타임과 오프라인 평가가 같은 채점 코드를 쓰고, Judge 호출이 실패하면 조용히 넘어가지 않고 멈춥니다.
- Judge도 사람 라벨로 검증합니다. 같은 두 후보라도 과제에 따라 순위가 뒤집혔습니다. 문항 품질은 sonnet(κ 0.87 vs luna 0.78)이, 그림 서술은 luna(κ 0.89 vs sonnet 0.63)가 더 정확했습니다.
- 기여를 확인하지 못한 기능은 뺍니다. 근거 규정을 찾지 못한 생기부 윤문 모듈과, 꺼 보니 품질 차이가 없던 RAG를 제거했습니다.
개발하며 찾은 문제
| 문제 | 원인 | 해결 |
|---|
| 몇 달간 쌓은 Judge 신뢰도 수치가 실제 배포 경로를 재지 않았음 | 오프라인 평가는 외부 Judge를, 런타임은 생성 모델의 자기 채점을 쓰고 있었음 | 별도 judge 노드를 두고 두 경로가 같은 채점 코드를 쓰도록 통일 |
| 모델 비교 사전 점검에서 두 API 모델의 차이가 전혀 보이지 않음 | 당시 Judge가 사람보다 오답매력도를 0.61점 후하게 줘 변별력이 없었음. 옛 κ 0.468도 Claude가 합성한 라벨 기준이었음 | 실제 생성 문항 95개에 블라인드로 사람 라벨을 달고 Judge부터 다시 고름 |
| 생성 모델 비교 33세트 내내 검색 도구가 실패했는데 드러나지 않음 | 로컬 벡터 DB 경로가 배포용이었고, 도구 예외가 메시지로만 모델에 돌아가 로그에 남지 않았음 | 경로 자동 전환, 도구 예외를 로그와 집계에 남김. qwen은 검색 도구 없이 다시 돌려 결론 유지를 확인 |
나머지 사례(중국어 오염, num_ctx 초과, OpenAI 400 오류 등)는 docs/ARCHITECTURE.md에 있습니다.
한계
- 사람 라벨은 라벨러 1인이 달아, 라벨러 간 일치도를 재지 못했습니다.
- 평가 지문은 합성이고 객관식만 라벨링했으며, 학생 기준 난이도 '상' 문항이 없습니다.
- 근거성 Judge κ는 신뢰구간 하한이 기준 아래라 미확정입니다.
- 요청 분석(문항 수, 형식 판정)과 해설은 생성 모델을 그대로 쓰고, 따로 고르거나 정확도를 재지 않았습니다.
- VLM 평가 그림 중 75건은 합성 초안이라 사람 검수 전이고, 중간 품질 검증에 쓴 결함은 인공 주입입니다.
- 2026-10-22·24에 운영 경로(Vercel → Render → API)에서 스모크 테스트와 소규모 부하 테스트로 동작을 확인했지만, 실사용 트래픽은 아직 없습니다.
빠른 시작
로컬 Ollama만으로 돌리는 최소 절차입니다. 환경변수 전체와 배포 절차는 docs/DEPLOY.md를 보세요.
git clone https://github.com/MachuEngine/bunpil.git && cd bunpil
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
ollama pull qwen2.5:14b # 생성 모델. JUDGE_BACKEND=local이면 Judge로도 재사용
# 터미널 1: API (포트 8765)
BUNPIL_API_KEY=change_me LLM_BACKEND=local OLLAMA_MODEL=qwen2.5:14b JUDGE_BACKEND=local \
.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8765
# 터미널 2: 웹 UI (포트 3000)
cd frontend && npm install
BUNPIL_API_KEY=change_me BACKEND_URL=http://localhost:8765 npm run dev
브라우저에서 http://localhost:3000 으로 접속합니다. 유닛 테스트는 LLM 호출 없이 몇 초 안에 끝납니다.
.venv/bin/python -m pytest tests/ -q
문서
