Azure AI Agent Service-hulpprogramma voor het zoeken van bestanden

Bestandszoekopdrachten verbeteren agents met kennis van buiten het model, zoals bedrijfseigen productgegevens of documenten die door uw gebruikers worden verstrekt.

Notitie

Met behulp van de standaardagentinstallatie zorgt het verbeterde hulpprogramma voor het zoeken van bestanden ervoor dat uw bestanden in uw eigen opslag blijven en dat uw Azure AI Search-resource wordt gebruikt om ze op te nemen, zodat u de volledige controle over uw gegevens behoudt.

Bestandsbronnen

• Lokale bestanden uploaden
• Azure Blob-opslag

Afhankelijkheid van agentinstallatie

Basisagent instellen

Het hulpprogramma voor het zoeken van bestanden heeft dezelfde functionaliteit als Azure OpenAI-assistenten. Door Microsoft beheerde zoek- en opslagbronnen worden gebruikt.

• Geüploade bestanden worden opgeslagen in door Microsoft beheerde opslag
• Er wordt een vectorarchief gemaakt met behulp van een door Microsoft beheerde zoekresource

Standaardagent instellen

Het hulpprogramma voor het zoeken van bestanden maakt gebruik van de Azure AI Search- en Azure Blob Storage-resources die u hebt verbonden tijdens het instellen van de agent.

• Geüploade bestanden worden opgeslagen in uw verbonden Azure Blob Storage-account
• Vector stores worden gemaakt met behulp van uw verbonden Azure AI Search-resource
  
  

Voor beide agentconfiguraties verwerkt Azure OpenAI het hele opnameproces, waaronder:

• Documenten automatisch parseren en segmenteren
• Insluitingen genereren en opslaan
• Door zowel vector- als trefwoordzoekopdrachten te gebruiken om relevante inhoud voor gebruikersquery's op te halen.

Er is geen verschil in de code tussen de twee setups; de enige variatie is waar uw bestanden en gemaakte vectorarchieven worden opgeslagen.

Hoe het werkt

Het hulpprogramma voor het zoeken van bestanden implementeert verschillende aanbevolen procedures voor het ophalen van bestanden, zodat u de juiste gegevens uit uw bestanden kunt extraheren en de antwoorden van het model kunt uitbreiden. Het hulpprogramma voor het zoeken van bestanden:

• Hiermee worden gebruikersquery's herschreven om ze te optimaliseren voor zoekopdrachten.
• Hiermee worden complexe gebruikersquery's opgesplitst in meerdere zoekopdrachten die parallel kunnen worden uitgevoerd.
• Voert zowel trefwoord- als semantische zoekopdrachten uit in zowel agent- als threadvectorarchieven.
• Hiermee worden zoekresultaten opnieuw geherrankerd om de meest relevante resultaten te kiezen voordat het uiteindelijke antwoord wordt gegenereerd.
• Het hulpprogramma voor het zoeken van bestanden gebruikt standaard de volgende instellingen:
  • Segmentgrootte: 800 tokens
  • Segment overlap: 400 tokens
  • Insluitmodel: tekst-insluiten-3-groot bij 256 dimensies
  • Maximum aantal segmenten toegevoegd aan context: 20

Vectorarchieven

Vector Store-objecten geven het hulpprogramma voor het zoeken van bestanden de mogelijkheid om uw bestanden te doorzoeken. Als u een bestand toevoegt aan een vectorarchief, worden het bestand automatisch geparseerd, segmenten, ingesloten en opgeslagen in een vectordatabase die geschikt is voor trefwoorden en semantische zoekopdrachten. Elk vectorarchief kan maximaal 10.000 bestanden bevatten. Vectorarchieven kunnen worden gekoppeld aan zowel agents als threads. Op dit moment kunt u maximaal één vectorarchief koppelen aan een agent en maximaal één vectorarchief aan een thread.

Op dezelfde manier kunnen deze bestanden worden verwijderd uit een vectoropslag door:

• Het vectoropslag bestandsobject te verwijderen of,
• Door het onderliggende bestandsobject te verwijderen, waardoor het bestand wordt verwijderd uit alle vector_store en code_interpreter configuraties voor alle agents en threads in uw organisatie

