PromptMask：本地隐私层实现大模型敏感数据脱敏与安全调用-编程阁

1. 项目概述：当大模型需要处理你的秘密时

如果你和我一样，既想享受云端大模型（比如 GPT-4、Claude 3）的强大能力，又对把公司内部数据、客户个人信息、医疗记录或者一行核心代码直接丢给第三方 AI 服务商感到心里发毛，那你来对地方了。过去几年，我参与过不少需要处理敏感信息的项目，从医疗数据分析到金融风控，一个核心的痛点始终存在：如何在利用外部 AI 能力的同时，守住数据的最后一道防线？

这就是 PromptMask 要解决的问题。它不是一个全新的 AI 模型，而是一个本地优先的隐私层。你可以把它想象成一个智能的“数据脱敏员”，在你和云端大模型之间站岗。它的工作流程非常直观：在你发送请求之前，PromptMask 会先用一个你信任的（通常是本地的、能力较弱但可控的）小模型，自动识别出文本中的敏感信息，比如人名、身份证号、电话号码、内部项目代号等，并用无害的占位符（如${PERSON_NAME}）替换掉它们。然后，这份“脱敏”后的文本被发送给强大的云端大模型。等云端返回结果后，PromptMask 再根据本地的“替换字典”，把占位符精准地还原成原始数据。整个过程中，你的原始秘密从未离开过你的机器。

这个项目完美地回应了一个现实困境：云 AI 聪明但不可信，本地 AI 安全但能力有限。PromptMask 试图鱼与熊掌兼得，用本地小模型守护隐私，用云端大模型提供智能。它提供了多种集成方式，从给 Python 开发者准备的“一行代码替换” SDK，到为普通用户准备的本地 API 网关，甚至还有一个直观的 Web 界面。无论你是想快速保护现有基于 OpenAI API 的应用，还是想在自定义流程中精细控制脱敏逻辑，都能找到合适的入口。

2. 核心原理与架构设计：隐私保护的“双车道”模型

要理解 PromptMask 的价值，得先拆解它解决的核心矛盾。云端大模型服务商通常会声明他们对用户数据的使用政策，但作为用户，你实际上失去了对数据的绝对控制权。数据一旦发出，其存储、处理、是否用于模型训练，都取决于服务商的条款和他们的安全实践。而本地部署的大模型，虽然数据不出域，但受限于算力和模型规模，在复杂任务上的表现往往难以令人满意。

2.1 工作流拆解：一次请求的隐私之旅

PromptMask 的核心工作流可以概括为“先脱敏，后处理，再还原”。我们以一个具体的用户请求为例，来走完这个流程：

原始请求输入：用户发送“患者张三（病历号：P2024001）主诉持续性头痛，服用布洛芬后缓解不明显，请分析可能原因。”
本地隐私过滤（Masking）：PromptMask 调用你配置的本地小模型（例如通过 Ollama 运行的 Qwen2.5-7B），分析这段文本。模型会识别出“张三”和“P2024001”属于敏感的个人身份信息（PII）。
生成脱敏文本与映射表：系统将敏感词替换为预定义的占位符，例如“患者${PATIENT_NAME}（病历号：${MEDICAL_RECORD_ID}）主诉...”。同时，在内存中生成并保存一个映射表（Mask Map），它就像一把钥匙，记录着${PATIENT_NAME} -> 张三，${MEDICAL_RECORD_ID} -> P2024001的对应关系。这个映射表绝不会离开你的本地环境。
发送至云端大模型：脱敏后的文本被发送给 OpenAI、Anthropic 或你信任的任何云端 API。
接收并处理云端响应：云端模型返回分析结果，例如“${PATIENT_NAME}的头痛可能源于... 针对病历号${MEDICAL_RECORD_ID}的患者，建议...”。注意，响应文本中仍然包含占位符。
本地信息还原（Unmasking）：PromptMask 收到响应后，利用本地的映射表，将${PATIENT_NAME}和${MEDICAL_RECORD_ID}替换回原始的“张三”和“P2024001”，得到最终可读的结果返回给用户。

