허깅페이스, OpenAI Privacy Filter 활용 PII 보호 웹앱 3종 가이드 공개… 1.5B 모델·128K 컨텍스트·BIOES 디코딩에 gradio.Server 통합
허깅페이스 블로그가 OpenAI의 PII 마스킹 모델 'Privacy Filter'를 활용해 확장 가능한 웹 애플리케이션을 만드는 방법을 정리해 공개했다. 글은 동일한 백엔드 패턴을 공유하는 세 가지 데모 앱 — Document Privacy Explorer, Image Anonymizer, SmartRedact Paste — 의 구조를 비교하며, 모든 앱이 gradio.Server 위에서 커스텀 HTML/JS 프런트엔드와 Gradio의 큐잉·ZeroGPU 할당·gradio_client SDK를 결합하는 방식을 설명한다.
Privacy Filter는 1.5B 파라미터에 50M 활성 파라미터를 갖는 모델로, Apache 2.0 라이선스가 적용된다. PII 카테고리는 private_person, private_address, private_email, private_phone, private_url, private_date, account_number, secret 8종이며 컨텍스트는 128,000 토큰이다. PII-Masking-300k 벤치마크에서 최고 성능(SOTA)을 달성한다는 점이 모델의 핵심 사양으로 제시됐다.
첫 번째 앱인 Document Privacy Explorer(ysharma/OPF-Document-PII-Explorer)는 PDF나 DOCX를 그대로 업로드하면 모든 PII 스팬을 카테고리별로 강조 표시하고, 사이드바 필터와 상단 요약 대시보드를 제공한다. 파일 전체가 단일 128K 컨텍스트 포워드 패스로 처리돼 청크나 스티칭이 필요 없으며, 스팬 오프셋이 렌더링된 텍스트와 그대로 정렬된다. 긴 모호 구간에서도 스팬 경계는 BIOES 디코딩으로 깔끔하게 유지된다.
두 번째 앱 Image Anonymizer(ysharma/OPF-Image-Anonymizer)는 이미지·스크린샷에서 PII 위에 검은 바를 덧씌우는 도구다. 백엔드는 Tesseract로 OCR을 돌려 단어별 바운딩 박스를 받고, 문자 오프셋과 박스를 매핑한 뒤 Privacy Filter를 전체 텍스트에 한 번 실행한다. 검출된 문자 스팬은 단어 맵을 통해 라인 단위 픽셀 사각형으로 합쳐진다. 사용자는 캔버스에서 바를 토글·드래그하거나 직접 그릴 수 있고, 자연 해상도 PNG 내보내기는 클라이언트 사이드에서 처리돼 서버 왕복이 없다.
세 번째 앱 SmartRedact Paste(ysharma/OPF-SmartRedact-Paste)는 페이스트빈 형태로, 민감 텍스트를 붙여넣으면 두 개의 URL을 돌려준다. 공개 URL은 검출된 스팬이 <PRIVATE_PERSON>, <PRIVATE_EMAIL>, <ACCOUNT_NUMBER> 같은 카테고리 플레이스홀더로 치환된 버전을 노출하고, 비공개 reveal 토큰 URL은 원문과 강조 스팬을 보여준다. 모델 카드 예시 기준 스페인어·프랑스어·중국어·힌디어 등 다국어 텍스트도 동일한 호출로 처리된다.
공통 백엔드인 gradio.Server는 FastAPI 위에서 동작하며, 모델을 건드리는 핸들러는 @server.api(name=...) 데코레이터로 노출된다. 이 데코레이터는 핸들러를 Gradio 큐에 연결해 동시 업로드를 직렬화하고, ZeroGPU의 @spaces.GPU와 올바르게 합성되며, 동일한 엔드포인트가 브라우저와 gradio_client에서 코드 중복 없이 호출되도록 한다. 큐가 필요 없는 일반 라우트는 같은 프로세스 안에서 @server.get 같은 평범한 FastAPI 라우트로 둔다.
프런트엔드는 @gradio/client의 Client.connect와 client.predict('/analyze_document', { file: handle_file(file) }) 패턴으로 백엔드를 호출한다. Image Anonymizer는 client.predict('/anonymize_screenshot', { image: handle_file(file) })를, SmartRedact Paste는 client.predict('/create_paste', { text, ttl })를 호출하는 식으로 같은 패턴이 반복된다. 예시는 jsDelivr CDN을 통해 ESM 모듈로 클라이언트 라이브러리를 로드한다.
SmartRedact Paste는 만료된 페이스트를 30초마다 정리하는 데몬 스레드를 두며, 저장소를 포함한 전체 서비스 코드는 약 200줄에 그친다고 글은 밝혔다. 모든 앱이 모델 호출은 @server.api로, 그 외 라우트는 평범한 FastAPI로 분리하는 동일한 분할을 따른다는 점이 글의 핵심 메시지다.