Strumento di ricerca file del servizio Azure AI Agent

La ricerca di file aumenta gli agenti con conoscenze esterne al modello, ad esempio informazioni sui prodotti proprietari o documenti forniti dagli utenti.

Nota

Usando la configurazione standard dell'agente, lo strumento di ricerca dei file migliorato garantisce che i file rimangano nella propria risorsa di archiviazione e che la risorsa di Ricerca di intelligenza artificiale di Azure venga usata per inserirli, assicurandosi di mantenere il controllo completo sui dati.

Origini file

• Caricare file locali
• Archiviazione BLOB di Azure

Dipendenza dall'installazione dell'agente

Configurazione dell'agente di base

Lo strumento di ricerca file ha le stesse funzionalità degli Assistenti OpenAI di Azure. Vengono usate le risorse di ricerca e archiviazione gestite da Microsoft.

• I file caricati vengono archiviati nell'archiviazione gestita da Microsoft
• Viene creato un archivio vettoriale usando una risorsa di ricerca gestita da Microsoft

Configurazione dell'agente standard

Lo strumento di ricerca file usa ricerca di intelligenza artificiale di Azure e Archiviazione BLOB di Azure risorse connesse durante l'installazione dell'agente.

• I file caricati vengono archiviati nell'account Archiviazione BLOB di Azure connesso
• Gli archivi vettoriali vengono creati usando la risorsa di Ricerca di intelligenza artificiale di Azure connessa
  
  

Per entrambe le configurazioni dell'agente, Azure OpenAI gestisce l'intero processo di inserimento, che include:

• Analisi automatica e suddivisione in blocchi di documenti
• Generazione e archiviazione di incorporamenti
• Utilizzo sia di ricerche vettoriali che di parole chiave per recuperare il contenuto pertinente per le query utente.

Non esiste alcuna differenza nel codice tra le due configurazioni; l'unica variante è la posizione in cui vengono archiviati i file e gli archivi vettoriali creati.

Funzionamento

Lo strumento di ricerca file implementa diverse procedure consigliate di recupero predefinite per consentire l'estrazione dei dati corretti dai file e l'aumento delle risposte del modello. Strumento di ricerca file:

• Riscrive le query utente per ottimizzarle per la ricerca.
• Suddivide le query utente complesse in più ricerche che può essere eseguita in parallelo.
• Esegue sia ricerche di parole chiave che semantiche in archivi di vettori di thread e agente.
• Classifica i risultati della ricerca per selezionare quelli più rilevanti prima di generare la risposta finale.
• Per impostazione predefinita, lo strumento di ricerca file usa le impostazioni seguenti:
  • Dimensioni blocco: 800 token
  • Sovrapposizione blocchi: 400 token
  • Modello di incorporamento: text-embedding-3-large a 256 dimensioni
  • Numero massimo di blocchi aggiunti al contesto: 20

Archivi di vettori

Gli oggetti dell'archivio vettoriale offrono allo strumento di ricerca file la possibilità di eseguire ricerche nei file. L'aggiunta di un file a un archivio vettoriale analizza automaticamente, blocchi, incorporamenti e archivia il file in un database vettoriale in grado di eseguire ricerche semantiche e parole chiave. Ogni archivio vettoriale può contenere fino a 10.000 file. Gli archivi vettoriali possono essere collegati sia agli agenti che ai thread. Attualmente è possibile collegare al massimo un archivio vettoriale a un agente e al massimo un archivio vettoriale a un thread.

Analogamente, questi file possono essere rimossi da un archivio di vettori tramite:

• Eliminazione dell'oggetto file dell'archivio di vettori o
• Eliminando l'oggetto file sottostante, che rimuove il file da tutte le configurazioni di vector_store e code_interpreter in tutti gli agenti e i thread dell'organizzazione

La dimensione massima del file è 512 MB. Ogni file deve contenere non più di 5.000.000 token per ogni file (calcolato automaticamente quando si allega un file).

