korean-pii

Korean PII detection and redaction(masking) for text and images in an air-gapped environment (Dockerized, CPU-only)

---

1. Policy

고유식별정보를 정규식+검증으로 발견하면 즉시 차단/마스킹하고, 그 외 일반개인정보는 지정된 조합이 n자 이내 함께 있을 때 차단/마스킹합니다.

Field	Categoary	Method	Policy
주민등록번호	고유식별정보	Regex + Checksum	단일탐지 즉시 차단
외국인등록번호	고유식별정보	Regex + Checksum	단일탐지 즉시 차단
운전면허번호	고유식별정보	Regex + Checksum	단일탐지 즉시 차단
여권번호	고유식별정보	Regex	단일탐지 즉시 차단
이름	일반개인정보	NER(KoELECTRA)	조합탐지 차단 (전화/이메일/계좌/카드/사업자번호)
전화번호	일반개인정보	Regex	조합탐지 차단 (이름/이메일/계좌/카드)
이메일	일반개인정보	Presidio	조합탐지 차단(이름/전화/계좌/카드)
계좌번호	일반개인정보	Regex	조합탐지 차단(이름/전화/이메일/카드/사업자번호)
카드번호	일반개인정보	Presidio	조합탐지 차단(이름/전화/이메일/계좌)
사업자등록번호	일반개인정보	Regex + Checksum	조합탐지 차단(이름/계좌)

---

2. Quick Start

2.1 Setup (uv)

Use uv for dependency management.

curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
uv sync  # Sync dependencies

2.2 Run Locally

Start the FastAPI application

uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2.3 Run with Docker

Build and run using the deployment compose file.

docker compose -f environments/deploy/docker-compose.yml up --build

2.4 Swagger API

Swagger UI assets are bundled in app/static (load in air‑gapped environment)

http://<host>:8000/pii/swagger

---

3. API

3.1 API Swagger

서버 실행 시 http://<host>:8000/pii/swagger에서 자세히 확인할 수 있습니다.

TAG	API	Detail
GET	/pii/swagger	Swagger UI
GET	/pii/openapi.json	OpenAPI
GET	/pii/ping	서버 상태 확인
POST	/pii/text	텍스트 개인정보 탐지 및 마스킹
POST	/pii/image	이미지 개인정보 탐지

3.2.1 API Request - /pii/text

text 필수 문자열 필드에 검사할 전체 문장을 넣어 JSON으로 POST합니다.

{
  "text": "홍길동의 주민등록번호는 900101-1234567입니다."
}

3.2.2 API Request - /pii/image

multipart/form-data로 파일을 전달합니다. 다중 파일도 files 키를 반복해서 전송하면 됩니다.

curl -X POST "http://<host>:8000/pii/image" \
  -F "files=@/path/to/id-card.png"

3.3 API Response - /pii/text, /pii/image

/pii/image는 masked_text를 반환하지 않습니다.

{
  "blocked": true,
  "masked_text": "홍길동의 주민등록번호는 [주민등록번호]입니다.",
  "label_list": ["주민등록번호"],
  "reason": "고유식별정보"
}

---

4. Settings for air-gapped environment

4.1 Docker Base Image

Point the python base image to internal registry (Dockerfile)

ARG UV_IMAGE=<registry-endpoint>/astral-sh/uv:python3.12-bookworm-slim
FROM ${UV_IMAGE} AS runtime

4.2 Package Mirror

Swap package index to match environment (pyproject.toml)

[[tool.uv.index]]
name = "pytorch-cpu"
url = "http://<internal-mirror>/pypi" # Nexus Proxy Mirror
verify_ssl = false
explicit = true

4.3 Package Proxy

Replace the source/sdist/wheels URLs with the proxy URLs (uv.lock)

[[package]]
name = "package-name"
version = "package-version"
source = { registry = "https://<registry-url>/simple" }
sdist = { url = "https://<registry-url>/packages/.../annotated_types-0.7.0.tar.gz", ... }
wheels = [
    { url = "https://<registry-url>/packages/.../annotated_types-0.7.0-py3-none-any.whl", ..." },
]

---

5. Models

Reference links

Name	Link
NER	KoELECTRA-small-v3-modu-ner
OCR (det)	PP-OCRv5_mobile_det
OCR (rec)	korean_PP-OCRv5_mobile_rec

---

License

This repository (including the ONNX artifact) is provided under the Apache License 2.0 (Apache-2.0). See LICENSE and NOTICE for details.

Upstream references: The ONNX model is derived from Leo97/KoELECTRA-small-v3-modu-ner and its base model monologg/koelectra-small-v3-discriminator, with conversion for CPU inference optimization only.

본 저장소의 소스 및 배포 산출물(ONNX 포함)은 Apache License 2.0(Apache-2.0) 를 따릅니다. 자세한 내용은 LICENSE 및 NOTICE를 참고하세요.

참조 모델: 본 ONNX 모델은 Leo97/KoELECTRA-small-v3-modu-ner(upstream) 및 해당 모델의 베이스인 monologg/koelectra-small-v3-discriminator를 참조하며, CPU 추론 최적화를 위한 ONNX 변환만 수행했습니다.