releaseguard

ReleaseGuard

安装 • 快速入门 • CLI 参考 • 库 API • 比较 • 常见问题

使用 Presidio 扫描数据集或模型目录中的个人身份信息（PII）和机密信息，对发现的内容进行脱敏，并通过一条命令生成公开发布包、Hugging Face 数据集／模型卡，以及符合《欧盟 AI 法案》第 53(1)(d) 条要求的训练数据摘要。

ReleaseGuard 不是 PII 检测器。它连接了“我有一个想要发布的数据集”和“我有一个已脱敏且相关文档已起草好的数据包”。检测完全由 Presidio 完成；这是一个积极维护的开源项目，在 GitHub 上拥有 10,000 多颗星。ReleaseGuard 将 Presidio 的扫描结果直接用于脱敏，并生成几乎所有公开数据集／模型发布实际需要的两份文档，无需你自己编写脚本。

安装

pip install releaseguard-cli
python -m spacy download en_core_web_sm   # Presidio's default NLP model (~13 MB, one-time)

# npm launcher (thin wrapper around the PyPI package, see "Why two registries" in FAQ)
npx releaseguard-cli --help

en_core_web_sm 是 spaCy 的小型英语模型，也是 Presidio 自带快速入门示例的默认模型。若要提高检测准确率，请改为安装较大的模型，并传入 --spacy-model：

python -m spacy download en_core_web_lg   # ~400 MB, Presidio's recommendation for production
releaseguard scan ./data --spacy-model en_core_web_lg

快速入门

以下是针对包含两行数据的示例 CSV 进行的真实、未经修改的运行结果，并非模拟内容：

$ releaseguard scan dataset --score-threshold 0.4
Scanned 1 file(s) under dataset
Total findings: 7

entity type                 count
URL                         3
PERSON                      2
EMAIL_ADDRESS               2

这行 URL: 3 是 Presidio 一个值得说明而非掩盖的真实特性：它基于正则表达式的 URL 识别器也会匹配电子邮件地址中的域名部分（[email protected] 中的 example.com），因此包含大量电子邮件地址的文本会同时被计为 EMAIL_ADDRESS 和 URL。这是 Presidio 自带识别器的行为，未作修改。还需注意，由于检测基于 NLP，而不是固定的查找表，不同 Presidio／spaCy 版本的实体计数可能略有变化（本次运行使用了 presidio-analyzer 2.2.364 和 en_core_web_sm 3.8.0）。如果你只关心电子邮件地址，可以使用 --entities 将其筛除：

releaseguard scan dataset --entities EMAIL_ADDRESS,PERSON,PHONE_NUMBER

通过一条命令先脱敏，再打包发布内容：

$ releaseguard package dataset --output bundle --score-threshold 0.4
Release bundle written to bundle
  dataset card: bundle/README-dataset-card.md
  EU AI Act Art. 53(1)(d) summary: bundle/eu-ai-act-training-summary.md
  redacted source: bundle-redacted-source

bundle/eu-ai-act-training-summary.md 的开头如下：其中填入了真实扫描计数，其余内容则保留为明确的占位项，供人工填写：

# Training Data Summary (EU AI Act Art. 53(1)(d))

_Draft generated by ReleaseGuard... Based on the European Commission's
training-data-summary template, published 2025-07-24. This covers the
narrow, currently-binding categorical-summary requirement only -- it is
not a claim of full training-data disclosure._

## 4. Personal Data and PII Handling (from ReleaseGuard scan)

A Presidio-backed scan (detector: `presidio`) covered 1 file(s) under `dataset`.

| PII/secret category detected | Occurrences |
| --- | --- |
| `EMAIL_ADDRESS` | 2 |
| `PERSON` | 2 |
| `URL` | 3 |

每个命令都可以使用 --json 切换为机器可读输出，供脚本和 Agent 使用。

快速概览

• 适用场景： 通过一条命令将 Presidio 扫描结果转化为脱敏副本、数据集／模型卡，以及符合《欧盟 AI 法案》第 53(1)(d) 条要求的训练数据摘要，无需使用三个独立工具和手动编写模板
• 不是什么： 它本身不是 PII 检测器，也不声称实现“完全透明”／完全符合训练数据披露要求。请参阅ReleaseGuard 不是什么
• 完全在本地运行。 数据集内容、扫描结果或脱敏输出都不会发送到远程服务。

CLI 参考