De maximale bestandsgrootte is 512 MB. Elk bestand mag niet meer dan 5.000.000 tokens per bestand bevatten (automatisch berekend wanneer u een bestand bijvoegt).

Gereedheid voor vectoropslag garanderen voordat er uitvoeringen worden gemaakt

We raden u ten zeerste aan ervoor te zorgen dat alle bestanden in een vector_store volledig worden verwerkt voordat u een uitvoering maakt. Dit zorgt ervoor dat alle gegevens in uw vectorarchief doorzoekbaar zijn. U kunt controleren op gereedheid voor vectoropslag met behulp van de polling-helpers in de SDK's of door het vectorarchiefobject handmatig te peilen om ervoor te zorgen dat de status is voltooid.

Als terugval is er een maximale wachttijd van 60 seconden in het uitvoeringsobject wanneer het vectorarchief van de thread bestanden bevat die nog worden verwerkt. Dit is om ervoor te zorgen dat bestanden die uw gebruikers uploaden in een thread een volledig doorzoekbaar zijn voordat de uitvoering wordt uitgevoerd. Deze terugvalwacht is niet van toepassing op het vectorarchief van de agent.

Quickstart: Lokale bestanden uploaden met het zoeken naar bestanden

In dit voorbeeld gebruiken we Azure AI Agent Service om een agent te maken die kan helpen bij het beantwoorden van vragen over informatie die u uploadt vanuit lokale bestanden.

Vereisten

1. Voltooi de installatie van de agent.

2. Zorg ervoor dat u de rol Opslagblobgegevensbijdrager hebt voor het opslagaccount van uw project.

3. Zorg ervoor dat u de rol Azure AI Developer in uw project hebt.

Stap 1: Een projectclient maken

Maak een clientobject dat de verbindingsreeks bevat om verbinding te maken met uw AI-project en andere resources.

Python

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FileSearchTool, MessageAttachment, FilePurpose
from azure.identity import DefaultAzureCredential


# 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

credential = DefaultAzureCredential()
project_client = AIProjectClient.from_connection_string(
    credential=credential, conn_str=os.environ["PROJECT_CONNECTION_STRING"] 
)

C#

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

// 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;
AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());

Stap 2: Bestanden uploaden en toevoegen aan een Vector Store

Voor toegang tot uw bestanden gebruikt het hulpprogramma voor het zoeken van bestanden het vectorarchiefobject. Upload uw bestanden en maak een vectorarchief. Nadat u het vectorarchief hebt gemaakt, controleert u de status totdat alle bestanden de status hebben in_progress bereikt om ervoor te zorgen dat alle inhoud volledig wordt verwerkt. De SDK biedt helpers voor het uploaden en peilen.

Python

# We will upload the local file and will use it for vector store creation.

#upload a file
file = project_client.agents.upload_file_and_poll(file_path='./data/product_catelog.md', purpose=FilePurpose.AGENTS)
print(f"Uploaded file, file ID: {file.id}")

# create a vector store with the file you uploaded
vector_store = project_client.agents.create_vector_store_and_poll(file_ids=[file.id], name="my_vectorstore")
print(f"Created vector store, vector store ID: {vector_store.id}")

C#

// Upload a file and wait for it to be processed
File.WriteAllText(
    path: "sample_file_for_upload.txt",
    contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
Response<AgentFile> uploadAgentFileResponse = await client.UploadFileAsync(
    filePath: "sample_file_for_upload.txt",
    purpose: AgentFilePurpose.Agents);

AgentFile uploadedAgentFile = uploadAgentFileResponse.Value;

// Create a vector store with the file and wait for it to be processed.
// If you do not specify a vector store, create_message will create a vector store with a default expiration policy of seven days after they were last active
VectorStore vectorStore = await client.CreateVectorStoreAsync(
    fileIds:  new List<string> { uploadedAgentFile.Id },
    name: "my_vector_store");

Stap 3: Een agent maken en zoeken naar bestanden inschakelen

Als u de bestanden toegankelijk wilt maken voor uw agent, maakt u een FileSearchTool object met de vector_store id en koppelt tools u deze aan de tool_resources agent.

Python

# create a file search tool
file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])

