Een bestaande AI Search-index gebruiken met het Azure AI Search-hulpprogramma

Gebruik een bestaande Azure AI Search-index met het Azure AI Search-hulpprogramma van de agent.

Notitie

Azure AI Search-indexen moeten voldoen aan de volgende vereisten:

• De index moet ten minste één doorzoekbaar en ophaalbaar tekstveld bevatten (type Edm.String)
• De index moet ten minste één doorzoekbaar vectorveld bevatten (type Collection(Edm.Single))
• De index moet een vectorprofiel/geïntegreerde vectorisatie gebruiken

Zoektypen

Index zonder semantische configuratie

• Het hulpprogramma Azure AI Search voert standaard een hybride zoekopdracht (trefwoord en vector) uit op alle tekstvelden.
  

Indexeren met semantische configuratie

• Het Azure AI Search-hulpprogramma voert standaard hybride en semantische zoekopdrachten uit op alle tekstvelden.

Gebruiksondersteuning

Ondersteuning voor Azure AI Foundry	Python SDK	C# SDK	JavaScript SDK	REST-API	Basisagent instellen	Standaardagent instellen
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Installatie: Een agent maken die een bestaande Azure AI Search-index kan gebruiken

Vereiste: een bestaande Azure AI Search-index hebben

Een vereiste voor het gebruik van het Azure AI Search-hulpprogramma is om een bestaande Azure AI Search-index te hebben. Als u geen bestaande index hebt, kunt u er een maken in Azure Portal met behulp van de wizard Gegevens importeren en vectoriseren.

• Quickstart: Een vectorindex maken met de wizard Gegevens importeren en vectoriseren in Azure Portal

Maak een projectverbinding met de Azure AI Search-resource met de index die u wilt gebruiken

Nadat u de agentinstallatie hebt voltooid, moet u een projectverbinding maken met de Azure AI Search-resource die de index bevat die u wilt gebruiken.

Als u de AI Search-resource die de index bevat die u wilt gebruiken voor uw project al hebt verbonden, slaat u deze stap over.

De verbindingssleutel en het eindpunt van uw Azure AI Search-resource ophalen

1. Open uw Azure AI Search-resource.

   • Navigeer in Azure Portal naar de AI Search-resource die de index bevat die u wilt gebruiken.

2. Kopieer het verbindingseindpunt.

   • Kopieer op het tabblad Overzicht de URL van uw resource. De URL moet de indeling https://<your-resource-name>.search.windows.net/hebben.

3. Controleer of API-toegangsbeheer is ingesteld op Beide en kopieer een van de sleutels onder Beheer van beheersleutels.

   • Schuif in de linkernavigatiebalk omlaag naar de sectie Instellingen en selecteer Sleutels.
   • Controleer in de sectie API-toegangsbeheer of de optie Api-sleutel en op rollen gebaseerd toegangsbeheer is geselecteerd.
   • Als u wilt dat de verbinding API-sleutels gebruikt voor verificatie, kopieert u een van de sleutels onder Beheer van beheersleutels.

Een Azure AI Search-projectverbinding maken

Als u Microsoft Entra ID gebruikt voor het verificatietype voor de verbinding, moet u de door het project beheerde identiteit handmatig toewijzen aan de rollen Search Index Data Contributor en Search Service Contributor aan de Azure AI Search-resource.

Azure-CLI

Maak het volgende connections.yml-bestand

U kunt een API-sleutel of een YAML-configuratiebestand met referenties gebruiken. Vervang de tijdelijke aanduidingen voor nameendpoint en api_key door uw Azure AI Search-resourcewaarden. Zie het YAML-schema van de Azure AI Search-verbinding voor meer informatie over het YAML-configuratiebestand van de YAML-verbinding.

• Voorbeeld van API-sleutel:

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

• Referentieloos

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

Voer vervolgens de volgende opdracht uit:

Vervang en vervang my_resource door my_project_name de resourcegroep en projectnaam die u hebt gemaakt in de agentinstallatie.

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

Python

Vervang de tijdelijke aanduidingen my_connection_nameen my_endpointmy_key (optioneel) door de verbindingsgegevens van Azure AI Search en voer de volgende code uit om een projectverbinding met uw Azure AI Search-resource te maken.

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. Navigeer in Azure AI Foundry naar het project dat u hebt gemaakt in de agentinstallatie. Klik op Openen in het beheercentrum.

2. Klik op het tabblad Verbindingen en selecteer Verbinding toevoegen.

3. Selecteer Azure AI Search.

4. Geef de vereiste verbindingsgegevens op voor de Azure AI Search-resource die u wilt gebruiken. Zowel beheerde identiteit als verificatie op basis van sleutels worden ondersteund. Zodra alle velden zijn ingevuld, klikt u op Verbinding toevoegen.

5. Controleer of de verbinding is gemaakt en nu wordt weergegeven op het tabblad Verbindingen van het project.

Nu u een projectverbinding met uw Azure AI Search-resource hebt gemaakt, kunt u het hulpprogramma Azure AI Search configureren en gebruiken met de SDK. Zie het tabblad Codevoorbeelden om aan de slag te gaan.

Het Azure AI Search-hulpprogramma toevoegen aan een agent

