Anonimal ドキュメント

Anonimal はテキスト内の PII を検出し、選択したモードに従って置換します。検出器 は範囲を見つけるだけで、置換は別途決定されます。すべてがローカルで動作し、元の データがマシンの外に出ることはありません。

検出する PII

検出はアクティブなエンジンに依存します。

構造化データ（両エンジン）

メール、電話番号、クレジットカード（Luhn チェックで検証）、URL、IPv4 アドレス、 一般的なシークレット。

LATAM 識別子（両エンジン）

アルゼンチンの DNI、CUIT / CUIL（チェックディジット付き）、CBU 銀行 番号。

自由形式 PII（ML エンジンのみ）

文章中の人物の氏名と住所を NER 経由で — 正規表現には見えない部分です。

カスタムルール

ユーザー指定のルール：常に隠す / 決して隠さないホワイトリストと、独自の {regex, placeholder} パターン。

エンジン：正規表現（lite）vs ML

検出器は detect(text) → [Span] を公開します。重複は最長の範囲で解決されます （同点はラベル優先度で決まります）。

• lite — 正規表現のみ。軽量、オフライン、モデルなし。上記の構造化データと LATAM 識別子をカバーします。自由形式の氏名や住所は見えません。lite イメージ や anonimal_lite ライブラリでも、常に存在します。
• ml — OpenAI Privacy Filter（OPF、Apache-2.0）をラップします。自由形式の PII に対して高精度です。重い（チェックポイント ~2.8 GB、RAM ~3 GB）、CPU バウンド、 バックグラウンドで遅延読み込みされ、推論はシリアライズされます。オプションです。

ANONIMAL_ENGINE で選択します：auto（準備ができていれば ML、そうでなければ lite） · lite · ml。リクエストは engine フィールドで呼び出しごとに デフォルトを上書きできます。

置換モード

2 つのモードは不透明（一方向）で、1 つは可逆です。ドキュメントごとに単一の 匿名化器が使われるため、同じ値には常に同じ置換が適用されます（一貫性）。

モード	結果	可逆
typed	[EMAIL]（カテゴリ別プレースホルダー）	いいえ
anon	«REDACTADO»（単一の不透明トークン）	いいえ
pseudo	EMAIL_1（安定した番号付き仮名）	はい（マップを返す）
mask	j***@***.com / ****-****-****-1234（型認識）	いいえ
hash	EMAIL_a1b2c3d4e5（決定論的 HMAC）	いいえ

不透明なマーカー

typed、anon、mask、hash は不可逆な出力を生成します。テキストを安全に共有 または保存するだけでよい場合に使用してください。hash モードは決定論的です。 ANON_HASH_KEY を設定すると、再起動をまたいで同じ値が同一にハッシュされます （マップを保存せずに安定したリンク付けが可能）。

可逆モード（再構成）

pseudo が可逆モードです。各値を安定したトークン（EMAIL_1、PERSON_2 など）で 置換し、さらに token → original のマップを返します。ワークフロー：

1. mode: "pseudo" で POST /anonymize → 匿名化された output と map を取得。
2. output を LLM に送信する（元の PII は決して LLM に届かない）。
3. LLM の回答と同じ map で POST /deanonymize → 元の値がテキストに再構成される。

注意

map は pseudo 出力を反転する唯一の手段です。元の PII を含むため、非公開に保って ください。他の 4 つのモードは空のマップを返し、反転できません。

フォーマット

Anonimal はすでにテキストであるファイルのフォーマットを保持します：txt、md、 log、srt、html、CSV（セルを匿名化、列はそのまま）、JSON（文字列値を 匿名化、キーには決して触れない；出力は有効な JSON のまま）。ファイルごとに単一の 匿名化器を使うことで、ドキュメント全体で一貫したマップになります。

Word / Excel / 画像 / 音声 / URL の変換は Anonimal の仕事ではありません — それは Escriba、Extracta、Fisherboy に属し、これらが変換済みのテキストを供給します。ただし Anonimal は本物の PDF 黒塗り（/redact_pdf）を提供します：検出された範囲の本物の 黒塗りに加え、メタデータの除去も行います。

REST API

/health を除くすべてのエンドポイントは require_auth で保護されています （認証を参照）。ベース URL はお客様のデプロイ先、たとえば http://localhost:8920 です。

