Guide · 使用教程
Presidio Python 教程:敏感信息识别、误报漏报与脱敏结果验证
用固定版本与合成样本运行自定义识别和替换,验证字符位置、误报漏报及已知残留,说明零命中和测试通过的边界。
把敏感字段替换成占位符之后,还要确认识别位置正确、业务信息没有误删,并且已知漏报能被测试发现。本教程用 Presidio 的真实 Python 包跑一条小型本地管线,重点验证这些工程条件。
示例只使用合成邮箱和虚构业务账号。直接调用两个自定义 PatternRecognizer,不加载预训练 NER 模型,不调用云 API 或付费模型。它不覆盖姓名、住址、真实电话号码、完整邮箱语法或全部中文敏感信息,不能作为可直接上线的完整检测器。
1. 固定环境和验证范围
本次核对日期为 2026-10-18,使用 Python 3.11,presidio-analyzer==2.2.364 与 presidio-anonymizer==2.2.364。官方安装页列出的 Python 支持范围为 3.10–3.13;安装当前版本时仍应核对依赖兼容性。安装说明
在一个新目录中创建虚拟环境:
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install 'presidio-analyzer==2.2.364' 'presidio-anonymizer==2.2.364'
本例没有实例化默认 AnalyzerEngine(),因此不需要下载英语 spaCy 模型。完整 AnalyzerEngine 工作流还涉及模型、registry 与上下文增强;加入这些组件后,应重新设计并运行覆盖测试。Analyzer 概念
2. 实现最小识别与转换管线
保存为 pii_pipeline.py。邮箱规则只接受这里定义的 ASCII 形态;账号格式限定为 acct_ 加四位数字。0.8 是示例规则分数,0.5 是本例的过滤阈值,不代表模型校准后的安全概率。
区间采用 Python 字符串的 start:end,不能把 UTF-8 字节位置或 JavaScript UTF-16 索引直接混入。检测后也不要先规范化字符串,再复用旧的 offset。本例遇到重叠区间直接报错,真实应用可以另行设计经过验证的冲突策略。
presidio_analyzer Pattern, PatternRecognizer
presidio_anonymizer AnonymizerEngine
presidio_anonymizer.entities OperatorConfig
RULES = [
PatternRecognizer(
supported_entity=,
patterns=[Pattern(, , )],
),
PatternRecognizer(
supported_entity=,
patterns=[Pattern(, , )],
),
]
OPERATORS = {
: OperatorConfig(, {: }),
: OperatorConfig(, {: }),
}
ENGINE = AnonymizerEngine()
():
hits = [h rule RULES h rule.analyze(text=text, entities=rule.supported_entities)
h.score >= ]
(hits, key= h: (h.start, h.end, h.entity_type))
():
previous_end =
hit (hits, key= h: (h.start, h.end)):
( <= hit.start < hit.end <= (text)):
ValueError()
hit.start < previous_end:
ValueError()
hit.entity_type OPERATORS:
ValueError()
previous_end = hit.end
():
hits = detect(text)
validate_spans(text, hits)
result = ENGINE.anonymize(text=text, analyzer_results=hits, operators=OPERATORS)
result.text, {: (hits), : }
():
(value value output value values):
AssertionError()
():
predicted = {(h.entity_type, h.start, h.end) h detect(text)}
expected = (expected)
{: (predicted & expected), : (predicted - expected),
: (expected - predicted)}
常见问题
- 示例会使用真实个人信息或调用云 API 吗?
- 不会。它仅用合成邮箱、虚构账号和本地 Presidio 包,不调用云 API、付费模型或预训练 NER。
- 为什么测试通过仍然存在误报和漏报?
- 测试既检查工程约束,也检查能否正确测量已知失败。已知误报和漏报被保留为反例,并没有因测试通过而消失。
- 教程能证明 Presidio 完整支持中文吗?
- 不能。中文和 emoji 前缀仅验证自定义 ASCII 规则的区间处理;中文姓名、地址等需要额外模型、规则和样本。
- 零命中可以证明原文没有敏感信息吗?
- 不能。它只表示当前检测器没有报告。教程用混淆邮箱展示零命中仍然漏报的情况。
- 重叠或越界的识别结果怎样处理?
- 本例在转换前校验区间并拒绝重叠或越界。真实应用可以另行设计冲突规则,但必须用边界样本验证。
- 为什么不直接把匹配原值写进日志?
- 日志会增加原值的复制和访问范围。本例只返回命中数量和规则版本,原文复核应走独立受控流程。