$ releaseguard --help
Usage: releaseguard [OPTIONS] COMMAND [ARGS]...

  Scan, redact, and package a dataset/model directory for public release.

  ReleaseGuard is a packaging layer on top of Presidio (originally a Microsoft
  project, now maintained by data-privacy-stack) -- it does not detect PII
  independently of Presidio. See the README's "What ReleaseGuard is not"
  section.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  mcp      Start an MCP server exposing scan/redact/package as agent tools.
  package  Scan PATH, optionally redact it, and generate a release bundle...
  redact   Scan PATH and write a redacted copy to --output.
  scan     Scan PATH (a file or directory) for PII and secrets using...

命令	用途
scan PATH	使用 Presidio 扫描文件或目录（CSV、JSON/JSONL、纯文本）。--entities、--score-threshold、--spacy-model、--json。
redact PATH --output DIR	扫描后，将脱敏副本写入 DIR。绝不修改 PATH。--strategy mask|hash|remove、--overwrite。
package PATH --output DIR	扫描（默认先脱敏），然后将 Hugging Face 数据集/模型卡以及《欧盟 AI 法案》第 53(1)(d) 条摘要写入 DIR。--kind dataset|model|both、--redact-first/--no-redact-first。
mcp	启动一个 MCP 服务（stdio），提供 scan_directory_tool、redact_directory_tool、package_release_tool。需要在 Python 3.10+ 上运行 pip install "releaseguard-cli[mcp]"。

每个命令都支持 --json。完整标志参考：releaseguard <command> --help。

库 API

from releaseguard.detectors import get_detector
from releaseguard.scanner import scan_directory
from releaseguard.redactor import redact_directory
from releaseguard.packager import build_release_bundle
from releaseguard.types import RedactionStrategy

detector = get_detector("presidio", score_threshold=0.4)
scan_result = scan_directory("dataset/", detector)

redaction_result = redact_directory(
    scan_result, "dataset-redacted/", strategy=RedactionStrategy.MASK
)

bundle = build_release_bundle(
    scan_result, "bundle/", redaction_result=redaction_result, source_kind="dataset"
)
print(bundle.eu_ai_act_summary_path)

PIIDetector（releaseguard.detectors.base）和 FileReader（releaseguard.readers.base）是两个扩展点。目前随附的检测器只有 Presidio；随附的读取器有三种：CSV、JSON/JSONL 和纯文本。两者都使用注册表，而非硬编码调用，专门为将来以较小范围添加新格式或第二种检测后端预留空间。请参阅 CONTRIBUTING.md。

MCP 服务

ReleaseGuard 随附一个 Model Context Protocol 服务，AI Agent（Claude、Cursor 或任何兼容 MCP 的客户端）无需人工手动调用 CLI，即可直接扫描、脱敏并打包数据集或 模型目录。

安装额外依赖：

pip install "releaseguard-cli[mcp]"

使用 mcp 子命令直接启动：

releaseguard mcp

将其添加到 MCP 客户端的配置中（对于 Claude Desktop，使用 claude_desktop_config.json）。服务 通过已发布的 releaseguard 控制台脚本的子命令启动，而非使用单独的 控制台脚本：

{
  "mcpServers": {
    "releaseguard": {
      "command": "uvx",
      "args": ["--from", "releaseguard-cli", "releaseguard", "mcp"]
    }
  }
}

传输方式为 stdio，因此无需托管：MCP 客户端会将服务作为本地子进程启动。源码：src/releaseguard/mcp_server.py。

该服务提供三个工具，每个工具都返回与对应 CLI --json 输出相同的 JSON 结构：

工具	用途
scan_directory_tool(path, spacy_model=None, score_threshold=0.35)	使用 Presidio 扫描目录中的 PII 和机密信息。
redact_directory_tool(path, output, strategy="mask", overwrite=False)	扫描后，将脱敏副本写入 output。绝不修改 path。strategy 可以是 "mask"、"hash" 或 "remove"。
package_release_tool(path, output, kind="dataset", redact_first=True, strategy="mask")	扫描并可选择进行脱敏，然后将发布包（数据集/模型卡以及《欧盟 AI 法案》第 53(1)(d) 条摘要）写入 output。

一个实际调用示例：

scan_directory_tool(path="./dataset", score_threshold=0.4)
-> {"files_scanned": 1, "root_path": "./dataset", "findings": [...], "entity_counts": {"URL": 3, "PERSON": 2, "EMAIL_ADDRESS": 2}}

每个工具都会先检查 path 是否存在，然后才执行其他操作；如果不存在，就会返回结构化错误 {"error": "Path '<path>' does not exist.", "error_type": "PathNotFound"}，而不是给出无声且误导性的“已扫描 0 个文件”成功结果。该服务的早期版本会跳过此检查，导致无效路径直接传入 scan_directory，后者返回虚假的成功结果而非错误；现在，每个工具处理程序也都经过包装，意外异常会以 {"error": ..., "error_type": ...} 的形式返回，而不会导致服务崩溃。仓库根目录附带了 .well-known/agent.json 清单，用于 A2A 风格的发现，列出了 CLI 和 MCP 接口，以及提供这些接口的软件包。

