English | 한국어

ko-pii

1.18에서는 잘못된 라벨·빈 Vault·문서 부분 추출·배치 누락/덮어쓰기 오류 처리를 보강했습니다. 정답 문서의 최종 가명화 출력까지 확인하려면 출력 평가를, 파일 처리 변경은 이전 안내를 참고하십시오.

한국어 문서의 개인정보를 검출하고 가역적으로 가명화하는 Python 라이브러리. 외부 ML 의존성 없이 룰 + 사전 + 체크섬만으로 동작. 공공 문서에서 특히 강하며, 어떤 ML 파이프라인의 전처리 레이어로도 활용 가능.

공개 측정값은 제품 자격증명이 아니라 분포별 참고 근거입니다. KDPII 대화체 4,891건에서 F1 0.66, 행정·서식형 생성 평가셋 540건에서 F1 0.79를 기록했습니다. 데이터셋, 라벨 정의와 채점 조건이 달라지면 결과도 달라지므로 보편적 순위나 고객 환경의 정확도로 해석하지 않습니다. 상세 조건은 벤치마크 문서를 따릅니다.

제품 계약

결정적 식별자와 PERSON·ADDRESS 같은 문맥형 라벨을 하나의 전체 F1으로 합쳐 운영 결정을 내리지 않습니다. 고객별 승격에서는 critical identifier, 문맥형 라벨, Vault 운영을 따로 검증해야 합니다.

from ko_pii import Anonymizer, ProcessingMode

result = Anonymizer(mode=ProcessingMode.STRICT, strategy="tokenize").process(
    "신청인 홍길동 (880101-1234568) 연락처 010-1234-5678"
)
print(result.text)
# 신청인 <PERSON_1> (<RRN_1>) 연락처 <PHONE_1>

print(result.vault.reveal("<RRN_1>"))            # 880101-1234568 (Vault 접근 권한은 앱에서 통제)
print(result.combined_risk.combined_risk.name)   # CRITICAL

조각 단위 입력은 각 조각을 따로 검사하지 말고, 최종 판정 전까지 보관하십시오.

from ko_pii import PreForwardAnonymizer

stream = PreForwardAnonymizer(max_chars=100_000)
stream.feed("주민번호 880101-")
stream.feed("1234568 입니다")
safe_result = stream.finalize()  # 이 시점 전에는 원문을 downstream으로 보내지 않음

이 API는 토큰별 저지연 출력을 가장하지 않습니다. 식별자가 임의의 chunk 경계에서 나뉠 수 있으므로, 개인정보 경계에서는 완성된 메시지를 가명화한 뒤 전달하는 것이 기본 계약입니다.

가명화 전후 비교

원본:
  신청인 홍길동 (880101-1234568) 연락처 010-1234-5678
  주소: 서울특별시 강남구 테헤란로 152

tokenize (토큰 치환 + Vault 복원 가능):
  신청인 <PERSON_1> (<RRN_1>) 연락처 <PHONE_1>
  주소: <ADDRESS_1>

partial (일부만 가림 — 실무 양식):
  신청인 홍OO (880101-1******) 연락처 010-****-5678
  주소: 서울특별시 강남구 ***

redact (카테고리명 치환):
  신청인 [성명] ([주민등록번호]) 연락처 [전화번호]
  주소: [주소]

처음이시면: 복원이 필요하면 STRICT + tokenize, 필요 없으면 원본 매핑을 남기지 않는 STRICT + redact를 사용하세요. Vault는 별도 보호가 필요한 개인정보 저장소입니다.

이런 것도 됩니다

1.20.0부터 지원하는 중첩 JSON·종류별 정책·원문 없는 설명 보고서:

from ko_pii import Anonymizer, anonymize_json

processed = anonymize_json(
    {"customer": {"email": "user@예시.kr", "phone": "010-2345-6789"}},
    anonymizer=Anonymizer(strategy="redact", strategies={"PHONE": "partial"}),
)
print(processed.data)
print(processed.report())  # 원문·치환값·키 경로를 기본 출력하지 않음

입력 객체와 숫자/불리언/null은 보존합니다. JSON 키 자체는 처리하지 않으며, 부분 가림은 정보 전체 제거가 아닙니다. 기존 문자열 API는 계속 사용할 수 있습니다. 반복 배열·선택 필드는 FieldRule/EACH로 명시할 수 있으며, ko-pii-compare-policies는 기존 Vault를 건드리지 않고 두 코어 설정의 처리 차이를 원문 없는 보고서로 보여줍니다. 둘 다 놓친 항목의 정확도나 원문 전체의 안전성을 판정하는 기능은 아닙니다.

