Anonimal 文档

Anonimal 检测文本中的 PII，并根据所选的模式进行替换。检测器只找到片段；替换则单独决定。一切都在本地运行——原始数据绝不离开机器。

它检测哪些 PII

检测内容取决于当前激活的引擎。

结构化数据（两个引擎）

邮箱、电话号码、信用卡（通过 Luhn 校验验证）、URL、IPv4 地址和常见密钥。

拉美身份标识（两个引擎）

阿根廷 DNI、CUIT / CUIL（含校验位）和 CBU 银行账号。

自由格式 PII（仅 ML 引擎）

流畅行文中的人物姓名和地址，通过 NER 实现——这是 regex 无法识别的部分。

自定义规则

用户提供的规则：始终隐藏 / 从不隐藏的白名单，以及你自己的 {regex, placeholder} 模式。

引擎：regex（lite）与 ML

检测器暴露 detect(text) → [Span]；重叠部分按最长片段解决（平局时按标签优先级裁定）。

• lite——仅 regex。轻量、离线、无模型。覆盖上述结构化数据和拉美身份标识。它不识别自由格式的姓名或地址。始终存在，即使在 lite 镜像和 anonimal_lite 库中。
• ml——封装了 OpenAI Privacy Filter（OPF，Apache-2.0）。对自由格式 PII 准确。较重（~2.8 GB 检查点，~3 GB 内存），受 CPU 约束，在后台惰性加载，推理串行化。可选。

通过 ANONIMAL_ENGINE 选择：auto（若 ML 就绪则用 ML，否则用 lite）· lite · ml。请求可通过 engine 字段在每次调用时覆盖默认值。

替换模式

两种模式是不透明的（单向），一种是可逆的。每个文档使用单个匿名化器，因此相同的值总是获得相同的替换（一致性）。

模式	结果	可逆
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 绝不会到达它）。
3. 用 LLM 的答案和相同的 map 发送 POST /deanonymize → 原始值被重新还原回文本中。

警告

map 是逆转 pseudo 输出的唯一方法。请妥善保密——它包含原始 PII。其他四种模式返回空映射，无法逆转。

格式

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

调用 POST /anonymize 时不带 mode，会返回嵌入式 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 上接受两种相互独立的凭证：

• 服务令牌——设置 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（仅 regex，纯标准库），因此它仍可独立进行匿名化。

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 有两条流程：一条人工路径（Extracta/Fisherboy 通过 sessionStorage['escriba.handoff'] 移交给 Escriba，而 Escriba 的”匿名化”按钮调用 API）和一条自动路径（一个无人值守的 worker 直接调用 API）。无论哪种方式，Anonimal 始终是匿名化发生的唯一场所。

自定义规则

/detect、/anonymize（字段 rules）和 /anonymize_file（rules_json）接受一个规则对象：always（始终隐藏）、never（从不隐藏）和 patterns（{regex, placeholder}）。这些模式是 Escriba 规则的超集，并带有可选的 RE2 以防范 ReDoS。