关键设计考量：为什么选择“本地小模型识别+映射表”的方案？而不是加密？早期我们考虑过对整段文本进行加密传输，但发现两个致命问题：第一，绝大多数云端大模型 API 不支持处理加密后的乱码文本；第二，即使支持，加密解密过程也破坏了文本的语义连贯性，可能影响模型的理解。而占位符替换方案，在去除敏感性的同时，最大程度保留了文本的语义结构和上下文，确保了云端模型能正确理解任务。

2.2 架构组件与选型逻辑

PromptMask 的架构清晰地区分了控制面和数据面：

控制面（配置与模型管理）：这是你与 PromptMask 交互的部分，包括配置文件（TOML）、环境变量和 Web UI。你需要在这里指定使用哪个本地模型进行脱敏（llm_api.model），定义什么是敏感信息（sensitive.include），以及占位符的格式（mask_wrapper）。它的设计哲学是“约定优于配置”，提供了合理的默认值，让你能快速上手，同时也允许深度定制。
数据面（核心处理引擎）：
- Masking Engine：负责与本地 LLM API 对话，发送精心设计的提示词（Prompt），引导模型识别并提取敏感实体。这里的提示词工程是关键，它需要明确告诉模型“找什么”和“怎么标记”。
- Unmasking Engine：一个轻量、确定性的字符串替换模块。它不依赖 AI，只依赖之前生成的映射表，因此速度极快且结果绝对可靠。
- API Gateway / SDK：这是面向应用的接口层。OpenAIMaskedSDK 通过猴子补丁（Monkey-patching）的方式，透明地拦截openai库的调用。API Gateway 则是一个独立的 HTTP 服务，将自己伪装成 OpenAI API，让任何兼容该协议的工具（如 Chatbot UI、自动化脚本）都能无缝接入。

本地模型选型的深层逻辑：你可能会问，这个本地模型需要多强？它不需要有 GPT-4 的推理能力，但必须在命名实体识别（NER）任务上足够可靠。经过我们的基准测试，参数量在 7B 到 14B 之间的模型，如 Qwen2.5-7B、Llama 3.1-8B、Gemma2-9B，在通用 PII 识别上已经能达到 95% 以上的准确率，并且可以在消费级 GPU 甚至高性能 CPU 上流畅运行。选择它们是在效果、速度和资源消耗之间取得的平衡。如果你的敏感信息类型非常特殊（如内部代码变量名），你可能需要通过微调（fine-tuning）或改进提示词来专门优化本地模型。

3. 实战部署与配置详解

理论讲完了，我们来动手把它跑起来。我会假设你是一个有一定技术背景的开发者或运维，从零开始部署一个可用的 PromptMask 环境。

3.1 基础环境搭建：本地模型服务

PromptMask 本身不包含模型，它需要一个已部署并提供 OpenAI 兼容 API 的本地模型服务。目前最省心的方案是Ollama。

安装 Ollama：前往官网下载并安装 Ollama。安装后，它会在后台运行一个服务。
拉取并运行模型：打开终端，运行以下命令拉取一个合适的模型。这里我推荐qwen2.5:7b，它在精度和速度上比较均衡。
```
ollama pull qwen2.5:7b ollama run qwen2.5:7b
```
默认情况下，Ollama 会在http://localhost:11434提供 API。你可以通过curl http://localhost:11434/api/generate -d '{"model": "qwen2.5:7b", "prompt":"hello"}'简单测试。
验证 OpenAI 兼容端点：PromptMask 需要的是 OpenAI 格式的 API。Ollama 从某个版本开始默认支持/v1端点。访问http://localhost:11434/v1/models，如果返回一个 JSON 格式的模型列表，说明配置正确。

踩坑记录：模型 API 端点不一致。除了 Ollama，llama.cpp、vLLM 等也提供 OpenAI 兼容 API，但它们的 URL 路径可能略有不同。例如，有些旧版 llama.cpp 的聊天补全端点是/v1/chat/completions，而模型列表在/v1/models。务必先用curl或浏览器测试一下/v1/models这个关键端点是否能正常返回，这是 PromptMask 自动检测可用模型的基础。

3.2 PromptMask 核心安装与配置

有了本地模型服务，现在安装 PromptMask。

