privyscope-ko 0.1.2

privyscope-ko — Korean language pack for the privyscope PII engine

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/ 폴더에 목적별로 정리해 뒀어요. 하고 싶은 걸 골라서 보세요:

이런 게 궁금하다면	가이드
터미널에서 돌리고 싶어요	CLI 레퍼런스
Python 코드에서 부르고 싶어요	Python API 레퍼런스
JSON 출력이 무슨 뜻인지 알고 싶어요	출력 스키마
내 라벨링 데이터로 점수를 매겨보고 싶어요	평가 및 출력 모드
정밀도와 재현율을 조절하고 싶어요	운영 포인트
인터넷 없이 폐쇄망에서 쓰고 싶어요	오프라인 사용
내 데이터로 파인튜닝하고 싶어요	파인튜닝

어떤 걸 찾아주나요

찾아주는 항목은 이렇게 여덟 가지예요: PER · PHONE · ID_NUM · EMAIL · LOC · BANK · DATE · SECRET.

정규식 규칙은 privyscope/regex_rules.yaml에 들어 있고, 코드를 건드리지 않고도 직접 추가하거나 고칠 수 있어요. 한국어에만 있는 확장 항목은 privyscope/entity_config.yaml에 정의돼 있습니다.

어떻게 동작하나요

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

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

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

모델과 성능

• 구조 — klue/roberta-base 인코더 → BIOES 토큰 분류 헤드 → Viterbi 디코더로 이어지는 형태예요.

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

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

  PER	LOC	DATE	EMAIL	ID_NUM	BANK	PHONE
  0.98	1.00	1.00	1.00	1.00	0.92	0.78

  PHONE는 정밀도가 0.64로 전화번호처럼 보이는 숫자를 과검출하는 경향이 있고, BANK는 재현율이 0.85라 일부를 놓쳐요. 검증 세트가 학습과 분리돼 있어 이 점수는 암기가 아니라 일반화 성능을 보여주지만, 분포 밖 문장에서는 더 낮게 나올 수 있어요. privyscope eval --lang ko your_val.jsonl로 직접 재현할 수 있고, 자세한 내용은 평가 및 출력 모드를 참고하세요.

한계

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

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

라이선스

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