• 조사 붙어있어도 잡힘 — "홍길동이" "홍길동에게" "홍길동의" → 조사 자동 분리 후 PERSON 검출
• 한자 병기 — "홍길동(洪吉童)" → 한글+한자 모두 인식
• 로마자 이름 — "Hong Gildong" → 한글로 정규화 후 매칭
• HWP/HWPX/DOCX/PDF 직접 입력 — ko-pii report.hwp --strategy tokenize (표·머리말·꼬리말·메타데이터 모두 처리)
• CSV/XLSX 헤더 자동 인식 — "성명/주민번호/연락처" 헤더 → 자동으로 PERSON/RRN/PHONE 매핑
• 공문서 날짜 자동 거부 — "시행일자: 2026-05-21" "감사기간: 3월~4월" → 생일 아님 (비-생일 키워드 30+)
• 가명 표기 자동 거부 — "박씨" "김모씨" "○○○ 시민" → 이미 가명화됨 (PII 아님)
• 관측 라벨의 결합 위험도 — 선택된 라벨 조합에 라이브러리 규칙을 적용합니다. RRN 라벨이 있으면 CRITICAL이며, 탐지 0건은 개인정보 부재나 법적 익명성의 판정이 아닙니다.
• 감사 로그 — 호출자가 제공한 actor/context와 토큰 처리 이력을 JSONL로 기록

목차

1. 왜 필요한가
2. 주요 특징
3. 설치
4. 사용 시나리오
5. 평가 결과
6. 사용법
7. 33 PII 카테고리
8. 검출 정책 — 어떤 접두어·anchor 가 작동하는가
9. 처리 모드 + 치환 전략
10. 부가 기능
11. FAQ
12. 개발
13. 라이선스

왜 필요한가

RAG·LLM 파이프라인은 미정제 비정형 데이터를 그대로 인덱싱·검색해 모델에 넣습니다 — PII 가 벡터 DB 와 응답 양쪽에 노출됩니다.

• 법적 의무 — 개인정보보호법(PIPA): 주민등록번호·건강정보 등 민감정보 처리 제한 (해외 GDPR·HIPAA 대응)
• 주권·폐쇄망 — 공공기관 망분리 환경은 외부 API 로 PII 를 보낼 수 없음 → 오프라인 결정적 검출이 필수
• 신뢰·평판 — 유출 1건이 서비스 신뢰를 무너뜨림
• ML 보완 — NER·LLM과 달리 형식·체크섬이 유효한 PII를 결정론적으로 검증해 구조적 식별자의 정밀도 기반을 제공함. 실제 F1은 입력 형식과 데이터셋별로 별도 측정

ko-pii 는 RAG 의 인제스트(벡터 DB 진입 전)와 검색(LLM 전달 전) 양단에서 PII 를 차단합니다. 같은 Vault 안에서는 같은 인물을 같은 토큰으로 치환해 문맥을 보존하고(LlamaIndex·LangChain 연동 제공), Vault 로 복원과 감사 기록을 지원합니다. 인증·인가와 키 관리는 호출 애플리케이션의 책임입니다.

주요 특징

• 한국 특화 — 한국어 PII 33 카테고리 (RRN · FRN · 여권 · 사업자 · 카드 · 계좌 · 전화 · 이메일 · 주소 · 차량 · 인명 · 직책 · 국적 등). 공공 문서에서 특히 강함
• 결정적 검출 — 룰 + 사전 + 체크섬. 주민등록번호·카드·사업자번호 등 형식 유효 식별자를 같은 정책으로 재현 가능하게 검증
• 우회 차단 — 전각 숫자(０１０)·제로폭 문자 삽입 등 유니코드 우회를 정규화로 무력화 (검출 offset 은 원본 보존)
• 외부 의존성 없음 — Python 표준 라이브러리만 사용. 오프라인/폐쇄망 동작, GPU 불필요
• 전처리 레이어 — DetectionResult (label/start/end/text/confidence) 표준 객체 출력. ML 파이프라인 앞단에 끼워넣기 편함
• 가역 가명화 + Vault — 토큰 ↔ 원본 매핑을 별도 저장소에 분리, 복원 가능
• 법적 근거 자동 부착 — 각 검출에 개인정보보호법 조항 자동 부착 (감사 추적)
• 다양한 입력 — TXT · CSV · XLSX · HWP · HWPX · DOCX · PDF ([file] extras)

도메인별 활용 가이드

# 의약품 도메인 — PERSON FP 방지 + 신체속성 오탐 방지
anon = Anonymizer(
    mode=ProcessingMode.STRICT,
    strategy="tokenize",
    exclude={"AGE", "HEIGHT", "WEIGHT"},  # "체중 1kg당" 오탐 방지
)

# PERSON FP가 많은 프로젝트만 별도 제외어 적용 (전역 사전은 변경하지 않음)
anon = Anonymizer(
    mode=ProcessingMode.STRICT,
    strategy="tokenize",
    exclude={"AGE", "HEIGHT", "WEIGHT"},
    person_exclusions={"이부프로펜", "한미약품", "메트포르민"},
)