# notices that FileSearchTool as tool and tool_resources must be added or the agent will be unable to search the file
agent = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-agent",
    instructions="You are a helpful agent",
    tools=file_search_tool.definitions,
    tool_resources=file_search_tool.resources,
)
print(f"Created agent, agent ID: {agent.id}")

C#

FileSearchToolResource fileSearchToolResource = new FileSearchToolResource();
fileSearchToolResource.VectorStoreIds.Add(vectorStore.Id);

// Create an agent with toolResources and process assistant run
Response<Agent> agentResponse = await client.CreateAgentAsync(
        model: "gpt-4o-mini",
        name: "SDK Test Agent - Retrieval",
        instructions: "You are a helpful agent that can help fetch data from files you know about.",
        tools: new List<ToolDefinition> { new FileSearchToolDefinition() },
        toolResources: new ToolResources() { FileSearch = fileSearchToolResource });
Agent agent = agentResponse.Value;

Stap 4: Een thread maken

U kunt ook bestanden toevoegen als berichtbijlagen in uw thread. Als u dit doet, wordt er nog een vector_store gekoppeld aan de thread gemaakt, of als er al een vectorarchief aan deze thread is gekoppeld, worden de nieuwe bestanden gekoppeld aan het bestaande threadvectorarchief. Wanneer u een run op deze thread maakt, wordt met het hulpprogramma voor het zoeken van bestanden query's uitgevoerd op zowel de vector_store agent als op de vector_store thread.

Python

# Create a thread
thread = project_client.agents.create_thread()
print(f"Created thread, thread ID: {thread.id}")

# Upload the user provided file as a messsage attachment
message_file = project_client.agents.upload_file_and_poll(file_path='product_info_1.md', purpose=FilePurpose.AGENTS)
print(f"Uploaded file, file ID: {message_file.id}")

# Create a message with the file search attachment
# Notice that vector store is created temporarily when using attachments with a default expiration policy of seven days.
attachment = MessageAttachment(file_id=message_file.id, tools=FileSearchTool().definitions)
message = project_client.agents.create_message(
    thread_id=thread.id, role="user", content="What feature does Smart Eyewear offer?", attachments=[attachment]
)
print(f"Created message, message ID: {message.id}")

C#

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

// Create message to thread
Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "Can you give me the documented codes for 'banana' and 'orange'?");
ThreadMessage message = messageResponse.Value;

Stap 5: Een uitvoering maken en de uitvoer controleren

Maak een uitvoering en kijk of het model het hulpprogramma voor het zoeken van bestanden gebruikt om een antwoord te geven op de vraag van de gebruiker.

Python

run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
print(f"Created run, run ID: {run.id}")

project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")

project_client.agents.delete_agent(agent.id)
print("Deleted agent")

messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")

C#

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

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

Response<PageableList<ThreadMessage>> afterRunMessagesResponse
    = await client.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();
    }
}

Quickstart: bestaande bestanden gebruiken in Azure Blob Storage met het zoeken naar bestanden

In dit voorbeeld gebruiken we Azure AI Agent Service om een agent te maken die u kan helpen bij het beantwoorden van vragen over gegevens uit bestanden in Azure Blob Storage.

Vereisten

1. Voltooi de standaardagentinstallatie.

2. Zorg ervoor dat u de rol Opslagblobgegevensbijdrager hebt voor het opslagaccount van uw project.

3. Zorg ervoor dat u de rol Azure AI Developer in uw project hebt.

Belangrijk

Zoeken in bestanden met Blob Storage wordt alleen ondersteund door de standaardagentinstallatie.

Stap 1: Een projectclient maken

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FileSearchTool, VectorStoreDataSource, VectorStoreDataSourceAssetType
from azure.identity import DefaultAzureCredential


# 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

credential = DefaultAzureCredential()
project_client = AIProjectClient.from_connection_string(
    credential=credential, conn_str=os.environ["PROJECT_CONNECTION_STRING"]
)

Stap 2: Lokale bestanden uploaden naar uw Azure Blob Storage-container