メソッド	パス	何をするか
GET	/health	ステータス + ML エンジンの可用性。常に開放。
POST	/detect	{text} → 検出された範囲。
POST	/anonymize	{text, mode, engine?} → {output, map, summary}。
POST	/deanonymize	{text, map} → 元のテキスト。
POST	/anonymize_file	ファイルアップロード + mode → 匿名化されたコンテンツ（同じフォーマット）。
POST	/redact_pdf	PDF → 黒塗りされた PDF（黒塗り + メタデータ消去）。

POST /anonymize

リクエスト：

{
  "text": "email juan@acme.com, CUIT 20-12345678-6",
  "mode": "pseudo",
  "engine": "auto",
  "rules": null
}

レスポンス：

{
  "engine": "lite",
  "mode": "pseudo",
  "output": "email EMAIL_1, CUIT ID_1",
  "spans": [
    { "label": "EMAIL", "start": 6, "end": 19, "text": "juan@acme.com" }
  ],
  "map": { "EMAIL_1": "juan@acme.com", "ID_1": "20-12345678-6" },
  "reversible": true,
  "summary": { "EMAIL": 1, "ID": 1 }
}

map は pseudo の場合のみ設定されます。reversible がそれを反映します。

POST /deanonymize

{ "text": "reply to EMAIL_1", "map": { "EMAIL_1": "juan@acme.com" } }

→ { "output": "reply to juan@acme.com" }。map が欠落または空の場合は 422 を 返します。

レガシー（ドロップイン）/anonymize

mode なしで POST /anonymize を呼び出すと、組み込み Anonimal が使用するレガシー 契約 — {text, detected_spans, redacted_text, summary} と範囲ごとの placeholder が返されます。これにより、Escriba と Fisherboy は一行もコードを変更せずに ANONIMAL_URL を新サービスに向けられます。

GET /health

status、デフォルトのエンジンとモード、そして available、ready、error を含む ml ブロックを返します。コンテナのヘルスチェックで使われます。

エラー

401（トークンまたはセッションが欠落 / 無効）、413（テキストまたは PDF がサイズ 上限を超過）、422（無効なモード / マップ欠落 / 無効な rules_json）、503（ML エンジンまたは PDF サポートが利用不可）。

認証

Anonimal は API 上で 2 つの独立した認証情報を受け付けます：

• サービストークン — ANONIMAL_TOKEN を設定します。設定後はすべてのリクエストが これを Authorization: Bearer <token> または X-Anonimal-Token ヘッダーとして 含む必要があります。これが Escriba と Fisherboy が内部ネットワーク経由で認証する 方法です。
• ブラウザセッション — ANONIMAL_AUTH_ENABLED=true のとき、/login ページからの 署名付き Cookie も API ゲートを満たします（Web UI 用）。

どちらも設定されていない場合、API は開放されています（localhost を想定）。 /health はヘルスチェックのために常に到達可能です。

エコシステム統合

Anonimal は Escriba Suite における匿名化の唯一の担い手であり、サテライトはこれに 委任します。

• サービスモード — ANONIMAL_URL が設定された製品は HTTP 経由で Anonimal を 呼び出し（フル ML カバレッジ）、X-Anonimal-Token で認証します。
• ライブラリフォールバック — ANONIMAL_URL がない場合、製品は同梱の anonimal_lite（正規表現のみ、純粋な標準ライブラリ）にフォールバックするため、 スタンドアロンでも匿名化できます。

pip install "anonimal-lite @ git+https://github.com/diegoparras/anonimal.git@v0.4.0"

from anonimal_lite import LiteEngine, Anonymizer, deanonymize

eng = LiteEngine()
out = Anonymizer("pseudo").process(text, eng.detect(text))

Anonimal への流入経路は 2 つあります：人間の経路（Extracta/Fisherboy が sessionStorage['escriba.handoff'] 経由で Escriba に引き渡し、Escriba の「匿名化」 ボタンが API を呼び出す）と、自動の経路（無人ワーカーが API を直接呼び出す）。 いずれにせよ、Anonimal は匿名化が行われる唯一の場所であり続けます。

カスタムルール

/detect、/anonymize（フィールド rules）、/anonymize_file（rules_json）は ルールオブジェクトを受け付けます：always（常に隠す）、never（決して隠さない）、 patterns（{regex, placeholder}）。パターンは Escriba のルールのスーパーセットで、 ReDoS を防ぐためのオプションの RE2 付きです。