privyscope-ko

한국어 텍스트에서 개인정보(PII)를 찾는 엔진이에요. privyscope 시리즈의 한국어 버전으로, 사람 이름, 전화번호, 주민등록번호, 이메일, 주소, 금융 정보, 비공개 날짜, 인증 정보(시크릿)를 알아서 찾아 마스킹해 줍니다.

⚠️ privyscope는 마스킹을 도와주는 도구일 뿐, 비식별화나 컴플라이언스를 보장하지는 않아요. 자세한 내용은 한계를 꼭 읽어보세요.

📖 English README

설치

pip install privyscope-ko

1분 만에 시작하기

Python에서 쓰기

from privyscope_ko import Privyscope

engine = Privyscope.from_pretrained()                 # 처음 실행할 때 ONNX 가중치를 내려받아요
result = engine.redact("홍길동의 전화번호는 010-1234-5678")

result.masked_text        # "<PER>의 전화번호는 <PHONE>"
result.detected_spans     # [DetectedSpan(label="PER", start=0, end=3, ...), ...]
result.summary            # {"span_count": 2, "by_label": {"PER": 1, "PHONE": 1}, ...}

터미널에서 쓰기

privyscope redact "홍길동의 전화번호는 010-1234-5678"
cat notes.txt | privyscope redact --operating-point high_recall

문서

더 자세한 가이드는 docs/ 폴더에 목적별로 정리해 뒀어요. 하고 싶은 걸 골라서 보세요:

어떤 걸 찾아주나요

기본 항목(정규식 + NER)은 여덟 가지예요: PER · PHONE · ID_NUM · EMAIL · LOC · BANK · DATE · SECRET.

정규식으로만 찾는 확장 항목도 있어요: BIZ_NUM · DRIVER_LICENSE · VEHICLE · CRYPTO · IP · DEVICE · URL — privyscope_ko/entity_config.yaml 참고.

Stage-1 정규식 규칙은 pii-pattern-engine 룰셋에서 가져와요. 대부분의 규칙에는 검증 함수(체크섬·사전 검사)가 붙어 있어서, 모양만 비슷한 값은 마스킹하지 않습니다. 예를 들어 900101-1234568은 주민등록번호 체크섬을 통과하니까 <ID_NUM>으로 가려지지만, 체크섬이 틀린 900101-1234567은 그대로 둡니다.

privyscope_ko/regex_rules.yaml은 scripts/gen_regex_rules.py가 자동 생성하는 파일이라 빌드할 때마다 덮어써져요. 규칙을 바꾸려면 YAML이 아니라 그 스크립트를 고쳐주세요. 자세한 건 CONTRIBUTING에 있습니다.

어떻게 동작하나요

크게 두 단계로 나눠서 PII를 찾고, 두 결과를 합쳐서(합집합) 돌려줘요 (SRS §3.4):

1. 정규식 필터 — 전화번호, 이메일, 주민번호, 카드번호, 시크릿처럼 형태가 딱 정해져 있는 PII를 잡아냅니다.
2. ONNX NER — 이름, 주소, 비공개 날짜처럼 앞뒤 문맥을 봐야 알 수 있는 PII를 잡아내요. BIOES 토큰 분류기에 제약 Viterbi 디코더를 붙여서 판단합니다.

추론할 때는 ONNX Runtime만 쓰고 PyTorch는 필요 없어요. 기본적으로 빠뜨리지 않는 걸(재현율) 우선하고, 재학습 없이 운영 포인트만 바꿔서 동작을 조절할 수 있습니다. PyTorch는 파인튜닝을 할 때만 있으면 돼요.

모델과 성능

• 구조 — beomi/kcbert-base (Apache-2.0) 인코더 → BIOES 토큰 분류 헤드 → Viterbi 디코더로 이어지는 형태예요.

• 실제 배포 파일 — INT8로 양자화한 ONNX 모델이고 크기는 약 105 MB라 150 MB 안에 넉넉히 들어와요. 최대 문장 길이는 256입니다. 가중치는 처음 쓸 때 Hugging Face Hub에서 내려받고, 파일이 멀쩡한지 확인할 수 있게 SHA-256 checksum.txt가 함께 들어 있어요.