1.21.0 업데이트: 구조화 문서에서는 field_person_exclusions로 제외 범위를 특정 필드에 한정할 수 있습니다. RegexDetector/CallableDetector는 기존 보조 탐지기 인터페이스에 연결하며, 선택적 겹침 추적은 원문 없이 판정 근거를 확인합니다. 필드별 설정·사용자 정의 규칙·설명 추적 사용법을 참고하세요. 코어 런타임 의존성은 추가하지 않습니다. 이 기능들은 1.21.0 이상에서 사용할 수 있습니다.

설치

python -m pip install --upgrade ko-pii

extras 옵션 (필요 시):

pip install "ko-pii[file]"       # HWP/HWPX/DOCX/PDF
pip install "ko-pii[security]"   # Vault AES-256-GCM

Python 3.10 이상. 코어는 표준 라이브러리만 사용.

1.20.1 업데이트: 난독화 이메일 앞의 문장을 과잉 치환하던 문제와 손상된 Vault의 토큰 매핑 충돌을 수정했습니다. 로컬 파트 내부 공백 복원은 명시적 선택으로 바뀌며, 잘못된 Vault는 오류로 거절합니다. 호환성 및 적용 안내.

내 문서로 확인하고 업데이트 비교하기

ko-pii-evaluate labeled-documents.jsonl --labels PHONE,PERSON,RRN \
  --output baseline.json
ko-pii-evaluate labeled-documents.jsonl --labels PHONE,PERSON,RRN \
  --baseline baseline.json --output current.json --fail-on-new-misses

직접 표시한 정답을 기준으로 라벨별 정탐·오탐·미탐과 새로 놓친 항목을 비교합니다. 원문을 보고서에 복사하거나 외부로 전송하지 않습니다. 입력 형식과 실행 예제는 내 문서 평가 가이드에 있습니다.

CLI·배치는 파일 크기·압축 해제량·추출 시간을 제한하며, PDF에서 읽지 못한 페이지는 성공으로 처리하지 않습니다. 기본값과 변경 방법은 파일 처리 가이드를 참조하십시오.

사용 시나리오

시나리오 1 — 결재 공문 일괄 가명화 (외부 공개·LLM 전송 전)

import os
from pathlib import Path

from ko_pii import Anonymizer, ProcessingMode
from ko_pii.io_ import read_text_isolated
from ko_pii.io_.atomic import write_text_atomic
from ko_pii.vault.encrypted import save_encrypted

Path("./가명화").mkdir(exist_ok=True)
Path("./vault").mkdir(exist_ok=True)
for path in Path("./공문서/").glob("*.hwp"):
    # 문서별 Vault로 연결 가능성과 사고 범위를 제한
    anon = Anonymizer(mode=ProcessingMode.PARANOID, strategy="tokenize")
    result = anon.process(read_text_isolated(path).text)
    save_encrypted(
        result.vault,
        f"./vault/{path.stem}.kvault",
        os.environ["KPII_VAULT_PASSWORD"],
    )
    write_text_atomic(f"./가명화/{path.stem}.txt", result.text)

• PARANOID 모드 — LOW 위험도 이상을 처리하는 보수적 전처리 모드입니다. 미탐이 없음을 보장하지 않으므로 외부 전송 전에는 대상 문서군으로 별도 검증해야 합니다.
• 가명화 결과는 외부에, Vault 는 사내 저장소에 분리 보관
• HWP 파서와 Vault 암호화: pip install "ko-pii[file,security]"

시나리오 2 — 민원 응대 시스템에서 사전 PII 검증

from ko_pii import Anonymizer, ProcessingMode, RiskLevel

anon = Anonymizer(mode=ProcessingMode.AUDIT)  # 차단 X, 검출만 보고

result = anon.process(incoming_petition_text)

# 결합 위험도가 CRITICAL 이면 담당자에게 알림
if result.combined_risk.combined_risk >= RiskLevel.CRITICAL:
    notify_admin(
        identifiers=result.combined_risk.distinct_identifiers,  # ["RRN"]
        quasi=result.combined_risk.distinct_quasi,              # ["ADDRESS", "PERSON", "PHONE"]
    )

# 응대 직원에게는 가명화 버전 제공
masked = Anonymizer(mode=ProcessingMode.STRICT, strategy="partial").process(
    incoming_petition_text
).text

• AUDIT 모드 — 차단 없이 검출만 보고 (감사·통계용)
• 결합 위험도 자동 평가 — 「개인정보 비식별 조치 가이드라인」 의 준식별자 결합 검증
• 응대 직원에게는 partial 전략으로 일부만 마스킹 (880101-1******)

시나리오 3 — Python 로그에 PII 자동 가명화 (개발자용)

# 코드 어디서든 logger.info("...") 호출 시 자동 가명화
import logging
from ko_pii import Anonymizer, ProcessingMode

_anon = Anonymizer(mode=ProcessingMode.STRICT, strategy="redact")

