企业官网建设流程全解析

读懂OpenAI Privacy Filter的输出：typed与redacted模式及JSON Schema完整解析

【免费下载链接】privacy-filterOpenAI Privacy Filter项目地址: https://gitcode.com/gh_mirrors/pr/privacy-filter

OpenAI Privacy Filter 是一个可在本地运行的 PII（个人敏感信息）检测与掩码模型，它通过typed与redacted两种输出模式，把检测结果以结构化的 JSON Schema 呈现给你。这篇教程带你逐字段读懂这份 JSON 输出，并讲清 typed、redacted、untyped 三个易混概念该怎么选。

一、30秒速览：Privacy Filter 到底能做什么

🧩OpenAI Privacy Filter（OPF）是一个双向 token 分类模型，一次前向推理就能为整段文本标注敏感区域，共识别 8 类隐私标签：

它只有 1.5B 参数（激活 50M），支持 128K 上下文，适合在笔记本甚至浏览器里跑。完整背景见 README.md。

二、输出模式怎么选：typed vs redacted 一图看懂

运行opf做一次性脱敏时，核心开关是--output-mode（定义见 opf/_cli/common.py）：

• typed（默认）：保留模型预测的具体子类别，比如private_person、private_date。
• redacted：把所有预测跨度折叠成一个通用redacted标签，占位符统一为<REDACTED>（常量定义在 opf/_common/constants.py）。

⚠️ 注意术语区分（官方说明在 EVAL_AND_OUTPUT_MODES.md）：

• typed/untyped是评估（eval）术语；
• typed/redacted是预测输出（redact）术语。

三、JSON Schema 逐字段解析：redact 输出长什么样

执行下面命令即可得到一份完整 JSON（每条输入输出一份，打印到 stdout）：

opf "Alice was born on 1990-01-02."

典型typed输出如下：

{ "schema_version": 1, "summary": { "output_mode": "typed", "span_count": 3, "by_label": { "private_person": 1, "private_date": 2 }, "decoded_mismatch": false }, "text": "Alice was born on 1990-01-02.", "detected_spans": [ { "label": "private_person", "start": 0, "end": 5, "text": "Alice", "placeholder": "<PRIVATE_PERSON>" } ], "redacted_text": "<PRIVATE_PERSON> was born on <PRIVATE_DATE>." }

1.schema_version：版本锚点

当前值为1。官方承诺现有键保持稳定，除非schema_version升级——所以程序化消费该 JSON 时，先看版本号再解析是最稳妥的做法（稳定性条款见 OUTPUT_SCHEMAS.md）。

2.summary：一眼概览

• output_mode：本次使用的模式（typed或redacted）；
• span_count：检测到的敏感跨度总数；
• by_label：按类别统计的数量，如private_date: 2；
• decoded_mismatch：词元往返解码是否与原文完全一致，true时输出会附带warning。

3.detected_spans：敏感跨度明细（核心字段）

每个跨度包含 5 个字段：

📌redacted模式下，label统一是redacted，占位符统一是<REDACTED>，方便下游只关心"哪里被掩掉了"而不暴露类别信息。

4.redacted_text与可选warning

redacted_text是用占位符替换后的最终脱敏文本，可直接入库或转发。warning字段仅在tokenizer 解码结果与输入不严格一致时出现，用于提醒你对齐偏移量。

四、评估模式怎么选：typed 与 untyped 的决策流程

当你有标注数据、要用opf eval跑指标时（参数定义见 opf/_eval/args.py）：

1. 标注体系 = OPF 官方 8 类→ 用--eval-mode typed（默认），得到类别级指标，可加--per-class看分类别表现；
2. 标注体系是自己的命名（如given name、street address） → 用--eval-mode untyped，忽略类别身份、只评"敏感区域有没有被找到"，并额外给出ground_truth_label_recall——回答"每个原始标注的跨度文本被预测覆盖了多少"。

决策表（摘自 EVAL_AND_OUTPUT_MODES.md）：

五、eval 的输出文件：--predictions-outJSONL

用--predictions-out可把每条样例的预测落成 JSONL（一行一个紧凑 JSON 对象）：

{ "example_id": "stable-id", "text": "Alice was born on 1990-01-02.", "predicted_spans": { "private_person: Alice": [[0, 5]] } }

• 键格式为"类别: 文本": [[start, end], ...]，同一文本多次命中会列出多个区间；
• 只有传了--predictions-token-logprobs-topk > 0时才会多出token_logprobs_topk字段；
• 仓库自带样例数据集 examples/data/sample_eval_five_examples.jsonl 可直接试跑：opf eval examples/data/sample_eval_five_examples.jsonl。

六、快速上手：三步拿到你的第一份 JSON

1. 安装（本地包安装即可使用opf命令）：

pip install -e .

2. 跑一条脱敏（首次运行会自动下载 checkpoint 到~/.opf/privacy_filter）：

opf "Alice was born on 1990-01-02."

3. 切换 redacted 模式（或整文件脱敏）：

opf --output-mode redacted -f /path/to/file

💡 Python 侧等价入口在 opf/_api.py 的OPF(output_mode="redacted")构造函数中，redact()返回的RedactionResult序列化后与 CLI 打印的 JSON 完全同构；终端彩色高亮预览逻辑则位于 opf/_cli/render.py。

七、小结与最佳实践

• 审计与治理场景用typed，保留类别便于统计合规；交付干净文本用redacted，不泄露类别细节。
• 消费 JSON 时先校验schema_version，再依赖detected_spans的偏移与占位符。
• 自定义标注体系别硬套typed，走untyped+ground_truth_label_recall更客观。
• 模型默认标签策略是静态的，政策不符时用opf train微调（指南见 FINETUNING.md），Privacy Filter 是隐私设计的辅助层，而非完整的匿名化保证。

【免费下载链接】privacy-filterOpenAI Privacy Filter项目地址: https://gitcode.com/gh_mirrors/pr/privacy-filter