安装核心包：如果你只需要 Python SDK，安装基础包即可。
```
pip install promptmask
```
如果你需要 Web UI 和 API 网关，安装全功能版本。
```
pip install "promptmask[web]"
```
理解配置优先级：这是避免后续混乱的关键。PromptMask 按以下顺序读取配置（后者覆盖前者）：
- 最低优先级：包内自带的default.toml。它定义了所有参数的默认值。
- 用户配置：在当前工作目录创建promptmask.config.user.toml文件。这是推荐的主要配置方式。
- 代码指定：在初始化PromptMask()或OpenAIMasked()时，通过config_file参数指定一个 TOML 文件路径，或直接用config参数传入一个字典。
- 环境变量：最高优先级。特别是LOCALAI_API_BASE和LOCALAI_API_KEY，用于动态覆盖本地模型的连接地址和密钥。
- 运行时字典：如果通过代码传入config字典，它的优先级最高。

创建你的配置文件：在你的项目根目录或你打算运行脚本的目录，新建一个promptmask.config.user.toml文件。下面是一个功能丰富的配置示例：

# promptmask.config.user.toml [llm_api] # 指定用于脱敏的本地模型。留空则自动使用 /v1/models 列表中的第一个。 # 对于 Ollama，就是 `ollama list` 显示的名字。 model = "qwen2.5:7b" # 本地模型服务的基地址。如果 Ollama 在另一台机器，改为其 IP。 base_url = "http://localhost:11434/v1" # 如果本地服务需要 API Key（如一些商业版），在这里设置。 api_key = "" [sensitive] # 这是核心提示词的一部分，告诉模型什么算敏感信息。 # 默认值比较通用。你可以根据你的领域细化，例如：“患者姓名、身份证号、社保号、诊断结果、药品名称” include = "personal names, identification numbers, phone numbers, email addresses, physical addresses, financial account numbers, and any confidential project code names" [mask_wrapper] # 定义占位符的包裹符号。默认是 ${}，清晰且不易与正常文本混淆。 left = "${" right = "}" [web] # 如果你使用 API 网关，并希望它代理到非 OpenAI 的服务（如 Google Gemini），在此设置。 # 格式必须是完整的 OpenAI API 兼容端点。 # upstream_oai_api_base = "https://generativelanguage.googleapis.com/v1beta/openai"

这个配置文件定义了：使用本地 Qwen2.5-7B 模型，识别常见的个人和金融信息，并用${VARIABLE}的格式进行替换。

3.3 两种核心使用模式实战

根据你的使用场景，选择最合适的方式。

模式一：Python SDK 无缝集成（推荐给开发者）

这是最优雅的方式。OpenAIMasked类完全模仿了openai.OpenAI客户端的接口。

# 在你的代码中，通常你会这样导入： # from openai import OpenAI # client = OpenAI(api_key="sk-...") # 现在，只需改变导入，其他代码几乎不用动！ from promptmask import OpenAIMasked as OpenAI import os # 初始化客户端。它会自动读取环境变量 OPENAI_API_KEY 和你的 promptmask 配置。 # 假设你的云端服务是 Azure OpenAI，或者任何兼容 OpenAI API 的代理。 client = OpenAI( base_url="https://your-trusted-ai-service.com/v1", # 你的云端 API 地址 api_key=os.getenv("TRUSTED_AI_API_KEY") # 你的云端 API 密钥 ) # 发起一个包含敏感信息的请求 response = client.chat.completions.create( model="gpt-4", # 云端模型的名称 messages=[ {"role": "system", "content": "你是一个有帮助的助手。"}, {"role": "user", "content": "我的客户李四，手机号是 13800138000，邮箱是 lisi@example.com。他想咨询关于订单号 ORDER-7789 的退款进度，请帮我起草一封礼貌的英文查询邮件。"} ], stream=False ) # 打印结果。response.choices[0].message.content 已经是还原后的文本！ print(response.choices[0].message.content) # 输出会类似于：Dear Sir/Madam, I'm writing on behalf of my client Li Si (Phone: 13800138000, Email: lisi@example.com) to inquire about the refund status for order ORDER-7789... # 注意：李四、手机号、邮箱、订单号这些真实信息，在发送到云端前已被替换为 ${NAME}, ${PHONE} 等。打印时已被完美还原。 # 如果你想查看被脱敏后实际发送出去的消息内容，可以访问这个属性： print(response.choices[0].message.original_content) # 输出会是占位符版本：我的客户${NAME}，手机号是${PHONE}，邮箱是${EMAIL}。他想咨询关于订单号${ORDER_ID}的退款进度...

