搭配 Azure AI 搜尋工具使用現有的 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 組態檔。 以您的 Azure AI 搜尋資源值取代 和 endpointapi_key 的佔位元name。 如需 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_project_name 取代my_resource為您在代理程式設定中建立的資源群組和項目名稱。

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

Python

以您的 Azure AI 搜尋連線詳細資料取代佔位元 my_connection_name元、 my_endpoint和 my_key （選擇性），然後執行下列程式代碼來建立 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 搜尋資源的項目連線，您可以設定及開始使用 Azure AI 搜尋工具搭配 SDK。 請參閱程式代碼範例索引標籤以開始使用。

快速入門 – 搭配 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 搜尋資源的連線標識碼

取得專案中 Azure AI 搜尋連線的連線的連線標識碼。 您可以使用代碼段來列印專案中所有 Azure AI 搜尋連線的連接識別碼。

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.");
        }

取得連線標識碼的第二種方式是流覽至 Azure AI Foundry 中的專案，然後按兩下 [ 已連線的資源 ] 索引標籤，然後選取您的 Azure AI 搜尋資源。 在 URL 中，您會看到 wsid=/subscription/your-subscription-id...，這是您需要使用的聯機標識碼。 複製 wsid=之後的所有專案。

步驟 3：設定 Azure AI 搜尋工具

使用您在上一個步驟中取得的連線標識碼，您現在可以將 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();
    }
}