1. 项目概述：为什么我们需要在推理前“拦截”提示词？

最近在折腾大语言模型（LLM）和视觉语言模型（VLM）的智能体应用时，我遇到了一个挺棘手的问题。我们团队开发了一个内部客服助手，它能接入公司的知识库，处理员工的各种咨询。一开始跑得挺好，直到有一天，一个同事在测试时，无意中在聊天框里粘贴了一段包含客户姓名、电话和部分订单号的文本，然后问了个业务问题。虽然模型最终的回答没有直接复述这些敏感信息，但我们在后端的日志里发现，这些隐私数据被完整地作为提示词的一部分，发送给了云端的大模型API。

这件事让我惊出一身冷汗。我们用的虽然是合规的商用API，但隐私数据一旦离开我们的可控环境，其传播链条就变得模糊且不可控。模型供应商的日志策略、数据传输过程中的潜在风险，都成了未知数。更关键的是，在智能体（Agent）的工作流中，一个任务的输出往往会成为下一个任务的输入，隐私信息可能像“击鼓传花”一样，在多个模型调用、工具使用和外部服务交互中被无意识地传播和扩散。

这就是 BodhiPromptShield 这个项目想解决的核心问题。它的名字直译过来是“菩提提示盾”，理念很直接：与其在隐私泄露后亡羊补牢，不如在源头——也就是模型进行推理（Inference）之前——就筑起一道防线。 Pre-Inference Prompt Mediation ，即“推理前提示调解”，就是这个理念的技术实现。它不是一个事后的过滤器，而是一个事前的“安检员”，在用户输入的提示词（Prompt）被交给LLM/VLM处理之前，就对其中的隐私实体进行识别、分类和适当的处理（如脱敏、替换或拦截），从而从根本上抑制隐私在智能体工作流中的传播。

这个需求在当下越来越迫切。随着多模态智能体能够处理文本、图像甚至音频，隐私泄露的载体也从纯文本扩展到了图片中的车牌号、人脸，语音中的身份信息等。 BodhiPromptShield 的目标，就是为构建负责任、可信赖的AI应用，提供一个轻量级、可插拔的隐私安全层。

2. 核心设计思路：构建一个高效、精准的提示词“安检站”

设计 BodhiPromptShield 时，我首要考虑的是平衡三个关键点： 检测精度 、 处理速度 和 对原有工作流的侵入性 。它必须足够聪明，能准确识别各种形式的隐私信息；必须足够快，不能成为智能体响应链路的瓶颈；还必须易于集成，不能要求开发者重写大量业务代码。

2.1 架构总览：模块化与流水线

整个系统的架构采用经典的管道过滤器（Pipeline-Filter）模式，核心是一条可配置的 处理流水线 。原始提示词从入口进入，依次通过多个独立的“检查站”，每个检查站专注于一类隐私风险的检测与处理，最后输出“净化”后的安全提示词。这个设计的好处是高度模块化，你可以像搭积木一样，根据实际需求组合不同的检测器。

原始提示词输入
        |
        v
[ 文本规范化模块 ] -> 统一编码、去除无关字符等
        |
        v
[ 隐私实体检测流水线 ]
        |
        |---> [ 正则/规则检测器 ] (用于电话号码、身份证号等格式固定的信息)
        |
        |---> [ 命名实体识别（NER）检测器 ] (用于人名、地名、组织名)
        |
        |---> [ 关键词/模式匹配检测器 ] (用于自定义敏感词，如内部项目代号)
        |
        |---> [ 图像元数据与OCR结果检测器 ] (针对VLM，检查图片内嵌信息及识别文字)
        |
        v
[ 上下文风险评估模块 ] -> 结合对话历史、智能体状态判断风险等级
        |
        v
[ 处置策略执行器 ] -> 根据风险等级执行脱敏、替换、阻断或放行
        |
        v
安全提示词输出

2.2 为什么选择“推理前”而非“推理后”？

这是本项目最根本的设计决策。常见的做法是在模型输出（Post-Inference）后进行过滤，但这存在几个致命缺陷：

1. 信息已暴露 ：隐私数据已经传递给了模型服务商，泄露风险已经产生。
2. 处理滞后 ：对于流式输出，事后过滤很难做到实时和无缝，可能导致敏感信息在客户端短暂闪现。
3. 影响模型逻辑 ：如果提示词中包含“请忽略以下电话号码：138xxxx1234”，模型在推理时仍然“看到”了这个号码，其内部注意力机制可能已经受到了影响，即使最终输出不包含，其推理过程也可能被污染。