模式二：独立 API 网关（适合非 Python 环境或现有工具）

如果你在用一些现成的、支持自定义 OpenAI API Base URL 的工具，比如 Open WebUI、Chatbox、或者一些自动化脚本（如curl），API 网关模式是绝配。

启动网关服务：

# 确保已安装 promptmask[web] promptmask-web # 输出：INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

配置你的应用：将应用中原本指向api.openai.com的 API Base URL，改为http://localhost:8000/gateway/v1。API Key 仍然使用你真实的云端 API Key。
- 在 Open WebUI 中：设置 -> 连接 -> 添加新连接，API 基址填http://localhost:8000/gateway/v1。
- 使用curl测试：
```
curl http://localhost:8000/gateway/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-real-openai-api-key" \ -d '{ "model": "gpt-4", "messages": [ {"role": "user", "content": "我的密码是 MyP@ssw0rd123，请评估其强度。"} ] }'
```
网关会拦截请求，将MyP@ssw0rd123脱敏后再转发给 OpenAI，拿到响应后再还原，最后返回给你。你的密码从未离开过你的电脑。

4. 高级技巧与深度定制

当你熟悉了基本用法后，这些高级功能能让 PromptMask 更贴合你的具体需求。

4.1 直接使用 PromptMask 核心类进行精细控制

OpenAIMasked和 API 网关提供了便利，但有时你需要更底层的控制，比如在异步框架中，或者需要单独对一批文本进行脱敏处理后再做其他操作。

import asyncio from promptmask import PromptMask async def batch_process_sensitive_documents(doc_list): """ 批量处理包含敏感信息的文档。 1. 对所有文档进行脱敏。 2. 将脱敏后的文档发送到某个处理管道。 3. 获取处理结果后，再批量还原。 """ masker = PromptMask() masked_docs = [] mask_maps = [] # 第一步：批量脱敏 for doc in doc_list: masked_text, mask_map = await masker.async_mask_str(doc) masked_docs.append(masked_text) mask_maps.append(mask_map) print(f"原文档片段: {doc[:50]}...") print(f"脱敏后片段: {masked_text[:50]}...") print(f"识别出的敏感信息: {list(mask_map.keys())}\n") # 第二步：假设这里将 masked_docs 发送到某个外部服务进行处理 # simulated_remote_results = await external_api.process(masked_docs) simulated_remote_results = [ "分析报告：用户${USER}的行为数据${DATA_ID}显示...", "总结：针对${COMPANY}的合同${CONTRACT_NO}，条款建议..." ] # 第三步：批量还原结果 for i, (result, mask_map) in enumerate(zip(simulated_remote_results, mask_maps)): unmasked_result = masker.unmask_str(result, mask_map) print(f"还原后的结果 {i+1}: {unmasked_result}") # 示例文档 documents = [ "用户Alice（工号：EMP007）在2023年的销售数据文件‘sales_q4.xlsx’中表现突出。", "与‘Acme Corp’（税号：US-123-456789）的合同‘CT-2024-001’将于下月到期。" ] asyncio.run(batch_process_sensitive_documents(documents))

这种模式把控制权完全交给你，适合集成到更复杂的数据流水线中。

4.2 优化敏感信息识别效果

默认的sensitive.include提示词可能无法覆盖你所有的敏感信息类型。例如，如果你处理的是法律文件，需要识别“条款编号”、“当事人别名”；如果是代码库，需要识别“API密钥”、“数据库连接字符串”。

技巧一：细化提示词在promptmask.config.user.toml中，你可以写得非常具体：