对比

	ReleaseGuard	Presidio	huggingface_hub 卡片工具	pii-lib
检测 PII/密钥	否，封装了 Presidio	是（这是它的专职工作）	否	是（正则表达式 + NER，针对代码训练数据）
对检测到的实体进行脱敏	是（通过 presidio-anonymizer）	是（库级别）	否	是
生成 Hugging Face 数据集/模型卡片	是，基于实际扫描结果	否	是（手动填写字段，不集成扫描）	否
生成《欧盟 AI 法案》第 53(1)(d) 条摘要	是，基于实际扫描结果	否	否	否
一条命令完成从扫描到发布包的全流程	是	否（仅提供库，你需要自行编写衔接代码）	否（仅提供库）	否
GitHub 星标数（截至 2026-08）	2026 年新项目	约 10,300	约 3,800	16

星标数于 2026-08-03 通过 GitHub API 实时核查：data-privacy-stack/presidio（原为 microsoft/presidio；项目迁移到了其他组织，代码库不变）、huggingface/huggingface_hub、bigcode-project/pii-lib。pii-lib 的低星标数本身就很能说明问题：它是此前最接近的一次尝试，旨在针对训练数据发布工作流进行 PII 脱敏，但并未获得显著采用。ReleaseGuard 并不假设自己会有不同的结果；请参阅 FAQ 中关于需求的条目。

企业数据治理平台（Databricks Unity Catalog、Credo AI、BigID 等）已将 PII 分类和脱敏纳入面向大型组织的综合付费平台。ReleaseGuard 是一个免费、用途单一的开源替代方案，适合只想为一次发布完成扫描、脱敏和打包工作流，而不需要治理套件的团队。

什么是 ReleaseGuard，它为何存在

ReleaseGuard 是一个开源 CLI、Python 库和 MCP 服务，可将三个步骤串联成一条命令：PII/密钥检测（通过 Presidio）、脱敏和公开发布文档生成。每个步骤原本都已有独立工具：Presidio 负责检测，presidio-anonymizer 负责脱敏，huggingface_hub 提供卡片生成辅助工具，欧洲委员会则发布了一份需要手动填写的训练数据摘要模板。在 ReleaseGuard 之前，没有工具能将实际扫描直接串联到已填写的模板中。

它之所以存在，是因为要负责任地发布数据集或模型，需要先运行 PII 扫描、对扫描结果进行脱敏，然后几乎完全手动编写两份文档：卡片，以及（针对通用 AI 模型提供方的）《欧盟 AI 法案》训练数据摘要。ReleaseGuard 自动化了该工作流的后半部分，让生成的文档反映实际扫描的内容，而不是某人事后记得写下的内容。

《欧盟 AI 法案》第 53(1)(d) 条的准确说明：该条要求通用人工智能（GPAI）模型提供方发布一份关于训练内容的“足够详细的摘要”，并使用欧洲委员会 AI 办公室于 2025-07-24 发布的模板（对 2025-08-02 起推出的新模型生效；已上市模型的过渡期限为 2027-08-02；AI 办公室从 2026-08-02 起开始进行合规检查）。该条要求提供数据来源和模态的分类摘要，不要求公开原始训练样本、完整训练方案或模型权重，且具体适用于 GPAI 模型提供方，而不是所有数据集发布者。ReleaseGuard 生成的摘要是针对这项具体要求的初稿，绝不代表对更广泛的“全面透明度”要求的合规声明。

ReleaseGuard 不是什么

• 不是 PII 检测器。 所有实体类型、置信度分数和检测决策都来自 Presidio。ReleaseGuard 不添加 NLP 模型或识别器，也不对准确性做任何承诺。如果 Presidio 漏掉了某些内容或过度计数（参见上文 Quickstart 中的 URL/电子邮件重叠），ReleaseGuard 会原样继承这种行为。
• 不是托管服务。 所有操作都在本地运行。扫描目标、扫描结果或脱敏输出都不会传输到任何地方。请参阅 SECURITY.md 中的范围部分。
• 不能证明符合法规。 生成的《欧盟 AI 法案》摘要只是草稿，仍需要人工填写 ReleaseGuard 无法通过扫描推断出的许可、数据来源和版权部分。运行 releaseguard package 本身并不能满足第 53(1)(d) 条或任何其他法规的要求。
• 不能证明存在超出上述引用内容的需求。 最接近的同类工作流先例 pii-lib 在 GitHub 上只有 16 个星标。ReleaseGuard 并未声称解决了该项目遇到的采用难题；它声称填补了一个真实、范围明确且经过独立验证的空白（目前没有现成的开源工具能将 Presidio 扫描直接接入第 53(1)(d) 条模板），其余则交由实际使用来验证。

