Privacy Filter SDK

English · 简体中文

基于 openai/privacy-filter 和 Transformers.js 的浏览器端 TypeScript SDK，用于本地 PII 检测。

这是一个社区 SDK，并非 OpenAI 官方 npm 包。

功能特性

• 在浏览器中加载 openai/privacy-filter。
• 可使用 WebGPU，并在不可用时回退到 WASM。
• 提供适合 UI 集成的实例 API。
• 提供便捷的单例 API。
• 返回稳定的 PrivacySpan[]，而不是直接暴露原始模型输出。
• 提供纯函数形式的脱敏工具。
• 不包含 UI、OCR、canvas 或 DOM 遮罩逻辑。

安装

pnpm add privacy-filter

实例 API

import { createPrivacyFilter, redactText } from "privacy-filter";

const detector = createPrivacyFilter({
  model: "openai/privacy-filter",
  dtype: "q4",
  device: "auto",
  remoteHost: "/hf/"
});

await detector.load({
  onProgress(event) {
    console.log(event.status, event.file, event.progress);
  }
});

const result = await detector.detect("Alice wrote to [email protected]");
const redacted = redactText(result.text, result.spans);

// 人工审查模型输出时，可以降低阈值。
const reviewResult = await detector.detect("Alice wrote to [email protected]", {
  minScore: 0
});

单例 API

import { detectPrivacy, loadPrivacyFilter, redactPrivacyText } from "privacy-filter";

await loadPrivacyFilter();
const result = await detectPrivacy("Alice wrote to [email protected]");
const redacted = await redactPrivacyText("Alice wrote to [email protected]");

检测结果

detect() 返回原始输入文本和规范化后的 spans：

type PrivacyDetectionResult = {
  text: string;
  spans: PrivacySpan[];
  model: string;
  device: "webgpu" | "wasm";
};

type PrivacySpan = {
  label: string;
  score: number;
  text: string;
  start: number;
  end: number;
};

text 始终保留调用方传入的原始字符串，包括首尾空白。start 和 end 是 text 中的 JavaScript 字符串 offset。

默认情况下，detect() 会应用 0.5 的保守分数阈值，让自动脱敏避开低置信度 span。可以通过 minScore 调整该行为：

await detector.detect(text); // 使用默认保守阈值。
await detector.detect(text, { minScore: 0 }); // 返回所有规范化 span。
await detector.detect(text, { minScore: 0.75 }); // 使用更严格的阈值。

redactText() 只脱敏传入的 spans。它不会重新执行分数过滤，也不会修复无效 offset。

错误处理

SDK 可控的失败会使用带稳定 code 的 PrivacyFilterError：

import { detectPrivacy, isPrivacyFilterError } from "privacy-filter";

try {
  const result = await detectPrivacy(text);
  console.log(result.spans);
} catch (error) {
  if (isPrivacyFilterError(error)) {
    switch (error.code) {
      case "invalid_input":
      case "load_failed":
      case "detection_failed":
      case "unsupported_environment":
        console.error(error.code, error.message);
        break;
    }
  }
}

请基于 error.code 分支处理，不要解析错误消息文本。

浏览器要求

该包面向浏览器使用。Chrome 和 Edge 可在可用时使用 WebGPU，其他现代浏览器会使用 WASM。需要 SharedArrayBuffer 支持的托管环境应为页面提供以下响应头：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

SDK 会在浏览器本地执行推理。npm 包不包含模型文件；浏览器首次加载时会从 Hugging Face 或你配置的 remoteHost 下载模型，后续加载使用已配置的浏览器/WASM 缓存。模型文件可能较大，实际加载时间取决于 dtype 和网络状况。

0.x 版本属于早期 API；升级 minor 版本前应查看 release notes。

示例页面

运行 Vite 示例页面：

pnpm example:dev

然后打开 Vite URL 并访问 /examples/。该页面直接从 src/index.ts 导入，并使用真实模型运行时，首次手动加载会下载模型文件。

Playground 支持选择 Auto、WebGPU 或 WASM、调整最低置信度、在上下文中检查高亮 span，以及复制脱敏结果。切换运行设备后需要重新加载模型。

开发

pnpm install
pnpm test
pnpm check
pnpm build
pnpm example:build

单元测试会 mock Transformers runtime，不会下载模型文件。真实模型下载 smoke test 需要手动执行。

许可证

SDK 源码采用 MIT License。单独下载的 openai/privacy-filter 模型采用 Apache-2.0，并继续受其自身模型条款约束。