class PIIFilter(logging.Filter):
    def filter(self, record):
        record.msg = _anon.process(str(record.msg)).text
        return True

logging.getLogger().addFilter(PIIFilter())
logging.info("신청인 홍길동 (880101-1234568) 처리 완료")
# → "신청인 [성명] ([주민등록번호]) 처리 완료"

평가 결과

아래 비교는 과거 실행 기록이며 현재 최신 제품 간 순위가 아닙니다. 현재 Presidio는 한국 식별자 인식기를 포함합니다. 기존 비교의 활성 인식기·패키지 버전과 모델 checkpoint가 완전히 고정된 실행 manifest가 없는 항목은 최신 비교 주장에 사용하지 않습니다. OpenAI Privacy Filter의 현재 공식 모델 설명과 과거 기록의 파라미터 표기도 다르므로 같은 모델이라고 가정하지 않습니다. 새 비교는 버전·설정·라벨 매핑을 고정해 다시 측정해야 합니다. 현재 Presidio 지원 목록, 현재 Privacy Filter 모델 설명.

아래 결과는 명시한 데이터셋과 단일 채점 조건의 측정값입니다. 보편적 정확도 순위나 고객 환경의 운영 적합성을 자동으로 의미하지 않습니다:

이 실행 환경에서는 ko-pii 0.19ms, Presidio 4.2ms, openai/privacy-filter 481ms로 측정됐습니다. 각 시스템의 활성 recognizer, 모델과 런타임 구조가 다르므로 이 수치는 동일 기능의 보편적 속도 순위가 아니라 해당 구성의 처리 비용 비교입니다. 상세 조건: 종합 비교표(한글). 외부 API 요금이 없다는 뜻이며 서버 CPU·저장공간·운영 비용이 0이라는 뜻은 아닙니다.

• KDPII의 과거 비교는 단일 매처(match_forms_overlap, person_min_length=3)로 전체 4,891문서를 처리한 기록입니다. 당시 모델의 정확한 checkpoint 식별이 필요한 상태이므로 최신 모델 평가로 인용하지 않습니다.
• 전체 점수에는 당시 구성에서 매핑하지 않았던 라벨의 영향이 포함됩니다. 당시 매핑 라벨로 좁힌 기록은 openai/PF 비교 0.61 : 0.37(7라벨), Presidio 비교 0.87 : 0.65(9라벨)입니다. 현재 지원 범위·최적 구성의 우열을 뜻하지 않습니다.
• 생성 평가셋의 구조적 라벨은 EMAIL 0.998, PHONE 0.989, CARD 0.988, RRN 0.955로 측정됐다. 이 값은 해당 gold·matcher 조건이며 보편적 보장이 아니다.
• KDPII 라벨별 F1은 RRN·EMAIL·IP·FRN 1.000, PHONE 0.992인 반면 PERSON 0.135, ADDRESS 0.241입니다. 운영 판단은 전체 F1보다 실제로 필요한 라벨의 precision·recall과 TP/FP/FN을 우선해야 합니다.
• **생성 평가셋(540)**은 생성 단계에서 ko-pii 룰을 참조하지 않은 프로젝트 구축 데이터 (행정/서식체, 26라벨)이며 gold를 2단계 검토(data/generated_eval.jsonl)했다. 자기 주입 데이터는 아니지만 독립 제3자 평가도 아니며, 생성 데이터의 분포 편향과 평가 불확실성이 남으므로 고객 문서 성능을 대체하지 않는다 (상세 BENCHMARK §3b).
• 상세·재현: docs/BENCHMARK.md · docs/EVALUATION_REPORT.md. (KLUE 는 이전 방법론 수치)

운영 전 권장: 실제 문서 30~100건은 통합 오류와 명백한 오탐·미탐을 찾는 초기 smoke/calibration 표본입니다. 통계적 적합성이나 무누출을 보장하지 않습니다. 배포 전에는 위험도와 라벨 분포에 맞춘 더 큰 frozen set에서 라벨별 TP/FP/FN·재현율·신뢰구간을 기록하고 shadow/canary를 거치세요. 절차: docs/domain_fit_report.md.

알려진 한계