常见问题

ReleaseGuard 检测个人身份信息是否比 Presidio 更准确？ 不能，因为它每次做出检测判断时都会调用 Presidio 自己的 AnalyzerEngine。任何准确性问题都应归结为 Presidio 的问题；请参阅 Presidio 自己的文档 和 presidio-research，了解其评估方法。

为什么 scan 需要下载 spaCy 模型？ Presidio 的 AnalyzerEngine 需要 spaCy 语言模型来进行上下文感知检测（根据周围文本识别出“John Smith”是一个名字，而不只是一个首字母大写的词）。spaCy 模型以独立的可安装软件包形式发布，而不是作为 pip 依赖，因此 python -m spacy download en_core_web_sm 是必需的一次性步骤，任何直接使用 Presidio 的人都需要执行这一步。

ReleaseGuard 能在 Windows、macOS 和 Linux 上运行吗？ 它是纯 Python 实现，没有特定于操作系统的代码路径；npm 启动器填充程序会根据平台选择 where 或 which，以定位已安装的 CLI（npm-shim/bin/releaseguard-cli.js）。目前 CI 仅在 ubuntu-latest 上运行，覆盖 Python 3.10 和 3.12，因此 macOS 和 Windows 尚未纳入自动化测试矩阵。在测试矩阵扩展之前，应将它们视为预期可运行，但未经 CI 验证。

欧盟《人工智能法案》第 53(1)(d) 条摘要单独来看在法律上是否足够？ 不够。这是一份结构正确的初稿，其中 ReleaseGuard 能够验证的部分（个人身份信息／机密信息部分）填入了真实扫描数据，而它无法验证的部分（数据来源、许可、版权状态）则明确标注为占位内容。发布为合规材料之前，必须由人工（最好经过法律审查）填写这些占位内容。

这只适用于训练通用人工智能（GPAI）模型的情况吗？ 第 53(1)(d) 条摘要专门面向欧盟《人工智能法案》下的通用人工智能模型提供者，适用对象范围较窄。无论第 53(1)(d) 条是否适用于你，ReleaseGuard 的 scan、redact 和 Hugging Face 卡片生成部分都适用于任何数据集或模型发布。

为什么使用两个注册表？ ReleaseGuard 使用 Python 实现，因为 Presidio 本身就是 Python 实现（presidio-analyzer/presidio-anonymizer）；用另一种语言封装它，就意味着要再次调用 Shell 或重新实现绑定。npm 软件包（releaseguard-cli）只是一个轻量启动器，而非重新实现。它会定位并执行从 PyPI 安装的真正 releaseguard 二进制文件，因此面向 npm 的 Agent 工具可以使用 npx releaseguard-cli，而无需用两种语言重复实现 Presidio 的检测逻辑。

ReleaseGuard 使用什么许可证？我可以将它用于商业用途吗？ Apache 2.0，与 Presidio 使用的许可证相同。它允许商业使用、修改和再分发，包括用于专有产品，但须遵守 Apache 2.0 的标准条款：保留许可证和版权声明，并注明对源代码所做的任何更改。完整文本请参阅 许可证。

真的有人需要这个吗？还是说它只是“没人要求的胶水代码”？ 坦率地说，截至本项目的初期调研，尚未出现自然需求信号（即 HN／Reddit 上有人描述这一确切工作流是亲身经历的痛点）。可独立验证、也更站得住脚的事实范围较窄：目前没有现有的开源工具能够通过一条命令、基于一次扫描，将 Presidio 扫描结果直接串接到第 53(1)(d) 条模板，或生成包含二者的 HF 卡片。这个缺口是否会转化为真实使用需求，仍是一个开放且可证伪的问题；本项目会持续跟踪，而非预设答案。

ReleaseGuard 无法解析的文件（图片、模型权重文件、缺少额外组件的 Parquet 文件）会怎样处理？ scan 和 redact 会跳过这些文件（在 --json 输出中的 files_skipped 项下列出）；redact 会将它们原样复制到输出目录，而不是悄悄将它们从发布包中丢弃。这些文件不会接受个人身份信息扫描，因此发布前请单独检查。

Contributing

See CONTRIBUTING.md. Security issues: see SECURITY.md.

License

Apache 2.0