OneAIFW：保护大模型数据隐私的轻量级开源防火墙

OneAIFW（aifw）是由Funstory.ai开发的一款旨在解决大语言模型（LLM）数据隐私问题的开源工具。在当前的大模型应用中，用户经常需要将包含个人身份信息（PII）或商业机密的文本发送给云端模型（如ChatGPT、Claude等）进行处理，这带来了巨大的隐私泄露风险。OneAIFW 遵循“第一性原则”解决此问题：数据在离开用户控制环境前必须是安全的。它作为一个中间层“防火墙”，在本地（或受控服务器）拦截对LLM的请求。

该工具的核心工作机制非常直观：“屏蔽（Mask）”与“还原（Restore）”。在请求发送给外部LLM之前，OneAIFW会自动识别并替换文本中的敏感信息（如姓名、电话、邮箱等）为匿名占位符；当LLM返回结果后，它再将这些占位符精准还原为原始数据。这一过程对LLM服务商是透明的，服务商只能看到脱敏后的数据，从而从源头上杜绝了敏感数据外泄。OneAIFW 采用高性能的 Zig 和 Rust 编写核心引擎，支持 WebAssembly（WASM），这意味着它既可以在服务器端高效运行，也可以直接在用户的浏览器中离线运行，实现真正的端侧零信任隐私保护。

功能列表

• 双向隐私管道：提供 mask（屏蔽）和 restore（还原）两个核心接口。发送前将敏感实体替换为通用标签（如 <PERSON>），接收后将标签还原为原始内容。
• 高精度PII识别：内置混合识别引擎，结合了高性能的正则表达式（基于Rust regex）和命名实体识别（NER）模型，能够精准捕获人名、地名、联系方式等敏感信息。
• 多语言与跨平台支持：
  • Core：核心库由 Zig 和 Rust 编写，极度轻量且高性能。
  • Python绑定：提供 aifw-py，兼容 HuggingFace transformers 生态，适合后端服务集成。
  • JavaScript/WASM绑定：提供 aifw-js，结合 transformers.js，支持在浏览器端直接运行完整的脱敏流程，无需后端服务器。
• 灵活的部署方式：支持作为独立的 HTTP 服务（基于 FastAPI/Presidio）运行，或作为库集成到现有代码中，甚至以浏览器插件形式工作。
• 自定义配置：支持通过 YAML 配置文件自定义屏蔽规则、忽略列表和使用的底层检测模型。
• 零痕迹处理：所有处理均在内存中完成，不持久化存储任何用户数据，确保“阅后即焚”。

使用帮助

OneAIFW 的设计理念是“轻量”与“可移植”。为了让您能够顺利在生产环境或本地开发中使用该工具，以下将详细介绍从环境准备、编译安装到实际代码调用的完整流程。

一、 环境准备与安装

由于 OneAIFW 的核心使用 Zig 语言编写并集成了 Rust 组件，您需要准备相应的编译工具链。

1. 安装基础工具链

在开始之前，请确保您的系统中安装了以下工具：

• Zig 编译器：版本需为 0.15.2。您可以从 Zig 官网下载并添加到系统环境变量 PATH 中。验证命令：zig version。
• Rust 工具链：建议安装 stable 版本。如果您需要编译 WASM 版本，还需添加 target。
  • 安装 Rust：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • 添加 WASM 支持：rustup target add wasm32-unknown-unknown
• Node.js & pnpm（仅 JS 开发需要）：Node.js 18+ 以及 pnpm 9+。
• Python（仅 Python 开发需要）：Python 3.10+。

2. 获取源码与编译核心库

首先从 GitHub 克隆仓库：

git clone https://github.com/funstory-ai/aifw.git
cd aifw

使用 Zig 构建核心库（包含 Native 和 WASM 产物）：

# 在项目根目录下执行
zig build
# 如果需要运行单元测试以确保环境正常
zig build -Doptimize=Debug test

该步骤会生成底层的 aifw 静态库和动态库，供上层语言调用。

二、 Python 环境下的使用（后端集成）

如果您是 Python 开发者，希望在您的 AI 应用后端集成隐私防火墙，请按照以下步骤操作。

1. 安装依赖
进入 Python 绑定目录并安装依赖：

cd libs/aifw-py
# 建议创建虚拟环境
python -m venv .venv
source .venv/bin/activate
pip install -e .

2. 核心代码调用示例
以下代码展示了如何加载防火墙并对一段包含敏感信息的文本进行“脱敏”和“还原”。

from aifw import AIFirewall
# 初始化防火墙，加载默认配置
fw = AIFirewall()
# 模拟用户输入的敏感文本
user_prompt = "请帮我联系张三，他的电话是 13800138000，我们要讨论关于 ProjectX 的秘密。"
# 步骤1：屏蔽（Mask）
# firewall 会自动识别 PII 并替换，同时返回一个 session 对象用于后续还原
masked_text, session_id = fw.mask(user_prompt)
print(f"发送给LLM的文本: {masked_text}")
# 输出示例: "请帮我联系<PERSON_1>，他的电话是<PHONE_NUMBER_1>，我们要讨论关于<ORG_1>的秘密。"
# 注意：此时真实数据从未离开本地内存
# ... 模拟将 masked_text 发送给 LLM，并获取回复 ...
# 假设 LLM 回复了包含占位符的内容：
llm_response = "好的，我已经记下了<PERSON_1>的电话<PHONE_NUMBER_1>，关于<ORG_1>的事项会保密。"
# 步骤2：还原（Restore）
# 使用之前的 session_id 将占位符还原为真实信息
final_response = fw.restore(llm_response, session_id)
print(f"展示给用户的文本: {final_response}")
# 输出: "好的，我已经记下了张三的电话 13800138000，关于 ProjectX 的事项会保密。"

