시스템 구성도¶

GovOn의 전체 시스템 아키텍처를 설명합니다. 데이터 수집부터 프론트엔드 서빙까지의 End-to-End 파이프라인과 각 모듈의 역할을 다룹니다.

E2E 아키텍처¶

데이터 수집에서 사용자 인터페이스까지의 전체 흐름입니다.

graph LR
    subgraph "1. 데이터 파이프라인"
        A1[AI Hub 수집] --> A2[PII 마스킹]
        A2 --> A3[EXAONE 형식 변환]
        A3 --> A4[AWQ 캘리브레이션<br/>데이터 생성]
    end

    subgraph "2. 모델 학습"
        B1[QLoRA 파인튜닝<br/>SFTTrainer]
        B1 --> B2[W&B 실험 추적]
    end

    subgraph "3. 양자화"
        C1[LoRA 어댑터 병합<br/>BF16]
        C1 --> C2[AWQ W4A16g128<br/>양자화]
    end

    subgraph "4. 추론 서빙"
        D1[FastAPI + vLLM]
        D2[FAISS + BM25<br/>하이브리드 검색]
        D3[Agent Manager]
    end

    subgraph "5. 프론트엔드"
        E1[Next.js 웹 UI]
    end

    A3 --> B1
    A4 --> C2
    B1 --> C1
    C2 --> D1
    D1 --- D2
    D1 --- D3
    D1 --> E1

모듈 상세¶

src/data_collection_preprocessing/¶

AI Hub에서 민원 데이터를 수집하고 학습에 사용할 수 있는 형태로 전처리하는 모듈입니다.

최종 데이터셋: Train 10,148건 / Validation 1,265건 / Test 1,265건 (총 12,678건)

파이프라인 실행:

python -m src.data_collection_preprocessing.pipeline --mode full

src/training/¶

EXAONE-Deep-7.8B를 민원 도메인에 특화시키기 위한 QLoRA 파인튜닝 모듈입니다.

학습 과정은 Weights & Biases로 실시간 추적합니다. 학습 곡선, 손실값, 토큰 정확도 등을 W&B 대시보드에서 확인할 수 있습니다.

• W&B Run: umyun3/GovOn-retrain-v2/uggxvc3s

src/quantization/¶

파인튜닝된 모델을 프로덕션 서빙에 적합한 크기로 양자화하는 모듈입니다. 2단계로 구성됩니다.

Stage 1 -- LoRA 병합 (merge_lora.py)

QLoRA 어댑터를 베이스 모델에 BF16으로 병합합니다. 병합 후 파라미터 수가 베이스 모델과 일치하는지 검증하고, 추론 테스트로 무결성을 확인합니다.

Stage 2 -- AWQ 양자화 (quantize_awq.py)

병합된 BF16 모델에 AutoAWQ로 W4A16g128 양자화를 적용합니다.

결과: 모델 크기 15.6GB에서 4.94GB로 68.3% 감소

src/inference/¶

FastAPI + vLLM 기반 추론 서빙 모듈입니다. GovOn의 핵심 런타임 모듈로, 민원 분류, 답변 생성, 유사 민원 검색을 수행합니다.

graph TB
    subgraph "api_server.py"
        A[FastAPI App]
        B[vLLMEngineManager]
    end

    subgraph "AI 엔진"
        C[AsyncLLMEngine<br/>vLLM]
        D[AgentManager<br/>classifier / generator]
    end

    subgraph "검색 엔진"
        E[CivilComplaintRetriever<br/>retriever.py]
        F[MultiIndexManager<br/>index_manager.py]
        G[BM25Indexer<br/>bm25_indexer.py]
        H[HybridSearchEngine<br/>hybrid_search.py]
    end

    subgraph "보안"
        I[API Key 인증]
        J[Rate Limiting]
        K[Prompt Injection 방어]
    end

    A --> B
    B --> C & D
    B --> H
    H --> E & F & G
    A --> I & J & K

주요 컴포넌트¶

API 명세 보기

src/evaluation/¶

파인튜닝 및 양자화된 모델의 성능을 평가하는 모듈입니다.

보안 아키텍처¶

GovOn은 공공기관 폐쇄망 환경을 위해 다층 보안을 적용합니다.

API Key 인증¶

X-API-Key 헤더를 통한 인증입니다. API_KEY 환경변수가 설정된 경우 모든 API 요청에 유효한 키가 필요합니다.

Authorization: X-API-Key: <your-api-key>

Rate Limiting¶

slowapi 기반 요청 속도 제한입니다.

CORS¶

CORS_ORIGINS 환경변수로 허용 출처를 제어합니다. 쉼표로 구분된 도메인 목록을 설정합니다.

Prompt Injection 방어¶

_escape_special_tokens() 메서드가 사용자 입력에서 EXAONE 특수 토큰을 이스케이프하여 프롬프트 주입 공격을 방어합니다. 이스케이프 대상 토큰:

• [|user|], [|assistant|], [|system|], [|endofturn|]
• <thought>, </thought>

PII 마스킹¶

검색 결과를 클라이언트에 반환하기 전에 PIIMasker가 개인식별정보(전화번호, 주민등록번호, 이메일 등)를 마스킹합니다.

오류 응답 제한¶

내부 스택 트레이스나 시스템 정보가 클라이언트에 노출되지 않습니다. 오류 발생 시 일반적인 메시지만 반환합니다.

EXAONE 채팅 템플릿¶

EXAONE-Deep-7.8B는 고유한 채팅 템플릿을 사용합니다.

[|system|]당신은 지자체 민원 상담 AI 어시스턴트입니다.[|endofturn|]
[|user|]주민등록증 재발급 절차가 어떻게 되나요?[|endofturn|]
[|assistant|]<thought>주민등록증 재발급 절차를 단계별로 안내해야 합니다.</thought>
주민등록증 재발급 절차를 안내드립니다...
[|endofturn|]

• [|system|] ~ [|endofturn|]: 시스템 프롬프트 (에이전트 페르소나)
• [|user|] ~ [|endofturn|]: 사용자 입력 (민원 내용)
• [|assistant|]: 모델 응답 시작
• <thought> ~ </thought>: 모델의 내부 추론 과정 (클라이언트 응답에서 자동 제거)

환경변수¶

관련 문서¶

• API 명세 -- 전체 REST API 엔드포인트 레퍼런스
• 모델 카드 -- EXAONE-Deep-7.8B 파인튜닝 모델 상세 정보
• ADR 목록 -- 아키텍처 결정 기록