BoranT-3000/turkish-pii-detection-openai-privacy-filter

# 使用 OpenAI Privacy Filter 进行土耳其语 PII 检测 本仓库记录了一个基于 **OpenAI Privacy Filter** 的端到端土耳其语 PII 检测项目。 该项目通过创建大型合成土耳其语隐私 NER 数据集，使用针对土耳其语的特定隐私标签微调模型，并在留出的合成测试集上评估生成的 checkpoint，从而将最初面向英语的隐私过滤模型适配到土耳其语。 作者：**Boran Toktay** ## 项目概述 个人身份信息 (PII) 检测是隐私保护 AI 系统中一项重要的 NLP 任务，尤其是在日志、客户支持消息、表单、教育记录、医疗类文档、索引 pipeline 和模型训练数据中。 原始的 [`openai/privacy-filter`](https://huggingface.co/openai/privacy-filter) 模型旨在检测和编辑文本中涉及隐私的片段。然而，土耳其语包含一些特定于语言的挑战，例如后缀、本地标识符、土耳其语地址格式、类似 TCKN 的数字、类似 VKN 的数字、土耳其语电话号码格式以及 IBAN 变体。 本项目使用自定义的合成数据集和针对土耳其语的特定隐私标签空间，对 OpenAI Privacy Filter 进行了微调，以实现土耳其语 PII 检测。 ## Hugging Face 资源 | 资源 | 链接 | |---|---| | 数据集 | [`BTX24/turkish-privacy-pii-ner`](https://huggingface.co/datasets/BTX24/turkish-privacy-pii-ner) | | 微调模型 | [`BTX24/turkish-privacy-filter-pii`](https://huggingface.co/BTX24/turkish-privacy-filter-pii) | | 基础模型 | [`openai/privacy-filter`](https://huggingface.co/openai/privacy-filter) | | 基础 GitHub 仓库 | [`openai/privacy-filter`](https://github.com/openai/privacy-filter) | ## 主要贡献 本项目包括： - 包含 **103,923 行 JSONL 数据**的完全合成的土耳其语隐私 NER 数据集 - 针对土耳其语的特定隐私标签空间 - 基于 Colab 的 OpenAI Privacy Filter 微调工作流 - 微调后的土耳其语 Privacy Filter checkpoint - 在留出的合成土耳其语测试集上的评估结果 - 数据集准备、模型训练、推理和局限性的文档说明 ## 仓库结构 推荐的结构： ``` turkish-pii-detection-openai-privacy-filter/ ├── README.md ├── LICENSE ├── privacy_filter_tr_pii_colab.ipynb ├── configs/ │ └── label_space.json ├── reports/ │ └── Turkish_Privacy_Filter_Final_Report_English_Boran_Toktay.docx ``` 完整的数据集和模型权重托管在 Hugging Face 上，并未直接包含在此 GitHub 仓库中。 ## 数据集 本项目使用的数据集可在以下地址获取： ``` https://huggingface.co/datasets/BTX24/turkish-privacy-pii-ner ``` ### 数据集摘要 | 指标 | 值 | |---|---:| | 总 JSONL 行数 | 103,923 | | 标签类别 | 10 | | 训练样本 | 83,138 | | 验证样本 | 10,392 | | 测试样本 | 10,393 | | 总字符数 | 7,404,532 | | 平均文本长度 | 71.3 字符 | | 平均实体长度 | 19.2 字符 | | 数据集类型 | 合成的土耳其语隐私 NER | | 标注类型 | 字符级 span | 该数据集完全是合成的。未刻意收集或使用任何真实的个人数据。 ## 标签空间 最终的土耳其语隐私标签空间为： ``` { "category_version": "tr_privacy_v1", "span_class_names": [ "O", "tckn", "secret", "iban", "vkn", "account_number", "private_address", "private_date", "private_phone", "private_email", "private_person" ] } ``` ### 标签描述 | 标签 | 描述 | |---|---| | `O` | 外部 / 非 PII token | | `tckn` | 合成的类似土耳其语国民身份标识的值 | | `secret` | 合成的密码、OTP、类似 API-key 的字符串、访问令牌、恢复码 | | `iban` | 合成的类似土耳其语的 IBAN 值 | | `vkn` | 合成的类似土耳其语税务识别码的值 | | `account_number` | 账号、客户编号、参考代码、会员 ID、订单/工单参考号 | | `private_address` | 合成的土耳其语风格的地址表达 | | `private_date` | 涉及隐私的日期表达 | | `private_phone` | 类似土耳其语手机号码的合成电话号码 | | `private_email` | 合成的、不可路由的电子邮件地址 | | `private_person` | 合成的土耳其语风格的人名 | ## 数据集格式 该数据集采用 JSONL 格式，并带有字符级 span 标注。 示例： ``` { "text": "Ahmet Yılmaz için telefon numarası 0532 000 00 00 olarak kaydedildi.", "spans": { "private_person: Ahmet Yılmaz": [[0, 12]], "private_phone: 0532 000 00 00": [[35, 49]] }, "info": { "id": "synthetic_tr_000001", "source": "synthetic_tr" } } ``` 字符偏移量使用 Python 的切片语义： ``` text[start:end] ``` `end` 索引是排他的（不包含该索引对应的字符）。 ## 模型 微调后的模型可在以下地址获取： ``` https://huggingface.co/BTX24/turkish-privacy-filter-pii ``` 它基于： ``` openai/privacy-filter ``` 该模型使用自定义的土耳其语隐私标签空间，在土耳其语合成隐私 NER 数据集上进行了微调。 ## 训练摘要 | 指标 | 值 | |---|---:| | 基础模型 | `openai/privacy-filter` | | 微调模型 | `BTX24/turkish-privacy-filter-pii` | | 数据集 | `BTX24/turkish-privacy-pii-ner` | | 最佳 epoch | 3 | | 最佳指标 | `validation_loss` | | 最佳验证损失 | 0.002157915852249276 | | 训练样本 | 83,138 | | 验证样本 | 10,392 | | 设备 | Google Colab Pro GPU 环境 | ### Epoch 指标 | Epoch | 训练损失 | 训练 Token 准确率 | 验证损失 | 验证 Token 准确率 | |---:|---:|---:|---:|---:| | 1 | 0.038908 | 0.990768 | 0.003961 | 0.999100 | | 2 | 0.002714 | 0.999463 | 0.002181 | 0.999583 | | 3 | 0.001393 | 0.999704 | 0.002158 | 0.999641 | 基于验证损失，在第 3 个 epoch 选择了最佳 checkpoint。 ## 测试评估 评估在留出的合成土耳其语测试集上进行。 | 指标 | 值 | |---|---:| | 测试样本 | 10,393 | | 测试 token | 241,020 | | 评估模式 | typed | | 损失 | 0.0028 | | Token 准确率 | 0.9996 | | 推理 token/秒 | 3027.20 | ### 检测指标 | 指标 | 值 | |---|---:| | 检测精确率 | 0.9998 | | 检测召回率 | 0.9996 | | 检测 F1 分数 | 0.9997 | | 检测 F2 分数 | 0.9996 | | Span 精确率 | 0.9988 | | Span 召回率 | 0.9978 | | Span F1 分数 | 0.9983 | | Span F2 分数 | 0.9980 | ### 各类别 Span 指标 | 标签 | 精确率 | 召回率 | F1 分数 | F2 分数 | |---|---:|---:|---:|---:| | `tckn` | 1.0000 | 0.9990 | 0.9995 | 0.9992 | | `secret` | 0.9990 | 1.0000 | 0.9995 | 0.9998 | | `iban` | 1.0000 | 1.0000 | 1.0000 | 1.0000 | | `vkn` | 0.9990 | 0.9990 | 0.9990 | 0.9990 | | `account_number` | 1.0000 | 0.9992 | 0.9996 | 0.9993 | | `private_address` | 0.9980 | 0.9940 | 0.9960 | 0.9948 | | `private_date` | 1.0000 | 1.0000 | 1.0000 | 1.0000 | | `private_phone` | 0.9991 | 1.0000 | 0.9995 | 0.9998 | | `private_email` | 1.0000 | 0.9902 | 0.9951 | 0.9922 | | `private_person` | 0.9928 | 0.9959 | 0.9943 | 0.9953 | 这些结果是在合成的测试集上测量的。实际场景下的性能可能有所不同。 ## Colab Notebook 主要的训练 notebook 是： ``` notebooks/privacy_filter_tr_pii_colab.ipynb ``` 该 notebook 涵盖： - 安装 OpenAI Privacy Filter - 下载 OPF 原生基础 checkpoint - 创建 `label_space.json` - 加载并验证土耳其语隐私数据集 - 将 span 标注转换为 OPF 兼容格式 - 运行微调 - 运行评估 - 在土耳其语示例上测试推理 - 将微调后的 checkpoint 上传到 Hugging Face - 从 Hugging Face 验证已上传的模型 ## 重要实现说明 在开发过程中，解决了几个实际的工程问题： ### JSONL 换行符问题 JSONL 写入函数最初写入记录时没有换行符，导致： ``` JSONDecodeError: Extra data ``` 修复方法是确保每个 JSON 对象单独写入一行： ``` f.write(json.dumps(row, ensure_ascii=False) + "\n") ``` ### OPF checkpoint 路径问题 OPF 训练命令期望在 `openai/privacy-filter` 的 `original/` 目录下找到 OPF 原生 checkpoint，而不仅仅是根目录下的 Transformers 风格 checkpoint。 正确的 checkpoint 加载模式： ``` from huggingface_hub import snapshot_download snapshot_download( repo_id="openai/privacy-filter", repo_type="model", local_dir=str(BASE_SNAPSHOT_DIR), allow_patterns=["original/*"], ) ``` 然后使用： ``` --checkpoint path/to/base_openai_privacy_filter_snapshot/original ``` ### OPF JSON 输出解析问题 某些 OPF CLI 输出可能包含 JSON 以及随后的附加颜色图例文本。为避免 `JSONDecodeError`，请仅解析第一个 JSON 对象： ``` payload, end_idx = json.JSONDecoder().raw_decode(stdout.lstrip()) ``` ## 本地使用 ### 1. 安装 OpenAI Privacy Filter ``` git clone https://github.com/openai/privacy-filter.git cd privacy-filter pip install -e . ``` ### 2. 下载微调后的 checkpoint ``` python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='BTX24/turkish-privacy-filter-pii', local_dir='tr_privacy_filter_pii')" ``` ### 3. 运行推理 CUDA： ``` opf --checkpoint ./tr_privacy_filter_pii --device cuda --format json "Mehmet Kaya TCKN 12345678901" ``` CPU： ``` opf --checkpoint ./tr_privacy_filter_pii --device cpu --format json "Mehmet Kaya TCKN 12345678901" ``` 更多示例： ``` opf --checkpoint ./tr_privacy_filter_pii --device cuda --format json "Ahmet Yılmaz için telefon numarası 0532 000 00 00 olarak kaydedildi." ``` ``` opf --checkpoint ./tr_privacy_filter_pii --device cuda --format json "İade için IBAN TR00 0000 0000 0000 0000 0000 00 bilgisi girildi." ``` ``` opf --checkpoint ./tr_privacy_filter_pii --device cuda --format json "Doğrulama kodu OTP-482193 destek kaydına yazılmış." ``` ## Python 下载示例 ``` from huggingface_hub import snapshot_download checkpoint_dir = snapshot_download( repo_id="BTX24/turkish-privacy-filter-pii", local_dir="tr_privacy_filter_pii", ) print(checkpoint_dir) ``` ## 土耳其语测试文本示例 ``` Hasta Mehmet Kaya, 14.03.2025 tarihinde Ankara Çankaya'daki Atatürk Mahallesi No: 12 Daire: 5 adresinden başvuru yaptı. TCKN bilgisi 12345678901 olarak, VKN bilgisi ise 1234567890 olarak kaydedildi. Ödeme için verilen IBAN: TR330006100519786457841326. İletişim telefonu 0555 123 45 67. E-posta adresi mehmet.kaya@example.com. Sistem entegrasyonu için secret değeri sk-demo-1234567890abcdef olarak not edildi. ``` 预期行为： - 人名 → `private_person` - 日期 → `private_date` - 地址 → `private_address` - 类似 TCKN 的值 → `tckn` - 类似 VKN 的值 → `vkn` - 类似 IBAN 的值 → `iban` - 电话号码 → `private_phone` - 电子邮件 → `private_email` - 类似 Secret 的值 → `secret` ## 局限性 本项目使用合成数据。因此： - 模型可能会对合成模板产生过拟合。 - 真实的土耳其语文本可能包含更多噪声、更长或更模糊的表达。 - OCR 错误、非正式拼写、混合语言文本和特定领域的文档可能会降低性能。 - 模型可能会对数字或类似代码的字符串产生误报。 - 模型可能会遗漏合成数据集中未表示的罕见 PII 格式。 - 在生产环境使用之前，应基于真实的或人工策划的领域内测试集验证结果。 不应将此模型视为提供法律层面的匿名化保证。 ## 伦理考量 为了防止刻意收集或分发真实的个人信息，该数据集是合成生成的。 然而，基于合成数据训练的模型仍然可能犯错。对于敏感或生产环境的用例，此模型应作为更广泛的隐私保护 pipeline 的一个组成部分使用，并结合： - 人工审查 - 基于规则的检查 - 特定领域的验证 - 保守的脱敏策略 - 日志记录与监控 - 隐私保护设计 (Privacy-by-design) 安全防护措施 ## 项目交付成果 本项目包括： - 合成的土耳其语隐私 NER 数据集 - 微调的土耳其语 Privacy Filter 模型 - Colab 训练 notebook - 最终学术报告 - 数据集卡片 - 模型卡片 - 评估指标 - 推理工作流示例 ## 许可证 除非另有说明，本仓库的代码和文档基于 **Apache License 2.0** 发布。 相关资源： | 资源 | 许可证 | |---|---| | 项目代码 | Apache-2.0 | | 微调模型 | Apache-2.0 | | 训练数据集 | CC BY 4.0 | | 基础模型 | 参见 `openai/privacy-filter` 许可证 | 使用前，请查阅基础模型、数据集和微调 checkpoint 的许可证。 ## 引用 如果您使用了本项目或模型，请引用： ``` @model{toktay_2026_turkish_privacy_filter_pii, title = {Turkish Privacy Filter PII}, author = {Boran Toktay}, year = {2026}, publisher = {Hugging Face}, howpublished = {\url{https://huggingface.co/BTX24/turkish-privacy-filter-pii}}, note = {Fine-tuned OpenAI Privacy Filter checkpoint for Turkish PII span detection} } ``` 如果您使用了该数据集，请同时引用： ``` @dataset{toktay_2026_turkish_privacy_pii_ner, title = {Turkish Privacy PII NER Dataset}, author = {Boran Toktay}, year = {2026}, publisher = {Hugging Face}, howpublished = {\url{https://huggingface.co/datasets/BTX24/turkish-privacy-pii-ner}}, note = {Synthetic Turkish privacy-oriented named entity recognition dataset for PII detection} } ``` ## 致谢本项目基于以下内容构建： - [`openai/privacy-filter`](https://github.com/openai/privacy-filter) - [Hugging Face 上的 `openai/privacy-filter`](https://huggingface.co/openai/privacy-filter) - Hugging Face Hub 和 Datasets 工具 - 合成的土耳其语 PII 数据生成工作流 ## 联系方式 如有任何问题、建议或议题，请在此仓库中提一个 issue。

标签：IaC 扫描, NLP, PII检测, 命名实体识别, 土耳其语, 微调模型, 时序数据库, 网络安全, 逆向工具, 隐私保护