> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Foundry 中间件集成

> 使用 LangChain Python 与 Azure AI 中间件集成。

专为 Microsoft Foundry 和 Azure AI 内容安全设计的中间件。了解更多关于[中间件](/oss/python/langchain/middleware/overview)的信息。

这些中间件类位于 `langchain-azure-ai` 包中，并从 `langchain_azure_ai.agents.middleware` 导出。

<Info>
  Azure AI 内容安全中间件目前在上游被标记为实验性。随着 Azure AI 内容安全和 LangChain 中间件支持的不断成熟，预计 API 接口将会演进。
</Info>

## 概览

| 中间件             | 描述                            |
| --------------- | ----------------------------- |
| [文本审核](#文本审核)   | 筛选输入和输出文本中的有害内容和黑名单匹配项        |
| [图像审核](#图像审核)   | 使用 Azure AI 内容安全图像分析筛选图像输入和输出 |
| [提示防护](#提示防护)   | 检测直接和间接的提示注入尝试                |
| [受保护材料](#受保护材料) | 检测受版权保护或其他受保护的文本或代码           |
| [事实依据](#事实依据)   | 根据事实来源评估模型输出并标记幻觉             |

### 功能特性

* 针对有害内容和自定义黑名单的文本审核。
* 针对数据 URL 和公共 HTTP(S) 图像输入的图像审核。
* 使用提示防护进行提示注入检测。
* 针对文本和代码的受保护材料检测。
* 针对检索到的上下文评估生成答案的事实依据。
* 自定义 `context_extractor` 钩子，以适应您的代理状态进行筛选和评估。

## 设置

要使用 Azure AI 内容安全中间件，请安装集成包，配置 Azure AI Foundry 项目端点或 Azure 内容安全端点，并提供凭据。

### 安装

安装包：

<CodeGroup>
  ```bash pip theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  pip install -U langchain-azure-ai
  ```

  ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  uv add langchain-azure-ai
  ```
</CodeGroup>

### 凭据

进行身份验证时，通过 `credential` 参数传递 `DefaultAzureCredential()` 或 API 密钥字符串。使用 Foundry 项目需要使用 Microsoft Entra ID 进行身份验证。

```python 初始化凭据 icon="shield-lock" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
```

### 实例化

中间件支持两种端点样式：

* 通过 `AZURE_CONTENT_SAFETY_ENDPOINT` 使用 Azure 内容安全资源端点
* 通过 `AZURE_AI_PROJECT_ENDPOINT` 使用 Azure AI Foundry 项目端点

如果两者都可用，优先使用 `project_endpoint`，因为它为基于 Azure AI Foundry 的工作流提供了更好的默认设置。在大多数设置中，您可以设置一次环境变量，并在每个中间件实例化时省略 `endpoint` 或 `project_endpoint`。

```python 配置端点 icon="key" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import os

os.environ["AZURE_AI_PROJECT_ENDPOINT"] = "https://<resource>.services.ai.azure.com/api/projects/<project>"
```

从 `langchain_azure_ai.agents.middleware` 导入并配置您的中间件。

```python 初始化中间件 icon="arrows-shuffle" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

middleware = AzureContentModerationMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    categories=["Hate", "Violence"],
    exit_behavior="error",
)
```

## 与代理一起使用

按顺序将中间件传递给 [`create_agent`](https://reference.langchain.com/python/langchain/agents/factory/create_agent)。您可以将 Azure AI 中间件与[内置中间件](/oss/python/langchain/middleware/built-in)结合使用。

```python 使用中间件的代理 icon="robot" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential
from langchain.agents import create_agent
from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

agent = create_agent(
    model="azure_ai:gpt-5.4",
    middleware=[
        AzureContentModerationMiddleware(
            project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
            credential=DefaultAzureCredential(),
            categories=["Hate", "Violence"],
            exit_behavior="error",
        )
    ],
)
```

<Tip>
  如果已设置 `AZURE_AI_PROJECT_ENDPOINT`，通常可以在实例化时省略 `project_endpoint`。
</Tip>

## Azure AI 内容安全

### 文本审核

使用 `AzureContentModerationMiddleware` 在代理运行前筛选最后一条 `HumanMessage`，并在代理运行后筛选最后一条 `AIMessage`。此中间件使用 Azure AI 内容安全有害内容检测，还可以检查在您的资源中配置的自定义黑名单。

文本审核适用于以下情况：

* 在模型调用前阻止有害的用户输入
* 在模型输出到达最终用户前进行筛选
* 在受监管或企业部署中强制执行自定义黑名单
* 使用不同的类别和方向设置组合多个审核流程

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureContentModerationMiddleware

middleware = AzureContentModerationMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    categories=["Hate", "SelfHarm", "Sexual", "Violence"],
    severity_threshold=4,
    exit_behavior="error",
    apply_to_input=True,
    apply_to_output=True,
)
```

<Accordion title="配置选项">
  <ParamField body="categories" type="list[str] | None">
    要分析的有害内容类别。有效值为 `'Hate'`、`'SelfHarm'`、`'Sexual'` 和 `'Violence'`。默认为所有四个类别。
  </ParamField>

  <ParamField body="severity_threshold" type="int" default="4">
    触发配置行为的最低严重性分数，范围从 `0` 到 `6`。
  </ParamField>

  <ParamField body="exit_behavior" type="string" default="error">
    `'error'`、`'continue'` 或 `'replace'` 之一。
  </ParamField>

  <ParamField body="apply_to_input" type="bool" default="True">
    是否在代理运行前筛选最后一条 `HumanMessage`。
  </ParamField>

  <ParamField body="apply_to_output" type="bool" default="True">
    是否在代理运行后筛选最后一条 `AIMessage`。
  </ParamField>

  <ParamField body="blocklist_names" type="list[str] | None">
    在 Azure 内容安全资源中配置的自定义黑名单名称。
  </ParamField>

  <ParamField body="context_extractor" type="Callable | None">
    可选的可调用对象，用于从代理状态和运行时中提取要筛选的文本。
  </ParamField>
</Accordion>

### 图像审核

当您的代理处理视觉内容时，使用 `AzureContentModerationForImagesMiddleware`。它从最新的输入或输出消息中提取图像，并使用 Azure AI 内容安全图像分析 API 进行筛选。

此中间件支持：

* Base64 数据 URL，例如 `data:image/png;base64,...`
* 公共 HTTP(S) 图像 URL

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import (
    AzureContentModerationForImagesMiddleware,
)

middleware = AzureContentModerationForImagesMiddleware(
    endpoint="https://<resource>.cognitiveservices.azure.com/",
    credential=DefaultAzureCredential(),
    categories=["Hate", "SelfHarm", "Sexual", "Violence"],
    severity_threshold=4,
    exit_behavior="error",
    apply_to_input=True,
    apply_to_output=False,
)
```

<Accordion title="配置选项">
  <ParamField body="categories" type="list[str] | None">
    要分析的图像有害内容类别。默认为所有四个支持的类别。
  </ParamField>

  <ParamField body="severity_threshold" type="int" default="4">
    触发配置行为的最低严重性分数，范围从 `0` 到 `6`。
  </ParamField>

  <ParamField body="exit_behavior" type="string" default="error">
    `'error'` 或 `'continue'` 之一。
  </ParamField>

  <ParamField body="apply_to_input" type="bool" default="True">
    是否筛选最新 `HumanMessage` 中的图像。
  </ParamField>

  <ParamField body="apply_to_output" type="bool" default="False">
    是否筛选最新 `AIMessage` 中的图像。
  </ParamField>

  <ParamField body="context_extractor" type="Callable | None">
    可选的可调用对象，用于从代理状态和运行时中提取图像。
  </ParamField>
</Accordion>

### 提示防护

使用 `AzurePromptShieldMiddleware` 检测用户提示和可选支持文档中的提示注入。默认情况下，它仅筛选输入，因为提示注入通常是输入端攻击，但您也可以启用输出筛选。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzurePromptShieldMiddleware

middleware = AzurePromptShieldMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    exit_behavior="continue",
    apply_to_input=True,
    apply_to_output=False,
)
```

<Accordion title="配置选项">
  <ParamField body="exit_behavior" type="string" default="error">
    `'error'`、`'continue'` 或 `'replace'` 之一。
  </ParamField>

  <ParamField body="apply_to_input" type="bool" default="True">
    是否在代理运行前筛选最新的 `HumanMessage`。
  </ParamField>

  <ParamField body="apply_to_output" type="bool" default="False">
    是否在代理运行后筛选最新的 `AIMessage`。
  </ParamField>

  <ParamField body="context_extractor" type="Callable | None">
    可选的可调用对象，用于从代理状态和运行时中提取用户提示和事实依据文档。
  </ParamField>
</Accordion>

### 受保护材料

使用 `AzureProtectedMaterialMiddleware` 检测受保护内容，例如受版权保护的文本或代码。此中间件可以筛选最新的用户输入和最新的模型输出。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureProtectedMaterialMiddleware

middleware = AzureProtectedMaterialMiddleware(
    endpoint="https://<resource>.cognitiveservices.azure.com/",
    credential=DefaultAzureCredential(),
    type="code",
    exit_behavior="replace",
    apply_to_input=False,
    apply_to_output=True,
    violation_message="检测到受保护材料。请提供更高级别的摘要。",
)
```

<Accordion title="配置选项">
  <ParamField body="type" type="string" default="text">
    要筛选的内容类型：`'text'` 或 `'code'`。
  </ParamField>

  <ParamField body="exit_behavior" type="string" default="error">
    `'error'`、`'continue'` 或 `'replace'` 之一。
  </ParamField>

  <ParamField body="apply_to_input" type="bool" default="True">
    是否筛选最新的 `HumanMessage`。
  </ParamField>

  <ParamField body="apply_to_output" type="bool" default="True">
    是否筛选最新的 `AIMessage`。
  </ParamField>

  <ParamField body="context_extractor" type="Callable | None">
    可选的可调用对象，用于从代理状态和运行时中提取文本。
  </ParamField>
</Accordion>

### 事实依据

使用 `AzureGroundednessMiddleware` 评估模型响应是否基于代理可用的上下文。与本页上的其他中间件类不同，事实依据在模型生成后运行，并根据支持来源检查生成的答案。

默认情况下，事实依据从当前对话中收集来源，包括系统内容、工具输出以及附加到模型响应的相关注释。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.agents.middleware import AzureGroundednessMiddleware

middleware = AzureGroundednessMiddleware(
    project_endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>",
    credential=DefaultAzureCredential(),
    domain="Generic",
    task="QnA",
    exit_behavior="continue",
)
```

<Accordion title="配置选项">
  <ParamField body="domain" type="string" default="Generic">
    分析领域。支持的值为 `'Generic'` 和 `'Medical'`。
  </ParamField>

  <ParamField body="task" type="string" default="Summarization">
    分析的任务类型。支持的值为 `'Summarization'` 和 `'QnA'`。
  </ParamField>

  <ParamField body="exit_behavior" type="string" default="error">
    `'error'` 或 `'continue'` 之一。
  </ParamField>

  <ParamField body="context_extractor" type="Callable | None">
    可选的可调用对象，用于从代理状态和运行时中提取答案、事实依据来源和可选问题。
  </ParamField>
</Accordion>

## API 参考

有关完整的公共 API，请参阅 [`langchain_azure_ai.agents.middleware`](https://github.com/langchain-ai/langchain-azure/tree/main/libs/azure-ai/langchain_azure_ai/agents/middleware) 中的中间件导出，以及 [`langchain_azure_ai.agents.middleware.content_safety`](https://github.com/langchain-ai/langchain-azure/tree/main/libs/azure-ai/langchain_azure_ai/agents/middleware/content_safety) 中的基础内容安全中间件包。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/middleware/azure_ai.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>