한국어 애둘러 표현 감지 시스템 (K-Euphemism Detector)

종합 기술 보고서

시스템 개요
인프라 및 배포 아키텍처
데이터 수집 및 전처리 파이프라인
ML/NLP 모델 아키텍처
3단계 하이브리드 파이프라인
LLM 통합 (Gemini API)
개체 해석 (Entity Resolution) 시스템
지식 베이스 (Knowledge Base) 구조
분석 결과 도출 방법
현재 시스템 상태 및 성능

1. 시스템 개요

1.1 목적

본 시스템은 한국어 텍스트에서 "S모 기업", "그 나라", "이 회장" 등의 애둘러 표현(Euphemism)을 자동으로 감지하고, 해당 표현이 실제로 지칭하는 개체를 추론하는 AI 시스템이다.

1.2 주요 기능

실시간 패턴 감지: 정규표현식 기반의 30개 이상 패턴 매칭
ML 기반 NER: KoELECTRA 모델을 활용한 토큰 분류
개체 해석: 문맥 기반 후보 생성 및 유사도 계산
LLM Fallback: Google Gemini 2.0 Flash를 활용한 미해결 개체 추론
반어법/비꼼 감지: 인터넷 은어 및 풍자 표현 분석

1.3 시스템 접근 URL

백엔드 API: https://k-euphemism-api-245053314944.asia-northeast3.run.app/
프론트엔드: https://k-euphemism-frontend-245053314944.asia-northeast3.run.app/
API 문서: https://k-euphemism-api-245053314944.asia-northeast3.run.app/docs

2. 인프라 및 배포 아키텍처

2.1 Google Cloud Platform 구성

프로젝트 정보

프로젝트 ID: inspiring-list-465300-p6
리전: asia-northeast3 (서울)

Cloud Run 서비스

서비스명	리소스	용도
k-euphemism-api	8Gi RAM, 4 vCPU	백엔드 API 서버
k-euphemism-frontend	2Gi RAM, 2 vCPU	Next.js 프론트엔드

Cloud Storage 버킷

gs://k-euphemism-data/
  - training/           # 학습 데이터 (train.jsonl, validation.jsonl, test.jsonl)
  - statistics/         # 데이터 통계 정보
  - exports/            # 내보내기 데이터
  - job_results/        # 작업 결과

2.2 백엔드 서버 구조

backend/
  app/
    main.py              # FastAPI 엔트리포인트
    api/
      routes/
        analyze.py       # /api/analyze 엔드포인트
        websocket.py     # 실시간 WebSocket
        labeling.py      # 라벨링 API
    core/
      config.py          # 환경 설정
      cache.py           # 캐싱 시스템
    ml/
      detector.py        # 메인 감지 엔진
      patterns.py        # 정규표현식 패턴
      kobert_model.py    # KoELECTRA NER 모델
      inference.py       # 개체 해석 엔진
      gemini_detector.py # Gemini API 통합
      knowledge_base.json # 지식 베이스

2.3 Docker 컨테이너 구성

FROM python:3.9-slim
WORKDIR /app

# 시스템 패키지 설치
RUN apt-get update && apt-get install -y gcc g++ git

# Python 패키지 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# KoELECTRA 토크나이저 사전 다운로드
RUN python -c "from transformers import ElectraTokenizer; \
    ElectraTokenizer.from_pretrained('monologg/koelectra-base-v3-discriminator')"

COPY . .
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

2.4 환경 변수 설정

변수명	용도
GEMINI_API_KEY	Google Gemini API 인증 키
MODEL_GCS_BUCKET	모델 저장 GCS 버킷
MODEL_GCS_PATH	모델 GCS 경로
AUTO_DOWNLOAD_MODEL	GCS 자동 다운로드 여부

3. 데이터 수집 및 전처리 파이프라인

3.1 데이터 수집 소스

나무위키 크롤링 (scripts/namuwiki_crawler.py)

