你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure AI 搜索工具

注释

本文档引用 Microsoft Foundry （经典）门户。

🔍 查看 Microsoft Foundry （new）文档，了解新门户。

代理服务中的 Azure AI 搜索工具将代理连接到新的或现有的搜索索引。可以使用此工具检索和汇总索引文档，从而将代理的响应记录在专有内容中。

本文介绍如何设置 Azure AI 搜索工具，包括创建项目连接并将该工具添加到代理。

先决条件

Microsoft Foundry 代理。
为矢量搜索配置的 Azure AI 搜索索引。索引必须包括：
- 一个或多个 Edm.String （文本）字段被标注为可搜索和可检索。
- 一个或多个 Collection(Edm.Single) （向量）字段被标记为可搜索。

Tip

无需使用现有索引，无需离开 Foundry 门户即可创建索引。有关详细信息，请参阅 “将工具添加到代理 ”部分。

使用支持

Azure AI Foundry 支持	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	基本代理设置	标准代理设置
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

局限性

若要在虚拟网络后面的 Foundry 门户中使用 Azure AI 搜索工具，必须使用 SDK 或 REST API 创建代理。以编程方式创建代理后，可以在门户中使用它。
Azure AI 搜索工具只能面向一个索引。若要使用多个索引，请考虑使用连接的代理，每个代理都有一个配置的索引。
具有基础智能体部署的 Foundry 资源不支持专用 Azure AI 搜索资源，也不支持禁用公用网络访问并启用专用终结点的 Azure AI 搜索。若要将专用 Azure AI 搜索工具用于代理，请使用虚拟网络注入部署标准代理。
Azure AI 搜索资源和 Foundry 代理需要位于同一租户中。

Setup

在本部分中，你将创建一个连接，连接包含你代理的 Foundry 项目和包含你索引的 Azure AI 搜索服务。

如果已将项目连接到搜索服务，请跳过本部分。

获取搜索服务连接详细信息

项目连接需要搜索服务的终结点，以及基于密钥的身份验证或使用 Microsoft Entra ID 进行的无密钥身份验证。

对于无密钥身份验证，必须启用基于角色的访问控制（RBAC），并将角色分配给项目的托管标识。尽管此方法涉及额外的步骤，但它通过消除对硬编码 API 密钥的需求来提高安全性。

选择所需身份验证方法的选项卡。

基于密钥的身份验证
无密钥身份验证

登录到 Azure 门户并选择搜索服务。
若要获取端点，请执行以下步骤：
1. 在左窗格中，选择“ 概述”。
2. 记下 URL，应如下所示 https://my-service.search.windows.net。
若要获取 API 密钥，请执行以下作：
1. 在左窗格中，选择“设置”“密钥”。>
2. 选择 “两者 ”以启用基于密钥的身份验证和无密钥身份验证，这是大多数方案建议的。
3. 记下 “管理管理密钥”下的其中一个密钥。

登录到 Azure 门户并选择搜索服务。
若要获取端点，请执行以下步骤：
1. 在左窗格中，选择“ 概述”。
2. 记下 URL，应如下所示 https://my-service.search.windows.net。
启用 RBAC：
1. 在左窗格中，选择“设置”“密钥”。>
2. 选择 “两者 ”以启用基于密钥的身份验证和无密钥身份验证，这是大多数方案建议的。
若要分配必要的角色，请执行以下步骤：
1. 在左窗格中，选择“访问控制”（IAM）。
2. 选择添加>添加角色分配。
3. 将 搜索索引数据参与者 角色分配给项目的托管标识。
4. 重复 搜索服务参与者的角色分配。

创建项目连接

下一步是使用收集的搜索服务详细信息创建项目连接。连接名称必须是搜索索引的名称。有关此步骤的详细信息，请参阅向项目添加新连接。

选择所需使用方法的选项卡。

创建以下 connections.yml 文件：

可以将 YAML 配置文件用于基于密钥的身份验证和无密钥身份验证。将 name、endpoint 和（可选的）api_key 占位符替换为搜索服务的详细信息。有关详细信息，请参阅 Azure AI 搜索连接 YAML 架构。

下面是一个基于密钥的示例：

name: my_project_acs_connection_keys
type: azure_ai_search
endpoint: https://contoso.search.windows.net/
api_key: XXXXXXXXXXXXXXX

下面是无键示例：

name: my_project_acs_connection_keyless
type: azure_ai_search
endpoint: https://contoso.search.windows.net/

然后运行以下命令：

将 my_resource 替换为包含您的项目的资源组，并将 my_project_name 替换为您的项目名称。

az ml connection create --file {connection.yml} --resource-group {my_resource_group} --workspace-name {my_project_name}

将 my_connection_name、my_endpoint 和 my_key（可选）占位符替换为你的搜索服务详细信息，然后运行以下代码：

from azure.ai.ml.entities import AzureAISearchConnection

# Create an Azure AI Search project connection
my_connection_name = "my-connection-name"
my_endpoint = "my-endpoint" # This could also be called target
my_api_keys = None # Leave blank for Authentication type = AAD

my_connection = AzureAISearchConnection(name=my_connection_name,
                                    endpoint=my_endpoint, 
                                    api_key= my_api_keys)

# Create the connection
ml_client.connections.create_or_update(my_connection)

将该工具添加到代理中

可以通过编程方式或通过 Foundry 门户将 Azure AI 搜索工具添加到代理。有关编程示例，请参阅将现有索引与 Azure AI 搜索工具配合使用。

若要通过门户添加该工具，请执行以下作：

在左窗格中，选择 “代理”。
从列表中选择您的代理，然后选择知识>添加。
选择“Azure AI 搜索”。
在 “连接到索引”下，选择 不属于此项目的索引。
在 Azure AI 搜索资源连接下，选择在上一部分中创建的项目连接。
在 Azure AI 搜索索引下，选择矢量索引。

Tip

如果没有索引，请选择“ 创建新索引”。然后，系统会提示你为索引命名，连接到数据源，选择现有的嵌入模型部署，并同意条款。

创建索引后，可以在代理内外使用它。例如，可以将索引与 Azure AI 搜索 REST API 或 SDK 配合使用。
在 “显示名称”下，输入索引的名称。
根据索引配置，选择以下搜索类型之一：
- 简单
- 语义
- 向量
- 混合（矢量 + 关键字）
- 混合 + 语义
默认情况下，Azure AI 搜索工具在所有文本字段上运行混合搜索（矢量 + 关键字）。
选择 “连接 ”，将 Azure AI 搜索工具添加到代理。