Använda ett befintligt AI Search-index med Azure AI Search-verktyget

Använd ett befintligt Azure AI Search-index med agentens Azure AI Search-verktyg.

Kommentar

Azure AI Search-index måste uppfylla följande krav:

• Indexet måste innehålla minst ett sökbart textfält (typ Edm.String)
• Indexet måste innehålla minst ett sökbart vektorfält (typ Collection(Edm.Single))
• Indexet måste använda en vektorprofil/integrerad vektorisering

Söktyper

Index utan semantisk konfiguration

• Som standard kör Azure AI Search-verktyget en hybridsökning (nyckelord + vektor) i alla textfält.
  

Index med semantisk konfiguration

• Som standard kör Azure AI Search-verktyget hybrid - och semantisk sökning i alla textfält.

Installation: Skapa en agent som kan använda ett befintligt Azure AI Search-index

Krav: Ha ett befintligt Azure AI Search-index

En förutsättning för att använda Azure AI Search-verktyget är att ha ett befintligt Azure AI Search-index. Om du inte har ett befintligt index kan du skapa ett i Azure Portal med hjälp av guiden importera och vektorisera data.

• Snabbstart: Skapa ett vektorindex med guiden importera och vektorisera data i Azure Portal

Skapa en projektanslutning till Azure AI Search-resursen med det index som du vill använda

När du har slutfört agentkonfigurationen måste du skapa en projektanslutning till Azure AI Search-resursen som innehåller det index som du vill använda.

Om du redan har anslutit AI Search-resursen som innehåller det index som du vill använda till projektet hoppar du över det här steget.

Hämta din Azure AI Search-resursanslutningsnyckel och slutpunkt

1. Få åtkomst till din Azure AI Search-resurs.

   • I Azure Portal navigerar du till ai-sökresursen som innehåller det index som du vill använda.

2. Kopiera anslutningsslutpunkten.

   • På fliken Översikt kopierar du resursens URL. URL:en ska vara i formatet https://<your-resource-name>.search.windows.net/.

3. Kontrollera att API-åtkomstkontrollen är inställd på Båda och kopiera en av nycklarna under Hantera administratörsnycklar.

   • I det vänstra navigeringsfältet rullar du ned till avsnittet Inställningar och väljer Nycklar.
   • Under avsnittet API-åtkomstkontroll kontrollerar du att alternativet Både API-nyckel och rollbaserad åtkomstkontroll är valt.
   • Om du vill att anslutningen ska använda API-nycklar för autentisering kopierar du en av nycklarna under Hantera administratörsnycklar.

Skapa en Azure AI Search-projektanslutning

Om du använder Microsoft Entra-ID för anslutningsautentiseringstypen måste du manuellt tilldela den projekthanterade identiteten rollerna Search Index Data Contributor och Search Service Contributor till Azure AI Search-resursen.

Azure CLI

Skapa följande connections.yml-fil

Du kan använda antingen en API-nyckel eller yaml-konfigurationsfil utan autentiseringsuppgifter. Ersätt platshållarna för nameoch endpointapi_key med dina Azure AI Search-resursvärden. Mer information om YAML-konfigurationsfilen finns i YAML-schemat för Azure AI Search-anslutning.

• EXEMPEL på API-nyckel:

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

• Mindre autentiseringsuppgifter

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

Kör sedan följande kommando:

Ersätt my_resource och my_project_name med resursgruppen och projektnamnet som skapades i agentkonfigurationen.

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

Python

Ersätt platshållarna my_connection_name, my_endpointoch my_key (valfritt) med anslutningsinformationen för Azure AI Search och kör följande kod för att skapa en projektanslutning till din Azure AI Search-resurs.

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. I Azure AI Foundry navigerar du till det projekt som du skapade i agentkonfigurationen. Klicka på Öppna i hanteringscenter.

2. Klicka på fliken Anslutningar och välj Lägg till anslutning.

3. Välj Azure AI Search.

4. Ange nödvändig anslutningsinformation för den Azure AI Search-resurs som du vill använda. Både hanterad identitet och nyckelbaserad autentisering stöds. När alla fält har fyllts i klickar du på Lägg till anslutning.

5. Kontrollera att anslutningen har skapats och visas nu på projektets fliken Anslutningar.

Nu när du har skapat en projektanslutning till din Azure AI Search-resurs kan du konfigurera och börja använda Azure AI Search-verktyget med SDK:n. Se fliken kodexempel för att komma igång.

Snabbstart – Använda ett befintligt Azure AI Search-index med Azure AI Search-verktyget

Den här snabbstarten visar hur du använder ett befintligt Azure AI Search-index med Azure AI Search-verktyget.

Förutsättningar

Slutför konfigurationen av Azure AI Search-verktyget.

Steg 1: Skapa en Azure AI-klient

Skapa först en Azure AI-klient med hjälp av projektets anslutningssträng.

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);

Steg 2: Hämta anslutnings-ID för Azure AI Search-resursen

Hämta anslutnings-ID för Azure AI Search-anslutningen i projektet. Du kan använda kodfragmentet för att skriva ut anslutnings-ID:t för alla Azure AI Search-anslutningar i projektet.

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

Det andra sättet att hämta anslutnings-ID:t är att navigera till projektet i Azure AI Foundry och klicka på fliken Anslutna resurser och sedan välja din Azure AI Search-resurs. I URL:en visas wsid=/subscription/your-subscription-id..., det här är det anslutnings-ID som du behöver använda. Kopiera allt som kommer efter wsid=.

Steg 3: Konfigurera Azure AI Search-verktyget

Med hjälp av anslutnings-ID:t som du fick i föregående steg kan du nu konfigurera Azure AI Search-verktyget så att det använder ditt Azure AI Search-index.

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

Steg 4: Skapa en agent med Azure AI Search-verktyget aktiverat

Ändra modellen till den som distribueras i projektet. Du hittar modellnamnet i Azure AI Foundry under fliken Modeller . Du kan också ändra agentens namn och instruktioner så att de passar dina behov.

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;

Steg 5: Ställ frågor till agenten om data i indexet

Nu när agenten har skapats ställer du frågor om data i ditt Azure AI Search-index. Exemplet förutsätter att ditt Azure AI Search-index innehåller information om hälso- och sjukvårdsplaner.

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();
    }
}