astrlink-pii-tracer-int4

<!-- markdownlint-configure-file { "MD013": { "tables": false } } -->

AstrLink PII-Tracer 0.6B INT4

面向本地隐私检测的 ONNX 模型，由 QuantumNous / AstrLink 基于 Perplexity PII-Tracer 转换和校准。用于识别文本、代码片段、配置与日志中的个人信息及凭据，供应用进行脱敏处理。

约 450 MiB；INT4 骨干权重 + FP16 低秩误差补偿；分类头保留 FP32。 模型可以公开下载，无需逐用户申请访问。下载后可在本地运行，推理无需访问模型托管服务。

English summary: A local ONNX privacy span detector derived from Perplexity PII-Tracer, with INT4 backbone weights, rank-64 FP16 residual corrections, and FP32 classification heads. The package is approximately 450 MiB. Its small synthetic regression evaluation covers English, Chinese, and code/configuration examples; it does not establish production accuracy or broad multilingual coverage. Full span extraction requires the PII-Tracer BIOES/Viterbi decoder.

模型概览

名称中的 0.6B 指基座规模。误差补偿额外引入约 40.37M 个以 FP16 保存的参数。完整模型包含多种精度，量化配置和文件校验值见 quantization.json。

来源与转换方法

本次转换使用的 FP32 导出固定为：

lemonade-sdk/pplx-pii-masking-onnx
5ba4e413b78ff0f83d3c9cddee1bb5fdccbeee00

处理步骤：

1. 使用对称 RTN 权重量化，位宽为 4，分组大小为 32。196 个骨干线性投影转换为 MatMulNBits，词嵌入转换为 GatherBlockQuantized。
2. 保留 token 分类头和辅助敏感度分类头的 FP32 权重。
3. 使用 FP32 模型的激活，估计量化误差对输出的影响，为骨干线性投影加入 rank-64 低秩残差补偿。补偿矩阵以 FP16 保存，以 FP32 参与计算。
4. MatMulNBits 的 accuracy_level=4，偏好 INT8 点积内核；图的激活张量接口仍为 FP32。

校准语料由 24 条独立生成的中英文、代码和隐私示例组成，每条最多取 128 tokens，共 3072 tokens。本次转换没有使用用户请求日志，也没有进行带标签的监督微调。基座模型的训练数据与训练方法请参阅上游模型说明。

校准与回归评估使用不同样例。校准语料标识为 synthetic-code-and-privacy-v1，其 SHA-256、随机种子及工具版本均记录在 quantization.json 中。

构建工具版本为 ONNX Runtime 1.23.2、ONNX 1.19.1、NumPy 2.4.6、Tokenizers 0.23.1 和 PyTorch 2.8.0。使用 AstrLink 原生 worker 推理时不需要安装 Python 或 PyTorch。

检测标签

输出标签 ID 0 为 O。随后按上表实体顺序，每类依次分配 B、I、E、S 四个标签，共 37 个标签。config.json 中骨干自带的通用 id2label 不是这套实体标签表。

other_pii 默认忽略意味着该类不会出现在 AstrLink 的默认脱敏结果中。需要覆盖该类时，应明确选择应用中的映射和处理策略。

使用方式

在 AstrLink 中使用

在支持此版本的 AstrLink 中，进入安全策略的模型页面，选择 AstrLink PII-Tracer 0.6B INT4 / CPU INT4，完成安装和标签映射后启用。也可以下载本仓库的文件，通过“本地导入”选择模型目录。

仓库根目录中的 astrlink-model.json 描述安装及推理参数。安装器会生成包含文件校验值和标签映射的本地运行清单，原生 worker 使用该运行清单启动。

通过 Python 检查 ONNX 输出

下面的示例下载固定版本并运行原始输出，便于集成到自己的检测流程。公开下载不需要 Hugging Face Token。

python -m pip install "onnxruntime==1.23.2" "tokenizers==0.23.1" numpy huggingface_hub

from pathlib import Path

import numpy as np
import onnxruntime as ort
from huggingface_hub import snapshot_download
from tokenizers import Tokenizer

model_dir = Path(
    snapshot_download(
        repo_id="QuantumNous/astrlink-pii-tracer-int4",
        revision="0f9a56fc32062ea5827f4d908e7afaa22b88c902",
        token=False,
    )
)

tokenizer = Tokenizer.from_file(str(model_dir / "tokenizer.json"))
tokenizer.no_truncation()
tokenizer.no_padding()

text = 'SMTP_USER="[email protected]"'
encoding = tokenizer.encode(text)
if len(encoding.ids) > 1024:
    raise ValueError("For longer inputs, use overlapping windows before decoding.")

input_ids = np.asarray([encoding.ids], dtype=np.int64)
options = ort.SessionOptions()
options.intra_op_num_threads = 2
options.inter_op_num_threads = 1
session = ort.InferenceSession(
    str(model_dir / "model_int4.onnx"),
    sess_options=options,
    providers=["CPUExecutionProvider"],
)
logits, sensitivity_logits = session.run(
    ["logits", "sensitivity_logits"],
    {
        "input_ids": input_ids,
        "attention_mask": np.ones_like(input_ids),
    },
)
print(logits.shape)  # (1, token_count, 37)
print(sensitivity_logits.shape)  # (1,)