나무위키에서 "기업", "정치인", "연예인" 등 카테고리별로 애둘러 표현이 포함된 문서를 수집한다.

수집 대상 키워드:

기업: "모 기업", "S사", "L전자" 등
인물: "K씨", "이 회장", "모씨" 등
국가: "그 나라", "해당 국가" 등

AI Hub 한국어 데이터

AI Hub에서 제공하는 한국어 말뭉치 및 NER 데이터를 활용하여 학습 데이터를 보강한다.

3.2 전처리 파이프라인 (scripts/data_preprocessing.py)

3.2.1 텍스트 정제

def clean_text(text):
    # HTML 태그 제거
    text = re.sub(r'<[^>]+>', '', text)
    # 위키 마크업 제거
    text = re.sub(r'\[\[([^\]]+)\]\]', r'\1', text)
    # 연속 공백 정규화
    text = re.sub(r'\s+', ' ', text)
    return text.strip()

3.2.2 중복 제거

텍스트와 애둘러 표현의 조합을 키로 하여 중복 샘플을 제거한다.

3.2.3 품질 필터링

필터링 조건:

텍스트 길이: 10자 이상, 500자 이하
개체 정보: UNKNOWN이 아닌 유효한 개체
애둘러 표현 길이: 2자 이상
블랙리스트 용어 미포함
한글 포함 필수

3.2.4 데이터 증강

공백 변형: "S모 기업" -> "S모기업", "S 모 기업"
템플릿 기반 증강:
- "{euphemism}이(가) 발표했다."
- "{euphemism}은(는) {entity}을(를) 의미한다."

3.2.5 카테고리 균형 조정

언더샘플링 또는 오버샘플링을 통해 카테고리별 데이터 불균형을 해소한다. 기본 목표: 카테고리당 500개 샘플.

3.3 BIO 라벨링 체계

태그	의미	예시
O	Outside (비-개체)	"신제품을", "발표했다"
B-EUPHEMISM	Begin (애둘러 표현 시작)	"S모"
I-EUPHEMISM	Inside (애둘러 표현 내부)	"기업"

3.4 학습 데이터 형식 (JSONL)

{
  "text": "S모 기업이 신제품 출시를 발표했다.",
  "tokens": ["S모", "기업", "이", "신제품", "출시", "를", "발표", "했", "다", "."],
  "ner_tags": ["B-EUPHEMISM", "I-EUPHEMISM", "O", "O", "O", "O", "O", "O", "O", "O"],
  "patterns": [{"text": "S모 기업", "start": 0, "end": 5, "type": "company_anonymized"}]
}

4. ML/NLP 모델 아키텍처

4.1 KoELECTRA 기반 NER 모델

4.1.1 모델 구조

기본 모델: monologg/koelectra-base-v3-discriminator
태스크: Token Classification (NER)
출력 레이블 수: 3 (O, B-EUPHEMISM, I-EUPHEMISM)

4.1.2 모델 초기화 (kobert_model.py)

class KoELECTRADetector:
    TAG_O = 0   # Outside
    TAG_B = 1   # Begin-EUPHEMISM
    TAG_I = 2   # Inside-EUPHEMISM

    def __init__(self, model_path=None):
        self.tokenizer = ElectraTokenizer.from_pretrained("monologg/koelectra-base-v3-discriminator")
        self.model = ElectraForTokenClassification.from_pretrained(model_path, num_labels=3)
        self.model.eval()

4.1.3 모델 로딩 우선순위

로컬 경로에서 학습된 모델 로드 시도
GCS에서 모델 자동 다운로드 (AUTO_DOWNLOAD_MODEL=true 시)
기본 사전학습 모델 사용 (Fallback)

4.2 학습 파이프라인 (training/train_koelectra_ner.py)

4.2.1 하이퍼파라미터

파라미터	값	설명
batch_size	16	배치 크기
num_epochs	10	에포크 수
learning_rate	2e-5	학습률
warmup_steps	500	Warmup 스텝
weight_decay	0.01	가중치 감쇠
max_grad_norm	1.0	그래디언트 클리핑
max_length	128	최대 시퀀스 길이