因此， Pre-Inference 的优势是决定性的： 将风险扼杀在摇篮里 。它确保了模型“看到”的始终是经过清理的输入，从根源上切断了隐私通过模型本身进行传播的路径。这对于使用第三方API的场景尤为重要，因为你完全掌控了发出请求的内容。

2.3 核心挑战与应对策略

挑战一：检测的准确性与召回率 误报（把非隐私信息当成隐私）会干扰正常对话；漏报（没识别出隐私）则导致防护失效。

• 策略 ：采用 多层检测机制 。先用高速、低开销的正则和规则匹配抓取格式明确的实体（如身份证号、信用卡号）。再用更精准但稍慢的NER模型（如微调的BERT、RoBERTa）识别上下文相关的人名、机构名。对于特定领域，加载自定义词典。这种组合拳在精度和效率间取得了良好平衡。

挑战二：对提示词语义和功能的破坏 简单地将“张三的电话是13800138000”中的电话号码替换成 [PHONE] ，可能导致模型无法理解用户意图。如果用户的问题是“这个号码是张三的，对吗？”，脱敏后的提示词就失去了意义。

• 策略 ：引入 上下文风险评估 。系统会分析整个对话历史和当前查询的意图。对于明显的“查询/验证”类意图，可以采取更保守的策略，例如仅对隐私实体进行部分掩码（如“138****8000”），或记录映射关系在本地，将原始信息与脱敏标识符关联，仅在绝对必要时在完全可控的内部环节使用。

挑战三：与智能体工作流的无缝集成 智能体往往由多个步骤（规划、工具调用、反思）循环构成。

• 策略 ：将 BodhiPromptShield 设计为一个 可插拔的中间件 。无论是基于LangChain、LlamaIndex还是自定义的Agent框架，都可以将其注入到LLM调用前的环节。它提供简单的 mediate(prompt, context) 接口，智能体在每次调用模型前，都先通过这个接口处理提示词。

3. 关键技术模块深度解析

3.1 隐私实体检测引擎：规则与模型的交响乐

这是盾牌最核心的部件。我将其设计为可插拔的检测器集合。

3.1.1 基于正则与规则的快速匹配层 这一层追求极致的速度，用于拦截那些有严格国家或国际格式标准的信息。我们维护了一套可更新的规则库：

• 中国身份证号 ： \b[1-9]\d{5}(18|19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]\b
• 手机号码 ： \b1[3-9]\d{9}\b （国内），并包含国际号码的常见模式。
• 银行卡号 ：匹配Luhn算法校验的13到19位数字串。
• 邮箱地址 ：相对宽松但有效的正则匹配。

注意 ：正则表达式需要根据业务所在地域进行定制和更新。例如，不同国家的身份证、护照号码格式迥异。我们将其设计为配置文件，支持热更新。

3.1.2 基于NER的语义理解层 对于人名、公司名、地理位置等没有固定格式的实体，我们依赖预训练的语言模型。这里没有选择庞大的通用模型，而是采用“小模型+精调”的策略。

• 模型选型 ：我们选择了 BERT 或 RoBERTa 的轻量级变体（如 BERT-tiny , ALBERT ）作为基础，因为它们在速度和精度上取得了较好平衡。
• 数据精调 ：使用公开的隐私相关NER数据集（如包含人名、地址的标注数据）与业务场景产生的匿名化日志（将真实实体替换为标签）进行混合训练。关键是要让模型学会识别业务场景下的特定实体，比如我们内部的“项目彩虹桥”代号。
• 推理优化 ：使用 ONNX Runtime 或 TensorRT 对训练好的模型进行转换和加速，确保单次检测在毫秒级完成。

3.1.3 针对VLM的视觉信息检测 对于视觉语言模型，风险来自两方面：

1. 图像元数据 ：照片中可能嵌入了GPS坐标、拍摄设备、时间等Exif信息。
2. 图像内容本身 ：包含人脸、车牌、证件照、敏感文件截图等。