• PERSON 오탐 (FP) + 도메인 의존성 — 룰 기반 PERSON 검출의 가장 큰 약점. 성씨 글자로 시작하는 일반명사·생약명·외래어가 사람 이름으로 잡힐 수 있음. 외부 신문 NER(KLUE-NER PS, 5K 문장)에서는 F1 0.419로, 신문체 인명(역사·외국인·공인)과 일반명사 과탐이 크다. 일반 도메인 NER 용도라면 person_exclusions={...}, exclude={"PERSON"}, 또는 직접 학습한 토큰 NER 하이브리드를 권한다. (재현: python -c "from ko_pii.eval.klue_ner import load_klue_ner, evaluate_person; print(evaluate_person(load_klue_ner('data/klue_ner/klue-ner-v1.1_dev.tsv')).format())")
• ADDRESS 비정형 — "강남 쪽에 살아" 같은 비정형 주소는 약함 (anchor 필요). 정형 주소 ("서울특별시 강남구 테헤란로 152") 는 OK
• 형식이 겹치는 비-PII — 대표번호 4-4(1588-2024)는 제품·연식 번호와, 무구분자 13~19자리는 바코드·IMEI와 형식이 같다. 길이-브랜드 일관성·단어경계 문맥으로 상당수 거르지만, recall 우선이라 형식만으로 완전 구분은 불가 — 최종 정밀 판단은 주변 문맥(검토 큐) 또는 하이브리드 분류기(dev/classifier)의 몫
• 체크섬을 적용하는 구조적 라벨은 형식만 보는 라벨보다 오탐 억제 근거가 강하지만, OCR·새 구분자·지원하지 않는 실제 형식에서는 미탐이 생길 수 있으므로 재현율을 별도 검증해야 함

상세 평가: docs/EVALUATION_REPORT.md.

사용법

CLI

# 기본
ko-pii input.txt --mode STRICT --strategy tokenize \
       --vault vault.json -o output.txt --report report.html

# 배치 (디렉토리 일괄, 병렬)
ko-pii ./incoming/ --batch --workers 4 --output-dir ./anonymized/

# Vault 암호화 + 감사 로그
KPII_VAULT_PASSWORD=secret ko-pii doc.hwp \
    --vault vault.kvault --audit-log audit.jsonl

# 프로젝트별 PERSON 제외어 (UTF-8, 줄마다 한 단어; 빈 줄과 # 주석 무시)
ko-pii doc.txt --person-exclusions-file tenant-person-exclusions.txt

--batch는 파일별 독립 처리이며 --vault, --vault-password, --audit-log를 지원하지 않습니다. 해당 옵션을 함께 지정하면 조용히 무시하지 않고 오류로 종료합니다. 가역 Vault와 감사 이력이 필요한 문서는 단일 파일 모드로 처리하십시오. --json-summary를 사용하면 경고도 JSON의 warnings 배열에 포함되어 stderr 전체를 하나의 JSON 객체로 파싱할 수 있습니다. 이 모드에서는 대화형 --vault-password 프롬프트 대신 KPII_VAULT_PASSWORD를 사용해야 합니다.

Python API

from ko_pii import Anonymizer, ProcessingMode

anon = Anonymizer(mode=ProcessingMode.STRICT, strategy="tokenize")
result = anon.process(text)

print(result.text)                       # 가명화된 텍스트
print(result.vault.reveal("<RRN_1>"))    # 원본 복원 (호출자 권한은 애플리케이션에서 검사)
print(result.summary["by_label"])        # {"RRN": 1, "PHONE": 1, "PERSON": 1}

결합 위험도 + k-익명성

# 검출 결과의 결합 위험도 자동 평가
print(result.combined_risk.combined_risk.name)    # CRITICAL
print(result.combined_risk.distinct_identifiers)  # ["RRN"]
print(result.combined_risk.distinct_quasi)        # ["PERSON", "PHONE"]

# k-익명성 평가 (집단 데이터)
from ko_pii.analytics import k_anonymity
report = k_anonymity(records, quasi_keys=["age", "city", "job"], threshold=5)
print(report.k)                     # 최소 그룹 크기
print(report.satisfies_threshold)   # True/False
print(report.rationale)             # ["준식별자 ['age', 'city', 'job'] 기준 N개 그룹", ...]

CSV/XLSX 표 자동 처리

from ko_pii.tabular import anonymize_records
import csv

rows = list(csv.DictReader(open("employees.csv")))
# 헤더 "성명/주민번호/연락처/주소" → 자동으로 PERSON/RRN/PHONE/ADDRESS 매핑
anon_rows, vault = anonymize_records(rows, strategy="tokenize")
print(anon_rows[0])
# {'성명': '<PERSON_1>', '주민번호': '<RRN_1>', '연락처': '<PHONE_1>', '주소': '<ADDRESS_1>'}

1.19부터 자동 매핑은 공백·대소문자를 정규화한 완전 일치와 제한된 복합 헤더를 사용합니다. 신청인 연락처는 PHONE이지만 상품이름, filename, product_name은 사람 이름으로 처리하지 않습니다. 미매핑 열은 그대로 남습니다. 자동 추론만으로 모든 개인정보 열을 찾았다고 간주하지 말고, 실제 열을 확인해 column_map을 지정하십시오.

from ko_pii import ProcessingMode
from ko_pii.tabular import map_columns

print(map_columns(["상품이름", "신청인 연락처"]))  # {'신청인 연락처': 'PHONE'}
anon_rows, vault = anonymize_records(rows, column_map={"성명": "PERSON", "연락처": "PHONE"})
unchanged, audit_vault = anonymize_records(rows, mode=ProcessingMode.AUDIT)
assert unchanged == rows and len(audit_vault) == 0

