カスタム認識器ガイド

業務固有のPIIを検出するためのカスタム認識器の作成方法を説明します。

概要

PII-Fi APIは 4層アプローチ でPIIを検出します。

💡 4層アプローチ

AIベース認識器 - 組み込み認識器が人名・組織名等を文脈から高精度検出
ルールベース認識器 - 電話番号・メールアドレス等の定型パターンを高速検出
辞書マッチング - ユーザー登録の固有名詞リストから検出
文脈解析パイプライン - 周辺文脈から機密カテゴリを自動分類

標準で多くのPIIタイプ（人名、電話番号、メールアドレスなど）が組み込まれていますが、業務固有の情報を検出したい場合は 3種類のカスタム認識器 を追加できます。

認識器	方式	得意な用途	ガイド
パターンマッチ認識器	正規表現	フォーマットが決まったID・番号	本ガイドで詳説
辞書認識器	辞書照合	固有名詞・禁止ワードのリスト	辞書マッチングガイド
文脈解析パイプライン	高度なNLP解析	周辺文脈に依存する分類	API仕様書

3種類の使い分け

社員番号 EMP-123456 を検出したい
  → フォーマットが明確 → パターンマッチ認識器

社名「トヨタ自動車」やプロジェクト名「ProjectX」を検出したい
  → 固有名詞のリスト → 辞書認識器（タイプミスもファジーマッチで対応可）

「年収500万円」を個人収入として、「売上高500万円」を企業収益として区別したい
  → 周辺文脈に依存 → 文脈解析パイプライン

本ガイドでは パターンマッチ認識器 について詳しく説明します。

パターンマッチ認識器とは

正規表現パターンを登録して、フォーマットが明確に決まっている業務固有のIDや番号を検出する認識器です。

1. 認識器を追加 → 2. 自動リロード → 3. /detect で検出 → 4. 不要なら削除

API Endpoint

POST /api/policy/recognizers

⚠ 楽観的ロック（ETag/If-Match）が必要です

ポリシー変更APIには楽観的ロックが必要です。まずアクティブポリシーのETagを取得し、If-Matchヘッダーに設定してリクエストしてください。

# 1. ETagを取得
ETAG=$(curl -s -I https://api.pii-fi.com/api/policy/active \
  -H "Authorization: Bearer YOUR_API_KEY" | grep -i etag | awk '{print $2}' | tr -d '\r')

# 2. If-Matchヘッダー付きでリクエスト
curl -X POST ... -H "If-Match: $ETAG" ...

Request Parameters

Parameter	Required	Description
`id`	Required	認識器の一意ID（`custom.` プレフィックス推奨）
`name`	Required	表示名
`entity_type`	Required	検出結果のエンティティタイプ（`JPII_` プレフィックス推奨）
`patterns`	Required	パターン定義のリスト
`category`	Optional	カテゴリ（default: `custom`）
`description`	Optional	説明
`priority`	Optional	優先度（default: `75`）
`context`	Optional	コンテキストキーワード（スコア向上に使用）
`supported_languages`	Optional	対応言語（default: `["ja", "en"]`）

Pattern Definition

{
  "name": "pattern_name",
  "regex": "正規表現",
  "score": 0.9
}

Field	Description
`name`	パターン名
`regex`	Python正規表現
`score`	検出信頼度（0.0〜1.0）

Priority Settings

優先度は、同じ位置で複数のエンティティが検出された場合にどちらを優先するかを決定します。

Level	Range	Description
低	50-70	他の検出器に負けやすい
中（デフォルト）	75	カスタム認識器のデフォルト
高	80-100	多くの既存検出器より優先
最高	100-120	重要なエンティティ用

💡 Reference: Built-in Recognizer Priorities

人名（パターン）: 85
人名（AI）: 98
電話番号: 110
メールアドレス: 120

Custom Recognizer Examples

1. 社員番号（JPII_EMPLOYEE_ID）

形式: EMP-XXXXXX（EMP- + 6桁の数字）

# 1. ETagを取得
ETAG=$(curl -s -I https://api.pii-fi.com/api/policy/active \
  -H "Authorization: Bearer YOUR_API_KEY" | grep -i etag | awk '{print $2}' | tr -d '\r')

# 2. If-Matchヘッダー付きでカスタム認識器を追加
curl -X POST https://api.pii-fi.com/api/policy/recognizers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-Match: $ETAG" \
  -d '{
    "id": "custom.employee_id",
    "name": "社員番号認識器",
    "entity_type": "JPII_EMPLOYEE_ID",
    "category": "custom",
    "description": "社員番号（EMP-XXXXXX形式）を検出",
    "priority": 100,
    "patterns": [
      {
        "name": "employee_id_pattern",
        "regex": "EMP-\\d{6}",
        "score": 0.9
      }
    ],
    "context": ["社員番号", "社員ID", "employee"]
  }'

import requests

API_KEY = "YOUR_API_KEY"
# デモ環境（本番環境では専用エンドポイントを提供）
BASE_URL = "https://api.pii-fi.com/api"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

# アクティブポリシーのETagを取得
response = requests.get(f"{BASE_URL}/policy/active", headers=headers)
etag = response.headers.get("ETag")

# カスタム認識器を追加（If-Matchヘッダー必須）
requests.post(
    f"{BASE_URL}/policy/recognizers",
    headers={**headers, "If-Match": etag},
    json={
        "id": "custom.employee_id",
        "name": "社員番号認識器",
        "entity_type": "JPII_EMPLOYEE_ID",
        "priority": 100,
        "patterns": [
            {"name": "emp", "regex": "EMP-\\d{6}", "score": 0.9}
        ]
    }
)

# 検出テスト
result = requests.post(
    f"{BASE_URL}/detect",
    headers=headers,
    json={
        "text": "社員番号 EMP-123456 の田中太郎です"
    }
).json()

