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

将现有 AI 搜索索引与 Azure AI 搜索工具配合使用

将现有的 Azure AI 搜索索引与代理的 Azure AI 搜索工具配合使用。

注意

Azure AI 搜索索引必须满足以下要求：

• 索引必须至少包含一个可搜索且可检索的文本字段（类型为 Edm.String）
• 索引必须至少包含一个可搜索矢量字段（类型为 Collection(Edm.Single)）
• 索引必须使用矢量配置文件/集成矢量化

搜索类型

没有语义配置的索引

• 默认情况下，Azure AI 搜索工具在所有文本字段上运行混合搜索（关键字 + 矢量）。
  

具有语义配置的索引

• 默认情况下，Azure AI 搜索工具会在所有文本字段上运行混合 + 语义搜索。

设置：创建可以使用现有 Azure AI 搜索索引的代理

先决条件：具有现有的 Azure AI 搜索索引

使用 Azure AI 搜索工具的先决条件是拥有现有的 Azure AI 搜索索引。 如果没有现有索引，可以使用导入和矢量化数据向导在 Azure 门户中创建一个索引。

• 快速入门：在 Azure 门户中使用导入和矢量化数据向导创建矢量索引

使用要使用的索引创建与 Azure AI 搜索资源的项目连接

完成代理设置后，必须创建与包含要使用的索引的 Azure AI 搜索资源的项目连接。

如果已连接包含要用于项目的索引的 AI 搜索资源，请跳过此步骤。

获取 Azure AI 搜索资源连接密钥和终结点

1. 访问 Azure AI 搜索资源。

   • 在 Azure 门户中，导航到包含要使用的索引的 AI 搜索资源。

2. 复制连接终结点。

   • 在“概述”选项卡中，复制资源的 URL。 URL 的格式应为 https://<your-resource-name>.search.windows.net/。

3. 验证 API 访问控制是否设置为“两者”，并在“管理管理员密钥”下复制其中一个密钥。

   • 在左侧导航栏中，向下滚动到“设置”部分，然后选择“密钥”。
   • 在“API 访问控制”部分下，确保选中 API 密钥和基于角色的访问控制“两者”的选项。
   • 如果希望连接使用 API 密钥进行身份验证，请复制管理管理密钥下的其中一个密钥。

创建 Azure AI 搜索项目连接

如果将 Microsoft Entra ID 用于连接身份验证类型，则需要手动将项目托管标识分配给 Azure AI 搜索资源的角色搜索索引数据参与者和搜索服务参与者。

Azure CLI

创建以下 connections.yml 文件

可以使用 API 密钥或无凭据 YAML 配置文件。 将 name、endpoint 和 api_key 的占位符替换为 Azure AI 搜索资源值。 有关 YAML 配置文件的详细信息，请参阅Azure AI 搜索连接 YAML 架构。

• API 密钥示例：

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

• 无凭据

  name: my_project_acs_connection_credentialless
  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}

Python

将占位符 my_connection_name、my_endpoint 和 my_key（可选）替换为 Azure AI 搜索连接详细信息，并运行以下代码来创建与 Azure AI 搜索资源的项目连接。

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)

Azure AI Foundry

1. 在 Azure AI Foundry 中，导航到在代理设置中创建的项目。 单击“在管理中心”中打开。

2. 单击“连接”选项卡，然后选择“添加连接”。

3. 选择“Azure AI 搜索”。

4. 提供要使用的 Azure AI 搜索资源所需的连接详细信息。 同时支持托管标识和基于密钥的身份验证。 填充所有字段后，单击“添加连接”。

5. 验证连接是否已成功创建，现在显示在项目的“连接”选项卡中。

创建与 Azure AI 搜索资源的项目连接后，可以配置并开始使用 SDK 的 Azure AI 搜索工具。 请参阅代码示例选项卡以开始使用。

快速入门 - 将现有的 Azure AI 搜索索引与 Azure AI 搜索工具配合使用

本快速入门介绍如何将现有的 Azure AI 搜索索引与 Azure AI 搜索工具配合使用。

先决条件

完成 Azure AI 搜索工具设置。

步骤 1：创建 Azure AI 客户端

首先，使用项目的连接字符串创建 Azure AI 客户端。

Python

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.projects.models import AzureAISearchTool

# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery" 
# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
# Project Connection example: eastus.api.azureml.ms;my-subscription-id;my-resource-group;my-hub-name

connection_string = os.environ["PROJECT_CONNECTION_STRING"] 

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=connection_string,
)

C#

using System;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Core.TestFramework;
using NUnit.Framework;
using System.Collections.Generic;

// Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
// At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
// Customer needs to login to Azure subscription via Azure CLI and set the environment variables
var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
var clientOptions = new AIProjectClientOptions();

// Adding the custom headers policy
clientOptions.AddPolicy(new CustomHeadersPolicy(), HttpPipelinePosition.PerCall);
var projectClient = new AIProjectClient(connectionString, new DefaultAzureCredential(), clientOptions);

