DataFog/datafog-python
GitHub: DataFog/datafog-python
DataFog 是一个轻量级 Python 库，提供基于正则和 NLP 的 PII 检测、编辑与 LLM 护栏功能，帮助开发者在文本处理和大模型调用中保护敏感信息。
Stars: 67 | Forks: 14
# DataFog Python
DataFog 是一个用于检测和编辑个人身份信息（PII）的 Python 库。
它提供：
- 通过正则表达式进行快速的结构化 PII 检测
- 通过 spaCy 和 GLiNER 提供可选的 NER 支持
- 面向 LLM 应用的简单 agent 导向 API
- 向后兼容的 `DataFog` 和 `TextService` 类
## 4.5 版本重点
DataFog 4.5 专注于轻量级的文本 PII 扫描：极简的核心安装，
基于正则表达式的快速扫描/编辑辅助工具，明确的可选附加组件，以及
为未来 middleware 用例铺平的更清晰道路。专用的 Sentry、OpenTelemetry、
日志框架和云 DLP 适配器属于面向未来的工作，不包含在 4.5 版本中。
## 安装
```
# 核心安装 (regex engine)
pip install datafog
# 添加 spaCy 支持
pip install datafog[nlp]
# 添加 GLiNER + spaCy 支持
pip install datafog[nlp-advanced]
# 添加本地 OCR 支持
pip install datafog[ocr]
# 添加 Spark/distributed 支持
pip install datafog[distributed]
# 全部
pip install datafog[all]
```
Python 3.13 支持已通过核心 SDK、CLI、`nlp`、
`nlp-advanced` 和 `ocr` 安装配置的认证。Donut OCR 在运行时使用前，
仍需在本地准备好可用的模型。在 4.5 版本中，`distributed` 和 `all`
尚未获得针对 Python 3.13 的新认证。
## 快速开始
```
import datafog
text = "Contact john@example.com or call (555) 123-4567"
clean = datafog.sanitize(text, engine="regex")
print(clean)
# 联系 [EMAIL_1] 或致电 [PHONE_1]
```
## 面向 LLM 应用
```
import datafog
# 1) 在发送给 LLM 之前扫描 prompt 文本
prompt = "My SSN is 123-45-6789"
scan_result = datafog.scan_prompt(prompt, engine="regex")
if scan_result.entities:
print(f"Detected {len(scan_result.entities)} PII entities")
# 2) 在返回之前对 model 输出进行 redact
output = "Email me at jane.doe@example.com"
safe_result = datafog.filter_output(output, engine="regex")
print(safe_result.redacted_text)
# 发送电子邮件至 [EMAIL_1]
# 3) 单行 redaction
print(datafog.sanitize("Card: 4111-1111-1111-1111", engine="regex"))
# 信用卡: [CREDIT_CARD_1]
```
## 德国结构化 PII
德国结构化 PII 特定于国家/地区且需主动选择。当您需要处理德国增值税号、
德国 IBAN、税号、邮政编码、护照或居留许可时，
请使用明确的区域设置选择或实体类型过滤。
```
import datafog
text = "Steuer-ID 12345678901 liegt vor."
print(datafog.scan(text, engine="regex").entities)
# []
print(datafog.scan(text, engine="regex", locales=["de"]).entities)
# [Entity(type='DE_TAX_ID', text='12345678901', ...)]
```
### Guardrails
```
import datafog
# 可重用的 guardrail 对象
guard = datafog.create_guardrail(engine="regex", on_detect="redact")
@guard
def call_llm() -> str:
return "Send to admin@example.com"
print(call_llm())
# 发送至 [EMAIL_1]
```
## 引擎
请使用符合您准确率和依赖限制的引擎：
- `regex`：
- 最快且始终可用。
- 最适合默认的结构化实体：`EMAIL`、`PHONE`、`SSN`、`CREDIT_CARD`、`IP_ADDRESS`、`DATE`、`ZIP_CODE`。
- 使用 `locales=["de"]` 处理德国结构化 ID，例如 `DE_VAT_ID`、`DE_IBAN`、`DE_TAX_ID`、`DE_POSTAL_CODE` 以及护照或居留许可号码。
- `spacy`：
- 需要通过 `pip install datafog[nlp]` 安装。
- 适用于非结构化实体，如人名和组织名称。
- `gliner`：
- 需要通过 `pip install datafog[nlp-advanced]` 安装。
- 对于非结构化文本，其 NER 覆盖范围比正则表达式更广。
- `smart`：
- 将正则表达式与可选的 NER 引擎级联使用。
- 如果缺少可选依赖项，它会优雅降级并发出警告。
## 可选的 OCR 和 Spark 接口
DataFog 4.5 继续将主包的核心功能集中在轻量级文本 PII
扫描上。OCR 和 Spark 对于已经依赖它们的用户来说仍然是受支持的可选接口，
但它们并不是核心导入、默认扫描/编辑辅助工具或 guardrail 辅助工具所必需的。
- OCR：
- 安装 `datafog[ocr]` 以使用本地图像 OCR 辅助工具。
- 基于 URL 的图像下载还需要 `datafog[web,ocr]`。
- 使用 Tesseract 需要系统安装 `tesseract` 二进制文件。
- Python 3.13 已针对 OCR 安装配置、Pillow、
pytesseract 以及系统 Tesseract 的冒烟测试进行了验证。
- Donut OCR 需要 `datafog[nlp-advanced,ocr]` 并且本地已有可用模型。
- Spark：
- 安装 `datafog[distributed]` 以使用 `SparkService`。
- Spark PII UDF 辅助工具还需要 `datafog[nlp]` 以及已安装的 spaCy
模型。
- PySpark 需要安装 Java 运行时。
OCR 和 Spark 并未被弃用。它们更广泛的 API 和打包重构工作
已被推迟；4.5 的目标是保持它们的独立性、文档化，并与
轻量级核心路径相互隔离。
## 向后兼容的 API
现有的公共 API 仍然可用。
### `DataFog` 类
```
from datafog import DataFog
result = DataFog().scan_text("Email john@example.com")
print(result["EMAIL"])
```
### `TextService` 类
```
from datafog.services import TextService
service = TextService(engine="regex")
result = service.annotate_text_sync("Call (555) 123-4567")
print(result["PHONE"])
```
## CLI
```
# 扫描文本
datafog scan-text "john@example.com"
# Redact 文本
datafog redact-text "john@example.com"
# 用 pseudonyms 替换文本
datafog replace-text "john@example.com"
# 对检测到的 entity 进行 Hash
datafog hash-text "john@example.com"
# 启用德语 regex identifiers
datafog redact-text "Steuer-ID 12345678901" --locale de
```
## Telemetry
DataFog 的 Telemetry 默认是禁用的。
要选择启用：
```
export DATAFOG_TELEMETRY=1
```
要强制关闭 Telemetry：
```
export DATAFOG_NO_TELEMETRY=1
# 或
export DO_NOT_TRACK=1
```
Telemetry 不包含输入文本或检测到的 PII 值。
## 开发
```
git clone https://github.com/datafog/datafog-python
cd datafog-python
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[all,dev]"
pip install -r requirements-dev.txt
pytest tests/
```
标签：DLL 劫持, PII检测, Python SDK, 大语言模型, 数据脱敏, 文档结构分析, 网络安全, 逆向工具, 隐私保护