VoiceGuardian_mean-win

데이콘 보이스피싱 공모전

1. GitHub 관련 명령어

0. 깃허브 파일을 clone 하기
git clone https://github.com/Choa0Kim/VoiceGuardian_mean-win.git .
1. 매일 아침 Pull 받아서 최신화 하기
git fetch
git pull origin main
2. 마무리 작업
git add .
git commit -m "Commit Message" // gitmoji -c
git push origin main

2. Gitmoji로 Commit Message 남기기

3. 프로젝트 구조

.
├── app.py # Streamlit 웹 UI 진입점
├── requirements.txt # Python 의존성
├── .env.example # 환경변수 템플릿
│
├── src/
│ ├── config.py # 전역 설정 (LLM, RAG, PII, STT/TTS, LangSmith)
│ ├── main.py # CLI 실행 진입점
│ │
│ ├── agents/ # 에이전트 모듈
│ │ ├── master.py # Master Agent — 대화 흐름 총괄, 시나리오 유형 결정, 하위 에이전트 지시
│ │ ├── roleplay_agent.py # Roleplay Agent — 사기범/정상 담당자 역할 대사 생성
│ │ ├── evaluator.py # Evaluator Agent — 사용자 응답 평가 (KcELECTRA / LLM 이중 경로)
│ │ └── guardian.py # Guardian Agent — 위험 경고, 교육 메시지, 정상 시나리오 피드백
│ │
│ ├── evaluator/ # PII 탐지 모델 (KcELECTRA 파인튜닝, CPU 전용)
│ │ └── pii_model.py # beomi/KcELECTRA-base-v2022 기반 이진 분류 (Safe/PII)
│ │
│ ├── graph/ # LangGraph 워크플로우
│ │ ├── state.py # 공유 상태 정의 (VoiceGuardianState)
│ │ └── workflow.py # StateGraph 구성, interrupt 기반 노드/엣지 연결
│ │
│ ├── voice/ # 음성 처리 (STT/TTS)
│ │ ├── stt.py # OpenAI Whisper API 기반 음성→텍스트
│ │ └── tts.py # edge-tts 기반 텍스트→음성
│ │
│ ├── tools/ # 공용 도구 (여러 에이전트가 공유)
│ │ └── voice_phishing_rag.py # ChromaDB 기반 보이스피싱 뉴스 RAG
│ │
│ ├── utils/ # 유틸리티
│ │ ├── llm.py # 에이전트별 ChatAnthropic 싱글톤 관리
│ │ ├── memory.py # 단기 메모리 (10턴) + 장기 메모리 (5턴 주기 요약)
│ │ └── rag.py # RAG 컨텍스트 빌드 공통 래퍼 (search → format 통합)
│ │
│ ├── collect_news/ # 뉴스 수집 파이프라인
│ │ ├── naver_to_BS_article.py # 매일경제 뉴스 크롤링
│ │ └── with_ChromaDB.py # 크롤링 데이터 → ChromaDB 벡터 적재
│ │
│ └── make_test_set/ # 테스트 데이터셋 생성
│ ├── connet_db.py
│ └── make_json.py
│
├── Data/
│ ├── chroma_db/ # ChromaDB 벡터 데이터베이스 (로컬 파일)
│ └── news/ # 수집된 뉴스 JSON
│
└── SQLite3/ # 사용자 더미 데이터 DB

4. 시스템 아키텍처

[START] → master ──┬──→ roleplay → human_input → master (루프)
 ├──→ evaluate ──┬──→ roleplay (safe)
 │ └──→ guardian (danger)
 └──→ human_input (주제 선택 대기)
guardian ──┬──→ human_input (위험 경고 후 대화 계속)
 └──→ END (세션 종료)

[START] → master ──→ roleplay → human_input → master ─┬─→ roleplay (대화 계속)
 ├─→ guardian → END (자연 종료)
 └─→ guardian → END (오인 거절)

5. 에이전트 상세

5-1. Master Agent (src/agents/master.py)

5-2. Roleplay Agent (src/agents/roleplay_agent.py)

5-3. Evaluator Agent (src/agents/evaluator.py)

5-4. Guardian Agent (src/agents/guardian.py)

5-5. PII 탐지 모델 (src/evaluator/pii_model.py)

5-6. 음성 처리 (src/voice/)

6. 실행 방법

환경 설정

# 1. 의존성 설치
pip install -r requirements.txt
# 2. 환경변수 설정
cp .env.example .env
# .env 파일에 ANTHROPIC_API_KEY 입력
# (음성 기능 사용 시) OPENAI_API_KEY 입력

Streamlit 웹 UI

streamlit run app.py

CLI 모드

# 대화형 시나리오 선택
python -m src.main
# 특정 시나리오로 바로 시작
python -m src.main --topic 검찰사칭
python -m src.main --topic 카드사사칭
python -m src.main --topic 대출사기
# 구조 확인 데모 (API 키 불필요)
python -m src.main --demo

7. 환경 변수 설정

8. RAG (ChromaDB) 설정

# 1. 뉴스 크롤링 (Data/news/에 JSON 저장)
python src/collect_news/naver_to_BS_article.py
# 2. ChromaDB에 벡터 적재
python src/collect_news/with_ChromaDB.py

master.py ─→ utils/rag.py ─→ voice_phishing_rag.py ─→ ChromaDB
 ↑
roleplay_agent.py ─→ utils/rag.py (캐시 재활용)
 ↑
guardian.py ─→ voice_phishing_rag.py (직접 호출 — LINK 태그 매칭용 raw results 필요)

9. 참고 기사