model_int4.onnx 和 model_int4.onnx.data 必须位于同一个目录。本包通过 ONNX Runtime 加载；config.json 保留了上游架构信息，其中的 dtype 和 auto_map 不代表本包提供对应的 Transformers 权重或 Python 模型代码。

从 logits 得到隐私片段

输入 input_ids 和 attention_mask 均为形状 [batch, sequence] 的 INT64 张量。 logits 为 [batch, sequence, 37] 的 FP32 张量；辅助输出 sensitivity_logits 为 [batch]。

完整集成需要：

• 按上述标签顺序执行有合法 BIOES 转移约束的 Viterbi 解码。当前 viterbi_b_bias 和 viterbi_e_bias 均为 0。
• 对长文本使用重叠窗口，并在统一 token 序列上合并输出、解码。AstrLink 使用原始 logits，不会在窗口合并前将其替换为 softmax 概率。
• 用 tokenizer 的偏移将 token 片段映射回原文。AstrLink 返回 UTF-8 字节偏移；Python 字符索引与 UTF-8 字节索引在中文等文本上不同，需要显式转换。
• 按 sigmoid(mean(selected raw logits)) 计算片段分数。分数不是已经验证的真实正确概率；应用仍需结合标签、上下文和自身阈值处理。

当前 AstrLink 检测流程不使用 sensitivity_logits 跳过整段文本的实体检测。默认窗口为 1024 tokens、重叠 128 tokens；安装描述中的 131072 tokens 是分块处理的请求总预算，不是单个注意力窗口的上下文长度。

回归评估

结果来自 AstrLink 原生 worker。FP32 与 INT4 使用相同的解码和边界规范化逻辑。

边界规范化包括代码引号、完整邮箱、电话数字及受约束的赋值语句边界修复。下表描述包含这些后处理的完整检测流程。

评估集包含 62 条合成样例：36 条不含待脱敏信息的样例，以及 26 条含待脱敏信息的样例，共标注 31 个目标片段。

“严格匹配”要求类别、起始字节位置和结束字节位置全部一致。两版正常样例的误报数量相同，但发生误报的样例并不完全相同。INT4 在一条含邮箱的 YAML 样例中额外将普通重试次数误标为日期。

这是开发回归集，不是独立的生产准确率评测。量化方案曾根据回归结果调整；新增的 32 条样例也用于开发验证，不构成最终封存的盲测集。零漏检只描述这批有限样例，不能推导出其他代码、语言或真实请求中的零漏检。详见 validation.json。

资源与性能

本模型包约 450 MiB，相比所用 FP32 ONNX 包约 2.24 GiB，下载体积减少约 80%。下载体积与运行内存是不同指标。

在 macOS arm64 CPU、ONNX Runtime 1.23.2 上，使用 1024-token 窗口处理一条 4914-token 合成长代码样例，记录到约 26.7 秒、约 1.43 GiB 峰值 RSS，正确识别了末尾的一个邮箱，无额外误报。

这些数字来自单机测量。62 条短样例的批次耗时包含启动成本，已观察到约 6.1–13.9 秒的运行波动，未据此给出稳定的加速倍率。 validation.json 中的长文本 FP32 对照使用 4096-token 窗口，因此两者的长文本耗时和内存差异同时受到窗口大小与量化影响。其他硬件、操作系统及执行提供程序的性能尚未系统评估。

使用范围与限制

适合在本地处理包含文字、源代码、配置和日志的隐私候选片段，并由上层应用决定脱敏、拦截或人工复核。模型本身输出分类分数，不会修改原始文本。

• 版本号、校验和、占位符及普通配置数字等内容仍可能被误报。
• 量化和补偿会改变预测与分数，不能假定与 FP32 逐项一致。
• 当前验证主要覆盖中英文合成样例；没有全面验证所有语言、实体类别和生产场景。
• 1024-token 窗口降低了单窗上下文，依赖更远上下文的判断可能受影响。
• 默认忽略 other_pii；标签表不意味着所有类别都有同等可靠的识别能力。
• 处理自己的数据时应评估误报和漏检，不能把模型输出当作无敏感信息的证明。

文件与版本

经过下载、安装及原生推理验证的权重发布版本：

0f9a56fc32062ea5827f4d908e7afaa22b88c902

该版本固定模型文件；后续 model card 的文字更新不会改变其权重校验值。

许可证与致谢

本模型包使用 MIT 许可证，保留 Perplexity AI, Inc. 的版权声明。

感谢 Perplexity AI 提供 PII-Tracer 基座，以及 Lemonade SDK 提供 FP32 ONNX 导出。本仓库的量化、校准及 AstrLink 集成由 QuantumNous / AstrLink 完成。