01. 한 줄로 보는 CallGuard

CallGuard

120 다산콜센터 통화를 실시간으로 들으며 필요한 문서를 상담원 화면에 띄우고, 개인정보는 화면에 뜨기 전에 가리는 StreamRAG 시스템

기간

2026-08-20 ~ 진행 중

팀 · 역할

4명 · 백엔드·AI — ai 브랜치(초기) · server 브랜치 담당 (허브-스포크 골격·청킹·개인정보 마스킹·평가 하네스)

• Python 3.13
• FastAPI
• PostgreSQL
• Elasticsearch 9 · nori
• KoE5 임베딩
• Google STT
• WebSocket
• React
• k3s · AWS

↓ 스크롤 또는 ← → 키로 넘기기

02. 설계 원칙 - server와 ai를 따로 배포할 수 있게

두 사람이 server와 ai를 나눠 개발해도 의존이 섞이지 않도록, 허브-스포크 골격과 import-linter 계약 5종을 직접 세웠습니다.

문제

요청 흐름(server)과 검색·모델(ai)을 서로 다른 팀원이 동시에 개발 — 한쪽이 다른 쪽을 import하는 순간 따로 배포할 수 없게 된다

선택

허브는 포트·DTO 계약만, 스포크는 서로 import 금지. server는 ai·torch·langchain import 금지, domain은 순수 파이썬 — 계약 5종을 CI에서 KEPT 검사

대가

스포크끼리 협력할 때마다 hub에 포트를 먼저 만들어야 해 배선 코드가 늘었다

효과

모델 없이도 규칙 채점이 CI에서 돈다. 현재 server/apps 코드의 약 75%를 작성 (git blame)

근거: server/.importlinter — 계약 5종 · docs/architecture.md

03. 개인정보 실시간 마스킹 - 애매하면 가린다

멈춰 있던 마스킹 모듈을 넘겨받아, 통화 자막이 상담원 화면에 뜨기 전에 주민번호·전화·카드·주소를 가리도록 만들었습니다.

문제

마스킹 포트 구현이 없어 자막 수신 API가 501을 돌려주고 파이프라인 전체가 막혀 있었다

선택

구분자 제거 → 한글 수사 변환(3자 이상) → 유형별 정규식·문맥 규칙. 겹치면 넓은 쪽을 남기고, 중간 자막은 3자리 이상 숫자를 전부 가림. 전화번호는 받는 즉시 HMAC 해시

대가

과잉 마스킹을 감수했고, 음성 인식(STT) 오류가 섞이면 누락이 생긴다

효과

골든셋 누락 3건 → 0건. 운영 구성 누락 0건 (n=40)

→

근거: pii_detector.py · 결정 019 — C-5 담당 이관 · 결정 324 — 중간 자막 숫자 가림

04. StreamRAG - 말이 끝난 순간에만 찾는다

통화 중 자막은 20초에 199건씩 들어옵니다. 매번 검색하지 않고, 고객의 말이 확정된 순간에만 문서를 찾아 카드로 띄우는 흐름을 배선했습니다.

문제

중간 자막마다 검색하면 검색 서버가 과부하되고, 상담원 화면이 계속 바뀌어 읽을 수 없다

선택

STT 확정(is_final) + 고객 발화일 때만 검색을 발동. 추천 API 배선, 게이트웨이 실제 도착 시각 전달, 검색 장애 시 503, 모노 녹음 화자 분리

대가

트리거 지연은 상수로 모형화한 값이라 채점하지 않는다 — 채점하면 가짜 만점이 나온다

효과

검색이 고객 발화가 확정될 때만 한 번씩 발동해 카드가 흔들리지 않는다 (트리거 지연은 측정 전)

근거: docs/architecture.md

05. 검색 구성 - 측정하고 하이브리드를 뺐다

기획서는 BM25 + 벡터 + RRF 하이브리드를 최종형으로 가정했습니다. 같은 골든셋으로 나란히 재 보니 하이브리드가 벡터 단독보다 낮아, 팀은 벡터 검색을 택했습니다.

문제

Elasticsearch의 내장 RRF는 무료(basic) 라이선스에서 403 — 기획서의 최종형을 그대로 쓸 수 없었다

선택

RRF를 순수 파이썬 domain 계층에 직접 구현해 BM25 · dense · hybrid를 같은 골든셋(n=96)으로 비교. 저는 초기 ai 브랜치에서 지식베이스 조항 단위 청킹(첫 스포크)과 ES+nori 이미지를 맡음

대가

운영에 임베딩 모델 이미지와 벡터 적재가 필요해졌다

효과

Recall@5 — BM25 0.833 · dense 0.979 · hybrid 0.927 → 하이브리드 기각. 운영 dense 0.971 (BM25 기준선 0.853)

근거: 결정 206 — 검색 구성 · RRF 비채택 · fusion.py — RRF 직접 구현

06. 평가 하네스 - 측정 불가를 숫자로

구현은 끝났는데 하네스는 "측정 불가"만 보고했고, 수치는 터미널에서 사라졌습니다. 하네스를 배선하고 측정값을 DB에 남겨 어떤 수치든 재현할 수 있게 했습니다.

문제

모듈이 다 있는데도 통합 측정이 한 번도 돌지 않았고, 결과가 남지 않아 비교할 수 없었다

선택

마스킹 · 판정 모듈을 하네스에 배선(프로젝트 첫 통합 측정), eval_run/eval_result 기록 — 3회 중 최저치만, NaN · 미구현은 기록 안 함. 과잉 마스킹 음성 케이스와 골든셋 v1-50 작성

대가

골든셋 대부분이 팀이 직접 쓴 문장이라 실제 통화 분포와 다를 수 있다

효과

이후 모든 수치가 run_id · 커밋 · 표본 수와 함께 남는다 (운영 Recall@5 0.971 · 누락 0건)

근거: _project/STATE.md — 실측 기록

07. 결과와 회고

운영 검색 Recall@5

0.971 (BM25 0.853)

운영 검색 MRR

0.875

개인정보 누락 (운영 구성)

0건 (n=40)

테스트

server 1,257 · ai 496

본인 커밋

114개 (server/apps 코드 약 75%)

AWS 배포 런북

21단계 최초 작성