Partilhar via

Ferramenta de pesquisa de ficheiros do Azure AI Agent Service

  • Artigo

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

Nota

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

Fontes de ficheiros

  • Carregar ficheiros locais
  • Armazenamento de Blobs do Azure

Dependência da configuração do agente

Configuração básica do agente

A ferramenta de pesquisa de ficheiros tem a mesma funcionalidade que os Assistentes OpenAI do Azure. São utilizados recursos de pesquisa e armazenamento geridos pela Microsoft.

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

Configuração padrão do agente

A ferramenta de pesquisa de arquivos usa os recursos Azure AI Search e Azure Blob Storage que você conectou durante a configuração do agente.

  • Os ficheiros carregados são armazenados na sua conta de Armazenamento de Blobs do Azure ligada
  • Os repositórios vetoriais são criados usando seu recurso de Pesquisa de IA do Azure conectado

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

  • Análise e fragmentação automáticas de documentos
  • Geração e armazenamento de incorporações
  • Utilizando pesquisas vetoriais e de palavras-chave para recuperar conteúdo relevante para consultas do usuário.

Não há diferença no código entre as duas configurações; A única variação é onde seus arquivos e armazenamentos vetoriais criados são armazenados.

Como funciona

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

  • Reescreve as consultas do usuário para otimizá-las para pesquisa.
  • Divide consultas complexas de usuários em várias pesquisas que podem ser executadas em paralelo.
  • Executa pesquisas semânticas e de palavras-chave 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 do bloco: 800 tokens
    • Sobreposição de blocos: 400 tokens
    • Modelo de incorporação: text-embedding-3-large em 256 dimensões
    • Número máximo de partes adicionadas ao contexto: 20

Repositórios vetoriais

Os objetos de armazenamento vetorial dão à ferramenta de pesquisa de arquivos a capacidade de pesquisar seus arquivos. Adicionar um arquivo a um repositório vetorial analisa, fragmenta, incorpora e armazena automaticamente o arquivo em um banco de dados vetorial capaz de pesquisa semântica e de palavras-chave. Cada armazenamento vetorial pode armazenar até 10.000 arquivos. Os armazenamentos vetoriais podem ser anexados a agentes e threads. Atualmente, você pode anexar no máximo um repositório vetorial a um agente e, no máximo, um armazenamento vetorial a um thread.

Da mesma forma, estes ficheiros podem ser removidos de um arquivo de vetores ao:

  • Eliminar o objeto de ficheiro do arquivo de vetores.
  • Excluindo o objeto de arquivo subjacente, que remove o arquivo de todas as configurações de vetor_store e code_interpreter em todos os agentes e threads em sua organização

O tamanho máximo do ficheiro é de 512 MB. Cada ficheiro não deve conter mais de 5 000 000 tokens por ficheiro (calculado automaticamente quando anexa um ficheiro).

Garantindo a prontidão do armazenamento vetorial antes de criar execuções

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

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

Guia de início rápido – Carregar arquivos locais com pesquisa de arquivos

Neste exemplo, usamos o Azure AI Agent Service para criar um agente que pode ajudar a responder a perguntas sobre informações carregadas de arquivos locais.

Pré-requisitos

  1. Conclua a configuração do agente.

  2. Certifique-se de ter a função de Colaborador de Dados de Blob de Armazenamento na conta de armazenamento do seu projeto.

  3. Certifique-se de que tem a função de Programador de IA do Azure no seu projeto.

Etapa 1: Criar um cliente de projeto

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

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

Passo 2: Carregar ficheiros e adicioná-los a uma Loja de Vetores

Para acessar seus arquivos, a ferramenta de pesquisa de arquivos usa o objeto de armazenamento vetorial. Carregue seus arquivos e crie uma loja vetorial. Depois de criar o repositório vetorial, pesquise seu status até que todos os arquivos estejam fora do estado para garantir que todo o in_progress conteúdo esteja totalmente processado. O SDK fornece auxiliares para upload e sondagem.

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

Para tornar os arquivos acessíveis ao seu agente, crie um FileSearchTool objeto com a vector_store ID e anexe tools e tool_resources ao agente.


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

Etapa 4: Criar um thread

Você também pode anexar arquivos como anexos de mensagem no seu 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 o vector_store do seu agente e o vector_store no thread.

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

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.

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

Guia de início rápido – Usar arquivos existentes no Armazenamento de Blobs do Azure com pesquisa de arquivos

Neste exemplo, usamos o Azure AI Agent Service para criar um agente que pode ajudar a responder a perguntas sobre informações de arquivos no Armazenamento de Blobs do Azure.

Pré-requisitos

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

  2. Certifique-se de ter a função de Colaborador de Dados de Blob de Armazenamento na conta de armazenamento do seu projeto.

  3. Certifique-se de que tem a função de Programador de IA do Azure no seu projeto.

Importante

A pesquisa de arquivos usando o armazenamento de Blob só é suportada pela configuração padrão do agente.

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 para seu contêiner de Armazenamento de Blob do Azure do projeto

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

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 o segundo repositório vetorial usando o arquivo carregado anteriormente

Agora, crie um segundo repositório vetorial 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 acessar os 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 ficheiro suportados

Nota

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

File format Tipo de 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

Criação de repositórios vetoriais e adição de arquivos

Adicionar arquivos a repositórios vetoriais é uma operação assíncrona. Para garantir que a operação seja concluída, recomendamos que você use os auxiliares de 'criar e pesquisar' em nossos SDKs oficiais. Se você não estiver usando os SDKs, poderá recuperar o vector_store objeto e monitorar sua file_counts propriedade para ver o resultado da operação de ingestão de arquivos.

Os ficheiros também podem ser adicionados a um arquivo de vetores depois deste ser criado.


# 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 vetorial 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 vetoriais

Os arquivos podem ser removidos de um armazenamento vetorial por:

  • Eliminar o objeto de ficheiro do arquivo de vetores.
  • Excluindo o objeto de arquivo subjacente, que remove o arquivo de todas as configurações de vetor_store e code_interpreter em todos os agentes e threads em sua organização

O tamanho máximo do ficheiro é de 512 MB. Cada ficheiro não deve conter mais de 5 000 000 tokens por ficheiro (calculado automaticamente quando anexa um ficheiro).

Remover armazenamento de vetores

Você pode remover um armazenamento vetorial 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 vetoriais

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

Gerenciando custos com políticas de expiração

Para a configuração básica do agente, a file_search ferramenta usa o vector_stores objeto como seu recurso e você é cobrado com base no tamanho dos vetor_store objetos criados. O tamanho do objeto de armazenamento de vetor é a soma de todos os blocos analisados de seus arquivos e suas incorporações correspondentes.

Para ajudá-lo a gerenciar os custos associados a esses objetos vetor_store, adicionamos suporte para políticas de expiração no vector_store objeto. Você pode definir essas políticas ao criar ou atualizar o vector_store objeto.

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 usando 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 terem sido ativos pela última vez (definidos como a última vez que o repositório de vetores fez parte de uma execução).

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