Korzystanie z istniejącego indeksu wyszukiwania sztucznej inteligencji za pomocą narzędzia azure AI Search

Użyj istniejącego indeksu usługi Azure AI Search z narzędziem azure AI Search agenta.

Uwaga

Indeksy usługi Azure AI Search muszą spełniać następujące wymagania:

• Indeks musi zawierać co najmniej jedno pole tekstowe umożliwiające wyszukiwanie i pobieranie (wpisz ciąg Edm.String)
• Indeks musi zawierać co najmniej jedno pole wektora z możliwością wyszukiwania (typ Collection(Edm.Single))
• Indeks musi używać profilu wektorowego/zintegrowanej wektoryzacji

Typy wyszukiwania

Indeks bez konfiguracji semantycznej

• Domyślnie narzędzie Azure AI Search uruchamia wyszukiwanie hybrydowe (słowo kluczowe + wektor) we wszystkich polach tekstowych.
  

Indeksowanie z konfiguracją semantyczną

• Domyślnie narzędzie azure AI Search uruchamia wyszukiwanie hybrydowe i semantyczne we wszystkich polach tekstowych.

Konfiguracja: tworzenie agenta, który może używać istniejącego indeksu usługi Azure AI Search

Wymaganie wstępne: masz istniejący indeks usługi Azure AI Search

Warunkiem wstępnym korzystania z narzędzia azure AI Search jest posiadanie istniejącego indeksu usługi Azure AI Search. Jeśli nie masz istniejącego indeksu, możesz go utworzyć w witrynie Azure Portal przy użyciu kreatora importowania i wektoryzacji danych.

• Szybki start: tworzenie indeksu wektorowego za pomocą kreatora importowania i wektoryzacji danych w witrynie Azure Portal

Tworzenie połączenia projektu z zasobem usługi Azure AI Search za pomocą indeksu, którego chcesz użyć

Po zakończeniu konfiguracji agenta należy utworzyć połączenie projektu z zasobem usługi Azure AI Search zawierającym indeks, którego chcesz użyć.

Jeśli masz już połączony zasób wyszukiwania sztucznej inteligencji zawierający indeks, którego chcesz użyć do projektu, pomiń ten krok.

Uzyskiwanie klucza połączenia zasobu usługi Azure AI Search i punktu końcowego

1. Uzyskaj dostęp do zasobu usługi Azure AI Search.

   • W witrynie Azure Portal przejdź do zasobu wyszukiwania sztucznej inteligencji zawierającego indeks, którego chcesz użyć.

2. Skopiuj punkt końcowy połączenia.

   • Na karcie Przegląd skopiuj adres URL zasobu. Adres URL powinien mieć format https://<your-resource-name>.search.windows.net/.

3. Sprawdź, czy kontrola dostępu interfejsu API jest ustawiona na wartość Zarówno , jak i skopiuj jeden z kluczy w obszarze Zarządzanie kluczami administratora.

   • Na pasku nawigacyjnym po lewej stronie przewiń w dół do sekcji Ustawienia i wybierz pozycję Klucze.
   • W sekcji Kontrola dostępu do interfejsu API upewnij się, że wybrano opcję Zarówno klucz interfejsu API, jak i kontrola dostępu oparta na rolach.
   • Jeśli chcesz, aby połączenie używało kluczy interfejsu API do uwierzytelniania, skopiuj jeden z kluczy w obszarze Zarządzanie kluczami administratora.

Tworzenie połączenia projektu usługi Azure AI Search

Jeśli używasz identyfikatora Entra firmy Microsoft dla typu uwierzytelniania połączenia, musisz ręcznie przypisać tożsamość zarządzaną projektu role Współautor danych indeksu wyszukiwania i Współautor usługi wyszukiwania do zasobu usługi Azure AI Search.

Interfejs wiersza polecenia platformy Azure

Utwórz następujący plik connections.yml