AUDIT는 셀과 전달한 Vault를 변경하지 않습니다. 다른 모드에서는 매핑된 열 전체를 탐지 임계값과 무관하게 처리하는 기존 동작을 유지합니다. 표 API는 탐지 보고서를 반환하지 않으므로 값별 판정은 Anonymizer.process()로 확인합니다. 기존 부분 문자열 매칭이 꼭 필요한 경우 두 함수에 header_policy="legacy"를 지정할 수 있으나, 기존 오탐도 되살아나므로 명시적 매핑을 권장합니다.

SQL 스키마처럼 오탐이 곧 쿼리 차단으로 이어지는 경로에서는 복합 헤더 추론 대신 근거와 신뢰도를 반환하는 strict API를 사용합니다. product_name은 name으로 분류되지 않고, 단독 name은 자동 차단이 아니라 낮은 신뢰도의 검토 대상으로 표시됩니다.

from ko_pii.tabular import classify_schema_columns

evidence = classify_schema_columns(["성명", "주민등록번호", "product_name", "name"])
print(evidence["성명"])             # PERSON, confidence=1.0
print(evidence["name"].confidence)  # 0.60 (ambiguous)
assert "product_name" not in evidence

검토 큐 워크플로우 (오탐 학습)

confidence 낮은 검출 → 검토 큐에 저장 → 사용자가 FP/OK/FN 마킹 → 누적 마킹에서 사전 추천 패치 자동 생성 (자동 반영 X, 사람 검토 후 반영).

result = anon.process(text)

# 1. confidence 낮아 REVIEW 분류된 검출 (모드별 자동 분류)
for record in result.review_items():
    d = record.detection
    print(d.text, d.confidence, d.evidence)

# 2. 별도 JSONL 큐에 저장 → 사용자가 verdict 마킹
from ko_pii.review.queue import ReviewQueue
q = ReviewQueue("review.jsonl")
q.enqueue_review_records(result.review_items(), document="internal-document-id")

# 3. 누적 마킹 → 패치 파일 생성 (common_words 후보 / 이름 후보)
from ko_pii.review.feedback import apply_feedback
apply_feedback(
    queue_path="review.jsonl",
    output_dir="feedback_patches/",
    min_repeat=2,   # 같은 토큰이 2회 이상 FP → 후보 (사전 오염 방지)
)
# → feedback_patches/common_words_additions.txt  (PERSON FP 후보)
# → feedback_patches/names_to_add.txt           (FN 표시 이름)
# → feedback_patches/summary.json

검토한 common_words_additions.txt는 패키지 소스를 수정하지 말고 person_exclusions 또는 --person-exclusions-file 입력으로 사용합니다. 1.20.0부터 판정 철회 시 기존 후보 파일도 갱신하며, 손상된 큐는 건너뛰지 않고 원본을 보존한 채 오류로 반환합니다. 검토 기록·회귀 검사 계약을 참고하십시오.

개별 검출기 호출

from ko_pii.patterns.rrn import detect

for r in detect("신청인 880101-1234568"):
    print(r.label, r.text, r.confidence, r.legal_basis)
# RRN 880101-1234568 1.0 개인정보보호법 제24조의2

33 PII 카테고리

전체 라벨 키는 ko-pii --labels (CLI) 또는 from ko_pii.labels import ALL_LABELS, LABEL_INFO (Python) 로 조회할 수 있습니다.

결정적 검증 (체크섬·화이트리스트)

키워드 anchor (키워드 + 형식 모두 필요)

형식 검증

사전·휴리스틱

인적 속성 (준식별자 — 결합 시 식별 위험)

준식별자 (Quasi-Identifier) 단독으로는 식별 불가지만 다른 정보와 결합 시 재식별 위험. analytics/combined_risk 가 자동 평가.

검출 정책 — 어떤 접두어·anchor 가 작동하는가

각 PII 검출은 단순 정규식 매칭이 아닌 multi-gate: 접두어 라벨 / 키워드 anchor / 문맥 사전 / 형식 검증 의 조합.

PERSON 필드 라벨 (50+ 항목)

라벨 직후 1~4글자 한글 → 강한 PERSON 후보.

라벨 variant 7종 인식: 성명: 홍길동 / [성명] 홍길동 / (성명) 홍길동 / <성명> 홍길동 등.

PERSON 거부 룰 (17+, FP 방지)

• 단성 + 직급/지역/학교/은행: 김부장 김포시 이화여대 → 거부
• 한국어 어말 형태소 16종: ~은데 ~는데 ~라서 ~까지 끝 → 거부
• 부처·기관명: 보건복지부 행정안전부 → 거부
• 이미 가명화된 표기: 박씨 김모씨 ○○○ 시민 → 거부

검출 예시