Verifica dell'idoneità dell'archivio vettoriale prima della creazione delle esecuzioni

È consigliabile assicurarsi che tutti i file in un vector_store siano completamente elaborati prima di creare un'esecuzione. In questo modo tutti i dati nell'archivio vettoriale sono ricercabili. È possibile verificare l'idoneità dell'archivio vettoriale usando gli helper di polling negli SDK o eseguendo manualmente il polling dell'oggetto archivio vettoriale per assicurarsi che lo stato sia completato.

Come fallback, è previsto un'attesa massima di 60 secondi nell'oggetto run quando l'archivio vettoriale del thread contiene file ancora in fase di elaborazione. Ciò consente di assicurarsi che tutti i file caricati dagli utenti in un thread siano completamente ricercabili prima che l'esecuzione proceda. Questa attesa di fallback non si applica all'archivio vettoriale dell'agente.

Guida introduttiva: Caricare file locali con la ricerca di file

In questo esempio si usa il servizio Agente di intelligenza artificiale di Azure per creare un agente in grado di rispondere alle domande sulle informazioni caricate dai file locali.

Prerequisiti

1. Completare l'installazione dell'agente.

2. Assicurarsi di avere il ruolo Collaboratore ai dati dei BLOB di archiviazione nell'account di archiviazione del progetto.

3. Assicurarsi di avere il ruolo Azure AI Developer nel progetto.

Passaggio 1: Creare un client di progetto

Creare un oggetto client contenente il stringa di connessione per la connessione al progetto di intelligenza artificiale e ad altre risorse.

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

Passaggio 2: Caricare i file e aggiungerli a un archivio vettoriale

Per accedere ai file, lo strumento di ricerca file usa l'oggetto dell'archivio vettoriale. Caricare i file e creare un archivio vettoriale. Dopo aver creato l'archivio vettoriale, eseguire il polling dello stato fino a quando tutti i file non sono nello in_progress stato per assicurarsi che tutto il contenuto sia completamente in elaborazione. L'SDK fornisce helper per il caricamento e il polling.

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

Passaggio 3: Creare un agente e abilitare la ricerca di file

Per rendere i file accessibili all'agente, creare un FileSearchTool oggetto con l'ID vector_store e allegare tools e tool_resources all'agente.

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;

Passaggio 4: Creare un thread

È anche possibile allegare file come allegati di messaggi nel thread. In questo modo viene creato un altro vector_store oggetto associato al thread oppure, se è già presente un archivio vettoriale collegato a questo thread, collega i nuovi file all'archivio vettoriale di thread esistente. Quando si crea un'istruzione Esegui in questo thread, lo strumento di ricerca file esegue query sia dall'agente vector_store che dal 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;

Passaggio 5: Creare un'esecuzione e controllare l'output

Creare un'esecuzione e osservare che il modello usa lo strumento di ricerca file per fornire una risposta alla domanda dell'utente.

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

Guida introduttiva: Usare i file esistenti in Archiviazione BLOB di Azure con la ricerca di file

In questo esempio si usa il servizio Agente di intelligenza artificiale di Azure per creare un agente che consente di rispondere alle domande relative alle informazioni dai file in Archiviazione BLOB di Azure.

Prerequisiti

1. Completare la configurazione dell'agente standard.

2. Assicurarsi di avere il ruolo Collaboratore ai dati dei BLOB di archiviazione nell'account di archiviazione del progetto.

3. Assicurarsi di avere il ruolo Azure AI Developer nel progetto.

Importante

La ricerca di file con l'archiviazione BLOB è supportata solo dalla configurazione dell'agente standard.

Passaggio 1: Creare un client di progetto

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"]
)

Passaggio 2: Caricare file locali nel contenitore Archiviazione BLOB di Azure progetto