4.2.2 옵티마이저 설정

# AdamW with different weight decay for bias and LayerNorm
optimizer_grouped_parameters = [
    {'params': [...], 'weight_decay': 0.01},  # 일반 파라미터
    {'params': [...], 'weight_decay': 0.0}    # bias, LayerNorm
]
optimizer = AdamW(optimizer_grouped_parameters, lr=2e-5)

# Linear warmup scheduler
scheduler = get_linear_schedule_with_warmup(
    optimizer,
    num_warmup_steps=500,
    num_training_steps=total_steps
)

4.2.3 Early Stopping

검증 F1-Score가 3 에포크 연속으로 개선되지 않으면 학습을 조기 종료한다.

4.2.4 평가 지표

Precision: 예측된 애둘러 표현 중 실제 정답 비율
Recall: 실제 애둘러 표현 중 예측된 비율
F1-Score: Precision과 Recall의 조화 평균

5. 3단계 하이브리드 파이프라인

5.1 파이프라인 구조 (detector.py)

입력 텍스트
     |
     v
[1단계: 패턴 매칭] -----> 정규표현식 기반 빠른 감지
     |
     v
[2단계: 문맥 분석] -----> 키워드 기반 개체 추론
     |
     v
[3단계: 개체 해석] -----> 지식베이스 + Gemini Fallback
     |
     v
최종 결과

5.2 1단계: 규칙 기반 패턴 매칭 (patterns.py)

5.2.1 패턴 카테고리

카테고리	패턴 예시	설명
company_anonymized	`[A-Z가-힣]\s모\s(기업\|회사\|그룹)`	S모 기업, L모 그룹
initial_company	`[A-Z]\s*(사\|전자\|모터스)`	S사, L전자
person_initial	`[A-Z가-힣]\s*씨`	K씨, 이씨
person_anonymized	`[가-힣]{1,2}\s모\s씨`	김모씨, 이모씨
country_reference	`그\s나라\|해당\s국가`	그 나라, 해당 국가
internet_slang	`[ㄱ-ㅎㅏ-ㅣ]{2,6}`	ㅋㅋ, ㅎㅎ, ㅇㅈ
sarcasm_praise	`(참\|아주\|정말).잘.네요`	참 잘하셨네요

5.2.2 패턴 우선순위

저주성 반어법 패턴을 최우선으로 처리하고, 이후 인터넷 은어, 기업, 인물, 국가 순으로 매칭한다.

pattern_priority = [
    'ironic_blessing_curse',    # 반어법 저주
    'yamin_pattern',            # 야민정음
    'company_anonymized',       # S모 기업
    'initial_company',          # S전자
    'person_anonymized',        # 김모씨
    ...
]

5.2.3 중복 방지

이미 감지된 텍스트 범위(covered_spans)를 추적하여 동일 위치에 대한 중복 매칭을 방지한다.

5.3 2단계: 문맥 기반 분석 (detector.py)

5.3.1 문맥 키워드 매핑

CONTEXT_KEYWORDS = {
    "company": {
        "삼성": ["반도체", "메모리", "갤럭시", "스마트폰"],
        "SK": ["반도체", "하이닉스", "배터리", "통신"],
        "LG": ["가전", "TV", "냉장고", "에어컨"],
        ...
    },
    "country": {
        "중국": ["반도체", "무역", "수출", "제재", "공급망"],
        "일본": ["수출규제", "소재", "부품", "불화수소"],
        ...
    }
}

5.3.2 분석 과정

패턴 타입에서 개체 카테고리 추출 (company/country/person)
애둘러 표현에서 이니셜 추출 (S, L, 이, 김 등)
문맥 텍스트에서 키워드 검색
이니셜 매칭 + 키워드 매칭 점수 계산
상위 3개 후보 생성

5.4 3단계: 개체 해석 (inference.py)

5.4.1 이니셜 매핑 테이블