✓ 성명: 김도윤               (필드 라벨)
✓ 박지훈 과장님께            (직책 인접)
✓ 홍길동(洪吉童)             (한자 병기)
✓ 880101-1234568            (RRN — 체크섬)
✓ 120-81-47521              (사업자 — 국세청 체크섬)
✓ 4242-4242-4242-4242       (카드 — Luhn)
✓ M12345678                 (여권)

✗ 김부장이 협조 안 함        (호칭 = 거부)
✗ 보건복지부는 검토 후        (부처명)
✗ 시행일자: 2026-05-20       (비-생일 거부)
✗ 881301-1000004            (RRN — 13월 무효)
✗ A12345678                 (여권 — A prefix 거부)

처리 모드 + 치환 전략

fpe는 표준 암호화 방식이 아니며 원문과 변환값의 대응을 Vault에 저장합니다. 1.19.1부터 비표준 숫자 표기는 정규화 후 변환하므로 길이·구분자가 달라질 수 있습니다. 지원하지 않는 형식(예: [at] 이메일)이나 변환값이 원래 값과 같은 경우에는 전체 별표 마스킹으로 대체합니다. 이 경우 형식 보존보다 원문 노출 방지를 우선합니다. 일반적인 지원 형식의 매핑과 지문 설정은 유지하지만, 수정된 비표준 입력은 이전 버전과 출력이 달라질 수 있습니다. 가명값의 유일성이나 재식별 불가능성을 보장하지 않습니다.

partial도 숫자 정규화를 적용하며, CARD/ACCOUNT로 직접 지정된 8자리 이하 값은 앞뒤 보존만으로 전체가 노출되지 않도록 모두 가립니다. 생년의 연도·직책 등 기존의 의도된 일부 정보 보존 정책은 유지합니다.

부가 기능

파서 상세

PDF 참고: PDF는 글자 좌표 기반이라 칸별 공백·줄바꿈 삽입이 흔합니다. ko-pii는 내장 정규화 엔진(text_normalizer)으로 PII 패턴 중간의 불필요 공백/줄바꿈을 자동 보정합니다. pdfplumber가 pypdf보다 레이아웃 분석이 우수하므로 pdfplumber 설치를 권장합니다.

신뢰하지 않는 RAG 문서를 처리할 때는 일반 read_text() 대신 파일 크기, ZIP 멤버 수, 개별·전체 압축 해제량, 압축률, 경로 탈출, XML DTD·엔티티, 추출 문자 수를 먼저 검사하는 bounded API를 사용합니다.

from ko_pii.io_ import FileReadPolicy, read_text_bounded

document = read_text_bounded(
    "notice.hwpx",
    policy=FileReadPolicy(max_file_bytes=8 * 1024 * 1024),
)
print(document.sha256, document.archive_members)
text = document.text

기본 bounded allowlist는 TXT·Markdown·CSV·TSV·HWPX·DOCX·XLSX입니다. PDF와 구형 HWP는 파서 자체가 결정론적 페이지·압축 해제 budget을 제공하지 않으므로, 별도 메모리·시간 제한 worker에서 실행하는 배포만 allowed_extensions로 명시적으로 활성화해야 합니다. CLI와 read_text_isolated()는 이 worker를 기본 제공하며, 시간·메모리 제한과 PDF 처리 범위를 명시합니다.

RAG 파이프라인 연동

검색된 문서를 LLM 에 넣기 전에 PII 를 마스킹합니다. 한 번의 검색 결과 안에서 같은 인물은 같은 토큰(<PERSON_1>)으로 치환돼 문맥이 보존되고, vault 를 넘기면 답변 생성 후 vault.reveal() 로 복원할 수 있습니다.

# LlamaIndex — node postprocessor (검색 → 마스킹 → LLM)
from ko_pii.integrations.llamaindex import KoPiiNodePostprocessor

qe = index.as_query_engine(
    node_postprocessors=[KoPiiNodePostprocessor(mode="STRICT")]
)

# LangChain — Runnable 체인에 그대로 삽입
from ko_pii.integrations.langchain import KoPiiRedactor

chain = retriever | KoPiiRedactor(mode="STRICT") | prompt | llm

룰+ML 하이브리드 (opt-in)

코어는 ML 없이 동작하되, 정확도가 더 필요하면 ML 을 얹을 수 있습니다. 하이브리드는 두 종류이며 서로 다른 기능입니다:

① 토큰 NER 하이브리드 — docs/HYBRID_NER.md 레시피로 직접 학습한 NER 모델을 꽂으면 됩니다:

from ko_pii import Anonymizer
from ko_pii.integrations.hf_token_ner import HFTokenNERAdapter

ml = HFTokenNERAdapter("out/ner_fuzzy/final")   # 직접 학습한 모델 (레시피 참조)
anon = Anonymizer(secondary_detector=ml, merge_mode="role_split")
result = anon.process(text)   # 모든 전략(tokenize/partial/redact)·Vault 그대로 동작