三、 JavaScript/浏览器环境下的使用（前端集成）

OneAIFW 的强大之处在于可以直接在浏览器中运行，无需向任何服务器发送数据即可完成脱敏。

1. 编译 JS SDK

# 安装依赖
pnpm -w install
# 构建 JS 库（会自动处理 WASM 和 模型文件）
pnpm -w --filter @oneaifw/aifw-js build

2. 前端调用示例
在您的 Web 项目中（如 React 或 Vue），引入 aifw-js。

import { AIFirewall } from '@oneaifw/aifw-js';
async function protectData() {
// 初始化防火墙（会自动加载 WASM 和 浏览器端的小型 NER 模型）
const firewall = await AIFirewall.create();
const text = "我的邮箱是 alice@example.com";
// 1. Mask
const result = await firewall.mask(text);
console.log(result.masked); // 输出: "我的邮箱是 <EMAIL_1>"
// 模拟 AI 处理过程...
const aiOutput = `已向 <EMAIL_1> 发送邮件`;
// 2. Restore
const final = await firewall.restore(aiOutput, result.session);
console.log(final); // 输出: "已向 alice@example.com 发送邮件"
}

四、 运行 Web Demo

官方提供了一个直观的 Web 演示应用，您可以直接运行体验：

cd apps/webapp
pnpm dev

打开浏览器访问控制台输出的本地地址（通常是 http://localhost:5173）。在这个界面中，您可以在左侧输入框输入任意包含敏感信息的文本，点击处理，直观地看到：

1. PII 分析结果：识别到了哪些实体。
2. Masked Prompt：真正发送出去的文本长什么样。
3. Restored Response：最终还原后的样子。

五、 高级配置

您可以通过修改 aifw.yaml 或设置环境变量来调整行为：

• AIFW_MODELS_DIR: 指定 NER 模型存放路径。
• AIFW_API_KEY_FILE: 如果使用其内置的 LLM 转发服务，配置 API Key。
• 自定义 Regex：在源码的配置部分，您可以添加特定的正则表达式来识别特定的机密格式（如公司内部的项目代号格式）。

通过以上步骤，您可以将 OneAIFW 集成到任何现代 AI 应用栈中，实现“数据可用但不可见”的高级隐私保护。

应用场景

1. 企业内部知识库问答
   企业员工在使用基于公有云 LLM 的知识库助手时，往往涉及客户名单或财务数据。部署 OneAIFW 后，员工提问中的敏感实体在发送给 GPT-4 等模型前会被自动替换，确保企业核心数据不流出内网，同时不影响模型回答逻辑。
2. GDPR/CCPA 合规开发
   面向欧美市场的 AI 应用必须严格遵守数据隐私法规。开发者可以使用 OneAIFW 自动过滤用户输入的 PII（个人身份信息），无需针对每个输入手动编写复杂的清洗规则，快速满足法律合规要求。
3. 浏览器端隐私插件
   开发浏览器扩展，在用户使用网页版 ChatGPT 或 Claude 时，自动拦截请求框内容，进行本地脱敏后再填充回网页。这样用户即使使用官方网页版服务，也能确保个人隐私安全。
4. 医疗与法律文档辅助
   在处理病历或法律合同时，文档中包含大量极度敏感的姓名和身份证号。使用 OneAIFW 可以在保持文档结构和上下文完整的前提下，让 AI 协助润色或总结文档，而无需担心患者或客户隐私泄露给模型服务商。

QA

1. OneAIFW 会降低 AI 响应速度吗？
   OneAIFW 经过高度优化，核心层使用 Zig/Rust 编写，处理速度极快（微秒级）。主要的延迟通常来自于 NER 模型的推理，但在使用轻量级模型（如 neurobert-mini）时，这种延迟通常在毫秒级，相比 LLM 的网络请求和生成时间，几乎可以忽略不计。
2. 它支持哪些类型的敏感信息识别？
   默认支持常见的 PII 类型，包括人名、地名、组织机构名（通过 NER 模型识别），以及邮箱、电话号码、身份证号、信用卡号（通过 Regex 识别）。用户也可以自定义正则表达式来扩展识别类型。
3. 如果 LLM 的回复中没有包含占位符怎么办？
   如果 LLM 在生成内容时丢失了占位符（例如 <PERSON_1>），还原步骤将无法找回对应的原始信息。不过，OneAIFW 在设计 Prompt 时会优化提示词，引导 LLM 保持占位符不变。在大多数问答和摘要场景下，LLM 能够很好地保留这些标记。
4. 数据会在 OneAIFW 的服务器上保存吗？
   不会。OneAIFW 是一个纯粹的工具库或本地服务，Funstory.ai 不运营中心化的拦截服务器。所有数据处理都在您部署的服务器内存或用户的浏览器内存中完成，进程结束后数据即销毁。