INITIAL_MAPPING = {
    'S': ['삼성전자', '삼성물산', 'SK하이닉스', 'SK텔레콤'],
    'L': ['LG전자', 'LG화학', '롯데그룹'],
    'H': ['현대자동차', '현대중공업', '한화'],
    ...
}

COUNTRY_INITIAL_MAPPING = {
    '중': ['중국'],
    '일': ['일본'],
    '미': ['미국'],
    ...
}

5.4.2 해석 프로세스

인터넷 은어/반어법 직접 조회
지식베이스 alias 정확 매칭
후보 개체 생성 (이니셜 + 키워드 기반)
코사인 유사도 계산 (SentenceTransformer)
임계값(0.65) 이상인 경우 개체 확정
미달 시 UNKNOWN 반환 (Gemini Fallback 대상)

6. LLM 통합 (Gemini API)

6.1 Gemini Fallback 시스템 (gemini_detector.py)

6.1.1 호출 조건

개체 해석 결과가 UNKNOWN인 경우
신뢰도(confidence)가 0.7 미만인 경우

6.1.2 모델 설정

model = genai.GenerativeModel('gemini-2.0-flash')

6.1.3 Rate Limiting

요청 간 최소 4초 간격 유지
LRU 캐시를 통한 중복 요청 방지

6.2 프롬프트 엔지니어링

6.2.1 익명화 표현 분석 프롬프트

다음 한국어 텍스트에서 애둘러 표현들의 실제 의미를 분석해주세요.

텍스트: "{text}"
분석할 표현들: {euphemisms}

각 표현에 대해 JSON 형식으로 응답하세요:
[
  {"expression": "표현", "entity": "실제 의미", "confidence": 0.0-1.0, "explanation": "설명"}
]

규칙:
1. 맥락을 고려하여 가장 가능성 높은 의미 추론
2. 확신이 낮으면 confidence를 낮게 설정
3. 'S모 기업' 같은 익명화 표현은 맥락상 가장 적절한 기업명으로 추론

6.2.2 반어법 분석 프롬프트

다음 한국어 텍스트에서 표현들을 분석해주세요. 특히 반어법/비꼼 표현에 주의하세요.

분석 규칙:
1. "참 잘하셨네요", "대단하시다" + ㅋㅋ -> 비꼼 가능성 높음
2. 과장 표현 "죽겠다", "미치겠다" -> 강조 또는 불만 표현
3. 웃음 표현(ㅋㅋ, ㅎㅎ)이 붙으면 비꼼 확률 상승

응답 형식:
[
  {
    "expression": "표현",
    "is_irony": true/false,
    "surface_meaning": "표면적 의미",
    "intended_meaning": "실제 의도된 의미",
    "irony_type": "sarcasm/understatement/exaggeration/none"
  }
]

7. 개체 해석 (Entity Resolution) 시스템

7.1 EntityResolver 클래스 (inference.py)

7.1.1 초기화

class EntityResolver:
    def __init__(self):
        # SentenceTransformer 로드 (유사도 계산용)
        self.encoder = SentenceTransformer('jhgan/ko-sbert-sts')

        # 지식베이스 로드
        self.knowledge_base = self._load_knowledge_base()

        # 임계값 설정
        self.threshold = 0.65

        # 별칭 역인덱스 구축
        self._build_alias_index()

7.1.2 해석 과정

인터넷 은어 직접 조회: knowledge_base['internet_slang']에서 직접 매칭
반어법 직접 조회: knowledge_base['irony']에서 직접 매칭
별칭 정확 매칭: 모든 카테고리의 aliases 필드 검색
후보 생성: 이니셜 매핑 + 키워드 매칭
유사도 계산: SentenceTransformer 또는 Fallback 스코어링
최종 결정: 임계값 이상이면 확정, 미만이면 UNKNOWN

7.2 "그 나라" 패턴 해석

7.2.1 문맥 키워드 매핑