[sensitive] include = """ 请识别以下所有类型的敏感信息： 1. 个人身份信息：中文姓名、英文名、身份证号（15或18位）、护照号、手机号（11位）、车牌号。 2. 金融信息：银行卡号（16或19位）、信用卡安全码（CVV，3位）。 3. 企业信息：统一社会信用代码（18位）、公司银行账号、内部项目代号（以‘PROJ-’开头的字符串）。 4. 医疗信息：病历号、医保卡号、诊断名称（如‘II型糖尿病’）。 5. 网络信息：IP地址、域名、邮箱地址。 请确保识别准确，不要误判普通数字和单词。 """

更详细的指示能显著提升本地模型的识别精度。

技巧二：处理模糊与边界情况有时模型会犹豫。比如“北京市海淀区”算敏感地址吗？这取决于上下文。PromptMask 的设计倾向于“宁可错杀，不可放过”，在模糊情况下可能会将其标记。如果你发现误判率太高，可以：

在提示词中增加反例：“不要识别常见的省市县名称，除非后面跟有详细街道门牌号。”
考虑使用一个在 NER 任务上专门微调过的本地模型，而不是通用聊天模型。

4.3 Web UI 的妙用：调试与监控

不要小看promptmask-web提供的 Web 界面 (http://localhost:8000)。它不仅是演示工具，更是强大的调试和监控中心。

实时测试脱敏效果：在 “Mask a String” 页面，直接输入文本，点击“Mask”，你可以立刻看到本地模型识别出了哪些信息，以及替换后的结果。这是验证你的sensitive.include配置是否生效的最快方式。
配置热重载：在 “Config Manager” 页面，你可以直接查看当前生效的所有配置项。如果你修改了promptmask.config.user.toml文件，点击“Reload Config”即可生效，无需重启服务。
网关请求监控：当通过网关发送请求时，Web UI 的后台日志（如果你以后台模式运行并查看日志）会记录脱敏前、脱敏后、还原前、还原后的消息，方便你跟踪整个数据流转过程，排查问题。

5. 常见问题与故障排查实录

在实际部署和使用中，你肯定会遇到一些问题。下面是我和社区遇到的一些典型情况及其解决方案。

5.1 连接与配置问题

问题1：启动promptmask-web或初始化PromptMask()时，报错连接不上http://localhost:11434/v1。

排查步骤：
1. 确认本地模型服务是否运行：执行curl http://localhost:11434/v1/models或ollama list。
2. 检查端口和地址：Ollama 默认端口是 11434。如果你改了端口，或者服务运行在另一台机器（如 Docker 容器、局域网内另一台服务器），必须在配置中修改llm_api.base_url。
3. 使用环境变量覆盖：最快的方法是启动前设置环境变量：LOCALAI_API_BASE=http://192.168.1.100:11434/v1 promptmask-web。
4. 检查防火墙：确保本地服务的端口没有被防火墙阻止。

问题2：本地模型服务返回了响应，但 PromptMask 报错，提示模型不支持或响应格式错误。

可能原因：本地模型的 OpenAI 兼容 API 实现不完整。PromptMask 会先调用/v1/models来获取模型列表，如果这个端点返回的格式不符合 OpenAI 标准，或者模型名称列表为空，就会出错。
解决方案：
1. 在配置文件中显式指定模型 ID：model = "qwen2.5:7b"。这样 PromptMask 会跳过自动检测，直接使用你指定的模型。
2. 如果指定后仍报错，可能是聊天补全端点路径问题。尝试将base_url设置为更具体的路径，例如对于某些部署，可能需要base_url = "http://localhost:8080"（不带/v1），然后由 PromptMask 自己拼接路径。这需要你查阅本地模型服务的文档。

5.2 脱敏效果问题

问题3：本地模型漏掉了某些明显的敏感信息（如身份证号），或者把普通数字（如年份2024）误判为敏感信息。

原因分析：这几乎是必然会发生的情况，取决于本地模型的能力和你定义的“敏感信息”范围。
解决方案：
1. 升级本地模型：换一个更大、在 NER 任务上表现更好的模型。参考项目中的eval/benchmark.md选择。
2. 优化提示词（sensitive.include）：这是最有效的手段。描述要具体、有例子、有排除项。例如：“识别18位或15位的身份证号，格式为前6位地区码，后接生日码，最后是顺序码和校验码。不要识别单纯的年份数字如2024、1998。”
3. 后处理规则：对于规则非常明确的信息（如固定格式的身份证号、手机号），可以考虑在 PromptMask 处理前后，加入基于正则表达式的规则引擎进行二次校验和补全。这需要你修改或扩展 PromptMask 的代码。

问题4：流式响应（stream=True）时，还原后的文本出现乱码或占位符残留。

原因分析：流式响应是一段一段（chunk）返回的。占位符（如${NAME}）可能被拆分成多个 chunk 发送（例如“${NA”和“ME}”）。如果 unmask 操作在每一个 chunk 上独立进行，就会因为映射表不完整而失败。
解决方案：OpenAIMasked的流式处理已经考虑了这个问题。它内部会进行 chunk 的缓冲和重组，确保在 unmask 时面对的是一个完整的 token 或占位符。如果你是自己处理流式响应，需要实现类似的缓冲逻辑。一个重要的检查点：确保你使用的是最新版本的 PromptMask，因为这方面的修复会持续进行。

5.3 性能与稳定性

问题5：感觉整体响应变慢了，尤其是第一个请求。

原因分析：这是正常的。延迟主要来自两个环节：1) 本地模型对 prompt 进行脱敏需要时间（一次 LLM 调用）；2) 与云端模型的通信时间。第一个请求可能更慢，因为涉及到本地模型的加载（如果 Ollama 模型未缓存）和 PromptMask 自身的初始化。
优化建议：
1. 选择更快的本地模型：较小的模型（如 3B、7B）比大的模型（14B+）脱敏速度更快。在效果可接受的前提下，选择小模型。
2. 使用 GPU 运行本地模型：如果硬件允许，用 GPU 运行 Ollama 模型会极大提升脱敏速度。在 Ollama 运行时指定 GPU 层数：OLLAMA_NUM_GPU=100 ollama run qwen2.5:7b。
3. 预热：对于延迟敏感的生产环境，可以在服务启动后，主动发送一个简单的测试请求来“预热”本地模型。