Możesz użyć klucza interfejsu API lub pliku konfiguracji YAML bez poświadczeń. Zastąp symbole zastępcze wartościami namei endpointapi_key wartościami zasobów usługi Azure AI Search. Aby uzyskać więcej informacji na temat pliku konfiguracji YAML, zobacz schemat YAML połączenia usługi Azure AI Search.

• Przykład klucza interfejsu API:

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

• Bez poświadczeń

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

Następnie uruchom następujące polecenie:

Zastąp my_resource wartości i my_project_name nazwą grupy zasobów i projektu utworzonej w konfiguracji agenta.

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

Python

Zastąp symbole my_connection_namezastępcze , my_endpointi my_key (opcjonalnie) szczegółami połączenia usługi Azure AI Search i uruchom następujący kod, aby utworzyć połączenie projektu z zasobem usługi Azure AI Search.

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. W usłudze Azure AI Foundry przejdź do projektu utworzonego w konfiguracji agenta. Kliknij pozycję Otwórz w centrum zarządzania.

2. Kliknij kartę Połączenia i wybierz pozycję Dodaj połączenie.

3. Wybierz pozycję Azure AI Search.

4. Podaj wymagane szczegóły połączenia dla zasobu usługi Azure AI Search, którego chcesz użyć. Obsługiwane są zarówno tożsamości zarządzane, jak i uwierzytelnianie oparte na kluczach. Po wypełnieniu wszystkich pól kliknij pozycję Dodaj połączenie.

5. Sprawdź, czy połączenie zostało pomyślnie utworzone, a teraz jest wyświetlane na karcie Połączenia projektu.

Po utworzeniu połączenia projektu z zasobem usługi Azure AI Search możesz skonfigurować i rozpocząć korzystanie z narzędzia Azure AI Search za pomocą zestawu SDK. Zobacz kartę Przykłady kodu, aby rozpocząć pracę.

Szybki start — korzystanie z istniejącego indeksu usługi Azure AI Search za pomocą narzędzia azure AI Search

W tym przewodniku Szybki start pokazano, jak używać istniejącego indeksu usługi Azure AI Search za pomocą narzędzia azure AI Search.

Wymagania wstępne

Ukończ konfigurację narzędzia azure AI Search.

Krok 1. Tworzenie klienta sztucznej inteligencji platformy Azure

Najpierw utwórz klienta usługi Azure AI przy użyciu parametry połączenia projektu.

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

Krok 2. Pobieranie identyfikatora połączenia dla zasobu usługi Azure AI Search

Pobierz identyfikator połączenia połączenia usługi Azure AI Search w projekcie. Możesz użyć fragmentu kodu, aby wydrukować identyfikator połączenia wszystkich połączeń usługi Azure AI Search w projekcie.

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

Drugim sposobem uzyskania identyfikatora połączenia jest przejście do projektu w narzędziu Azure AI Foundry i kliknięcie karty Połączone zasoby , a następnie wybranie zasobu usługi Azure AI Search. W adresie URL zostanie wyświetlony identyfikator wsid=/subscription/your-subscription-id..., jest to identyfikator połączenia, którego należy użyć. Skopiuj wszystko, co następuje po wsid=.

Krok 3. Konfigurowanie narzędzia azure AI Search

Korzystając z identyfikatora połączenia, który został wyświetlony w poprzednim kroku, możesz teraz skonfigurować narzędzie Azure AI Search do korzystania z indeksu usługi Azure AI Search.

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

Krok 4. Tworzenie agenta z włączonym narzędziem azure AI Search

Zmień model na wdrożony w projekcie. Nazwę modelu można znaleźć w narzędziu Azure AI Foundry na karcie Modele . Możesz również zmienić nazwę i instrukcje agenta, aby odpowiadały Twoim potrzebom.

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;

Krok 5. Zadawanie pytań agenta dotyczących danych w indeksie

Po utworzeniu agenta zadaj mu pytania dotyczące danych w indeksie usługi Azure AI Search. W tym przykładzie przyjęto założenie, że indeks usługi Azure AI Search zawiera informacje o planach opieki zdrowotnej.

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