• 策略 ：在将图像输入VLM之前，先进行预处理流水线：
  • 元数据剥离 ：使用如 PIL （Python Imaging Library）或 exiftool ，无条件删除或清空所有Exif标签。
  • 内容预筛查 ：集成轻量级的目标检测模型（如YOLO的轻量版），快速检测图像中是否包含“人脸”、“车牌”、“护照”等敏感类别。如果检测到，可以触发更高精度的处理，如对敏感区域进行模糊（Blur）或像素化（Pixelation）处理， 然后将处理后的图像 交给VLM。这里的关键是，脱敏操作发生在视觉层面，VLM接收到的是已经“打码”的图片。

3.2 上下文风险评估与处置策略引擎

检测到实体只是第一步，如何处置需要智慧。我们设计了一个简单的规则引擎来评估风险并执行动作。

风险等级评估因素：

• 实体类型 ：身份证号风险高于人名。
• 实体出现频率 ：在单次提示中密集出现。
• 对话历史 ：当前query是否在反复追问某个已脱敏的实体。
• 智能体状态 ：智能体当前是在执行“信息检索”还是“创意写作”？不同任务对原始数据的依赖度不同。

处置策略矩阵：

风险等级	处置动作	示例（输入 -> 输出）	适用场景
高	阻断 (Block)	“告诉我13800138000机主的姓名” -> “[请求包含隐私信息，已拦截]”	明确试图查询隐私的恶意请求
中	替换/脱敏 (Replace/Redact)	“张三的电话是13800138000” -> “张三的电话是 [PHONE_1] ”	通用对话，隐私信息非查询核心
低	部分掩码 (Partial Mask)	“我的尾号8000的银行卡丢了” -> “我的尾号 ****8000 的银行卡丢了”	信息需要部分保留以维持上下文
可审计	标记与记录 (Tokenize & Log)	“联系李四（身份证：110101199003077XXX）” -> “联系 [PERSON_1] （身份证： [ID_1] ）” 并在本地安全存储映射关系	内部合规流程，需在严格管控下追溯

策略执行器 会根据配置的映射表，确保在同一会话中，同一个原始实体被替换为同一个标记符（如始终将“13800138000”替换为 [PHONE_1] ），以维持对话的一致性。

3.3 集成与部署模式

为了让 BodhiPromptShield 易于使用，我们提供了多种集成方式：

1. Python SDK/装饰器 ：对于Python开发的智能体，只需几行代码导入并包装你的LLM调用函数。

   from bodhipromptshield import Shield
   
   shield = Shield(config_path="shield_config.yaml")
   
   @shield.mediate
   def call_llm(prompt: str, history: list) -> str:
       # 你的原始LLM调用逻辑
       response = llm_client.chat(prompt, history)
       return response
   
   # 调用时，prompt会被自动处理
   safe_response = call_llm(user_input, chat_history)
   

2. LangChain/LlamaIndex 自定义组件 ：为流行的AI应用框架提供 CustomPromptTemplate 或 LLM Wrapper ，直接嵌入到Chain中。

3. 独立服务（微服务） ：部署为独立的HTTP/gRPC服务。其他语言的智能体或前端可以通过API调用。这种方式将计算资源隔离，便于统一更新检测模型和规则。

   POST /mediate
   Content-Type: application/json
   
   {
       "prompt": "用户输入的原始文本",
       "session_id": "abc123",
       "context": {...}
   }
   

4. 实操部署与性能调优指南

4.1 从零开始部署一个基础防护实例

假设我们有一个基于FastAPI的简单聊天后端，现在要集成防护功能。

步骤1：环境准备与安装

# 创建虚拟环境
python -m venv shield_env
source shield_env/bin/activate  # Linux/Mac
# shield_env\Scripts\activate  # Windows

# 安装核心库（假设已打包上传至私有或公开仓库）
pip install bodhipromptshield
# 安装运行时依赖，如onnxruntime用于加速NER模型推理
pip install onnxruntime

步骤2：编写配置文件 ( config.yaml )

shield:
  detectors:
    - name: "regex_detector"
      enabled: true
      rules_path: "./rules/patterns.json"
    - name: "ner_detector"
      enabled: true
      model_path: "./models/privacy_ner.onnx"
      label_map: {"PER": "PERSON", "LOC": "LOCATION", "ORG": "ORGANIZATION"}
  policy_engine:
    default_risk: "MEDIUM"
    strategies:
      HIGH: "BLOCK"
      MEDIUM: "REDACT"
      LOW: "PARTIAL_MASK"
    tokenization:
      enabled: true
      storage_backend: "local_memory" # 生产环境可换为redis
  logging:
    level: "INFO"
    audit_log_path: "./logs/audit.log"