Upload uw lokale bestand naar de Azure Blob Storage-container van het project. Dit is hetzelfde opslagaccount dat u tijdens de installatie met uw agent hebt verbonden. Wanneer u extra agents binnen hetzelfde project maakt, kunt u de asset-URI's hergebruiken van eerder geüploade bestanden die deze agents nodig hebben. Dit betekent dat u hetzelfde bestand niet herhaaldelijk hoeft te uploaden, omdat u met de asset-URI's rechtstreeks naar de bestanden kunt verwijzen.

Maak vervolgens een vectorarchief met behulp van de asset_urilocatie van het bestand in het gegevensarchief van uw project.

# We'll upload the local file to your project Azure Blob Storage container and will use it for vector store creation.
_, asset_uri = project_client.upload_file("sample_file_for_upload.md")
print(f"Uploaded file, asset URI: {asset_uri}")

# create a vector store with a file in blob storage and wait for it to be processed
ds = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
vector_store = project_client.agents.create_vector_store_and_poll(data_sources=[ds], name="sample_vector_store")
print(f"Created vector store, vector store ID: {vector_store.id}")

Stap 3: Een agent maken met toegang tot het hulpprogramma voor het zoeken van bestanden

# create a file search tool
file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])

# notices that FileSearchTool as tool and tool_resources must be added or the assistant unable to search the file
agent_1 = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-assistant",
    instructions="You are helpful assistant",
    tools=file_search_tool.definitions,
    tool_resources=file_search_tool.resources,
)
# [END upload_file_and_create_agent_with_file_search]
print(f"Created agent_1, agent_1 ID: {agent_1.id}")

thread = project_client.agents.create_thread()
print(f"Created thread, thread ID: {thread.id}")

message = project_client.agents.create_message(
    thread_id=thread.id, role="user", content="What feature does Smart Eyewear offer?"
)
print(f"Created message, message ID: {message.id}")

run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent_1.id)

project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")

project_client.agents.delete_agent(agent.id)
print("Deleted agent")

messages = project_client.agents.list_messages(thread_id=thread.id)
print(f"Messages: {messages}")

Stap 4: Tweede vectorarchief maken met behulp van het eerder geüploade bestand

Maak nu een tweede vectorarchief met behulp van het eerder geüploade bestand. asset_uri Het gebruik van een bestand dat zich al in Azure Blob Storage bevindt, is handig als u meerdere agents hebt die toegang nodig hebben tot dezelfde bestanden, omdat het niet meer nodig is om hetzelfde bestand meerdere keren te uploaden.

# create a vector store with a previously uploaded file and wait for it to be processed
ds_2 = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
vector_store_2 = project_client.agents.create_vector_store_and_poll(data_sources=[ds_2], name="sample_vector_store_2")
print(f"Created vector store, vector store ID: {vector_store.id}")

Stap 5: Een tweede agent maken met toegang tot het hulpprogramma voor het zoeken van bestanden

file_search_tool_2 = FileSearchTool(vector_store_ids=[vector_store_2.id])
# notices that FileSearchTool as tool and tool_resources must be added or the assistant unable to search the file
agent_2 = project_client.agents.create_agent(
    model="gpt-4o-mini",
    name="my-assistant-2",
    instructions="You are helpful assistant",
    tools=file_search_tool_2.definitions,
    tool_resources=file_search_tool_2.resources,
)
# [END upload_file_and_create_agent_with_file_search]
print(f"Created agent, agent ID: {agent_2.id}")

Ondersteunde bestandstypen

Notitie

Voor tekst-/MIME-typen moet de codering utf-8, utf-16 of ASCII zijn.

File format	MIME-type
.c	text/x-c
.cs	text/x-csharp
.cpp	text/x-c++
.doc	application/msword
.docx	application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html	text/html
.java	text/x-java
.json	application/json
.md	text/markdown
.pdf	application/pdf
.php	text/x-php
.pptx	application/vnd.openxmlformats-officedocument.presentationml.presentation
.py	text/x-python
.py	text/x-script.python
.rb	text/x-ruby
.tex	text/x-tex
.txt	text/plain
.css	text/css
.js	text/javascript
.sh	application/x-sh
.ts	application/typescript

