关键词LangChainPIIMiddleware隐私保护PII 检测中间件数据脱敏目录引言1. PIIMiddleware 主要解决什么问题2. 内置 PIIMiddleware 的使用示例3. 自定义 PII 类型3.1 正则表达式模式字符串3.2 自定义函数3.3 自定义检测器函数签名3.4 示例代码3.5 参数配置详解4. 场景使用说明结语引言以 ChatGPT、GPT‑4 为代表的大语言模型正被快速集成到实际业务中智能客服、代码助手、自动化 Agent……几乎每个系统都会在对话或工具调用过程中传递大量用户原始文本。然而这些文本里常常混杂着邮箱、手机号、信用卡号、API 密钥等个人身份信息PII, Personally Identifiable Information。一旦 PII 未经处理直接进入模型或日志系统就可能触发数据保护法规的合规红线甚至导致严重的数据泄露事故。LangChain 作为当前最主流的 LLM 应用开发框架之一早在 2025 年就推出了专门的PIIMiddleware1以声明式的方式在 Agent 调用链中拦截、检测并脱敏 PII 数据。该中间件不仅内置了常见 PII 类型的检测能力更提供了高度可扩展的自定义检测器接口使得隐私保护逻辑可以无缝嵌入到任意 Agent 流程中而无需侵入业务代码。本文将基于 LangChain 官方文档并结合实战案例深入解析 PIIMiddleware 的设计思路、使用方式、自定义扩展以及最佳实践场景。1. PIIMiddleware 主要解决什么问题在大模型 Agent 的生命周期中文本数据会在用户输入、模型推理、工具调用、日志记录等多个环节流动。传统做法往往需要开发者在每个环节手动调用脱敏函数这种方式存在几个痛点重复且易遗漏不同的工具或节点都需要编写类似的脱敏逻辑不仅冗余而且一旦某些通道被遗忘就会暴露隐私。耦合度高脱敏代码与业务逻辑纠缠在一起后续维护困难。缺乏统一策略不同团队对“脱敏”的理解不一致有的地方用遮盖有的地方用删除输出行为不可预期。LangChain 的 PIIMiddleware 通过中间件Middleware机制在 Agent 调用管道中引入一个独立的隐私处理层。该中间件在用户输入进入模型之前apply_to_input以及模型输出返回给用户之前apply_to_output均可进行拦截自动识别并处理 PII 数据。其核心价值包括集中管理所有 PII 检测规则和脱敏策略统一配置在中间件列表中避免分散。即插即用通过middleware参数传递即可生效无需改动工具实现或 Agent 核心逻辑。灵活的策略选择支持redact替换为[REDACTED]、mask部分遮盖如j***example.com、hash哈希替换、block直接阻止请求等多种策略。高度可扩展除了内置类型如email、credit_card、phone_number、ssn、api_key等用户可以用正则表达式或自定义函数定义任意 PII 类型。下面我们通过代码和说明来逐一展开这些能力。2. 内置 PIIMiddleware 的使用示例LangChain 为常见 PII 类型提供了开箱即用的检测器只需通过字符串指定类型名称再配合策略参数即可。以下示例展示了如何同时为email和credit_card配置中间件fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportPIIMiddleware agentcreate_agent(modelgpt-5.5,tools[],middleware[PIIMiddleware(email,strategyredact,apply_to_inputTrue),PIIMiddleware(credit_card,strategymask,apply_to_inputTrue),],)在上述代码中Agent 接收到的任何用户输入都会先经过两个中间件email类型的 PII 被直接替换为[REDACTED]而credit_card类型则进行部分遮盖例如保留后四位其余用*替代。这样一来模型和下游工具拿到的已经是安全的文本而开发者几乎不需要编写额外的判断逻辑。3. 自定义 PII 类型真实业务中的 PII 形态远比内置类型丰富例如自定义 API 密钥格式、内部工单编号、社保号码的变体等等。PIIMiddleware 允许通过三种方式定义自定义检测器灵活度极高。3.1 正则表达式模式字符串最简单的扩展方式是直接传入一个正则表达式字符串。这种方式适合格式固定、无需额外验证的场景例如检测形如sk-开头、后接 32 位字母数字组合的 API 密钥PIIMiddleware(api_key,detectorrsk-[a-zA-Z0-9]{32},strategyblock,)当输入中包含匹配该模式的字符串时中间件会立即触发block策略阻止该次请求继续传递。3.2 自定义函数对于需要复杂验证逻辑的 PII例如检查信用卡号的 Luhn 算法或验证手机号的归属地区可以提供自定义 Python 函数。函数接收原始文本content: str返回一个字典列表每个字典必须包含text、start、end三个字段分别表示被检测到的具体文本及其在原字符串中的起止位置。这种设计使函数不仅可以进行模式匹配还能实现校验、去重等高级操作。3.3 自定义检测器函数签名自定义检测器函数的签名是固定的defdetector(content:str)-list[dict[str,str|int]]:...返回的列表中每个字典至少应包含text被匹配到的敏感字符串。start该字符串在原content中的起始索引。end该字符串在原content中的结束索引不包含。PIIMiddleware 会根据这些信息选定文本范围并执行对应的脱敏策略因此函数内部必须保证索引准确。3.4 示例代码下面通过一个完整示例展示三种自定义方式的组合使用涵盖了 API 密钥的简单匹配、编译后正则的手机号匹配以及带验证逻辑的社保号码SSN检测fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportPIIMiddlewareimportre# Method 1: Regex pattern stringagent1create_agent(modelgpt-5.5,tools[],middleware[PIIMiddleware(api_key,detectorrsk-[a-zA-Z0-9]{32},strategyblock,),],)# Method 2: Compiled regex patternagent2create_agent(modelgpt-5.5,tools[],middleware[PIIMiddleware(phone_number,detectorre.compile(r\?\d{1,3}[\s.-]?\d{3,4}[\s.-]?\d{4}),strategymask,),],)# Method 3: Custom detector functiondefdetect_ssn(content:str)-list[dict[str,str|int]]:Detect SSN with validation. Returns a list of dictionaries with text, start, and end keys. importre matches[]patternr\d{3}-\d{2}-\d{4}formatchinre.finditer(pattern,content):ssnmatch.group(0)# Validate: first 3 digits shouldnt be 000, 666, or 900-999first_threeint(ssn[:3])iffirst_threenotin[0,666]andnot(900first_three999):matches.append({text:ssn,start:match.start(),end:match.end(),})returnmatches agent3create_agent(modelgpt-5.5,tools[],middleware[PIIMiddleware(ssn,detectordetect_ssn,strategyhash,),],)注意自定义函数detect_ssn在正则匹配的基础上进一步过滤了不合法的号码段这使检测更加精准避免了将000-12-3456这类编号误识别为真实 SSN。3.5 参数配置详解PIIMiddleware 提供了丰富的参数来控制检测范围和处理策略核心参数如下2合理组合这些参数可以构建出既安全又不影响对话质量的隐私防护层。例如对于面向终端用户的产品推荐开启apply_to_input和apply_to_output并选用mask策略以保持输出可读性而对于内部日志系统则可选择redact或hash策略。4. 场景使用说明PIIMiddleware 在生产环境中适用性非常广泛以下列举几个典型场景客服 Agent 对话管道用户可能在对话中无意提供自己的邮箱、订单号等。在create_agent时配置PIIMiddleware(email, strategymask)可以确保客服 Agent 看到的输入已经是遮盖后的内容而真实邮件地址不会进入 LLM 推理或日志系统。代码审查 / API 密钥保护当 Agent 需要读取代码片段或配置文件时可能包含 API 密钥、数据库密码。使用detectorrsk-[a-zA-Z0-9]{32}搭配strategyblock可以让 Agent 在没有清理过密钥的对话中直接拒绝执行防止密钥泄露到外部模型。日志脱敏与审计在工具调用或 Agent 执行过程中Langfuse 等追踪系统会记录完整的输入输出。通过配置PIIMiddleware(credit_card, strategyhash)可以将卡号换成哈希值既保留了数据关联性又避免了明文卡号在日志中扩散。多 PII 类型分层防护真实业务中往往需要同时处理多种 PII例如同时屏蔽邮箱、手机号、身份证号。可以在middleware列表中连续添加多个PIIMiddleware实例每个负责一类信息彼此独立且顺序执行从而实现模块化的隐私防火墙。动态加载与配置中心集成由于中间件配置完全由 Python 代码控制可以轻松与配置中心如 Nacos、Apollo或环境变量结合实现动态调整检测规则和脱敏策略无需重启服务即可响应隐私合规要求的变化。结语LangChain 的 PIIMiddleware 以轻量、可扩展、无侵入的方式解决了大模型应用中 PII 数据防护的普遍痛点。从内置类型到自定义检测器从输入到输出它贯穿了 Agent 交互的全链路。在数据安全法规日趋严格的今天将 PIIMiddleware 作为 Agent 架构的标准一环不仅是合规的需要更是对用户隐私尊重的最佳实践。LangChain Built-in Middleware 官方文档https://docs.langchain.com/oss/python/langchain/middleware/built-in ↩︎同上详细参数说明可参见文档中的 PIIMiddleware 部分。 ↩︎
