nationaldesignstudio/rampart · Hugging Face

来源：https://huggingface.co/nationaldesignstudio/rampart rampart是一个14.7 MB的ONNX令牌分类模型，用于在文本离开用户设备之前检测其中包含的个人身份信息（PII）。它是Rampart（由National Design Studio发布的深度防御客户端脱敏系统）的本地端组件。发布的产物与确定性识别层协同运行，后者处理结构化标识符；两者共同构成完整系统。

本文档仅记录已发布的产物。模型选择过程中探索的其他配置（ELECTRA-small基础模型、关闭预过滤的训练变体、精简数据混合以及较小的语料切片）将在项目白皮书中进行背景说明，但未公开发布。

https://huggingface.co/nationaldesignstudio/rampart#model-summary模型摘要

属性值模型IDnationaldesignstudio/rampart架构nreimers/MiniLM-L6-H384-uncased (https://huggingface.co/nreimers/MiniLM-L6-H384-uncased)微调后带有35标签BIO头（17种实体类型）参数量≈18.5M（MiniLM-L6-H384使用精简后的19,730词片词汇表；完整的30,522词片BERT词汇表对应22.7M基础参数量）量化4-bit MatMul + INT8嵌入（onnx/model_q4.onnx）发布产物大小14.7 MB词汇表19,730个WordPiece（从BERT-uncased的30,522词片中精简，保留所有特殊字符和单字符词片，以及高频多字符词片）最大序列长度512个令牌支持语言英语、西班牙语、法语、德语、意大利语、葡萄牙语、荷兰语（均为拉丁字母）运行环境通过transformers.js使用ONNX Runtime Web（WASM/WebGPU）许可协议CC BY 4.0（Creative Commons Attribution 4.0 International）训练数据许可协议CC BY 4.0（ai4privacy/pii-masking-openpii-1.5m (https://huggingface.co/datasets/ai4privacy/pii-masking-openpii-1.5m)）发布方National Design Studio卡片版本1.0（初始公开发布）

https://huggingface.co/nationaldesignstudio/rampart#intended-use预期用途

该模型专为AI助手和输入流程中用户输入文本的客户端脱敏而设计——在任何数据传输给模型提供商、服务器或日志系统之前，将识别信息替换为稳定的占位符。

https://huggingface.co/nationaldesignstudio/rampart#direct-uses直接用途

• 在将用户内容传递给托管LLM之前进行脱敏。
• 在多轮对话中维持稳定的占位符（[GIVEN_NAME_1]、[SSN_1]等），并在客户端进行还原。
• 预防分析、跟踪和崩溃报告中意外收集个人数据。
• 在受监管环境中部署聊天系统前，验证特定领域的脱敏策略。

https://huggingface.co/nationaldesignstudio/rampart#out-of-scope不涵盖范围

• **独立政府ID检测。**该模型是深度防御系统的一个层次，不能替代与其一同发布的确定性识别层。社保号和支付卡由确定性层通过校验和验证（结构规则和Luhn算法）捕获，召回率高于仅使用模型。电话号码、路由号码、政府ID、护照和驾照号码不包含校验和，因此由模型捕获；确定性层不尝试检测这些信息。
• 间接/推断性标识符。“罕见疾病 + 5位邮编”组合可以重新识别个人，即使这两个令牌都不在脱敏集合中。模型不检测推断性泄露。
• **对抗鲁棒性作为安全保证。**我们公布关于恶意输入的数据并记录失败面；该系统的定位是为善意输入自己信息的用户减少伤害，而非针对恶意攻击者的安全边界。
• **非拉丁字母。**本版本仅限于上述七种拉丁字母语言。韩语、汉语、日语、阿拉伯语、西里尔字母和天城体文字的名称总体召回率约为14%（见下文“公平性与局限性”）。对于经常输入非拉丁字母名称的用户群体，在未采取补偿控制措施前，请勿部署此版本；请相应进行监控。

https://huggingface.co/nationaldesignstudio/rampart#usage使用方法

运行时以@nationaldesignstudio/rampart (https://www.npmjs.com/package/@nationaldesignstudio/rampart) 形式发布。createGuard()返回一个ChatGuard，它会加载此分类器并运行完整的确定性+模型流水线：

`` import { createGuard } from “@nationaldesignstudio/rampart”;

const guard = await createGuard(); const { text } = await guard.protect(“My name is Alex Rivera and my SSN is 472-81-0094.”); // → “My name is [GIVEN_NAME_1] [SURNAME_1] and my SSN is [SSN_1].” ``

https://huggingface.co/nationaldesignstudio/rampart#training-data训练数据

已发布模型基于累积的三源混合数据按以下顺序添加训练；选择矩阵发现，将三个来源合并后产生了所有最高召回率的配置，其中语料的广度比任何单一来源的数量更重要。

来源使用的行数许可协议角色合成对话语料（内部）约250,000次对话CC BY 4.0主要内部语料。生成故意杂乱且真实的聊天风格消息：低努力/易错文本、语音输入措辞、从表单中粘贴的值、多语言混合、矛盾/重复/字段错误的条目，涵盖多种助手角色——使模型学会在混乱的聊天中捕获碎片化PII，而不仅仅是整洁的散文。覆盖所有17种实体类型。OCR文档语料（内部）内部，跨度标注CC BY 4.0对扫描和拍摄的表单、身份证件和文档进行OCR处理，然后用17种实体类型进行跨度标注。增加了对话源中不存在的OCR噪声（字符混淆、断行换行、杂散字形）和表单式字段布局，强化了对从文档中提取的值的召回率。ai4privacy/pii-masking-openpii-1.5m (https://huggingface.co/datasets/ai4privacy/pii-masking-openpii-1.5m)完整语料：约1.4M训练 + 100,000保留CC BY 4.0公开AI4Privacy模板语料库，完整使用——其train和validation分割合并，按uid去重，用固定种子打乱，然后分割为除100k之外的所有行用于训练（约1.4M行）和100k保留集。未应用训练上限或语言筛选；这是完整的去重语料，而非子采样切片。7种拉丁字母语言（en, es, fr, de, it, pt, nl）的多语言熵；OpenPII模式映射到我们的35标签BIO模式（17种实体类型）。同时也是下面保留评估分割的来源。 合成语料和OCR语料提供了OpenPII所缺乏的杂乱、文档噪声输入（其对话是整洁且格式良好的）；OpenPII提供了多语言广度和保留测试集。具体的合成/OCR混合量和规模由端到端选择矩阵决定，而非假设——参见项目白皮书（§3.1、§3.5、§4.2）了解确定配方的消融实验。

保留的100,000行（来自AI4Privacy语料）被分割成两个不重叠的子集，并使用固定种子以实现完全可复现：

• 10,000行用于召回率下限的阈值调整。
• 30,000行用于下面的主要测试结果（评估表中每种语言的行数）。

其余60,000行保留用于未来评估，不在此版本中使用。

https://huggingface.co/nationaldesignstudio/rampart#pre-processing预处理

所有训练行都经过运行时在分词前应用的相同标准化：小写、NFKD分解和组合字符标记剥离。组合字符步骤将重音折叠——José变为jose，Müller变为muller——因此无论用户如何输入名称，模型看到的都是同一个规范形式。这与BERT的BasicTokenizer在推理时在do_lower_case=True下隐式执行的操作一致，因此训练时和运行时的分布通过构造保持一致。训练流水线中的守卫将在未来分词器更改破坏此假设时导致运行失败。

省略此标准化步骤的重新训练者将产生分布不匹配的模型，召回率数字将无法复现。

确定性层拥有的结构化类别（SSN、CREDIT_CARD、IP_ADDRESS）在分词之前也被掩盖为哨兵令牌——在推理时（src/premask.ts）和数据集构建期间均如此——因此模型从未学习对原始卡号/SSN/IP数字进行分类，并且训练时和推理时的输入通过构造保持一致。

https://huggingface.co/nationaldesignstudio/rampart#vocabulary词汇表

完整的BERT-uncased词汇表包含30,522个WordPiece。已发布的词汇表保留：

1. 所有特殊令牌（[PAD]、[UNK]、[CLS]、[SEP]、[MASK]）。
2. 所有单字符词片及其##延续，这保留了WordPiece对罕见名称的字符级回退机制。
3. 所有多字符词片中在训练语料中出现频率高于阈值的部分。

已发布的词汇表为19,730个词片。

https://huggingface.co/nationaldesignstudio/rampart#training-procedure训练过程

超参数值基础模型nreimers/MiniLM-L6-H384-uncasedEpochs3批大小32学习率5e-5权重衰减0.01最大序列长度512优化器AdamW评估策略在保留验证集上每个epoch保存策略每个epoch硬件Apple M系列MPs总运行时间约3.5小时 最终epoch是根据保留评估损失选择的。

https://huggingface.co/nationaldesignstudio/rampart#label-taxonomy标签分类

模型输出35个BIO标签（17种实体类型×{B-, I-} + O）；确定性识别层贡献了另外三个结构化类别，这些类别在模型运行前被掩盖。运行时应用默认拒绝策略：除非标签明确位于保留集合中，否则每个检测到的跨度都将被脱敏。

https://huggingface.co/nationaldesignstudio/rampart#redacted-by-default默认脱敏

由确定性识别层拥有（正则表达式+验证器，在模型前掩盖）：

标签描述SSN美国社会安全号码——结构验证CREDIT_CARD支付卡号码——Luhn验证EMAIL电子邮件地址URL用户内容中的URLIP_ADDRESSIPv4 / IPv6 / MAC地址 由令牌分类模型输出：

标签描述GIVEN_NAME名字/名SURNAME姓氏PHONE电话号码TAX_ID税务标识符BANK_ACCOUNT银行账户/IBAN号码ROUTING_NUMBER银行路由号码GOVERNMENT_ID政府颁发的ID/案件编号PASSPORT护照号码DRIVERS_LICENSE驾照号码BUILDING_NUMBER街道建筑编号STREET_NAME街道名称SECONDARY_ADDRESS次要地址行（公寓/单元/套房） BUILDING_NUMBER + STREET_NAME共同构成精确的街道行；两者均被脱敏，而城市/州/邮政编码则保留。

https://huggingface.co/nationaldesignstudio/rampart#kept-by-default默认保留

标签描述CITY城市——用于资格检查的粗略地理信息STATE州/地区ZIP_CODE邮政编码 保留集合保留粗略地理信息（城市/州/邮政编码），同时脱敏精确的街道行。要更改此设置，请编辑src/types.ts中的KEEP_LABELS——它是一个编译时集合，而非运行时标志。

分类刻意采用原子化方式：没有粗略的PERSON、STREET_ADDRESS、ADDRESS、ORGANIZATION或LOCATION标签，也没有万能SECRET标签。姓名拆分为GIVEN_NAME/SURNAME，街道行拆分为BUILDING_NUMBER/STREET_NAME，文档标识符拆分为特定类别，因此模型学会在杂乱文本中捕获PII碎片，而非期待一个整洁的块。日期、年龄和收入有意不被建模为PII（它们映射为O）：单纯的日期很少具有标识性，而且助手需要年龄和收入作为上下文，因此脱敏它们属于过度脱敏且无隐私增益。

https://huggingface.co/nationaldesignstudio/rampart#evaluation评估

我们对完整系统（模型+确定性层）进行评分，因为这是消费者端到端体验的。单独报告模型数字，供希望单独评估编码器的研究人员使用。

https://huggingface.co/nationaldesignstudio/rampart#primary-metrics主要指标

• 私有项召回率：对于每个黄金标准私有值，脱敏后的输出是否包含该值？这是隐私方面的关键指标；遗漏即泄露。
• 公共项保留率：对于每个黄金标准公共值，脱敏后的输出是否保留了该值？这衡量过度脱敏。
• 跨度F1严格（IoU=1.0）和宽松（IoU≥0.5）：在一对一贪婪匹配下，预测跨度边界与黄金边界的一致程度。
• 延迟：Node.js ONNX运行时在完整30,000行测试集上的冷启动/p50/p95/p99。浏览器延迟（WebGPU和WASM后端）由eval/bench/webgpu.ts单独测量——见下文。
• 校准：15箱可靠性ECE，按标签和整体，基于每跨度最大类别分数。

所有召回率和保留率均附有Wilson 95%置信区间；分层细分包括1000次迭代的自举区间。

https://huggingface.co/nationaldesignstudio/rampart#held-out-openpii-test-set–seven-supported-languages-30000-rows-131707-private-terms-87207-public-terms保留OpenPII测试集——七种支持语言（30,000行；131,707个私有项；87,207个公共项）

主要数字涵盖所有七种支持的拉丁字母语言。仅英语、仅西班牙语以及英语+西班牙语切片作为子集报告。

切片私有召回率（Wilson 95%）公共保留率*跨度F1严格延迟p50**所有七种语言****98.42% [98.35, 98.49]**91.69%0.5286.6 ms仅英语（11,569行）98.85%90.5%—6.6 ms仅西班牙语（3,234行）98.84%91.6%—6.6 ms英语+西班牙语98.85%91.0%—6.6 ms 在七种语言测试中，131,707个私有项中有2,082个泄露（每64个项中有1个漏过系统，在应用程序的下游防御机制触发之前）。在英语+西班牙语切片上，系统在67,613个项中泄露778个。

这些数字由已提交的eval/bench测试工具测量，该工具在pii-masking-openpii-1.5m的固定保留切片上端到端运行已发布的Q4流水线。相对于本卡片早期版本，测试工具已进行修正：城市/州/邮政编码现在按保留评分（与运行时保留集合匹配），而不是计为泄露，因此公共保留率直接反映策略感知行为。召回率针对完整且更具挑战性的七种语言切片报告。跨度F1严格（精确字节+标签匹配）为次要指标；项存在召回率为隐私关键指标。

上述6.6 ms p50是在30k保留集上的Node ONNX（CPU）数值。在浏览器中运行相同的已发布流水线（使用eval/bench/webgpu.ts），在WebGPU上测得3.9 ms p50（Apple Metal，p95 9.3 ms），在WASM上测得12.6 ms（p95 35.5 ms）——因此对于同类输入，WebGPU形态比Node CPU更快，而WASM是在没有GPU可用时的最低性能。

* 见下方“模式协调”——Rampart策略脱敏精确街道行（BUILDING_NUMBER + STREET_NAME）和次要地址行，同时保留城市/州/邮政编码，测试工具现予以遵循。

https://huggingface.co/nationaldesignstudio/rampart#per-language-slices-openpii-latin-test-30k-rows-across-7-languages每种语言切片（OpenPII拉丁测试，7种语言共30k行）

语言行数私有召回率公共保留率泄露/总计英语