步骤 2：获取 Azure AI 搜索资源的连接 ID

获取项目中 Azure AI 搜索连接的连接 ID。 可以使用代码片段打印项目中所有 Azure AI 搜索连接的连接 ID。

Python

# AI Search resource connection ID
# This code prints out the connection ID of all the Azure AI Search connections in the project
# If you have more than one AI search connection, make sure to select the correct one that contains the index you want to use.
conn_list = project_client.connections.list()
conn_id = ""
for conn in conn_list:
    if conn.connection_type == "AZURE_AI_SEARCH":
        print(f"Connection ID: {conn.id}")

C#

ListConnectionsResponse connections = await projectClient.GetConnectionsClient().GetConnectionsAsync(ConnectionType.AzureAISearch).ConfigureAwait(false);

        if (connections?.Value == null || connections.Value.Count == 0)
        {
            throw new InvalidOperationException("No connections found for the Azure AI Search.");
        }

获取连接 ID 的第二种方法是导航到 Azure AI Foundry 中的项目，并单击“已连接资源”选项卡，然后选择 Azure AI 搜索资源。 在 URL 中，可以看到 wsid=/subscription/your-subscription-id...，这是需要使用的连接 ID。 复制 wsid= 之后的所有内容。

步骤 3：配置 Azure AI 搜索工具

使用上一步骤中获取的连接 ID，现在可以将 Azure AI 搜索工具配置为使用 Azure AI 搜索索引。

Python

# TO DO: replace this value with the connection ID of the search index
conn_id =  "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-azure-ai-search-connection-name>"

# Initialize agent AI search tool and add the search index connection ID and index name
# TO DO: replace <your-index-name> with the name of the index you want to use
ai_search = AzureAISearchTool(index_connection_id=conn_id, index_name="<your-index-name>")

C#

// TO DO: replace this value with the connection ID of the search index
ConnectionResponse connection = connections.Value[0];

// Initialize agent Azure AI search tool and add the search index connection ID and index name
// TO DO: replace <your-index-name> with the name of the index you want to use
ToolResources searchResource = new ToolResources
{
    AzureAISearch = new AzureAISearchResource
    {
        IndexList = { new IndexResource(connection.Id, "<your-index-name>") }
    }
};

步骤 4：创建启用了 Azure AI 搜索工具的代理

将模型更改为项目中部署的模型。 可以在“模型”选项卡下的 Azure AI Foundry 中找到模型名称。还可以更改代理的名称和说明，以满足你的需求。

Python

agent = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-assistant",
    instructions="You are a helpful assistant",
    tools=ai_search.definitions,
    tool_resources = ai_search.resources,
)
print(f"Created agent, ID: {agent.id}")

C#

AgentsClient agentClient = projectClient.GetAgentsClient();

Response<Agent> agentResponse = await agentClient.CreateAgentAsync(
    model: "gpt-4o-mini",
    name: "my-assistant",
    instructions: "You are a helpful assistant.",
    tools: new List<ToolDefinition> { new AzureAISearchToolDefinition() },
    toolResources: searchResource);
Agent agent = agentResponse.Value;

步骤 5：询问代理有关索引中的数据的问题

创建代理后，请询问有关 Azure AI 搜索索引中的数据的问题。 该示例假定 Azure AI 搜索索引包含有关医疗保健计划的信息。

Python

# Create a thread
thread = project_client.agents.create_thread()
print(f"Created thread, thread ID: {thread.id}")
 
# Create a message
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="what are my health insurance plan coverage types?",
)
print(f"Created message, message ID: {message.id}")
    
# Run the agent
run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Run finished with status: {run.status}")
 
if run.status == "failed":
    # Check if you got "Rate limit is exceeded.", then you want to get more quota
    print(f"Run failed: {run.last_error}")

# Get messages from the thread 
messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")
    
assistant_message = ""
for message in messages.data:
    if message["role"] == "assistant":
        assistant_message = message["content"][0]["text"]["value"]

# Get the last message from the sender
print(f"Assistant response: {assistant_message}")

C#

// Create thread for communication
Response<AgentThread> threadResponse = await agentClient.CreateThreadAsync();
AgentThread thread = threadResponse.Value;

// Create message to thread
Response<ThreadMessage> messageResponse = await agentClient.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "Hello, send an email with the datetime and weather information in New York?");
ThreadMessage message = messageResponse.Value;

// Run the agent
Response<ThreadRun> runResponse = await agentClient.CreateRunAsync(thread, agent);

do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    runResponse = await agentClient.GetRunAsync(thread.Id, runResponse.Value.Id);
}
while (runResponse.Value.Status == RunStatus.Queued
    || runResponse.Value.Status == RunStatus.InProgress);

Response<PageableList<ThreadMessage>> afterRunMessagesResponse
    = await agentClient.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages)
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        else if (contentItem is MessageImageFileContent imageFileItem)
        {
            Console.Write($"<image from ID: {imageFileItem.FileId}");
        }
        Console.WriteLine();
    }
}