Caricare il file locale nel contenitore Archiviazione BLOB di Azure del progetto. Si tratta dello stesso account di archiviazione connesso all'agente durante l'installazione. Quando si creano agenti aggiuntivi all'interno dello stesso progetto, è possibile riutilizzare gli URI degli asset di tutti i file caricati in precedenza necessari per tali agenti. Ciò significa che non è necessario caricare ripetutamente lo stesso file, perché gli URI degli asset consentono di fare riferimento direttamente ai file.

Creare quindi un archivio vettoriale usando , asset_uriovvero il percorso del file nell'archivio dati del progetto.

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

Passaggio 3: Creare un agente con accesso allo strumento di ricerca file

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

Passaggio 4: Creare un secondo archivio vettoriale usando il file caricato in precedenza

Creare ora un secondo archivio vettoriale usando il file caricato in precedenza. L'uso asset_uri di un file già in Archiviazione BLOB di Azure è utile se si dispone di più agenti che devono accedere agli stessi file, in quanto elimina la necessità di caricare lo stesso file più volte.

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

Passaggio 5: Creare un secondo agente con accesso allo strumento di ricerca file

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

Tipi di file supportati

Nota

Per i tipi text/MIME, la codifica deve essere utf-8, utf-16 o ASCII.

File format	Tipo MIME
.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

Creazione di archivi vettoriali e aggiunta di file

L'aggiunta di file agli archivi vettoriali è un'operazione asincrona. Per assicurarsi che l'operazione sia completata, è consigliabile usare gli helper "create and poll" negli SDK ufficiali. Se non si usano gli SDK, è possibile recuperare l'oggetto vector_store e monitorarne la proprietà file_counts per visualizzare il risultato dell'operazione di inserimento file.

I file possono anche essere aggiunti a un archivio vettoriale dopo che è stato creato creando file dell'archivio vettoriale.

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

In alternativa, è possibile aggiungere più file a un archivio vettoriale creando batch di un massimo di 500 file.

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

Configurazione dell'agente di base: eliminazione di file da archivi vettoriali

I file possono essere rimossi da un archivio vettoriale in uno dei due casi:

• Eliminazione dell'oggetto file dell'archivio di vettori o
• Eliminazione dell'oggetto file sottostante, che rimuove il file da tutte le configurazioni di vector_store e code_interpreter in tutti gli agenti e i thread dell'organizzazione

La dimensione massima del file è 512 MB. Ogni file deve contenere non più di 5.000.000 token per ogni file (calcolato automaticamente quando si allega un file).

Rimuovere l'archivio vettoriale

È possibile rimuovere un archivio vettoriale dallo strumento di ricerca file.

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

Eliminazione di archivi vettoriali

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

Gestione dei costi con i criteri di scadenza

Per la configurazione dell'agente di base, lo file_search strumento usa l'oggetto vector_stores come risorsa e viene fatturato in base alle dimensioni degli oggetti vector_store creati. La dimensione dell'oggetto archivio vettoriale è la somma di tutti i blocchi analizzati dai file e degli incorporamenti corrispondenti.

Per gestire i costi associati a questi oggetti vector_store, è stato aggiunto il supporto per i criteri di scadenza nell'oggetto vector_store . È possibile impostare questi criteri durante la creazione o l'aggiornamento dell'oggetto vector_store.

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

Gli archivi vettoriali di thread hanno criteri di scadenza predefiniti

Gli archivi vettoriali creati usando gli helper thread (ad esempio tool_resources.file_search.vector_stores in Thread o message.attachments in Messaggi) hanno un criterio di scadenza predefinito di sette giorni dopo l'ultimo attivo (definito come l'ultima volta che l'archivio vettoriale faceva parte di un'esecuzione).

Quando un archivio vettoriale scade, l'esecuzione su tale thread ha esito negativo. Per risolvere questo problema, è possibile ricreare un nuovo vector_store con gli stessi file e ricollegarlo al thread.