# https://github.com/microsoft/presidio 项目说明书

生成时间：2026-06-20 16:32:35 UTC

## 目录

- [Presidio 概览与系统架构](#page-1)
- [分析器引擎、NLP 后端与识别器生态](#page-2)
- [脱敏算子、图像 DICOM 与结构化数据](#page-3)
- [部署、LLM 扩展与社区故障模式](#page-4)

<a id='page-1'></a>

## Presidio 概览与系统架构

### 相关页面

相关主题：[分析器引擎、NLP 后端与识别器生态](#page-2), [脱敏算子、图像 DICOM 与结构化数据](#page-3), [部署、LLM 扩展与社区故障模式](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [presidio/README.md](https://github.com/microsoft/presidio/blob/main/presidio/README.md)
- [presidio-analyzer/README.md](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/README.md)
- [presidio-anonymizer/README.md](https://github.com/microsoft/presidio/blob/main/presidio-anonymizer/README.md)
- [presidio-image-redactor/README.md](https://github.com/microsoft/presidio/blob/main/presidio-image-redactor/README.md)
- [presidio-structured/README.md](https://github.com/microsoft/presidio/blob/main/presidio-structured/README.md)
- [presidio-cli/README.md](https://github.com/microsoft/presidio/blob/main/presidio-cli/README.md)
</details>

# Presidio 概览与系统架构

## 项目定位与核心价值

Presidio 是由微软维护的**上下文感知、可插拔且可定制**的 PII（个人可识别信息）去标识化服务，同时覆盖**文本与图像**两种数据形态。其核心思路是：将"PII 检测"与"PII 变形"拆分为两条独立但可组合的流水线，使用户能够灵活地替换任意环节。资料来源：[presidio/README.md:1-7]()。

仓库通过一个轻量级的**元包**（meta-package）`presidio` 对外暴露入口，该元包本身不包含业务代码，只负责把 `presidio-analyzer` 与 `presidio-anonymizer` 及其依赖一并安装。资料来源：[presidio/README.md:9-19]()。这种"组合包"的形式让初学者能以 `pip install presidio` 一条命令即可跑通最小示例，同时高级用户仍可按需单独引用更细粒度的子包。

## 核心模块组成

仓库在 monorepo 形式下由若干互相正交的 Python 子包组成，每个子包对应一种数据形态或交付方式。

| 子包 | 角色 | 主要类与入口 |
|------|------|--------------|
| `presidio-analyzer` | PII 检测引擎，按实体类型运行多个 recognizer | `AnalyzerEngine.analyze()` |
| `presidio-anonymizer` | 匿名化/去匿名化引擎，提供多种 operator | `AnonymizerEngine.anonymize()` |
| `presidio-image-redactor` | 图像与 DICOM 像素内的文本 PII 遮盖 | `ImageRedactorEngine`、`DicomImageRedactorEngine` |
| `presidio-structured` | 对 DataFrame / JSON 等结构化/半结构化数据进行列级 PII 检测与变形 | `StructuredEngine`、`PandasAnalysisBuilder` |
| `presidio-cli` | 命令行工具，直接对文件目录运行 Analyzer | `presidio` 命令 |

资料来源：[presidio-analyzer/README.md:1-9]()、[presidio-anonymizer/README.md:1-15]()、[presidio-image-redactor/README.md:1-15]()、[presidio-structured/README.md:1-7]()、[presidio-cli/README.md:1-7]()。

`presidio-analyzer` 预置了一组基于正则、基于 spaCy 的 NER、基于校验位以及基于 LLM（如通过 `BasicLangExtractRecognizer` / `AzureOpenAILangExtractRecognizer` 调用 LangExtract）的 PII 识别器，并支持通过 YAML 加载与 GPU 加速。资料来源：[presidio-analyzer/README.md:11-71]()。`presidio-anonymizer` 则内置 `replace`、`redact`、`hash`、`mask`、`encrypt`、`ahds surrogate` 等 operator，开发者可通过 `OperatorConfig` 按实体粒度配置。资料来源：[presidio-anonymizer/README.md:17-77]()。

## 系统架构与端到端数据流

下图展示了文本场景下的典型处理流水线，结构化与图像场景会分别在检测前/后增加适配层（DataFrame 适配器或 OCR/PIL 适配器），但核心思想保持一致。

```mermaid
flowchart LR
    A[原始文本/图像] --> B[Adapter<br/>DataFrame / OCR / pydicom]
    B --> C[AnalyzerEngine]
    C -->|RecognizerResult 列表| D[AnonymizerEngine]
    D --> E[去标识化输出]
    C --> F[预置识别器<br/>Regex / spaCy NER / Checksum / LLM]
    F --> C
    D --> G[Operator 集合<br/>replace / redact / hash / mask / encrypt]
    G --> D
```

资料来源：[presidio-analyzer/README.md:65-73]()、[presidio-anonymizer/README.md:64-83]()、[presidio-image-redactor/README.md:17-25]()。

`AnalyzerEngine` 负责把"识别什么 PII"这件事抽象为可插拔的 recognizer 集合；`AnonymizerEngine` 则把"如何变形"抽象为可插拔的 operator 集合。两者通过 `RecognizerResult`（包含 `entity_type`、`start`、`end`、`score`）解耦，从而允许在同一条流水线上混用不同来源的检测结果。资料来源：[presidio-anonymizer/README.md:64-83]()。

## 安装、快速上手与典型使用模式

最简安装方式为：

```bash
pip install presidio
```

资料来源：[presidio/README.md:21-27]()。该命令会同时拉取 `presidio-analyzer` 与 `presidio-anonymizer` 及其依赖。

最小可运行示例：

```python
from presidio_analyzer import AnalyzerEngine
from presidio_anonymizer import AnonymizerEngine

analyzer = AnalyzerEngine()
anonymizer = AnonymizerEngine()

results = analyzer.analyze(text="My name is John Doe", language="en")
anonymized = anonymizer.anonymize(
    text="My name is John Doe", analyzer_results=results
)
print(anonymized)
```

资料来源：[presidio/README.md:29-39]()。在图像场景下，`ImageRedactorEngine` 通过 OCR 识别 PII 文本框后直接以指定颜色（默认黑色）遮盖；DICOM 场景则额外提供 `redact_and_return_bbox`、`redact_from_directory` 等高级入口。资料来源：[presidio-image-redactor/README.md:51-77]()。结构化场景下，`StructuredEngine` 借助 `PandasAnalysisBuilder` 把整张表先做一次"列级 PII 推断"，再按列调用 `presidio-anonymizer` 的 operator。资料来源：[presidio-structured/README.md:13-37]()。

## 社区关注的方向与已知风险

从社区讨论来看，常见诉求集中在以下几类：

1. **平台与部署**：issue #853 长期跟踪 Apple M1 / ARM64 镜像缺失的问题（`mcr.microsoft.com/presidio-analyzer:latest` 在 ARM64 上无法直接运行）。资料来源：[community context #853]()。
2. **国家特定识别器**：菲律宾（#2015）、德国（#1828）等国 PII 格式请求持续增加；2.2.360 起新增带校验位的韩国 RRN 识别器。资料来源：[community context #2015, #1828, Release 2.2.360]()。
3. **LLM 集成**：issue #1234 与 PR #1834 推动 LLM/Transformer 直接参与检测，最新版本提供 `HuggingFaceNerRecognizer` 与 LangExtract 系列识别器。资料来源：[presidio-analyzer/README.md:11-43]()、[community context #1234, Release 2.2.362]()。
4. **配置与配置 dump 缺陷**：issue #2080 指出通过 analyzer YAML 配置时，省略的可选字段在 registry 校验阶段会被序列化为 `None`，影响配置回写。资料来源：[community context #2080]()。
5. **图像/DICOM 评估链路**：issue #2083 报告 `DicomImagePiiVerifyEngine._remove_duplicate_entities` 中 `sorted()` 结果被丢弃，导致保留了**低分**实体而非高分；issue #1251 反映官方 DICOM 评估 notebook 报错。资料来源：[community context #2083, #1251]()。
6. **行为变更提示**：Release 2.2.359 起，大多数基于英文的国家特定识别器默认被关闭，以避免在非目标语言上产生误报；升级时需主动启用。资料来源：[community context Release 2.2.359]()。

## See Also

- [Presidian Analyzer 详细文档](presidio-analyzer-wiki.md)
- [Presidio Anonymizer 详细文档](presidio-anonymizer-wiki.md)
- [Presidio Image Redactor 详细文档](presidio-image-redactor-wiki.md)
- [Presidio Structured 详细文档](presidio-structured-wiki.md)
- [Presidio CLI 详细文档](presidio-cli-wiki.md)

---

<a id='page-2'></a>

## 分析器引擎、NLP 后端与识别器生态

### 相关页面

相关主题：[Presidio 概览与系统架构](#page-1), [脱敏算子、图像 DICOM 与结构化数据](#page-3), [部署、LLM 扩展与社区故障模式](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [presidio-analyzer/presidio_analyzer/analyzer_engine.py](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/analyzer_engine.py)
- [presidio-analyzer/presidio_analyzer/analyzer_engine_provider.py](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/analyzer_engine_provider.py)
- [presidio-analyzer/presidio_analyzer/recognizer_registry/recognizer_registry.py](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/recognizer_registry/recognizer_registry.py)
- [presidio-analyzer/presidio_analyzer/recognizer_registry/recognizer_registry_provider.py](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/recognizer_registry/recognizer_registry_provider.py)
- [presidio-analyzer/presidio_analyzer/recognizer_registry/recognizers_loader_utils.py](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/recognizer_registry/recognizers_loader_utils.py)
- [presidio-analyzer/presidio_analyzer/nlp_engine/nlp_engine_provider.py](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/nlp_engine/nlp_engine_provider.py)
- [presidio-analyzer/README.md](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/README.md)
- [presidio-analyzer/presidio_analyzer/predefined_recognizers/](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/predefined_recognizers/)

</details>

# 分析器引擎、NLP 后端与识别器生态

`presidio-analyzer` 是 Presidio 体系中的文本 PII 检测核心，负责对非结构化文本进行上下文感知、插件化、可定制的实体识别。其核心由三大组件构成：`AnalyzerEngine`（分析器引擎）、`NlpEngineProvider`（NLP 引擎提供者）和 `RecognizerRegistry`（识别器注册表）。三者通过分层解耦设计，使分析逻辑、NLP 推理能力与识别规则得以独立扩展。资料来源：[presidio-analyzer/README.md]()

## 1. 分析器引擎（AnalyzerEngine）

`AnalyzerEngine` 是对外暴露的主要入口，封装了 NLP 引擎、识别器注册表与日志组件，对外提供 `analyze()` 方法。调用方传入原始文本、目标语言、希望匹配的 `entities` 列表以及可选的 `ad_hoc_recognizers`（临时识别器）和 `regex_flags`，引擎会按 NLP 解析、识别器遍历、结果合并三个阶段返回 `RecognizerResult` 列表。资料来源：[presidio-analyzer/presidio_analyzer/analyzer_engine.py]()

`AnalyzerEngineProvider` 是其工厂类，承担配置加载职责：从 YAML 配置文件或 Python 字典中读取 `nlp_engine` 与 `recognizer_registry` 段，并据此实例化 `NlpEngine` 与 `RecognizerRegistry`，最终组装出 `AnalyzerEngine`。该 provider 是 CLI、Docker 容器以及 `presidio-analyzer[langextract]` 等扩展包共用的底层入口。资料来源：[presidio-analyzer/presidio_analyzer/analyzer_engine_provider.py]()

## 2. NLP 后端与提供者（NlpEngineProvider）

`NlpEngineProvider` 抽象了底层 NLP 框架，使 Presidio 不与某一特定模型库强绑定。默认实现基于 spaCy（`en_core_web_lg`），但通过 provider 模式可切换到 Hugging Face Transformers、Stanza 或自建 NER 模型。新增的 `HuggingFaceNerRecognizer`（Release 2.2.362）支持直接以 NER 模型推理的方式参与识别。资料来源：[presidio-analyzer/presidio_analyzer/nlp_engine/nlp_engine_provider.py]()

GPU 加速可通过环境变量控制：在 Linux + NVIDIA 环境下安装 `cupy-cuda12x`（与本地 CUDA 版本对齐），macOS Apple Silicon 的 MPS 暂未启用，分析器在 PyTorch 操作上回退至 CPU。资料来源：[presidio-analyzer/README.md]()

社区讨论 #1234 提议引入基于 LLM 的去识别能力，目前通过 `langextract` 扩展包（`BasicLangExtractRecognizer` 与 `AzureOpenAILangExtractRecognizer`）以本地 Ollama 或 Azure OpenAI 形式落地，初始化阶段不进行连通性校验，错误推迟到首次 `analyze()` 调用时上报。资料来源：[presidio-analyzer/README.md]()

## 3. 识别器注册表（RecognizerRegistry）

`RecognizerRegistry` 是所有识别器的容器与调度器，存储形如 `EntityRecognizer` 的实例列表并提供 `get_recognizers(language, entities)` 等查询接口。注册表支持两类来源：

| 来源类型 | 加载方式 | 典型用途 |
| --- | --- | --- |
| 预置识别器 | 代码内置或 YAML 字段 | 默认 PII 类别（PERSON、EMAIL_ADDRESS、CREDIT_CARD 等） |
| 自定义识别器 | 用户代码实例化后注入 | 业务特定实体（订单号、内部工号） |
| 临时识别器 | `analyze()` 的 `ad_hoc_recognizers` 参数 | 一次性实验性规则 |

注册表还负责语言回退：当请求语言（如 `de`）未注册时，可回退到 `en` 以避免空结果。资料来源：[presidio-analyzer/presidio_analyzer/recognizer_registry/recognizer_registry.py]()

`RecognizerRegistryProvider` 与 `recognizers_loader_utils` 协作完成从配置加载识别器的职责：解析 YAML 中的 `recognizers` 段、构造 Pydantic 配置模型、调用对应识别器构造函数。Issue #2080 反馈当某些可选字段在 YAML 中省略时，会被序列化为显式 `None`，影响后续 registry 校验与配置回写。资料来源：[presidio-analyzer/presidio_analyzer/recognizer_registry/recognizer_registry_provider.py]()、[presidio-analyzer/presidio_analyzer/recognizer_registry/recognizers_loader_utils.py]()

## 4. 识别器生态与扩展

`predefined_recognizers` 目录按"国家/地区"与"技术路线"两个维度组织识别器：

- **通用类别**：邮箱、电话、信用卡、IP、URL 等基于正则或 NLP 的识别器。
- **国家/地区专用**：自 Release 2.2.359 起，多数基于英文模式的国家识别器默认禁用，避免误报；Release 2.2.360 新增韩国 RRN 识别器（含 2020 年 10 月前号码的校验和验证）。社区 Issue #1828 与 #2015 分别提议新增德国与菲律宾专用识别器。资料来源：[presidio-analyzer/README.md]()
- **LLM/SLM 识别器**：`BasicLangExtractRecognizer`、`AzureOpenAILangExtractRecognizer`、GLiNER 集成示例。资料来源：[presidio-analyzer/README.md]()
- **远程/服务化识别器**：Release 2.2.360 引入 Azure Health Data Services 远程识别器（Entra ID 鉴权），AHDS 替代文本由 `presidio-anonymizer` 的 `surrogate` 操作符消费。资料来源：[presidio-analyzer/README.md]()

```mermaid
flowchart LR
    A[原始文本] --> B[AnalyzerEngine.analyze]
    B --> C[NlpEngineProvider<br/>spaCy / HF / Stanza]
    C --> D[NLP 文档]
    B --> E[RecognizerRegistry]
    E --> F[预置识别器]
    E --> G[自定义识别器]
    E --> H[ad_hoc_recognizers]
    D --> F
    D --> G
    D --> H
    F --> I[结果合并 & 评分]
    G --> I
    H --> I
    I --> J[RecognizerResult 列表]
```

扩展自定义识别器时，建议继承 `EntityRecognizer` 并实现 `analyze()` 与 `load()` 方法；将其加入注册表后即可被 `AnalyzerEngine` 自动调用，且无需改动引擎核心代码。这种插件化设计是 Presidio 适用于不同行业（医疗、金融、政务）的关键。资料来源：[presidio-analyzer/presidio_analyzer/recognizer_registry/recognizer_registry.py]()

## 常见失败模式与排障

- **NLP 模型未下载**：未执行 `python -m spacy download en_core_web_lg` 会导致 `AnalyzerEngine()` 初始化抛出 OSError。
- **YAML 配置 `None` 字段**：见 Issue #2080，可显式提供默认值或在加载工具中过滤 `None`。
- **arm64 镜像缺失**：见 Issue #853，Apple M1 用户需自行构建容器或使用 pip 安装。
- **LLM 识别器连通性**：错误延迟到 `analyze()` 阶段，需检查 `AZURE_OPENAI_ENDPOINT` / Ollama 服务可达性。资料来源：[presidio-analyzer/README.md]()

## See Also

- Presidio 匿名器（`presidio-anonymizer`）
- Presidio 结构化（`presidio-structured`）
- Presidio 图像脱敏（`presidio-image-redactor`）
- CLI 工具（`presidio-cli`）

---

<a id='page-3'></a>

## 脱敏算子、图像 DICOM 与结构化数据

### 相关页面

相关主题：[Presidio 概览与系统架构](#page-1), [分析器引擎、NLP 后端与识别器生态](#page-2), [部署、LLM 扩展与社区故障模式](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [presidio/README.md](https://github.com/microsoft/presidio/blob/main/presidio/README.md)
- [presidio-anonymizer/README.md](https://github.com/microsoft/presidio/blob/main/presidio-anonymizer/README.md)
- [presidio-analyzer/README.md](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/README.md)
- [presidio-image-redactor/README.md](https://github.com/microsoft/presidio/blob/main/presidio-image-redactor/README.md)
- [presidio-structured/README.md](https://github.com/microsoft/presidio/blob/main/presidio-structured/README.md)
- [presidio-cli/README.md](https://github.com/microsoft/presidio/blob/main/presidio-cli/README.md)
</details>

# 脱敏算子、图像 DICOM 与结构化数据

## 概览

Microsoft Presidio 是一个上下文感知、可插拔的 PII 脱敏框架，由多个互补子包组成。`presidio` 元包仅通过依赖方式拉取 `presidio-analyzer` 与 `presidio-anonymizer`，覆盖非结构化文本场景 ([资料来源: [presidio/README.md:1-15]()]())。对于图像与 DICOM 医学影像、`pandas`/JSON 等结构化数据，仓库提供专门的子包进行扩展。本文聚焦三块能力：文本脱敏算子、图像与 DICOM 脱敏、结构化数据脱敏，并整理社区中已知的相关问题与限制。

## 文本脱敏算子

`presidio-anonymizer` 内置多种匿名化算子（Anonymizer Operators），用于在 `RecognizerResult` 标注的实体位置进行替换或变形 ([资料来源: [presidio-anonymizer/README.md:20-65]()]())。其默认算子为 `replace`，若未提供 `new_value` 则回退为 `<entity_type>` 字符串。核心算子包括：

- **replace**：用指定值或默认占位符替换 PII，参数 `new_value`。
- **redact**：从文本中完全移除，无额外参数。
- **hash**：对 PII 进行散列（sha256/sha512），2.2.358 起弃用 `md5`，参数 `hash_type`。
- **mask**：以指定字符覆盖部分或全部，参数 `chars_to_mask`、`masking_char`、`from_end`。
- **encrypt**：使用 AES（Rijndael）加密，参数 `key`（128/192/256 位字符串）。
- **custom**：通过 `lambda` 自定义处理逻辑，返回值必须为字符串。
- **ahds surrogate**：调用 Azure Health Data Services 代理生成语义保真的占位符，需 `pip install presidio-anonymizer[ahds]`，参数包括 `endpoint`、`entities`、`input_locale`、`surrogate_locale` ([资料来源: [presidio-anonymizer/README.md:60-80]()]())。

当存在重叠实体时，`AnonymizerEngine` 需借助 `conflict_resolution_strategy` 决定如何合并或选择 ([资料来源: [presidio-anonymizer/README.md:80-110]()]())。`DeanonymizeEngine` 则用于将 `encrypt` 等可逆算子还原回原文。

## 图像与 DICOM 脱敏

`presidio-image-redactor` 提供两类引擎：`ImageRedactorEngine` 用于标准图像（PNG/JPG 等），`DicomImageRedactorEngine` 用于 DICOM 医学影像 ([资料来源: [presidio-image-redactor/README.md:40-70]()]()))。两者流程一致：使用 Tesseract OCR 进行文本识别与坐标定位 → 调用 `presidio-analyzer` 检测 PII → 以填充色（默认黑色，或 `contrast`/`background`）覆盖识别框。

DICOM 流程建议**先**做像素级文本脱敏，再使用外部工具处理元数据中的 PHI，例如 [Tools for Health Data Anonymization](https://github.com/microsoft/Tools-for-Health-Data-Anonymization)。`DicomImageRedactorEngine` 提供四个入口：`redact`、`redact_and_return_bbox`、`redact_from_file`、`redact_from_directory`，并支持 `padding_width`、`ocr_kwargs={"ocr_threshold": 50}` 等参数 ([资料来源: [presidio-image-redactor/README.md:10-40]()]())。需要安装 Tesseract OCR（v5.2.0 验证）及 spaCy 模型 `en_core_web_lg`。

社区已知问题与注意点：

- `DicomImagePiiVerifyEngine._remove_duplicate_entities` 中 `sorted()` 结果被丢弃，错误地保留了最低分实体（Issue #2083）。
- `example_dicom_redactor_evaluation.ipynb` 在某些环境下运行报错（Issue #1251）。
- Windows 上 DICOM 路径过长需启用系统长路径支持 ([资料来源: [presidio-image-redactor/README.md:95-115]()]())。
- ARM64 镜像长期缺失，社区多次请求（Issue #853）。

## 结构化数据脱敏

`presidio-structured` 是面向表格与半结构化数据的脱敏框架 ([资料来源: [presidio-structured/README.md:1-30]()]())。其核心为 `StructuredEngine`（默认基于 `pandas`）与 `PandasAnalysisBuilder`：

1. 通过 `PandasAnalysisBuilder().generate_analysis(df)` 生成 `TabularAnalysis`，描述每列所含 PII 实体；
2. `StructuredEngine` 调用 `presidio-analyzer` 检测列名/键名与值，并映射到实体类型；
3. 借助 `presidio-anonymizer` 的 `OperatorConfig`，对识别列按值应用算子（如 `replace`、`mask`、`encrypt`），可结合 `faker` 生成伪造数据 ([资料来源: [presidio-structured/README.md:25-55]()]())。

```mermaid
flowchart LR
  A[pandas DataFrame] --> B[PandasAnalysisBuilder]
  B --> C[TabularAnalysis]
  C --> D[StructuredEngine]
  D --> E[AnalyzerEngine 检测]
  E --> F[AnonymizerEngine 算子]
  F --> G[脱敏后 DataFrame]
```

自 2.2.354 起，`presidio-structured` 支持用户自定义实体选择策略（PR #1319），在多实体类型冲突时具备更细粒度控制 ([资料来源: [presidio-structured/README.md]()]())。

## 常见问题与限制

- **国家化识别器**：德语（Issue #1828）、菲律宾语（Issue #2015）国家识别器被陆续提议；2.2.359 起多数英语国家识别器改为默认禁用以减少误报。
- **GPU 加速**：2.2.362 起可通过环境变量控制 GPU 设备（PR #1844），并新增 `HuggingFaceNerRecognizer`。
- **LLM 集成**：`presidio-analyzer[langextract]` 引入 LangExtract，支持 Ollama 与 Azure OpenAI ([资料来源: [presidio-analyzer/README.md:10-50]()]())。
- **YAML 序列化**：分析器 YAML 配置中省略的识别器字段可能被序列化为 `None`（Issue #2080）。
- **密码识别**：社区请求增加密码实体识别（Issue #805），尚未在主分支实现。
- **CLI 配置**：`presidio-cli` 通过 `.presidiocli` 或 `-d` 参数传入语言、阈值、实体与忽略列表，支持 `standard`/`github`/`colored`/`parsable`/`auto` 五种输出格式 ([资料来源: [presidio-cli/README.md:30-90]()]())。

## See Also

- [Presidio Analyzer 文档](https://microsoft.github.io/presidio/analyzer/)
- [Anonymizer HTTP API 规范](https://microsoft.github.io/presidio/api-docs/api-docs.html)
- [DICOM 评估样例 Notebook](https://github.com/microsoft/presidio/blob/main/docs/samples/python/example_dicom_redactor_evaluation.ipynb)
- [Language Model-based PII/PHI Detection 指南](https://microsoft.github.io/presidio/samples/python/langextract/)

---

<a id='page-4'></a>

## 部署、LLM 扩展与社区故障模式

### 相关页面

相关主题：[Presidio 概览与系统架构](#page-1), [分析器引擎、NLP 后端与识别器生态](#page-2), [脱敏算子、图像 DICOM 与结构化数据](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [presidio/README.md](https://github.com/microsoft/presidio/blob/main/presidio/README.md)
- [presidio-analyzer/README.md](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/README.md)
- [presidio-anonymizer/README.md](https://github.com/microsoft/presidio/blob/main/presidio-anonymizer/README.md)
- [presidio-image-redactor/README.md](https://github.com/microsoft/presidio/blob/main/presidio-image-redactor/README.md)
- [presidio-structured/README.md](https://github.com/microsoft/presidio/blob/main/presidio-structured/README.md)
- [presidio-cli/README.md](https://github.com/microsoft/presidio/blob/main/presidio-cli/README.md)
- [docker-compose.yml](https://github.com/microsoft/presidio/blob/main/docker-compose.yml)
- [docker-compose-text.yml](https://github.com/microsoft/presidio/blob/main/docker-compose-text.yml)
- [docker-compose-image.yml](https://github.com/microsoft/presidio/blob/main/docker-compose-image.yml)
- [docker-compose-transformers.yml](https://github.com/microsoft/presidio/blob/main/docker-compose-transformers.yml)
- [presidio-analyzer/Dockerfile](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/Dockerfile)
- [presidio-anonymizer/Dockerfile](https://github.com/microsoft/presidio/blob/main/presidio-anonymizer/Dockerfile)
- [presidio-image-redactor/Dockerfile](https://github.com/microsoft/presidio/blob/main/presidio-image-redactor/Dockerfile)
</details>

# 部署、LLM 扩展与社区故障模式

## 概述

Presidio 是一个面向文本和图像的、可插拔的 PII 去标识化服务，由多个子包组成（`presidio-analyzer`、`presidio-anonymizer`、`presidio-image-redactor`、`presidio-structured`、`presidio-cli`）。本专题聚焦于三个相互关联的工程维度：容器化与多形态部署、基于大语言模型（LLM）的检测能力扩展，以及社区中反复出现的故障模式与近期修复方向。

资料来源：[presidio/README.md:1-30]()

---

## 1. 容器化与多形态部署

### 1.1 Docker Compose 编排

仓库根目录提供多个 compose 文件，分别覆盖不同子服务的部署形态：

| 文件 | 覆盖范围 |
|---|---|
| `docker-compose.yml` | 顶层编排，串联文本与图像服务 |
| `docker-compose-text.yml` | 仅启动 `presidio-analyzer` 与 `presidio-anonymizer` |
| `docker-compose-image.yml` | 仅启动 `presidio-image-redactor` 镜像服务 |
| `docker-compose-transformers.yml` | 引入 transformers 后端的分析器栈 |

各子包独立提供 Dockerfile，可在子包目录下单独执行 `docker-compose up -d` 启动对应服务。例如图像包中给出的运行方式为：在 `presidio/presidio-image-redactor` 目录下调用 `docker-compose up -d` 来拉起服务。资料来源：[presidio-image-redactor/README.md:1-40]()

### 1.2 部署入口与 HTTP 接口

- **Analyzer / Anonymizer**：提供文本 PII 检测与脱敏的 HTTP 接口，社区文档中给出了完整的 OpenAPI 入口（`/analyze`、`/anonymize`、`/deanonymize` 等）。资料来源：[presidio-anonymizer/README.md:1-80]()
- **Image Redactor**：`POST /redact` 接口接收 multipart 表单（`image` 文件 + `data` JSON 字符串），返回脱敏后的图像。资料来源：[presidio-image-redactor/README.md:1-60]()
- **Azure 一键部署**：每个子包 README 都提供 "Deploy to Azure" 按钮，对应 ARM 模板位于 `presidio-<pkg>/deploytoazure.json`。资料来源：[presidio-analyzer/README.md:1-40]()

### 1.3 架构与流程

```mermaid
flowchart LR
    A[客户端/SDK] --> B[presidio-analyzer]
    B --> C[Recognizer 池<br/>regex/NER/LLM]
    C --> D[AnalyzerEngine.analyze]
    D --> E[presidio-anonymizer]
    E --> F[Operators:<br/>replace/mask/hash/encrypt]
    F --> G[脱敏文本]
    B -.HTTP.-> H[REST API :3002]
    E -.HTTP.-> I[REST API :3001]
    J[图像/PDF] --> K[presidio-image-redactor]
    K --> L[Tesseract OCR]
    L --> B
```

### 1.4 部署相关社区议题

社区长期关注 **ARM64 镜像**（Apple M1 / 鲲鹏等）支持，议题 #853 反馈 `mcr.microsoft.com/presidio-analyzer:latest` 在 M1 上无法直接运行；目前主流应对仍是基于源码或自构建镜像。此外，2.2.356 之后容器切到 gunicorn 作为 WSGI 入口，提升并发吞吐。资料来源：[Release 2.2.356]()

---

## 2. LLM 与语言模型扩展

### 2.1 LangExtract 集成（官方主推路径）

`presidio-analyzer` 2.2.362 起官方引入基于 [LangExtract](https://github.com/google/langextract) 的 LLM 识别器，可对接 **Ollama**（本地模型）与 **Azure OpenAI**（云端）：

```python
# Ollama 路径
from presidio_analyzer.predefined_recognizers import BasicLangExtractRecognizer
recognizer = BasicLangExtractRecognizer()

# Azure OpenAI 路径
from presidio_analyzer.predefined_recognizers import AzureOpenAILangExtractRecognizer
recognizer = AzureOpenAILangExtractRecognizer(
    model_id="gpt-4",
    azure_endpoint="https://your-resource.openai.azure.com/",
    api_key="your-api-key",
)
```

安装时需要显式启用可选依赖：`pip install presidio-analyzer[langextract]`。初始化阶段不会校验连通性，连接错误会延迟到 `analyze()` 首次调用时才暴露。资料来源：[presidio-analyzer/README.md:1-60]()

### 2.2 HuggingFace 直接推理

2.2.362 引入 `HuggingFaceNerRecognizer`，允许在 Analyzer 内直接加载 HuggingFace 上的 NER 模型进行推理，避免再额外启动 transformers 容器。资料来源：[Release 2.2.362]()

### 2.3 GPU 加速与环境变量

自 2.2.362 起，Analyzer 支持通过环境变量控制 GPU 设备：

- Linux + NVIDIA GPU：安装 `cupy-cuda12x`（或匹配 CUDA 版本的轮子）以启用 GPU 加速；
- macOS Apple Silicon：MPS 暂不支持，相关 PyTorch 操作回退到 CPU。资料来源：[presidio-analyzer/README.md:60-90]()

### 2.4 LLM 相关社区诉求

- 议题 #1234（13 条评论，社区关注度最高）请求 LLM 直接作为 PII 检测器，从而支持任意自定义实体与"人物特征"型 PII。
- 议题 #1171 提议增加与 **Semantic Kernel** 集成的最小示例，覆盖 Prompt 输入输出两侧的脱敏。
- 议题 #1828 提议在 `presidio_analyzer/predefined_recognizers/country_specific/germany/` 下补充德语国家识别器（目前官方仅提供英文为主的预置国家识别器）。资料来源：[community_context 议题清单]()

---

## 3. 社区故障模式与近期修复

### 3.1 图像去标识化：去重逻辑反序

`DicomImagePiiVerifyEngine._remove_duplicate_entities` 中调用了 `sorted(...)` 但未接收返回值，导致去重时反而保留**最低分**的实体。issue #2083 复现了将高质量识别结果覆盖为低质量结果的故障，修复时需将排序结果赋回列表变量。资料来源：[community_context 议题 #2083]()

### 3.2 YAML 配置 None 序列化

issue #2080 指出：自定义 YAML 识别器在缺省可选字段时，注册校验阶段会将字段序列化为显式 `None`，进而影响配置 dump 路径。规避方式是显式给出空值或在 registry 中过滤空字段。资料来源：[community_context 议题 #2080]()

### 3.3 哈希算法迁移与 URL 识别器

2.2.358 起项目将默认哈希从 MD5 迁移到 **Blake2**，并废弃 `md5` 入参；同期 URL 识别器在匹配时排除闭合的单/双引号字符，避免把 `"https://example.com"` 的尾部引号纳入 URL。资料来源：[Release 2.2.358]()

### 3.4 DICOM 评估示例与元数据条件

issue #1251 报告 `example_dicom_redactor_evaluation.ipynb` 报错的根因之一是 DICOM 元数据判断条件错误，2.2.354 中通过 PR #1347 修正；同时 PR #1342 将 Analyzer 默认 `aggregation_strategy` 改为 `max`，显著降低漏检。资料来源：[Release 2.2.354]()

### 3.5 国家识别器默认行为变更

为减少误报，2.2.359 之后**多数英文优先的国家识别器**默认被标记为禁用，需要时显式启用；同期 2.2.360 新增 **韩国 RRN 识别器**（含 2020 年 10 月前的校验位校验）、**Azure Health Data Services 远端识别器**（带 Entra ID 鉴权）等。资料来源：[Release 2.2.359]()、[Release 2.2.360]()

### 3.6 结构化数据策略扩展

2.2.354 引入 `presidio-structured` 的**用户自定义实体选择策略**（PR #1319），让 DataFrame / JSON 列与 PII 实体的映射可由用户插件化。资料来源：[Release 2.2.354]()

---

## 4. CLI 与可编程入口

`presidio-cli` 提供命令行 PII 扫描入口，可读取 `.presidiocli` YAML 配置（`language`、`entities`、`ignore`、`allow`），输出支持 `standard` / `github` / `colored` / `parsable` / `auto` 五种格式。在 GitHub Actions 环境下，`auto` 模式会自动切换为 `github` 格式，便于嵌入 PR 检查。资料来源：[presidio-cli/README.md:1-80]()

---

## See Also

- Presidio Analyzer 概览
- Presidio Anonymizer 运算符
- Presidio Image Redactor（DICOM 子模块）
- Presidio Structured 策略
- 部署与配置（Azure / Docker）

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：microsoft/presidio

摘要：发现 9 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：运行坑 - 来源证据：Sample presidio image evaluation notebook generates error。

## 1. 运行坑 · 来源证据：Sample presidio image evaluation notebook generates error

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Sample presidio image evaluation notebook generates error
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/microsoft/presidio/issues/1251 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 安全/权限坑 · 来源证据：[Bug] Omitted YAML recognizer fields are passed as None

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Omitted YAML recognizer fields are passed as None
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/microsoft/presidio/issues/2080 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/microsoft/presidio | README/documentation is current enough for a first validation pass.

## 4. 运行坑 · 来源证据：bug(image-redactor): `sorted()` result discarded in `_remove_duplicate_entities`, lowest-scored entity kept instead of…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug(image-redactor): `sorted()` result discarded in `_remove_duplicate_entities`, lowest-scored entity kept instead of highest
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/microsoft/presidio/issues/2083 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/microsoft/presidio | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/microsoft/presidio | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/microsoft/presidio | no_demo; severity=medium

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/microsoft/presidio | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/microsoft/presidio | release_recency=unknown

<!-- canonical_name: microsoft/presidio; human_manual_source: deepwiki_human_wiki -->