u kunt het hulpprogramma Azure AI Search programmatisch toevoegen aan een agent met behulp van de codevoorbeelden bovenaan dit artikel of de Azure AI Foundry-portal. Als u de portal wilt gebruiken:

1. Schuif in het scherm Maken en foutopsporing voor uw agent omlaag in het deelvenster Setup aan de rechterkant. Selecteer vervolgens Toevoegen.

   

2. Selecteer Azure AI Search en volg de aanwijzingen om het hulpprogramma toe te voegen.

   

Quickstart: een bestaande Azure AI Search-index gebruiken met het Azure AI Search-hulpprogramma

In deze quickstart ziet u hoe u een bestaande Azure AI Search-index gebruikt met het hulpprogramma Azure AI Search.

Vereisten

Voltooi de installatie van het hulpprogramma Azure AI Search.

Stap 1: Een Azure AI-client maken

Maak eerst een Azure AI-client met behulp van de verbindingsreeks van uw project.

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

JavaScript

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
);

REST API

Volg de quickstart voor de REST API om de juiste waarden in te stellen voor de omgevingsvariabelen AZURE_AI_AGENTS_TOKEN en AZURE_AI_AGENTS_ENDPOINT.

Stap 2: De verbindings-id voor de Azure AI Search-resource ophalen

Haal de verbindings-id op van de Azure AI Search-verbinding in het project. U kunt het codefragment gebruiken om de verbindings-id van alle Azure AI Search-verbindingen in het project af te drukken.

Python

# AI Search resource connection ID
# This code looks for the AI Search Connection ID and saves it as variable conn_id

# If you have more than one AI search connection, try to establish the value in your .env file.
# Extract the connection list.
conn_list = project_client.connections._list_connections()["value"]
conn_id = ""

# Search in the metadata field of each connection in the list for the azure_ai_search type and get the id value to establish the variable
for conn in conn_list:
    metadata = conn["properties"].get("metadata", {})
    if metadata.get("type", "").upper() == "AZURE_AI_SEARCH":
        conn_id = conn["id"]
        break

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

JavaScript

const cognitiveServicesConnectionName = "<cognitiveServicesConnectionName>";
const cognitiveServicesConnection = await client.connections.getConnection(
  cognitiveServicesConnectionName,
);

REST API

Volg de volgende sectie over het ophalen van de verbindings-id van Azure AI Foundry.

De tweede manier om de verbindings-id op te halen, is door naar het project in Azure AI Foundry te gaan en op het tabblad Verbonden resources te klikken en vervolgens uw Azure AI Search-resource te selecteren. In de URL ziet u de wsid=/subscription/your-subscription-id..., dit is de verbindings-id die u moet gebruiken. Kopieer alles wat na wsid= komt.

Stap 3: Het hulpprogramma Azure AI Search configureren

Met behulp van de verbindings-id die u in de vorige stap hebt gekregen, kunt u nu het hulpprogramma Azure AI Search configureren om uw Azure AI Search-index te gebruiken.

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

JavaScript

const azureAISearchTool = ToolUtility.createAzureAISearchTool(
  cognitiveServicesConnection.id,
  cognitiveServicesConnection.name,
);

// Create agent with the Azure AI search tool
const agent = await client.agents.createAgent("gpt-4o-mini", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [azureAISearchTool.definition],
  toolResources: azureAISearchTool.resources,
});
console.log(`Created agent, agent ID : ${agent.id}`);

REST API

Niet van toepassing

Stap 4: Een agent maken waarvoor het Azure AI Search-hulpprogramma is ingeschakeld

Wijzig het model in het model dat in uw project is geïmplementeerd. U vindt de naam van het model in Azure AI Foundry op het tabblad Modellen . U kunt ook de naam en instructies van de agent aanpassen aan uw behoeften.

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;

JavaScript

const agent = await client.agents.createAgent("gpt-4o-mini", {
  name: "my-agent",
  instructions: "You are a helpful agent",
  tools: [azureAISearchTool.definition],
  toolResources: azureAISearchTool.resources,
});
console.log(`Created agent, agent ID : ${agent.id}`);

REST API

curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "instructions": "You are a helpful agent.",
        "name": "my-agent",
        "tools": [
          {"type": "azure_ai_search"}
        ],
        "model": "gpt-4o-mini",
        "tool_resources": {
            "azure_ai_search": {
              "indexes": [
                  {
                      "index_connection_id": "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-azure-ai-search-connection-name>",
                      "index_name": "<your-index-name>",
                      "query_type": "semantic"
                  }
              ]
            }
        }
      }'

Stap 5: Stel de agent vragen over gegevens in de index

Nu de agent is gemaakt, stelt u deze vragen over de gegevens in uw Azure AI Search-index. In het voorbeeld wordt ervan uitgegaan dat uw Azure AI Search-index informatie bevat over gezondheidsplannen.

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,
    "what are my health insurance plan coverage types?");
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();
    }
}

JavaScript

  // create a thread
  const thread = await client.agents.createThread();

  // add a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "what are my health insurance plan coverage types?",
  });

  // Intermission is now correlated with thread
  // Intermission messages will retrieve the message just added

  // create a run
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

REST API

Een thread maken

curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Een gebruikersvraag toevoegen aan de thread

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "what are my health insurance plan coverage types?"
    }'

De thread uitvoeren

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

De status van de uitvoering ophalen

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Het antwoord van de agent ophalen

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"