---

Hi Quindle Testwick ([email protected] / +1-415-555-0102),
account 40702810500001234567, 14 Beautiful Ct, Anytown USA,
password Priv4cy-Filt3r-2026.

private_person      Quindle Testwick
private_email       [email protected]
private_phone       +1-415-555-0102
account_number      40702810500001234567
private_address     14 Beautiful Ct, Anytown USA
secret              Priv4cy-Filt3r-2026

<REDACTED> 대신 무엇이 발견되었는지, 어디에 있는지(start, end), 그리고 어떤 유형인지 알 수 있습니다.

왜 필요한가

Privacy Filter는 "이 텍스트를 안전하게 만들어라"라는 질문에 답합니다. 때로는 다른 답이 필요할 때가 있습니다: "여기에 정확히 무엇이 들어 있나?"

• 경계를 벗어나기 전에 로그, 덤프, 내보내기 파일을 감사
• GDPR / CCPA 요청을 위한 개인 데이터 인벤토리 작성
• 유출된 비밀과 연락처 데이터에 대한 pre-commit 및 CI 검사
• 데이터셋 구축: 학습 또는 평가를 위한 PII 스팬 라벨링

세 가지 백엔드

백엔드	가중치 필요	속도	F1 *	사용 시점
PIIParser	아니오	µs	1.000	의존성 없음, 구조화된 패턴
ModelPIIParser	1.5B	~500 ms CPU	0.733	원시 모델 출력
HybridPIIParser	1.5B	~600 ms CPU	0.929	기본 선택

* 다섯 개의 opf 샘플 픽스처에 대한 정확한 스팬 일치. 작은 집합이므로 벤치마크가 아닌 스모크 테스트로 취급하십시오.

설치

git clone https://github.com/openai/privacy-filter
git clone https://github.com/chiefautism/privacy-parser

uv venv
uv pip install -e ./privacy-filter    # only for the model backends
uv pip install -e ./privacy-parser

첫 번째 모델 실행 시 opf 체크포인트(~3 GB)를 ~/.opf/privacy_filter/에 다운로드합니다. 다른 위치를 사용하려면 OPF_CHECKPOINT를 설정하거나 model=을 전달하세요.

빠른 시작

하이브리드 (권장)

from pii_parser.hybrid import HybridPIIParser

parser = HybridPIIParser(device="cpu")   # or "cuda"
result = parser.parse("Hi Quindle Testwick, call me at +1-415-555-0102")

for s in result.spans:
    print(s.label, s.start, s.end, s.text)

print(result.to_json())

정규식만 사용, 가중치 없음

from pii_parser import parse

result = parse("mail [email protected], token ghp_abcdefghijklmnopqrstuvwxyz0123456789")

result.detected_spans   # (DetectedSpan(label='private_email', ...), ...)
result.redacted_text    # 'mail <REDACTED>, token <REDACTED>'
result.summary          # {'span_counts': {...}, 'total_spans': 2}

CLI

정규식 백엔드, 모델 없음:

$ echo "Alice paid 40702810500001234567 on 2026-05-17." | pii-parser --mode spans
account_number  11  31  40702810500001234567
private_date    35  45  2026-05-17

$ pii-parser "mail [email protected]" --mode redacted
mail <REDACTED>

플래그	값	기본값
TEXT	텍스트, 또는 -f FILE, 또는 stdin
--mode	json · spans · redacted	json
--placeholder	임의의 문자열	<REDACTED>
--indent	정수, 압축 JSON의 경우 0	2

모델 백엔드:

python -m pii_parser.cli_model "Alice paid 40702810500001234567 on 2026-05-17."
python -m pii_parser.cli_model -f dump.txt --device cuda --mode spans

레이블

opf v2 분류 체계, 8개 카테고리:

레이블	예시
private_person	Quindle Testwick
private_email	[email protected]
private_phone	+1-415-555-0102
private_address	14 Beautiful Ct, Anytown USA
private_url	https://example.com/u/quindle
private_date	2026-05-17
account_number	40702810500001234567
secret	sk-…, ghp_…, AKIA…, Bearer …

스팬이 겹칠 경우 더 긴 것이 우선하며, 그다음으로 우선순위가 높은 레이블이 우선합니다: email > url > secret > account > phone > date > address > person.

하이브리드 방식의 동작 원리

text
  │
  ▼
opf 1.5B ──► BIOES logits ──► Viterbi (tuned biases) ──► char spans
  │
  ▼
span merge        glues "Quindle" + "Testwick" into one person
  │
  ▼
regex backstop    adds url / secret / account where the model missed them
  │
  ▼
spans[]

각 단계는 비활성화할 수 있습니다:

HybridPIIParser(
    enable_merge=True,
    enable_regex_backstop=True,
    enable_viterbi_tuning=True,
    decode_mode="viterbi",   # or "argmax"
)

출력 스키마

{
  "text": "Hi Quindle Testwick ...",
  "spans": [
    { "label": "private_person", "start": 3, "end": 19, "text": "Quindle Testwick" }
  ]
}

정규식 PIIParser는 opf.RedactionResult(schema_version, summary, detected_spans, redacted_text)를 그대로 반영하므로, 소비자 쪽을 건드리지 않고 백엔드를 교체할 수 있습니다.

테스트

테스트는 이 저장소 옆에 privacy-filter가 클론되어 있을 것을 전제로 합니다(해당 저장소의 샘플 픽스처를 읽습니다).

python tests/test_hybrid.py

Fixture F1:  0.929
Scenarios:   8/8 passed
Latency:     ~600 ms CPU

책임 있는 사용

이것은 이중 용도 도구입니다. 소유하고 있거나 처리 권한이 있는 데이터에 대해서만 실행하십시오. 유출되거나 도난당한 출처에서 개인 데이터를 추출하는 것은 대부분의 관할 구역에서 불법입니다.

라이선스

Apache-2.0