问题6：在高并发下，PromptMask 服务不稳定或内存占用高。

原因分析：每个请求都需要独立调用本地模型，如果并发数超过本地模型服务的处理能力，就会排队或失败。此外，每个请求的映射表都保存在内存中，直到请求结束。
解决方案：
1. 对本地模型服务进行扩容：部署多个 Ollama 实例，并在 PromptMask 前加一个负载均衡器，将llm_api.base_url指向这个负载均衡器。
2. 限制 PromptMask 的并发：如果你使用promptmask-web作为网关，Uvicorn 工作进程数（--workers）和每个进程的并发数（--limit-concurrency）需要根据你的机器配置进行调整。
3. 监控与告警：监控本地模型服务的 GPU/CPU 和内存使用情况，以及 PromptMask 网关的请求延迟和错误率。

5.4 安全考量与局限性

重要提醒：PromptMask 极大地提升了隐私安全，但并非银弹，你需要理解其局限性：

依赖本地模型的安全性：如果你的本地模型服务被入侵，那么隐私保护就失效了。请确保运行本地模型的机器环境安全。
元数据泄露：即使内容被脱敏，请求的元数据（如发送时间、频率、大致长度）以及通过占位符类型（${NAME},${PHONE}）推断出的信息结构，仍可能泄露一些信息。在极高安全要求的场景下，需要结合其他匿名化技术。
上下文关联泄露：如果一段对话中，同一个占位符（如${NAME}）在不同回合出现，结合对话上下文，可能间接泄露信息。PromptMask 目前每个请求独立处理，跨请求的对话需要更复杂的会话管理。
最终信任链：你仍然需要信任云端模型服务商不会滥用你脱敏后的数据。PromptMask 解决的是“不把原始数据给对方”的问题，而不是“完全信任对方”的问题。

在我自己的使用中，PromptMask 已经成为连接内部系统和外部 AI 能力的标准中间件。它带来的心理安全感是实实在在的——我知道我的原始数据从未离开过我的控制范围。对于大多数涉及中度敏感信息的应用场景（如客服对话脱敏、内部文档分析、代码审查辅助），它提供了一个近乎完美的平衡点。