步骤3：在应用代码中集成

from fastapi import FastAPI, Request
from bodhipromptshield import Shield
import yaml

app = FastAPI()

# 加载配置并初始化盾牌
with open("config.yaml", 'r') as f:
    config = yaml.safe_load(f)
shield = Shield(config=config)

@app.post("/chat")
async def chat_endpoint(request: Request):
    data = await request.json()
    user_prompt = data.get("prompt", "")
    session_id = data.get("session_id", "")

    # 关键步骤：在调用LLM前进行调解
    mediated_result = shield.mediate(
        prompt=user_prompt,
        context={"session_id": session_id, "source": "web_chat"}
    )

    if mediated_result.action == "BLOCKED":
        return {"error": "请求包含敏感信息，已被拦截。"}

    # 使用净化后的安全提示词调用LLM
    safe_prompt = mediated_result.safe_prompt
    llm_response = await call_your_llm_api(safe_prompt)

    # （可选）如果需要，可以根据映射关系将响应中的标记符反向替换为可读形式（仅在安全环境下）
    # final_response = shield.restore(llm_response, session_id)

    return {"response": llm_response}

4.2 性能调优与压测心得

在真实流量下，性能至关重要。我们进行了多轮压测，以下是一些关键发现和调优建议：

• 瓶颈定位 ：初期，NER模型推理是主要耗时点（约50ms）。通过将模型转换为 ONNX 格式并使用 ONNX Runtime 提供者，延迟降低了约40%。
• 缓存策略 ：对于高频但固定的敏感词列表（如内部员工姓名），我们将其加载到内存哈希表中，实现O(1)时间复杂度的查找，完全绕过了模型推理。
• 异步处理 ：将检测流水线设计为异步非阻塞模式。当处理一个包含多段文本的复杂提示时，不同的检测器可以并行工作。
• 规则引擎优化 ：将正则表达式编译后缓存，避免每次匹配都重新编译。对规则进行优先级排序，高命中率、低成本的规则（如手机号）先执行，一旦触发高风险动作可提前返回，避免不必要的后续检测。

实操心得 ：压测时不要只用标准数据集。构造一些“对抗性样本”，比如故意在文本中插入大量无关数字干扰正则引擎，或者使用同音字、特殊符号分隔隐私信息（如“138-0013-8000”），以测试系统的鲁棒性。我们正是在这种测试中发现，需要增加一个“文本规范化”预处理模块来统一字符格式。

4.3 模型更新与规则管理

隐私保护的规则和模型不是一成不变的。新的隐私格式会出现，业务逻辑也会变化。

• 模型热更新 ：我们将NER模型文件放在对象存储（如S3）中。守护进程定期检查版本号，发现新模型后自动下载、验证并无缝切换到新的推理引擎。采用 model_version 配置项，实现灰度发布和快速回滚。
• 规则动态加载 ：规则文件（JSON/YAML）同样支持远程加载。我们甚至设计了一个简单的管理后台，允许合规管理员在审核后，动态添加新的正则模式或关键词，实时生效，无需重启服务。
• 反馈闭环 ：所有被拦截或脱敏的操作（在脱敏后）都会生成匿名化的审计日志。定期分析这些日志，可以发现新的隐私模式或误报案例，用于迭代改进检测规则和模型。

5. 常见问题与排查实录

在实际部署和运维 BodhiPromptShield 的过程中，我们遇到了不少典型问题。这里记录下排查思路和解决方案，希望能帮你绕过这些坑。

问题1：误报率过高，正常业务对话被频繁拦截。

• 现象 ：用户输入“我们公司今年第三季度的营收达到了8000万元”，其中的“8000万”被识别为银行卡号或类似数字串并被拦截。
• 排查 ：
  1. 检查审计日志，确认触发拦截的实体类型和匹配的规则。
  2. 发现是“金额数字+‘万/亿’单位”的模式被一个过于宽泛的“长数字串”规则匹配了。
• 解决 ：
  • 优化规则 ：修改正则表达式，为“金额”模式增加更精确的上下文限制，例如要求前面有“营收”、“利润”、“元”等金融相关词汇，或者后面必须跟“元”、“美元”等单位符号。
  • 引入白名单 ：对于已知的业务高频词（如产品代号“Project-1001”），将其加入规则引擎的白名单，避免误伤。
  • 调整风险策略 ：将此类模糊匹配的风险等级从“HIGH”（阻断）下调为“LOW”（部分掩码或仅记录），观察其在实际对话中对模型的影响。