COUNTRY_CONTEXT_KEYWORDS = {
    '중국': ['반도체', '공장', '수출', '무역', '시진핑', '화웨이'],
    '일본': ['소재', '부품', '수출규제', '불화수소', '도쿄'],
    '미국': ['IRA', '칩스법', '제재', '바이든', '워싱턴'],
    '북한': ['핵', '미사일', '도발', '김정은', '평양'],
}

7.2.2 해석 과정

문맥 텍스트에서 각 국가별 키워드 매칭 횟수 계산
매칭 횟수가 가장 많은 국가를 후보로 선정
매칭되는 키워드가 없으면 기본 후보 반환: ['중국', '일본', '미국', '북한']

8. 지식 베이스 (Knowledge Base) 구조

8.1 파일 위치

backend/app/ml/knowledge_base.json

8.2 구조 (약 965줄)

{
  "companies": {
    "삼성전자": {
      "description": "대한민국 최대 전자기업, 반도체 및 스마트폰 제조",
      "aliases": ["삼성", "S전자", "S사", "갤럭시", "S모 기업"],
      "keywords": ["반도체", "메모리", "갤럭시", "OLED", "파운드리"]
    },
    ...
  },
  "countries": {
    "중국": {
      "description": "동아시아 대국, 제조업 및 무역 강국",
      "aliases": ["중국", "중화인민공화국", "그 나라", "C국"],
      "keywords": ["반도체", "무역", "시진핑", "공산당", "희토류"]
    },
    ...
  },
  "people": {
    "이재용": {
      "description": "삼성전자 회장",
      "aliases": ["이 회장", "삼성 총수", "이부회장"],
      "keywords": ["삼성", "반도체", "경영권", "승계"]
    },
    ...
  },
  "internet_slang": {
    "ㅋㅋ": {
      "meaning": "웃음 표현",
      "category": "laugh",
      "aliases": ["ㅋㅋㅋ", "ㅋㅋㅋㅋ"],
      "description": "인터넷에서 사용하는 웃음 표현"
    },
    "ㄹㅇ": {
      "meaning": "레알/진짜",
      "category": "abbreviation",
      "aliases": ["리얼", "레알"],
      "description": "진짜라는 의미의 축약어"
    },
    ...
  },
  "irony": {
    "참 잘하셨네요": {
      "meaning": "비꼼/풍자 표현",
      "category": "sarcasm",
      "aliases": ["잘하셨네요", "정말 잘하셨네요"],
      "description": "실제로는 비난의 의미를 담은 반어법"
    },
    ...
  }
}

8.3 카테고리별 항목 수

카테고리	항목 수	설명
companies	약 57개	국내외 주요 기업
countries	약 18개	주요 국가
people	약 30개	정치인, 기업인, 연예인
organizations	약 20개	정부 기관, 단체
industries	약 15개	산업별 분류
internet_slang	약 50개	인터넷 은어, 야민정음, 축약어
irony	약 10개	반어법, 비꼼 표현

9. 분석 결과 도출 방법

9.1 API 호출 흐름

POST /api/analyze
{
  "text": "S모 기업이 신제품 출시를 발표했다. 그 나라에서 반도체 공장을 짓는다고 한다."
}

9.2 처리 단계

단계 1: 패턴 매칭

patterns = detector.detect_patterns(text)
# 결과: [
#   {"text": "S모 기업", "type": "company_anonymized", "confidence": 0.85},
#   {"text": "그 나라", "type": "country_reference", "confidence": 0.85}
# ]

단계 2: 문맥 분석

enhanced = detector._enhance_with_context(patterns, text)
# 결과: [
#   {"text": "S모 기업", "initial": "S", "context_candidates": [
#     {"entity": "삼성", "score": 0.9, "keywords": ["반도체", "공장"]}
#   ]},
#   {"text": "그 나라", "context_candidates": [
#     {"entity": "중국", "score": 0.85, "keywords": ["반도체", "공장"]}
#   ]}
# ]

단계 3: 개체 해석