Vectorarchieven maken en bestanden toevoegen

Het toevoegen van bestanden aan vectorarchieven is een asynchrone bewerking. Om ervoor te zorgen dat de bewerking is voltooid, raden we u aan de helpers 'maken en peilen' te gebruiken in onze officiële SDK's. Als u de SDK's niet gebruikt, kunt u het object ophalen en de vector_store eigenschap ervan bewaken file_counts om het resultaat van de bestandsopnamebewerking te zien.

Bestanden kunnen ook worden toegevoegd aan een vectoropslag nadat deze is gemaakt door vectoropslagbestanden te maken.

# create a vector store with no file and wait for it to be processed
vector_store = project_client.agents.create_vector_store_and_poll(data_sources=[], name="sample_vector_store")
print(f"Created vector store, vector store ID: {vector_store.id}")

# add the file to the vector store or you can supply file ids in the vector store creation
vector_store_file_batch = project_client.agents.create_vector_store_file_batch_and_poll(
    vector_store_id=vector_store.id, file_ids=[file.id]
)
print(f"Created vector store file batch, vector store file batch ID: {vector_store_file_batch.id}")

U kunt ook verschillende bestanden toevoegen aan een vectorarchief door batches van maximaal 500 bestanden te maken.

batch = project_client.agents.create_vector_store_file_batch_and_poll(
  vector_store_id=vector_store.id,
  file_ids=[file_1.id, file_2.id, file_3.id, file_4.id, file_5.id]
)

Basisagent instellen: bestanden verwijderen uit vectorarchieven

Bestanden kunnen worden verwijderd uit een vectorarchief door:

• Het vectoropslag bestandsobject te verwijderen of,
• Het onderliggende bestandsobject verwijderen, waardoor het bestand uit alle vector_store en code_interpreter configuraties voor alle agents en threads in uw organisatie wordt verwijderd

De maximale bestandsgrootte is 512 MB. Elk bestand mag niet meer dan 5.000.000 tokens per bestand bevatten (automatisch berekend wanneer u een bestand bijvoegt).

Vectorarchief verwijderen

U kunt een vectorarchief verwijderen uit het zoekprogramma voor bestanden.

file_search_tool.remove_vector_store(vector_store.id)
print(f"Removed vector store from file search, vector store ID: {vector_store.id}")

project_client.agents.update_agent(
    assistant_id=agent.id, tools=file_search_tool.definitions, tool_resources=file_search_tool.resources
)
print(f"Updated agent, agent ID: {agent.id}")

Vectorarchieven verwijderen

project_client.agents.delete_vector_store(vector_store.id)
print("Deleted vector store")

Kosten beheren met verloopbeleid

Voor het instellen van de basisagent gebruikt het file_search hulpprogramma het vector_stores object als resource en wordt u gefactureerd op basis van de grootte van de vector_store objecten die zijn gemaakt. De grootte van het vectorarchiefobject is de som van alle geparseerde segmenten uit uw bestanden en de bijbehorende insluitingen.

Om u te helpen de kosten te beheren die zijn gekoppeld aan deze vector_store-objecten, hebben we ondersteuning toegevoegd voor verloopbeleid in het vector_store object. U kunt deze beleidsregels instellen bij het maken of bijwerken van het vector_store object.

vector_store = project_client.agents.create_vector_store_and_poll(
  name="Product Documentation",
  file_ids=[file_1.id],
  expires_after={
      "anchor": "last_active_at",
      "days": 7
  }
)

Thread vector stores hebben standaard verloopbeleid

Vectorarchieven die zijn gemaakt met thread-helpers (zoals tool_resources.file_search.vector_stores in threads of message.attachments in berichten) hebben een standaardverloopbeleid van zeven dagen nadat ze voor het laatst actief waren (gedefinieerd als de laatste keer dat het vectorarchief deel uitmaakte van een uitvoering).

Wanneer een vectorarchief verloopt, mislukken de uitvoeringen op die thread. U kunt dit probleem oplossen door een nieuwe vector_store opnieuw te maken met dezelfde bestanden en deze opnieuw aan de thread te koppelen.