Ferramenta de pesquisa de arquivos do Serviço do Agente de IA do Azure

A pesquisa de arquivos aumenta os agentes com conhecimento de fora de seu modelo, como informações de produtos proprietários ou documentos fornecidos por seus usuários.

Observação

Usando a configuração do agente padrão, a ferramenta de pesquisa de arquivos aprimorada garante que seus arquivos permaneçam em seu próprio armazenamento e seu recurso do Azure AI Search seja usado para ingeri-los, garantindo que você mantenha o controle total sobre seus dados.

Fontes de arquivo

• Carregar arquivos locais
• Armazenamento do Blobs do Azure

Dependência da configuração do agente

Configuração básica do agente

A ferramenta de pesquisa de arquivos tem a mesma funcionalidade que os Assistentes do Azure OpenAI. Recursos de pesquisa e armazenamento gerenciados da Microsoft são usados.

• Arquivos carregados são armazenados no armazenamento gerenciado da Microsoft
• Um repositório de vetores é criado usando um recurso de pesquisa gerenciado pela Microsoft

Configuração do agente padrão

A ferramenta de pesquisa de arquivos usa os recursos do Azure AI Search e do Armazenamento de Blobs do Azure conectados durante a instalação do agente.

• Arquivos carregados são armazenados em sua conta de Armazenamento de Blobs do Azure conectada
• Os repositórios de vetores são criados usando o recurso conectado do Azure AI Search
  
  

Para ambas as configurações de agente, o Azure OpenAI manipula todo o processo de ingestão, que inclui:

• Analisar e agrupar documentos automaticamente
• Gerando e armazenando inserções
• Utilizando pesquisas de vetor e palavra-chave para recuperar conteúdo relevante para consultas de usuário.

Não há diferença no código entre as duas configurações; a única variação é em que os arquivos e os repositórios de vetores criados são armazenados.

Como ele funciona

A ferramenta de pesquisa de arquivos implementa as melhores práticas de recuperação prontas para ajudá-lo a extrair os dados certos de seus arquivos e aumentar as respostas do modelo. A ferramenta de pesquisa de arquivo:

• Reescreve as consultas de usuário para otimizá-las para pesquisa.
• Divide consultas de usuário complexas em várias pesquisas que podem ser executadas em paralelo.
• Executa pesquisas de palavra-chave e semântica em repositórios de vetores de agente e thread.
• Reclassifica os resultados da pesquisa para escolher os mais relevantes antes de gerar a resposta final.
• Por padrão, a ferramenta de pesquisa de arquivos usa as seguintes configurações:
  • Tamanho da parte: 800 tokens
  • Sobreposição da parte: 400 tokens
  • Modelo de inserção: text-embedding-3-large em 256 dimensões
  • Número máximo de partes adicionadas ao contexto: 20

Repositórios de vetores

Os objetos do repositório de vetores dão à ferramenta de pesquisa de arquivos a capacidade de pesquisar seus arquivos. A adição de um arquivo a um repositório de vetores analisa automaticamente, divide, incorpora e armazena automaticamente o arquivo em um banco de dados de vetores capaz de fazer a pesquisa semântica e de palavra-chave. Cada repositório de vetores pode armazenar até 10.000 arquivos. Os repositórios de vetores podem ser anexados a agentes e threads. Atualmente, você pode anexar no máximo um repositório de vetores a um agente e, no máximo, a um repositório de vetores a um thread.

Da mesma forma, esses arquivos podem ser removidos de um repositório de vetores ao:

• Excluir o objeto do arquivo do repositório de vetores ou
• Excluindo o objeto de arquivo subjacente, que remove o arquivo de todas as configurações de vector_store e code_interpreter em todos os agentes e threads em sua organização

O arquivo pode ter no máximo 512 MB. Cada arquivo não deve conter mais de 5.000.000 tokens por arquivo (computado automaticamente quando você anexa um arquivo).

Garantir a preparação do repositório de vetores antes de criar execuções

É altamente recomendável garantir que todos os arquivos em um vector_store sejam totalmente processados antes de criar uma execução. Isso garante que todos os dados no seu repositório de vetores sejam pesquisáveis. Você pode verificar a preparação do repositório de vetores usando os auxiliares de sondagem nos SDKs ou sondando manualmente o objeto do repositório de vetores para garantir que o status seja concluído.

Como um fallback, há uma espera de, no máximo, 60 segundos no objeto run quando o repositório de vetores do thread contém arquivos que ainda estão sendo processados. Isso é para garantir que todos os arquivos carregados por seus usuários em um thread sejam totalmente pesquisáveis antes que a execução continue. Essa espera de fallback não se aplica ao repositório de vetores do agente.

Início Rápido – Carregar arquivos locais com a pesquisa de arquivos

Neste exemplo, usamos o Serviço do Agente de IA do Azure para criar um agente que possa ajudar a responder perguntas sobre as informações que você carrega de arquivos locais.

Pré-requisitos

1. Conclua a configuração do agente.

2. Verifique se você tem a função Colaborador de Dados de Blobs de Armazenamento na conta de armazenamento do projeto.

3. Verifique se você tem a função desenvolvedor de IA do Azure em seu projeto.

Etapa 1: Criar um cliente de projeto

Crie um objeto cliente que contenha a cadeia de conexão para se conectar ao projeto de IA e a outros recursos.

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

Etapa 2: Carregar arquivos e adicioná-los a um Repositório de Vetores

Para acessar seus arquivos, a ferramenta de pesquisa de arquivos usa o objeto do repositório de vetores. Carregue seus arquivos e crie um repositório de vetores. Depois de criar o repositório de vetores, faça a sondagem de seu status até que todos os arquivos estejam fora do estado in_progress para garantir que todo o conteúdo esteja sendo totalmente processado. O SDK fornece auxiliares para carregamento e sondagem.

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

