IOSYS ItemBank AI

AI 기반 차세대 문항은행 시스템

프로젝트 개요

교육 콘텐츠(문항)의 멀티모달 임베딩 기반 검색, 자동 분류, 이미지 참조형 문항 생성을 위한 AI 시스템

핵심 기능

기능	설명	상태
자연어 문항 검색	Qwen3-VL 기반 의미 검색	API 완료
유사 문항 추천	멀티모달 임베딩 기반 추천	API 완료
RAG 질의응답	LangChain 기반 문항 Q&A	API 완료
자동 분류	교육과정/성취기준/난이도 분류	예정
이미지 문항 생성	Fact Graph 기반 환각 방지 생성	예정

아키텍처

┌─────────────────────────────────────────────────────────────┐
│                      Client Applications                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                  itembank-api (FastAPI)                      │
│  ┌─────────────┬─────────────┬─────────────┐                │
│  │ /search/*   │ /rag/*      │ /health     │                │
│  │ 자연어 검색  │ RAG 응답    │ 헬스체크    │                │
│  └──────┬──────┴──────┬──────┴─────────────┘                │
└─────────┼─────────────┼─────────────────────────────────────┘
          │             │
┌─────────▼─────────────▼─────────────────────────────────────┐
│                    Service Layer                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ Qwen3VLService  │  │ EmbeddingService│  │ LLMService   │ │
│  │ (자연어 인코딩)  │  │ (벡터 검색)     │  │ (LangChain)  │ │
│  └────────┬────────┘  └────────┬────────┘  └──────┬───────┘ │
└───────────┼────────────────────┼──────────────────┼─────────┘
            │                    │                  │
┌───────────▼────────┐  ┌────────▼────────┐  ┌─────▼─────────┐
│ Qwen3-VL-Embedding │  │ In-Memory NPZ   │  │ OpenAI API    │
│ (GPU ~4.3GB)       │  │ (176K vectors)  │  │               │
└────────────────────┘  └────────┬────────┘  └───────────────┘
                                 │
                        ┌────────▼────────┐
                        │   PostgreSQL    │
                        │   + pgvector    │
                        └─────────────────┘

디렉토리 구조

iosys-generative/
├── itembank-api/              # 🆕 REST API 서버
│   ├── api/
│   │   ├── core/              # 설정, 의존성
│   │   ├── models/            # Pydantic 스키마
│   │   ├── routers/           # API 엔드포인트
│   │   ├── services/          # 비즈니스 로직
│   │   │   ├── qwen3vl.py     # 자연어 임베딩 (Qwen3-VL)
│   │   │   ├── embedding.py   # 벡터 검색
│   │   │   ├── database.py    # DB 연동
│   │   │   └── llm.py         # LLM 서비스
│   │   └── main.py
│   ├── API.md                 # API 문서
│   ├── HANDOVER.md            # 인수인계 문서
│   └── README.md              # API 서버 가이드
├── poc/                       # POC 구현 (실험/평가)
│   ├── models/                # 다운로드된 모델
│   ├── results/               # 임베딩 결과 (npz)
│   ├── scripts/               # 실험 스크립트
│   ├── POC-Report.md          # POC 최종 보고서
│   └── HANDOVER.md            # POC 인수인계
├── preprocessing/             # 전처리 파이프라인
├── data/                      # 원본 데이터
├── docs/                      # 프로젝트 문서
│   ├── 01 IOSYS-ITEMBANK-AI-001.md  # 마스터 플랜
│   ├── 05 ...-R02.md                # Qwen3-VL 리서치
│   └── 06 ...-POC.md                # POC 계획서
└── CLAUDE.md                  # AI 어시스턴트 지침

기술 스택

AI 모델

모델	용도	크기	차원
Qwen3-VL-Embedding-2B	멀티모달 임베딩 (Primary)	4.3GB	2048
Qwen3-VL-Reranker-2B	재순위화 (예정)	4GB	-
KURE-v1	한국어 텍스트 임베딩 (Fallback)	2.2GB	1024

인프라

구성요소	기술	버전
API Framework	FastAPI	0.128.0
Vector DB	PostgreSQL + pgvector	16 + 0.7
LLM Framework	LangChain	1.2.7
Runtime	Python	3.12.3
Deep Learning	PyTorch + CUDA	2.5.1 + 12.1
ML Library	Transformers	5.0.0
Container	Docker Compose	-

빠른 시작

요구사항

• GPU: NVIDIA RTX 2070 8GB 이상
• RAM: 32GB 이상
• Storage: 50GB 이상
• Python: 3.12+

API 서버 실행

# itembank-api 디렉토리로 이동
cd itembank-api

# 가상환경 활성화
source .venv/bin/activate

# 서버 시작
uvicorn api.main:app --host 0.0.0.0 --port 8000

# API 테스트
curl http://localhost:8000/health

자연어 검색 테스트

# 자연어로 유사 문항 검색
curl -X POST http://localhost:8000/search/text \
  -H "Content-Type: application/json" \
  -d '{"query_text": "삼각형의 넓이를 구하시오", "top_k": 5}'

POC 실험 실행

# POC 디렉토리로 이동
cd poc
source .venv/bin/activate

# 임베딩 생성
python scripts/generate_qwen_embeddings.py

# 검색 평가
python scripts/evaluate_search.py --model all

API 엔드포인트

검색 API

Method	Endpoint	설명
POST	/search/text	자연어 검색 (Qwen3VL 모델)
POST	/search/similar	유사 문항 검색 (item_id 또는 자연어)
GET	/search/items/{id}	문항 상세 조회

RAG API

Method	Endpoint	설명
POST	/rag/query	RAG 기반 질의응답
POST	/rag/generate	유사 문항 생성

상세 API 문서: itembank-api/API.md

성능

API 서버 (itembank-api)

지표	값	비고
자연어 검색 (첫 쿼리)	~25초	모델 로딩 포함
자연어 검색 (이후)	0.8-1.0초	목표 달성
임베딩 수	176,443개	전과목 문항
GPU 메모리	~4.3GB	RTX 2070 SUPER

POC 평가 결과

지표	목표	결과	상태
P95 Latency	≤200ms	30.5ms	✅
VRAM Usage	≤8GB	4.3GB	✅
MRR	≥0.65	0.74	✅
Top-5 Recall	≥80%	40.4%	⚠️

Top-K Recall 미달은 자동 생성된 Ground Truth의 한계로 판단됨

로드맵

Phase 1: 문항 벡터화 및 검색 ✅ 완료

• Qwen3-VL-Embedding POC
• pgvector 연동
• REST API 개발 (itembank-api)
• 자연어 검색 통합 (Qwen3-VL)
• 전체 데이터(176,443건) 임베딩

Phase 2: 자동 분류 시스템 (예정)

• 교육과정 분류 모델
• 성취기준 매핑
• 난이도 예측

Phase 3: 이미지 문항 생성 (예정)

• Fact Graph 추출 파이프라인
• 문항 생성 모델
• Integrity Gate 검증

Phase 4: 통합 플랫폼

• REST API 개발
• Qwen3-VL-Reranker 통합
• 관리자 UI
• 모니터링 대시보드

문서

API 서버 (itembank-api)

문서	설명
API 문서	REST API 명세
인수인계	작업 이력 및 환경 정보
README	서버 시작 가이드

POC

문서	설명
POC 보고서	POC 최종 결과
인수인계	POC 작업 이력

프로젝트 전체

문서	설명
마스터 플랜	프로젝트 전체 계획
Qwen3-VL 리서치	모델 리서치 결과

변경 이력

날짜	변경 내용
2026-01-29	itembank-api: Qwen3-VL 자연어 검색 통합, Python 3.12 업그레이드
2026-01-29	itembank-api: FastAPI 서버 구축, 문서화
2026-01-27	POC: Qwen3-VL-Embedding 평가 완료

라이선스

Private - IOSYS Internal Use Only