privyscope-ja

日本語テキストから個人情報（PII）を検出・マスキングするエンジンです。 privyscope シリーズの日本語版で、氏名・電話番号・ 各種ID・メールアドレス・住所・金融情報・非公開の日付・認証情報（シークレット）を 自動で見つけてマスキングします。

⚠️ privyscope はマスキングを補助するツールであり、匿名化やコンプライアンスを 保証するものではありません。詳しくは制限事項をご覧ください。

📖 English README

インストール

pip install privyscope-ja      # `privyscope` 本体も自動で入ります

1分で始める

Python から使う

from privyscope_ja import Privyscope

engine = Privyscope.from_pretrained()                 # 初回実行時に ONNX 重みをダウンロード
result = engine.redact("田中さんの電話は090-1234-5678、メールは taro@example.co.jp")

result.masked_text        # "<PER>さんの電話は<PHONE>、メールは <EMAIL>"
result.detected_spans     # [DetectedSpan(label="PER", start=0, end=2, ...), ...]
result.summary            # {"span_count": 3, "by_label": {"PER": 1, "PHONE": 1, "EMAIL": 1}, ...}

ターミナルから使う

privyscope redact "田中さんの電話は090-1234-5678、メールは taro@example.co.jp"
cat notes.txt | privyscope redact --operating-point high_recall

ドキュメント

詳しいガイドは docs/ に目的別でまとめてあります。

検出できる項目

基本項目（正規表現 + NER）は8種類です： PER · PHONE · ID_NUM · EMAIL · LOC · BANK · DATE · SECRET。

正規表現のみで検出する拡張項目もあります： MYNUMBER · PASSPORT · DRIVER_LICENSE · CRYPTO · IP · DEVICE · URL — privyscope_ja/entity_config.yaml を参照。

Stage-1 の正規表現ルールは pii-pattern-engine のルールセットから 取り込んでいます。多くのルールには検証関数（チェックサム・辞書チェック）が 付いており、形が似ているだけの値はマスキングしません。

日本語は漢字・ひらがな・カタカナの3種類の文字が混在し、単語間に空白がないため、 氏名の検出は正規表現ではなく NER 段に任せています。形態素解析には fugashi + unidic-lite（MeCab）を使用します。

privyscope_ja/regex_rules.yaml は scripts/gen_regex_rules.py が自動生成する ファイルで、ビルドのたびに上書きされます。ルールを変えるときは YAML ではなく そのスクリプトを編集してください。詳しくは CONTRIBUTING を参照。

仕組み

2段ハイブリッドパイプラインで PII を検出し、両者の結果を和集合で統合します （SRS §3.4）：

1. 正規表現フィルタ — 電話番号・メール・各種ID・カード番号・シークレットなど、 形が決まっている PII を捕捉します。
2. ONNX NER — 氏名・住所・非公開の日付など、前後の文脈から判断する PII を 捕捉します。BIOES トークン分類器に制約付き Viterbi デコーダを組み合わせています。

推論時は ONNX Runtime のみで動作し、PyTorch は不要です。既定では取りこぼしを 避ける（再現率重視）方針で、再学習なしに オペレーティングポイントだけで挙動を調整できます。 PyTorch が要るのはファインチューニングのときだけです。

モデルと性能

• 構成 — tohoku-nlp/bert-base-japanese-v3（Apache-2.0）エンコーダ → BIOES トークン分類ヘッド → 制約付き Viterbi デコーダ。

• 配布物 — INT8 量子化した ONNX モデルで、サイズは約 107 MB（≤150 MB の 予算内）、最大系列長 256。重みは初回利用時に Hugging Face Hub からダウンロードされ、 整合性確認用の SHA-256 checksum.txt が付属します。

• 精度 — 学習と重複しない検証セット（1,000文、typed/strict 採点、 regex + NER 全体パイプライン）でのエンティティ単位の strict F1：

  PER	LOC	DATE	ID_NUM	BANK	PHONE	SECRET
  0.99	1.00	1.00	0.56	0.71	0.90	0.84

  micro-F1 は 0.921。氏名・住所・日付といった文脈依存の項目はほぼ完璧です。 一方 ID_NUM（マイナンバー等）と BANK は数字項目で、口語・空白なし・タイポを 含む厳しめのストレステストを strict（オフセット完全一致）で採点するため低めに 出ます —— これは保守的な下限値で、実際のきれいなテキストではより高くなります。 EMAIL は正規表現で確定的に検出され、このサンプルには含まれていませんでした。 学習と分離した検証セットなので、この数値は暗記ではなく汎化性能を表します。 privyscope eval --lang ja your_val.jsonl で再現できます。

実例：ネットショップの問い合わせ

顧客がショッピングモールに送った実際の問い合わせ（約300文字、氏名・日付・メール・ 電話番号・住所・カード番号を含む）を engine.redact() に通した結果です。

入力

お世話になっております。田中太郎と申します。2024年3月14日に注文したランニングシューズがまだ届いておらず、ご連絡いたしました。会員登録の際に使用したメールアドレスは taro.tanaka92@gmail.com で、日中に連絡が取れる携帯電話番号は 090-2345-6789 です。お届け先の住所は東京都渋谷区神南1-2-3 で、お支払いはクレジットカード 4539-1488-0343-6467 で完了しております。もし商品が紛失している場合は、お支払いした金額をカードへ返金していただけますでしょうか。現在の配送状況をご確認のうえ、早めのご返信をお願いいたします。どうぞよろしくお願いいたします。

マスキング結果（result.masked_text）

お世話になっております。<PER>と申します。<DATE>に注文したランニングシューズがまだ届いておらず、ご連絡いたしました。会員登録の際に使用したメールアドレスは <EMAIL> で、日中に連絡が取れる携帯電話番号は <PHONE> です。お届け先の住所は<LOC> で、お支払いはクレジットカード <BANK> で完了しております。もし商品が紛失している場合は、お支払いした金額をカードへ返金していただけますでしょうか。現在の配送状況をご確認のうえ、早めのご返信をお願いいたします。どうぞよろしくお願いいたします。

検出された6件

制限事項

• 匿名化やコンプライアンスを保証するものではありません。プライバシー設計の 多層防御のひとつとして使ってください。
• 苦手なケースもあります。珍しい氏名や地域色の強い名前は取りこぼすことがあり、 文脈が曖昧だと公人まで過剰にマスキングすることがあります。形式が複雑に混在した テキストではスパンが分割されたり、初見の形式の SECRET を見逃したりします。
• 医療・法務・金融・行政など機微な業務では、人によるダブルチェックを推奨します。

ライセンス

Apache-2.0 で配布しています。モデルの重みも同じ Apache-2.0 で、整合性を確認できる checksum.txt（SHA-256）とともに Hugging Face Hub に公開されています。コントリ ビューションは歓迎です — CONTRIBUTING.md を参照してください。