Etapa 3: Criar um agente e habilitar a pesquisa de arquivos

Para tornar os arquivos acessíveis ao agente, crie um objeto FileSearchTool com a ID do vector_store e anexe tools e tool_resources ao 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;

Etapa 4: Criar um thread

Você também pode anexar arquivos como anexos de mensagem no thread. Isso cria outro vector_store associado ao thread ou, se já houver um repositório de vetores anexado a esse thread, anexa os novos arquivos ao repositório de vetores de thread existente. Quando você cria uma execução nesse thread, a ferramenta de pesquisa de arquivos consulta os vector_store do agente e o vector_store no 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;

Etapa 5: Criar uma execução e verificar a saída

Crie uma execução e observe que o modelo usa a ferramenta de pesquisa de arquivos para fornecer uma resposta à pergunta do usuário.

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

Início Rápido – Usar arquivos existentes no Armazenamento de Blobs do Azure com pesquisa de arquivos

Neste exemplo, usamos o Serviço do Agente de IA do Azure para criar um agente que possa ajudar a responder perguntas sobre informações de arquivos no Armazenamento de Blobs do Azure.

Pré-requisitos

1. Conclua a configuração do agente padrão.

2. Verifique se você tem a função Colaborador de Dados de Blobs de Armazenamento na conta de armazenamento do projeto.

3. Verifique se você tem a função desenvolvedor de IA do Azure em seu projeto.

Importante

A pesquisa de arquivos usando o Armazenamento de Blobs só é compatível com a configuração do agente padrão.

Etapa 1: Criar um cliente de projeto

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

Etapa 2: Carregar arquivos locais no contêiner do Armazenamento de Blobs do Azure do projeto

Carregue seu arquivo local no contêiner do Armazenamento de Blobs do Azure do projeto. Essa é a mesma conta de armazenamento que você conectou ao agente durante a instalação. Ao criar agentes adicionais no mesmo projeto, você pode reutilizar os URIs de ativos de todos os arquivos carregados anteriormente de que esses agentes precisam. Isso significa que você não precisa carregar o mesmo arquivo repetidamente, pois as URIs do ativo permitem que você faça referência diretamente aos arquivos.

Em seguida, crie um repositório de vetores usando o asset_uri, que é o local do arquivo no armazenamento de dados do projeto.

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

Etapa 3: Criar um agente com acesso à ferramenta de pesquisa de arquivos

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

Etapa 4: Criar um segundo repositório de vetores usando o arquivo carregado anteriormente

Agora, crie um segundo repositório de vetores usando o arquivo carregado anteriormente. Usar o asset_uri de um arquivo já no Armazenamento de Blobs do Azure é útil se você tiver vários agentes que precisam de acesso aos mesmos arquivos, pois elimina a necessidade de carregar o mesmo arquivo várias vezes.

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

Etapa 5: Criar um segundo agente com acesso à ferramenta de pesquisa de arquivos

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

Tipos de arquivo com suporte

Observação

Para texto/tipos MIME, a codificação deve ser utf-8, utf-16 ou ASCII.

Formato de arquivo	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

Criar repositórios de vetores e adicionar arquivos

A adição de arquivos a repositórios de vetores é uma operação assíncrona. Para garantir que a operação seja concluída, é recomendável usar os auxiliares para "criar e sondar" em nossos SDKs oficiais. Se você não estiver usando os SDKs, poderá recuperar o objeto vector_store e monitorar sua propriedade file_counts para ver o resultado da operação de ingestão de arquivos.

Os arquivos também podem ser adicionados a um repositório de vetores após sua criação, criando arquivos de armazenamento de vetores.

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

Como alternativa, você pode adicionar vários arquivos a um repositório de vetores criando lotes de até 500 arquivos.

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

Configuração básica do agente: excluindo arquivos de repositórios de vetores

Os arquivos podem ser removidos de um repositório de vetores:

• Excluir o objeto do arquivo do repositório de vetores ou
• Excluindo o objeto de arquivo subjacente, que remove o arquivo de todas as configurações de vector_store e code_interpreter em todos os agentes e threads em sua organização

O arquivo pode ter no máximo 512 MB. Cada arquivo não deve conter mais de 5.000.000 tokens por arquivo (computado automaticamente quando você anexa um arquivo).

Remover repositório de vetores

Você pode remover um repositório de vetores da ferramenta de pesquisa de arquivos.

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

Excluindo repositórios de vetores

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

Gerenciar custos com políticas de expiração

Para a configuração básica do agente, a ferramenta file_search usa o objeto vector_stores como seu recurso e você é cobrado com base no tamanho dos objetos vector_store criados. O tamanho do objeto do repositório de vetores é a soma de todas as partes analisadas de seus arquivos e suas inserções correspondentes.

Para ajudá-lo a gerenciar os custos associados a esses objetos vector_store, adicionamos suporte para políticas de expiração no objeto vector_store. Você pode definir essas políticas ao criar ou atualizar o objeto 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
  }
)

Os repositórios de vetores de thread têm políticas de expiração padrão

Os repositórios de vetores criados com auxiliares de thread (como tool_resources.file_search.vector_stores em Threads ou message.attachments em Mensagens) têm uma política de expiração padrão de sete dias após a última ativa (definida como a última vez em que o repositório de vetores fazia parte de uma execução).

Quando um repositório de vetores expira, as execuções nesse thread falham. Para corrigir esse problema, você pode recriar um novo vector_store com os mesmos arquivos e reanexá-lo ao thread.