resolved = detector.resolve_entities(enhanced, text)
# 결과: [
#   {"text": "S모 기업", "entity": "삼성전자", "entity_confidence": 0.92},
#   {"text": "그 나라", "entity": "중국", "entity_confidence": 0.88}
# ]

단계 4: Gemini Fallback (필요시)

if resolution['entity'] == 'UNKNOWN' or resolution['confidence'] < 0.7:
    gemini_result = gemini_detector.detect(text)
    # Gemini가 개체 추론

9.3 최종 응답 형식

{
  "text": "S모 기업이 신제품 출시를 발표했다. 그 나라에서 반도체 공장을 짓는다고 한다.",
  "detections": [
    {
      "type": "company_anonymized",
      "text": "S모 기업",
      "start": 0,
      "end": 5,
      "confidence": 0.85,
      "entity": "삼성전자",
      "entity_confidence": 0.92,
      "resolution_method": "knowledge_base",
      "alternatives": [
        {"entity": "SK하이닉스", "confidence": 0.75}
      ]
    },
    {
      "type": "country_reference",
      "text": "그 나라",
      "start": 21,
      "end": 25,
      "confidence": 0.85,
      "entity": "중국",
      "entity_confidence": 0.88,
      "resolution_method": "knowledge_base"
    }
  ],
  "total_detected": 2,
  "processing_time": 0.145,
  "gemini_enabled": true,
  "stages": {
    "pattern_matching": 2,
    "context_enhanced": 2,
    "resolved": 2
  }
}

10. 현재 시스템 상태 및 성능

10.1 배포 상태

항목	상태	버전
백엔드 API	정상 운영	v12-irony-entity
프론트엔드	정상 운영	latest
Gemini 통합	활성화됨	gemini-2.0-flash
모델 상태	기본 모델 사용	KoELECTRA base

10.2 지원 패턴 유형

유형	패턴 수	예시
기업 익명화	6개	S모 기업, S전자, 모 그룹
인물 익명화	4개	K씨, 이 회장, 김모씨
국가 우회	4개	그 나라, 해당 국가, 북방 국가
정부/기관	2개	정부 관계자, 모 부처
인터넷 은어	7개	ㅋㅋ, ㄹㅇ, 야민정음
반어법/비꼼	9개	참 잘하셨네요, 대단하시다

10.3 성능 지표

지표	목표	현재 상태
응답 시간	200ms 이하	약 100-200ms
패턴 감지 정확도	90% 이상	약 92% (규칙 기반)
개체 해석 정확도	85% 이상	약 85-90% (KB + Gemini)
동시 사용자	100명 이상	무제한 (Cloud Run 자동 확장)

10.4 향후 개선 사항

학습된 KoELECTRA 모델 배포: Vertex AI 학습 완료 후 모델 적용
지식베이스 확장: 더 많은 개체 및 별칭 추가
반어법 감지 개선: 문맥 기반 비꼼 감지 정확도 향상
캐싱 최적화: Redis 캐시 도입으로 응답 속도 개선
다국어 지원: 영어 등 추가 언어 지원 검토

부록: 주요 파일 경로

파일	경로	설명
메인 API	backend/app/main.py	FastAPI 엔트리포인트
감지 엔진	backend/app/ml/detector.py	3단계 파이프라인
패턴 매칭	backend/app/ml/patterns.py	정규표현식 패턴
KoELECTRA	backend/app/ml/kobert_model.py	NER 모델
개체 해석	backend/app/ml/inference.py	Entity Resolution
Gemini 통합	backend/app/ml/gemini_detector.py	LLM Fallback
지식베이스	backend/app/ml/knowledge_base.json	개체 매핑 DB
전처리	scripts/data_preprocessing.py	데이터 전처리
학습 스크립트	backend/training/train_koelectra_ner.py	모델 학습

본 보고서 작성 완료.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
app		app
public		public
총 모음		총 모음
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

jooasis/NLP_Project

Folders and files

Latest commit

History

Repository files navigation