print(result["deidentified_text"])
# 出力: 社員番号 <JPII_EMPLOYEE_ID> の<人名>です

2. 顧客ID（JPII_CUSTOMER_ID）

形式: CUS-XXXXX-XX（CUS- + 5桁 + ハイフン + 2桁）

# ETag取得後に実行
curl -X POST https://api.pii-fi.com/api/policy/recognizers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-Match: $ETAG" \
  -d '{
    "id": "custom.customer_id",
    "name": "顧客ID認識器",
    "entity_type": "JPII_CUSTOMER_ID",
    "priority": 100,
    "patterns": [
      {"name": "cus", "regex": "CUS-\\d{5}-\\d{2}", "score": 0.95}
    ],
    "context": ["顧客ID", "顧客番号", "customer"]
  }'

3. 注文番号（JPII_ORDER_NUMBER）

形式: ORD-YYYY-NNNNN（ORD- + 4桁年 + ハイフン + 5桁）

# ETag取得後に実行
curl -X POST https://api.pii-fi.com/api/policy/recognizers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-Match: $ETAG" \
  -d '{
    "id": "custom.order_number",
    "name": "注文番号認識器",
    "entity_type": "JPII_ORDER_NUMBER",
    "priority": 100,
    "patterns": [
      {"name": "order", "regex": "ORD-\\d{4}-\\d{5}", "score": 0.95}
    ],
    "context": ["注文番号", "注文ID", "order"]
  }'

4. 患者ID（JPII_PATIENT_ID）

形式: PT-NNNNNN（PT- + 6桁の数字）

# ETag取得後に実行
curl -X POST https://api.pii-fi.com/api/policy/recognizers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-Match: $ETAG" \
  -d '{
    "id": "custom.patient_id",
    "name": "患者ID認識器",
    "entity_type": "JPII_PATIENT_ID",
    "priority": 100,
    "patterns": [
      {"name": "patient", "regex": "PT-\\d{6}", "score": 0.95}
    ],
    "context": ["患者ID", "患者番号", "カルテ番号"]
  }'

5. 複数パターン対応認識器

1つの認識器で複数のパターンに対応することもできます。

# ETag取得後に実行
curl -X POST https://api.pii-fi.com/api/policy/recognizers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-Match: $ETAG" \
  -d '{
    "id": "custom.internal_id",
    "name": "社内ID認識器",
    "entity_type": "JPII_INTERNAL_ID",
    "priority": 100,
    "patterns": [
      {"name": "emp", "regex": "EMP-\\d{6}", "score": 0.9},
      {"name": "dept", "regex": "DEPT-\\d{4}", "score": 0.9},
      {"name": "proj", "regex": "PROJ-\\d{8}", "score": 0.9}
    ]
  }'

Industry Examples

Industry	Detection Target	Pattern Example
小売・EC	注文番号、会員番号、ポイントカード番号	`ORD-XXXX`, `M-XXXXXXXX`
金融	口座番号、契約番号、顧客ID	`ACC-XXXX`, `CNT-XXXX`
医療	患者ID、カルテ番号、保険証番号	`PT-XXXXXX`
製造	製品コード、シリアル番号、ロット番号	`PRD-XXX-XXXX`, `SN-XXXX`
物流	追跡番号、配送番号	`TRK-XXXXXXXXXXXX`
教育	学籍番号、教職員番号	`2024A0001`
不動産	物件番号、契約番号	`PROP-XXXX`
人材	応募者ID、社員番号	`APP-XXXX`, `EMP-XXXXXX`

💡 パターンマッチでは対応しにくい場合

固有名詞のリスト管理やタイプミス対応が必要 → 辞書認識器
周辺文脈に応じた機密カテゴリ分類が必要 → 文脈解析パイプライン

Recognizer Management

List Recognizers

curl https://api.pii-fi.com/api/policy/recognizers \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete Recognizer

# ETagを取得してから削除
ETAG=$(curl -s -I https://api.pii-fi.com/api/policy/active \
  -H "Authorization: Bearer YOUR_API_KEY" | grep -i etag | awk '{print $2}' | tr -d '\r')

curl -X DELETE https://api.pii-fi.com/api/policy/recognizers/custom.employee_id \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "If-Match: $ETAG"

Using with enabled_entities

カスタムエンティティも enabled_entities でフィルタリングできます。

# カスタムエンティティのみ検出
curl -X POST https://api.pii-fi.com/api/detect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "text": "社員番号 EMP-123456 の田中太郎（090-1234-5678）",
    "enabled_entities": ["JPII_EMPLOYEE_ID"]
  }'

# 社員番号のみ検出、人名と電話番号は無視

Regex Tips

Common Patterns

Pattern	Description	Example
`\\d{6}`	6桁の数字	123456
`[A-Z]{3}`	大文字アルファベット3文字	ABC
`[A-Za-z0-9]+`	英数字（1文字以上）	abc123
`\\w+`	単語文字（英数字とアンダースコア）	hello_123

JSON Escaping

JSONでは \ を \\ でエスケープする必要があります。

Regex	JSON Notation
`\d`	`\\d`
`\w`	`\\w`
`\s`	`\\s`
`\.`	`\\.`

Best Practices

ID命名規則: custom. プレフィックスを使用（例: custom.employee_id）
エンティティタイプ命名: JPII_ プレフィックスを使用（例: JPII_EMPLOYEE_ID）
適切な優先度: 重要なパターンには高い優先度（80-100）を設定
コンテキスト活用: 関連するキーワードを context に設定してスコア向上
テスト: 追加後に実際のテキストで検出をテスト

Next Steps

📚 Dictionary Matching 📖 API Reference 💻 Sample Code 🤖 LLM Workflow