Ferramenta de pesquisa de ficheiros do Foundry Agent Service (clássico)

Nota

Este documento refere-se aos agentes Microsoft Foundry (clássico).

🔍 Consulte a nova documentação de pesquisa de ficheiros. Os Agentes (clássicos) estão agora obsoletos e serão descontinuados a 31 de março de 2027. Use os novos agentes no Serviço de Agentes Foundry da Microsoft, disponível para o público em geral. Siga o guia de migração para atualizar as suas cargas de trabalho.

A pesquisa de ficheiros complementa os agentes com conhecimento externo ao seu modelo, como informações proprietárias de produtos ou documentos fornecidos pelos seus utilizadores.

Nota

Usando a configuração padrão de agentes, a ferramenta melhorada de pesquisa de ficheiros garante que os seus ficheiros permaneçam no seu próprio armazenamento, e o seu recurso Pesquisa de IA do Azure é usado para os ingerir, garantindo que mantém controlo total sobre os seus dados.

Fontes do ficheiro

• Carregar ficheiros locais
• Armazenamento de Blobs do Azure

Suporte de utilização

Nota

A ferramenta de pesquisa de ficheiros está atualmente indisponível nas seguintes regiões:

• Itália norte
• Brasil sul
• Europa Ocidental

Suporte para a fundição de IA do Azure	Python SDK	C# SDK	JavaScript SDK	Java SDK	API REST	Configuração básica do agente	Configuração padrão do agente
✔️	✔️	✔️	✔️	✔️	✔️	Apenas upload de ficheiros	Carregamento de ficheiros e utilização de armazenamento de blob próprio

Dependência da configuração do agente

Configuração básica do agente

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

• Os ficheiros carregados são armazenados no armazenamento gerido da Microsoft
• Uma loja vetorial é criada usando um recurso de pesquisa gerido pela Microsoft

Configuração padrão do agente

A ferramenta de pesquisa de ficheiros utiliza os recursos Pesquisa de IA do Azure e Armazenamento de Blobs do Azure que ligou durante a configuração do agente.

• Os ficheiros carregados são armazenados na sua conta Armazenamento de Blobs do Azure ligada
• As bases de vetores são criadas utilizando o seu recurso Pesquisa de IA do Azure conectado

Para ambas as configurações de agentes, o serviço gere todo o processo de ingestão, que inclui:

• Análise e fragmentação automática de documentos
• Geração e armazenamento de embeddings
• Utilizando pesquisas vetoriais e por palavras-chave para recuperar conteúdos relevantes para consultas dos utilizadores.

Não há diferença no código entre as duas configurações; A única variação está no local onde os teus ficheiros e os armazenamentos vetoriais criados estão armazenados.

Como funciona

A ferramenta de pesquisa de ficheiros implementa várias boas práticas de recuperação logo de início para o ajudar a extrair os dados corretos dos seus ficheiros e a complementar as respostas do modelo. A ferramenta de pesquisa de ficheiros:

• Reescreve as consultas dos utilizadores para as otimizar para a pesquisa.
• Desagrega consultas de utilizadores complexas em múltiplas pesquisas que podem ser executadas em paralelo.
• Executa pesquisas por palavras-chave e semânticas tanto em repositórios de agentes como em repositórios de vetores de thread.
• Reclassifica os resultados da pesquisa para escolher os mais relevantes antes de gerar a resposta final.
• Por defeito, a ferramenta de pesquisa de ficheiros utiliza as seguintes definições:
  • Tamanho do bloco: 800 fichas
  • Sobreposição de blocos: 400 tokens
  • Modelo de embedding: text-embedding-3-large com 256 dimensões
  • Número máximo de blocos adicionados ao contexto: 20

Armazenamentos vetoriais

Os objetos de armazenamento vetorial dão à ferramenta de pesquisa de ficheiros a capacidade de pesquisar os teus ficheiros. Adicionar um ficheiro a uma loja vetorial automaticamente analisa, fragmenta, incorpora e armazena o ficheiro numa base de dados vetorial capaz tanto de pesquisa por palavras-chave como semântica. Cada armazenamento vetorial pode armazenar até 10.000 ficheiros. Os armazenamentos vetoriais podem ser ligados tanto a agentes como a threads. Atualmente, pode-se anexar no máximo um armazenamento vetorial a um agente e, no máximo, um armazenamento vetorial a um thread.

De forma semelhante, estes ficheiros podem ser removidos de um armazenamento vetorial por:

• Eliminar o objeto de ficheiro de armazenamento vetorial ou,
• Ao eliminar o objeto de ficheiro subjacente, isso remove o ficheiro de todas as configurações vector_store e code_interpreter em todos os agentes e threads da sua organização

O tamanho máximo do ficheiro é de 512 MB. Cada ficheiro deve conter no máximo 5.000.000 de tokens por ficheiro (calculados automaticamente quando anexas um ficheiro).

Garantir a prontidão do armazenamento vetorial antes de iniciar processos

Recomendamos vivamente que garanta que todos os ficheiros de um vector_store são totalmente processados antes de criar uma execução. Isto garante que todos os dados no seu armazenamento vetorial são pesquisáveis. Pode verificar a disponibilidade do armazenamento vetorial usando as funcionalidades de polling nos SDKs, ou consultando manualmente a instância de armazenamento vetorial para garantir que o estado está completo.

Como recurso alternativo, há um tempo máximo de espera de 60 segundos no objeto de execução quando o armazenamento vetorial do thread contém ficheiros que ainda estão a ser processados. Isto serve para garantir que quaisquer ficheiros que os seus utilizadores carreguem numa thread sejam totalmente pesquisáveis antes da execução prosseguir. Esta espera alternativa não se aplica ao armazenamento vetorial do agente.

Criação de armazenamentos vetoriais e adição de ficheiros

Adicionar ficheiros a lojas vetoriais é uma operação assíncrona. Para garantir que a operação está concluída, recomendamos que utilize os utilitários 'criar e sondar' nos nossos SDKs oficiais. Se não estiveres a usar os SDKs, podes recuperar o vector_store objeto e monitorizar as suas file_counts propriedades para ver o resultado da operação de ingestão de ficheiros.

Os ficheiros também podem ser adicionados a uma loja vetorial depois de esta ser criada, criando ficheiros de armazenamento vetorial.

# create a vector store with no file and wait for it to be processed
vector_store = project_client.agents.vector_stores.create_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.vector_store_file_batches.create_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}")

Em alternativa, pode adicionar vários ficheiros a um armazenamento vetorial criando lotes de até 500 ficheiros.

batch = project_client.agents.vector_store_file_batches.create_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: Apagar ficheiros das lojas vetoriais

Os ficheiros podem ser removidos de um armazenamento vetorial por:

• Eliminar o objeto de ficheiro de armazenamento vetorial ou,
• Eliminar o objeto de ficheiro subjacente, que remove o ficheiro de todas as configurações de vector_store e code_interpreter em todos os agentes e threads da sua organização

O tamanho máximo do ficheiro é de 512 MB. Cada ficheiro deve conter no máximo 5.000.000 de tokens por ficheiro (calculados automaticamente quando anexas um ficheiro).

Remover armazenamento vetorial

Podes remover um armazenamento vetorial da ferramenta de pesquisa de ficheiros.

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(
    agent_id=agent.id, tools=file_search_tool.definitions, tool_resources=file_search_tool.resources
)
print(f"Updated agent, agent ID: {agent.id}")

Eliminar armazenamentos vetoriais

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

Gerir 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 és faturado com base no tamanho dos vector_store objetos criados. O tamanho do objeto de armazenamento vetorial é a soma de todos os blocos analisados dos teus ficheiros e das respetivas incorporações.

Para o ajudar a gerir os custos associados a estes vector_store objetos, adicionámos suporte para políticas de expiração no vector_store objeto. Pode definir estas políticas ao criar ou atualizar o vector_store objeto.

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

Os armazéns de vetores de threads têm políticas de expiração por defeito

As lojas vetoriais criadas usando ajudantes 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 atividade (definida como a última vez que a loja vetorial fez parte de uma execução).

Quando um armazenamento vetorial expira, as execuções nesse thread falham. Para resolver este problema, podes recriar um novo vector_store com os mesmos ficheiros e voltar a anexá-lo à thread.

Tipos de ficheiros suportados

Nota

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

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

Limitações

• Carregar ficheiros e criar armazenamento de vetores falhará se tiver uma Política do Azure para os Índices de Recurso de Pesquisa do Azure que recuse índices não-CMK para o valor Encryption. Neste caso, precisas de trazer os teus índices do recurso Pesquisa de IA do Azure logo à partida e depois consultá-los no teu Agente. Não pode criar índices a partir do Foundry com tipo de Encriptação = chaves geridas pelo cliente.