问题2：漏报，新型隐私格式未能识别。

• 现象 ：发现一种新型的会员卡号格式“ABC-12-345-6789”在日志中明文出现。
• 排查 ：分析原始请求日志，确认该格式未包含在任何现有规则或NER模型的训练数据中。
• 解决 ：
  1. 紧急规则上线 ：在管理后台快速添加一条新的正则规则： \b[A-Z]{3}-\d{2}-\d{3}-\d{4}\b ，并设置为高风险。
  2. 数据收集与模型迭代 ：将这批漏报的样本（已脱敏）加入训练数据集，安排下一轮NER模型的增量训练，使其能学会识别这类编码模式背后的“会员卡”实体概念。

问题3：集成后智能体逻辑异常，任务无法完成。

• 现象 ：一个负责“提取邮件中联系人信息”的智能体，在集成盾牌后，总是无法正确提取电话号码。
• 排查 ：
  1. 检查盾牌输出的安全提示词。发现“联系电话：13800138000”被替换成了“联系电话： [PHONE_1] ”。
  2. 问题根源：该智能体的任务就是提取原始号码，脱敏后的提示词使其失去了目标。
• 解决 ：
  • 上下文感知策略 ：改进策略引擎。当系统检测到当前智能体的“角色”或“任务描述”中包含“提取”、“解析”、“记录”等与原始信息相关的关键词时，自动采用“可审计”的标记化策略，而非直接脱敏。这样，智能体可以处理标记符 [PHONE_1] ，而原始信息被安全地存储在本地映射表中，供后续的内部合规流程使用。
  • 任务分流 ：对于核心任务必须使用原始数据的场景，重新设计工作流。将“隐私识别”和“信息提取”拆分为两个步骤，先由盾牌识别并标记出隐私位置，再由一个在 完全隔离的信任域 内运行的专用模块，根据标记位置从原始输入中提取信息，整个过程不离线。

问题4：处理图像时，VLM性能下降明显。

• 现象 ：集成图像预筛查后，包含图片的请求响应时间增加了数百毫秒。
• 排查 ：使用性能分析工具，发现时间主要耗在目标检测模型（如YOLO）的初始化与推理上。
• 解决 ：
  • 模型轻量化 ：换用更小的目标检测模型（如YOLOv5n或MobileNet-SSD），牺牲一点点精度换取大幅速度提升。对于客服场景，检测“人脸”、“证件”等大类即可，无需精细到人脸识别。
  • 异步与批处理 ：对于非实时的图片审核场景（如用户上传历史图片），可以将图片预处理任务放入消息队列异步执行。对于实时场景，可以考虑对短时间内的大量图片请求进行微批处理，提高GPU利用率。
  • 选择性启用 ：在配置中增加开关，允许根据图像来源（如来自内部系统的截图 vs. 来自外部用户的上传）决定是否启用深度图像内容检测。

问题5：在高并发下，内存占用持续增长。

• 现象 ：服务运行一段时间后，内存使用率不断上升，疑似内存泄漏。
• 排查 ：
  1. 使用内存分析工具（如 tracemalloc 或 objgraph ）抓取快照。
  2. 发现是“标记化存储后端”如果使用 local_memory ，且会话（ session_id ）无限增长未清理，会导致映射表越来越大。
• 解决 ：
  • 切换存储后端 ：将 tokenization 的 storage_backend 从 local_memory 改为 redis ，并设置合理的TTL（生存时间），让Redis自动清理过期会话的映射数据。
  • 增加会话管理 ：在应用层，明确会话的生命周期，在会话结束时主动调用盾牌的清理接口，移除相关映射数据。
  • 定期巡检 ：为服务增加健康检查端点，监控内存和连接数，设置告警阈值。

部署这样一个隐私防护层，最大的体会是它永远不是一个“一劳永逸”的项目。它更像一个持续运营的系统，需要随着业务、数据格式和攻击模式的变化而不断演进。核心在于建立一套从 检测、处置、审计到反馈优化 的完整闭环。从实际效果来看，它极大地增强了我们使用第三方大模型时的信心，将隐私泄露的主动权牢牢掌握在了自己手中。