• 정확도 — 학습과 겹치지 않는 검증 세트(1,000문장, typed/strict 채점, regex + NER 전체 파이프라인)에서 엔티티 단위 strict 마이크로 F1 = 0.940을 기록했어요. 엔티티별 strict F1:

  PER	LOC	DATE	EMAIL	ID_NUM	BANK	PHONE
  0.91	1.00	0.78	1.00	0.96	0.99	0.97

  이 검증 세트는 구어체·오타·띄어쓰기 없는 표현까지 섞은 까다로운 스트레스 세트이고, strict(오프셋 완전 일치)로 채점하기 때문에 점수는 보수적인 하한값 이에요 — 실제 정제된 문장에서는 더 높게 나옵니다. DATE(0.78)가 상대적으로 낮은데, 띄어쓰기가 불규칙한 날짜 표기에서 경계가 어긋나는 경우가 있어서예요. 검증 세트가 학습과 분리돼 있어 이 점수는 암기가 아니라 일반화 성능을 보여줍니다. privyscope eval --lang ko your_val.jsonl로 직접 재현할 수 있고, 자세한 내용은 평가 및 출력 모드를 참고하세요.

실전 예시: 온라인 쇼핑몰 문의

고객이 쇼핑몰에 보낸 실제 문의 글(약 300자, 이름·날짜·이메일·전화번호·주소· 카드번호 포함)을 engine.redact()에 그대로 넣은 결과예요.

입력

안녕하세요. 저는 김민준이라고 합니다. 2024년 3월 14일에 주문한 운동화가 아직도 배송되지 않아 문의드립니다. 제가 회원 가입할 때 사용한 이메일은 minjun.kim92@gmail.com 이고, 연락 가능한 휴대폰 번호는 010-2345-6789 입니다. 배송지 주소는 서울특별시 강남구 테헤란로 152 이며, 결제는 신한카드 4539-1488-0343-6467 로 완료했습니다. 혹시 상품이 분실된 것이라면 결제 금액을 제 카드로 환불해 주실 수 있을까요? 현재 배송 상태를 확인해 주시고, 가능한 한 빠른 답변 부탁드립니다. 감사합니다.

마스킹 결과 (result.masked_text)

안녕하세요. 저는 <PER>이라고 합니다. <DATE>에 주문한 운동화가 아직도 배송되지 않아 문의드립니다. 제가 회원 가입할 때 사용한 이메일은 <EMAIL> 이고, 연락 가능한 휴대폰 번호는 <PHONE> 입니다. 배송지 주소는 <LOC> 이며, 결제는 신한카드 <BANK> 로 완료했습니다. 혹시 상품이 분실된 것이라면 결제 금액을 제 카드로 환불해 주실 수 있을까요? 현재 배송 상태를 확인해 주시고, 가능한 한 빠른 답변 부탁드립니다. 감사합니다.

찾아낸 6개 항목

한계

쓰기 전에 이 점들은 꼭 알아두세요:

• 비식별화나 컴플라이언스를 보장하지는 않아요. 프라이버시 설계의 여러 안전장치 중 하나로 생각하고 쓰는 게 맞습니다.
• 잘 못 잡는 경우도 있어요. 예를 들어 드물거나 지역색이 강한 이름은 놓칠 수 있고, 문맥이 애매하면 공인(공개 인물)까지 과하게 가릴 수 있어요. 형식이 복잡하게 섞인 텍스트에서는 한 덩어리가 여러 조각으로 쪼개지기도 하고, 처음 보는 형식의 SECRET은 못 잡을 수 있습니다.
• 의료·법률·금융·정부 업무처럼 민감한 곳에서는 사람이 한 번 더 검토하는 걸 권장해요.

라이선스

Apache-2.0으로 배포돼요. 모델 가중치도 같은 Apache-2.0이고, 파일 무결성을 확인할 수 있는 checksum.txt(SHA-256)와 함께 Hugging Face Hub에 올라가 있습니다. 기여는 언제든 환영이에요 — CONTRIBUTING.md를 참고해 주세요.