> ## Documentation Index > Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 安全护栏 > 为你的智能体实现安全检查和内容过滤 安全护栏帮助你构建安全、合规的 AI 应用程序，通过在智能体执行的关键节点验证和过滤内容。它们可以检测敏感信息、执行内容策略、验证输出，并在不安全行为造成问题之前阻止它们。 常见用例包括： * 防止个人身份信息（PII）泄露 * 检测和阻止提示注入攻击 * 阻止不当或有害内容 * 执行业务规则和合规要求 * 验证输出质量和准确性 你可以使用[中间件](/oss/python/langchain/middleware)来实现安全护栏，在战略节点拦截执行——在智能体启动前、完成后，或在模型和工具调用周围。
中间件流程图
安全护栏可以使用两种互补的方法实现： 使用基于规则的逻辑，如正则表达式模式、关键词匹配或显式检查。快速、可预测且经济高效，但可能遗漏细微的违规。 使用大语言模型（LLM）或分类器通过语义理解来评估内容。可以捕捉规则遗漏的细微问题，但速度较慢且成本较高。 LangChain 提供了内置安全护栏（例如 [PII 检测](#pii-detection)、[人机协作](#human-in-the-loop)）以及灵活的中间件系统，用于使用任一方法构建自定义安全护栏。 ## 内置安全护栏 ### PII 检测 LangChain 提供了内置中间件，用于检测和处理对话中的个人身份信息（PII）。该中间件可以检测常见的 PII 类型，如电子邮件、信用卡、IP 地址等。 PII 检测中间件适用于医疗保健和金融应用等具有合规要求的场景、需要清理日志的客服智能体，以及一般处理敏感用户数据的任何应用。 PII 中间件支持多种处理检测到的 PII 的策略： | 策略 | 说明 | 示例 | | -------- | --------------------------- | --------------------- | | `redact` | 替换为 `[REDACTED_{PII_TYPE}]` | `[REDACTED_EMAIL]` | | `mask` | 部分遮蔽（例如只显示最后 4 位） | `****-****-****-1234` | | `hash` | 替换为确定性哈希值 | `a8f5f167...` | | `block` | 检测到时抛出异常 | 抛出错误 | ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain.agents import create_agent from langchain.agents.middleware import PIIMiddleware agent = create_agent( model="gpt-5.4", tools=[customer_service_tool, email_tool], middleware=[ # 在发送到模型之前编辑用户输入中的电子邮件 PIIMiddleware( "email", strategy="redact", apply_to_input=True, ), # 遮蔽用户输入中的信用卡号 PIIMiddleware( "credit_card", strategy="mask", apply_to_input=True, ), # 阻止 API 密钥 - 检测到时抛出错误 PIIMiddleware( "api_key", detector=r"sk-[a-zA-Z0-9]{32}", strategy="block", apply_to_input=True, ), ], ) # 当用户提供 PII 时，将根据策略进行处理 result = agent.invoke({ "messages": [{"role": "user", "content": "My email is john.doe@example.com and card is 5105-1051-0510-5100"}] }) ``` **内置 PII 类型：** * `email` - 电子邮件地址 * `credit_card` - 信用卡号（经 Luhn 验证） * `ip` - IP 地址 * `mac_address` - MAC 地址 * `url` - URL **配置选项：** | 参数 | 说明 | 默认值 | | ----------------------- | ---------------------------------------------------- | ------------ | | `pii_type` | 要检测的 PII 类型（内置或自定义） | 必填 | | `strategy` | 如何处理检测到的 PII（`"block"`、`"redact"`、`"mask"`、`"hash"`） | `"redact"` | | `detector` | 自定义检测器函数或正则表达式模式 | `None`（使用内置） | | `apply_to_input` | 在模型调用前检查用户消息 | `True` | | `apply_to_output` | 在模型调用后检查 AI 消息 | `False` | | `apply_to_tool_results` | 在执行后检查工具结果消息 | `False` | 有关 PII 检测功能的完整详情，请参见[中间件文档](/oss/python/langchain/middleware#pii-detection)。 ### 人机协作 LangChain 提供了内置中间件，用于在执行敏感操作之前要求人工批准。这是高风险决策中最有效的安全护栏之一。 人机协作中间件适用于金融交易和转账、删除或修改生产数据、向外部方发送通信，以及任何具有重大业务影响的操作。 ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain.agents import create_agent from langchain.agents.middleware import HumanInTheLoopMiddleware from langgraph.checkpoint.memory import InMemorySaver from langgraph.types import Command agent = create_agent( model="gpt-5.4", tools=[search_tool, send_email_tool, delete_database_tool], middleware=[ HumanInTheLoopMiddleware( interrupt_on={ # 对敏感操作要求批准 "send_email": True, "delete_database": True, # 自动批准安全操作 "search": False, } ), ], # 在中断之间持久化状态 checkpointer=InMemorySaver(), ) # 人机协作需要线程 ID 进行持久化 config = {"configurable": {"thread_id": "some_id"}} # 智能体将在执行敏感工具之前暂停并等待批准 result = agent.invoke( {"messages": [{"role": "user", "content": "Send an email to the team"}]}, config=config ) result = agent.invoke( Command(resume={"decisions": [{"type": "approve"}]}), config=config # 相同的线程 ID 以恢复暂停的对话 ) ``` 有关实现审批工作流程的完整详情，请参见[人机协作文档](/oss/python/langchain/human-in-the-loop)。 ## 自定义安全护栏 对于更复杂的安全护栏，你可以创建在智能体执行前后运行的自定义中间件。这使你可以完全控制验证逻辑、内容过滤和安全检查。 ### 智能体前安全护栏 使用"智能体前"钩子在每次调用开始时验证请求一次。这对于会话级检查非常有用，如身份验证、速率限制或在任何处理开始之前阻止不当请求。 ```python title="类语法" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from typing import Any from langchain.agents.middleware import AgentMiddleware, AgentState, hook_config from langgraph.runtime import Runtime class ContentFilterMiddleware(AgentMiddleware): """确定性安全护栏：阻止包含禁用关键词的请求。""" def __init__(self, banned_keywords: list[str]): super().__init__() self.banned_keywords = [kw.lower() for kw in banned_keywords] @hook_config(can_jump_to=["end"]) def before_agent(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None: # 获取第一条用户消息 if not state["messages"]: return None first_message = state["messages"][0] if first_message.type != "human": return None content = first_message.content.lower() # 检查禁用关键词 for keyword in self.banned_keywords: if keyword in content: # 在任何处理之前阻止执行 return { "messages": [{ "role": "assistant", "content": "I cannot process requests containing inappropriate content. Please rephrase your request." }], "jump_to": "end" } return None # 使用自定义安全护栏 from langchain.agents import create_agent agent = create_agent( model="gpt-5.4", tools=[search_tool, calculator_tool], middleware=[ ContentFilterMiddleware( banned_keywords=["hack", "exploit", "malware"] ), ], ) # 此请求将在任何处理之前被阻止 result = agent.invoke({ "messages": [{"role": "user", "content": "How do I hack into a database?"}] }) ``` ```python title="装饰器语法" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from typing import Any from langchain.agents.middleware import before_agent, AgentState, hook_config from langgraph.runtime import Runtime banned_keywords = ["hack", "exploit", "malware"] @before_agent(can_jump_to=["end"]) def content_filter(state: AgentState, runtime: Runtime) -> dict[str, Any] | None: """确定性安全护栏：阻止包含禁用关键词的请求。""" # 获取第一条用户消息 if not state["messages"]: return None first_message = state["messages"][0] if first_message.type != "human": return None content = first_message.content.lower() # 检查禁用关键词 for keyword in banned_keywords: if keyword in content: # 在任何处理之前阻止执行 return { "messages": [{ "role": "assistant", "content": "I cannot process requests containing inappropriate content. Please rephrase your request." }], "jump_to": "end" } return None # 使用自定义安全护栏 from langchain.agents import create_agent agent = create_agent( model="gpt-5.4", tools=[search_tool, calculator_tool], middleware=[content_filter], ) # 此请求将在任何处理之前被阻止 result = agent.invoke({ "messages": [{"role": "user", "content": "How do I hack into a database?"}] }) ``` ### 智能体后安全护栏 使用"智能体后"钩子在返回给用户之前验证最终输出一次。这对于基于模型的安全检查、质量验证或对完整智能体响应的最终合规扫描非常有用。 ```python title="类语法" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain.agents.middleware import AgentMiddleware, AgentState, hook_config from langgraph.runtime import Runtime from langchain.messages import AIMessage from langchain.chat_models import init_chat_model from typing import Any class SafetyGuardrailMiddleware(AgentMiddleware): """基于模型的安全护栏：使用大语言模型（LLM）评估响应安全性。""" def __init__(self): super().__init__() self.safety_model = init_chat_model("gpt-5.4-mini") @hook_config(can_jump_to=["end"]) def after_agent(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None: # 获取最终的 AI 响应 if not state["messages"]: return None last_message = state["messages"][-1] if not isinstance(last_message, AIMessage): return None # 使用模型评估安全性 safety_prompt = f"""Evaluate if this response is safe and appropriate. Respond with only 'SAFE' or 'UNSAFE'. Response: {last_message.content}""" result = self.safety_model.invoke([{"role": "user", "content": safety_prompt}]) if "UNSAFE" in result.content: last_message.content = "I cannot provide that response. Please rephrase your request." return None # 使用安全护栏 from langchain.agents import create_agent agent = create_agent( model="gpt-5.4", tools=[search_tool, calculator_tool], middleware=[SafetyGuardrailMiddleware()], ) result = agent.invoke({ "messages": [{"role": "user", "content": "How do I make explosives?"}] }) ``` ```python title="装饰器语法" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain.agents.middleware import after_agent, AgentState, hook_config from langgraph.runtime import Runtime from langchain.messages import AIMessage from langchain.chat_models import init_chat_model from typing import Any safety_model = init_chat_model("gpt-5.4-mini") @after_agent(can_jump_to=["end"]) def safety_guardrail(state: AgentState, runtime: Runtime) -> dict[str, Any] | None: """基于模型的安全护栏：使用大语言模型（LLM）评估响应安全性。""" # 获取最终的 AI 响应 if not state["messages"]: return None last_message = state["messages"][-1] if not isinstance(last_message, AIMessage): return None # 使用模型评估安全性 safety_prompt = f"""Evaluate if this response is safe and appropriate. Respond with only 'SAFE' or 'UNSAFE'. Response: {last_message.content}""" result = safety_model.invoke([{"role": "user", "content": safety_prompt}]) if "UNSAFE" in result.content: last_message.content = "I cannot provide that response. Please rephrase your request." return None # 使用安全护栏 from langchain.agents import create_agent agent = create_agent( model="gpt-5.4", tools=[search_tool, calculator_tool], middleware=[safety_guardrail], ) result = agent.invoke({ "messages": [{"role": "user", "content": "How do I make explosives?"}] }) ``` ### 组合多个安全护栏 你可以通过将多个安全护栏添加到中间件数组来堆叠它们。它们按顺序执行，允许你构建分层保护： ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain.agents import create_agent from langchain.agents.middleware import PIIMiddleware, HumanInTheLoopMiddleware agent = create_agent( model="gpt-5.4", tools=[search_tool, send_email_tool], middleware=[ # 第 1 层：确定性输入过滤（智能体前） ContentFilterMiddleware(banned_keywords=["hack", "exploit"]), # 第 2 层：PII 保护（模型前后） PIIMiddleware("email", strategy="redact", apply_to_input=True), PIIMiddleware("email", strategy="redact", apply_to_output=True), # 第 3 层：敏感工具的人工审批 HumanInTheLoopMiddleware(interrupt_on={"send_email": True}), # 第 4 层：基于模型的安全检查（智能体后） SafetyGuardrailMiddleware(), ], ) ``` ## 其他资源 * [中间件文档](/oss/python/langchain/middleware) - 自定义中间件完整指南 * [中间件 API 参考](https://reference.langchain.com/python/langchain/middleware/) - 自定义中间件完整指南 * [人机协作](/oss/python/langchain/human-in-the-loop) - 为敏感操作添加人工审查 * [测试智能体](/oss/python/langchain/test/) - 安全机制的测试策略 ***
[连接这些文档](/use-these-docs)到 Claude、VSCode 等工具，通过 MCP 获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/langchain/guardrails.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。