② 문서 분류기 하이브리드 — [classifier] extra 로 결합 방식과 민감도를 직접 설정:

classifier_threshold · gate_threshold 로 룰 ↔ ML 결합 비율(민감도)을 세밀하게 조절합니다.

from ko_pii import Anonymizer, ProcessingMode
from ko_pii.classifier import PIIClassifier, HybridAnonymizer, HybridMode

clf = PIIClassifier.from_pretrained("models/...")
hybrid = HybridAnonymizer(
    Anonymizer(mode=ProcessingMode.BALANCED), clf,
    mode=HybridMode.REVIEW_FLAG,     # 결합 방식
    classifier_threshold=0.5,        # 민감도(비율) 조절
)

pip install ko-pii[classifier]      # torch + transformers + scikit-learn
python -m ko_pii.classifier.train ...   # 모델은 직접 학습

사전학습 가중치는 배포하지 않습니다(학습 데이터 라이선스) — 코드·학습 레시피 제공. 튜닝 NER 모델은 추후 공개 예정(라이선스·일반화 평가 후).

하이브리드 평가(룰단독 vs 하이브리드, base vs tuned 매트릭스): docs/HYBRID_NER.md — 룰 대비 +0.14~0.19(klue), 단 제대로 튜닝된 한국어 NER이라야 일관 효과(base zero-shot 은 역효과). 실험 전 과정(학습·평가 코드, 실행 로그, 원시 결과)은 (내부 NER 실험 아카이브 — 비공개) 아카이브 참조.

FAQ

Q1. ML 없이 룰만으로 정말 잘 되나요? 한국 핵심 구조적 PII는 형식·체크섬으로 결정론 검증할 수 있어 ML과 상보적이다. PERSON 같은 맥락 의존적 PII는 ML이 더 나을 수 있고, 생성 행정·서식형 평가셋 540문서의 전체 F1 0.790은 고객 운영 보장이 아니라 도메인 qualification의 참고값이다 (docs/BENCHMARK.md §3b).

Q2. 오탐이 많으면? person_exclusions={...} 또는 --person-exclusions-file로 프로젝트별 용어를 제외하거나, exclude={"PERSON"}으로 카테고리를 끄고 모드를 조정하세요. 패키지 내장 사전을 직접 수정할 필요가 없습니다.

Q3. Vault는 접근 권한도 검사하나요? 아닙니다. ReversibleVault는 저장·복원 primitive이며 객체나 파일에 접근한 호출자를 인증하지 않습니다. 애플리케이션 IAM/ACL과 키 관리로 접근을 통제하고, 운영 CLI에서는 암호화와 --audit-failure-policy raise를 사용하세요. 복원이 필요 없다면 redact를 사용하십시오. 상세: docs/VAULT_SECURITY.md.

Q4. HWP 표·머리말 다 잡히나요? 네. [file] extras 설치 시 본문 + 표 + 머리말 + 꼬리말 + 메타데이터 모두 추출.

Q5. 다른 도구 (Presidio / openai) 와 뭐가 다르나요?

• Presidio — 다국어·다국가 인식기를 조합하는 프레임워크이며 한국 주민번호·외국인번호·사업자번호·여권·운전면허번호도 지원합니다. 언어 엔진, 한국 인식기 활성화, 전화번호 지역 설정에 따라 결과가 달라집니다. ko-pii는 별도 모델 없이 한국어 문서 전처리를 제공하는 라이브러리이며, 한국 식별자 지원 자체가 독점적 차별점은 아닙니다.
• openai/privacy-filter — 다국어 일반 PII. 한국 핵심 14 카테고리 라벨 없음
• ko-pii — 한국 특화 33 카테고리, 체크섬 검증, 법적 근거 자동 부착

Q6. 이름 단독 검출이 오탐이 많아요. 이름+전화번호 같이 있을 때만 차단할 수 있나요? PERMISSIVE 모드 (CRITICAL만 차단) + combined_risk 조건부 재처리:

result = Anonymizer(mode=ProcessingMode.PERMISSIVE).process(text)
if result.combined_risk.combined_risk >= RiskLevel.HIGH:
    result = Anonymizer(mode=ProcessingMode.STRICT).process(text)

개발

git clone https://github.com/Marker-Inc-Korea/ko-pii
cd ko-pii
pip install -e ".[dev]"
pytest    # 전체 테스트 통과

상세 문서: docs/ 디렉토리 참조.

라이선스

MIT License

법령 참고

• 개인정보보호법 (제2조, 제23조, 제24조, 제24조의2, 제28조의2-5, 제29조)
• 개인정보보호위원회 「가명정보 처리 가이드라인」 · 「개인정보 비식별 조치 가이드라인」
• 상법 제40조 · 출입국관리법 제31조 · 국민건강보험법 제96조 · 금융실명법