English | 한국어

ko-pii

한국어 문서의 개인정보를 검출하고 가역적으로 가명화하는 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 (권한자만 복원)
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 (카테고리명 치환):
  신청인 [성명] ([주민등록번호]) 연락처 [전화번호]
  주소: [주소]

처음이시면: mode=ProcessingMode.STRICT + strategy="tokenize" 추천. 가장 안전한 기본 설정 (MEDIUM 위험도 이상 차단 + 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 아님)
• 결합 위험도 자동 평가 — 이름만으로는 PII 아닐 수 있지만, 이름 + 주민번호 + 주소 가 같이 나오면 → CRITICAL (「개인정보 비식별 조치 가이드라인」 의 준식별자 결합 검증)
• 감사 로그 — 누가·언제·어떤 토큰을 복원했는지 JSONL 추적 (개인정보보호법 제29조)

---

목차

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 를 차단합니다. 같은 인물은 같은 토큰으로 치환해 문맥을 보존하고(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 가 많다면 — 도메인 사전 주입
# src/ko_pii/dictionaries/common_words.py 에 의약품 성분명·제조사명 추가
# 예: "이부프로펜", "한미약품", "메트포르민" → PERSON 에서 자동 제외

---

설치

pip install ko-pii  # 현재 PyPI stable

# main의 1.16 API를 태그 배포 전에 검증하려면
python3 -m pip install \
  "ko-pii @ git+https://github.com/Marker-Inc-Korea/ko-pii.git@main"

extras 옵션 (필요 시):

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

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

---

사용 시나리오

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

from pathlib import Path
from ko_pii import Anonymizer, ProcessingMode

anon = Anonymizer(mode=ProcessingMode.PARANOID, strategy="tokenize")

for path in Path("./공문서/").glob("*.hwp"):
    result = anon.process(path.read_text(encoding="utf-8"))
    Path(f"./가명화/{path.name}").write_text(result.text, encoding="utf-8")
    # vault.json 분리 보관 (권한 있는 사용자만 복원 가능)
    result.vault.save(f"./vault/{path.stem}.json")

• PARANOID 모드 — LOW 위험도 이상 모두 차단 (LLM/외부 전송 안전)
• 가명화 결과는 외부에, Vault 는 사내 저장소에 분리 보관
• HWP/HWPX 파서: pip install "ko-pii[file]"

시나리오 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) 처리 완료")
# → "신청인 [성명] ([주민등록번호]) 처리 완료"

---

평가 결과

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

→ 0.19 ms/문서(~5,350 문서/s)로 Presidio(4.2ms)보다 22배 빠르고, 결정적이라 같은 입력에 항상 같은 결과 · 검출마다 근거 조항/evidence 부착. 속도·비용·정성 전체 비교: 종합 비교표(한글).

• KDPII는 단일 매처(match_forms_overlap, person_min_length=3)로 전체 4,891문서 재측정 — openai/privacy-filter (660M ML) · Microsoft Presidio 등 룰·NER 도구 대비 우위.
• 공정 비교: 위 전체 점수는 해외 도구가 라벨 자체가 없는 항목(AGE·POSITION·RRN 등)에서 0점이라 격차가 커진다. 각 도구가 실제 지원하는 카테고리만으로 좁혀도 ko-pii가 앞선다 — vs openai/PF 0.61 : 0.37(그쪽 7라벨), vs Presidio 0.87 : 0.65(그쪽 9라벨).
• 생성 평가셋의 구조적 라벨은 EMAIL 0.998, PHONE 0.989, CARD 0.988, RRN 0.955로 측정됐다. 이 값은 해당 gold·matcher 조건이며 보편적 보장이 아니다.
• **생성 평가셋(540)**은 ko-pii 룰을 참조하지 않고 생성한 독립 데이터(행정/서식체, 26라벨)이며 gold를 2단계 검토(data/generated_eval.jsonl)했다. 자기 주입 데이터는 아니지만 생성 데이터의 분포 편향과 평가 불확실성은 남으므로 고객 문서 성능을 대체하지 않는다 (상세 BENCHMARK §3b).
• 상세·재현: docs/BENCHMARK.md · docs/EVALUATION_REPORT.md. (KLUE 는 이전 방법론 수치)

운영 전 권장: 사용하시는 도메인의 실제 문서 30~100건을 직접 테스트해보세요. 도메인마다 성능 차이가 있습니다.

알려진 한계

• PERSON 오탐 (FP) + 도메인 의존성 — 룰 기반 PERSON 검출의 가장 큰 약점. 성씨 글자로 시작하는 일반명사·생약명·외래어가 사람 이름으로 잡힐 수 있음. 외부 신문 NER(KLUE-NER PS, 5K 문장)에서는 F1 0.419로, 신문체 인명(역사·외국인·공인)과 일반명사 과탐이 크다. 일반 도메인 NER 용도라면 common_words.py 도메인 사전 주입, exclude={"PERSON"}, 또는 하이브리드 분류기(dev/classifier)를 권한다. (재현: 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)의 몫
• 결정적 PII (RRN·PHONE·EMAIL·카드·사업자) 는 체크섬/형식 검증이라 오탐 거의 없음

상세 평가: 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

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>'}

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=text)

# 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

개별 검출기 호출

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 거부)

---

처리 모드 + 치환 전략

---

부가 기능

파서 상세

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로 명시적으로 활성화해야 합니다.

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. 오탐이 많으면? common_words.py 에 도메인 사전 주입, exclude={"PERSON"} 으로 특정 카테고리 끄기, 모드 변경 (STRICT → BALANCED).

Q3. Vault 분실하면? 복원 불가 (보안 설계). [security] extras 로 암호화 보관 또는 strategy="redact" (카테고리명 치환, Vault 불필요) 사용.

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

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

• Presidio — 영어 위주. 한국 특화 PII (RRN/FRN/여권 등) 부재
• 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조 · 금융실명법