TL;DR: A ferramenta File Search da Assistants API, que permite a assistentes buscar informações em arquivos externos através de Vector Stores, está sendo aprimorada com base no feedback beta e será migrada para a Responses API até 2026. Ela automatiza o processamento de documentos (parsing, chunking, embedding) e utiliza busca híbrida (vetorial e keyword) para respostas mais precisas. Desenvolvedores precisam habilitar a ferramenta, gerenciar uploads para Vector Stores, associá-los a assistentes/threads e configurar políticas de expiração para controle de custos.

Takeaways:

File Search automatiza o processamento e a busca vetorial/keyword em arquivos, permitindo que assistentes usem conhecimento externo armazenado em Vector Stores.
A ativação requer habilitar ‘file_search’ na criação do assistente e associar Vector Stores (com arquivos carregados e processados) via tool_resources aos assistentes ou threads.
Parâmetros como tamanho/sobreposição de chunks (max_chunk_size_tokens, chunk_overlap_tokens) e número máximo de resultados (max_num_results) podem ser personalizados para otimizar a busca.
A ferramenta File Search será descontinuada até o primeiro semestre de 2026, sendo substituída pela Responses API, exigindo que os desenvolvedores migrem suas implementações.
Os custos são baseados no armazenamento em Vector Stores (US$ 0,10/GB/dia após o primeiro GB), sendo crucial usar políticas de expiração para gerenciá-los (padrão de 7 dias para threads).

Assistants API: Aprimoramentos da Ferramenta de Busca de Arquivos e Migração para a Responses API

Introdução

A Assistants API vem passando por importantes transformações que impactam diretamente as estratégias de busca e recuperação de informações. Com o aprimoramento da ferramenta File Search baseada em feedback da fase beta, as mudanças se refletem em uma evolução que culmina na migração para a Responses API. Essa transição visa oferecer uma experiência mais eficaz e integrada para o desenvolvimento de assistentes que utilizam conhecimento extraído de arquivos.

O File Search, que permite o processamento automático de documentos – desde sua análise, divisão em partes (chunking) até a criação de embeddings – passa a oferecer uma capacidade ampliada de resposta, utilizando técnicas de busca vetorial e por palavras-chave. Essa funcionalidade possibilita que os assistentes acessem informações provenientes de documentos externos e bases proprietárias, aprimorando a precisão das respostas geradas para os usuários. Dessa forma, o assistente se torna uma ferramenta mais robusta e contextualizada, capaz de fornecer respostas fundamentadas em um vasto repositório de conhecimento.

Este artigo apresenta, de forma didática e acessível, os principais pontos relacionados à evolução da ferramenta File Search e seu processo de migração para a Responses API. Serão explorados tópicos que abordam desde as melhorias implementadas em fase beta até questões de configuração, upload de arquivos, personalização de parâmetros e gerenciamento de custos. Dessa maneira, desenvolvedores e demais interessados poderão compreender os desafios e as oportunidades que acompanham essa transição.

Melhorias no Beta do File Search e Plano de Descontinuação

A ferramenta File Search, originalmente disponibilizada em versão beta, vem sendo aprimorada com base no feedback dos usuários. As melhorias implementadas visam aumentar a eficácia na busca e na integração dos conteúdos externos, preparando o terreno para uma transição mais fluida para a Responses API. Nesse processo evolutivo, os ajustes técnicos oferecem uma resposta mais precisa e orientada ao contexto da consulta.

Paralelamente aos aprimoramentos, a estratégia de depreciação do File Search já está definida, com a sua descontinuação prevista para o primeiro semestre de 2026. Essa decisão, alinhada às melhores práticas de atualização de APIs, garante que os desenvolvedores migrem suas implementações para a nova Responses API antes do encerramento. Assim, a ferramenta antiga será gradativamente retirada de operação, permitindo maior foco nas inovações tecnológicas.

A comunicação dessa mudança está programada para ocorrer ainda este ano, com o anúncio oficial do plano de depreciação. Durante esse período de transição, os usuários são incentivados a acompanhar as atualizações e a adaptar seus sistemas para a nova abordagem de respostas baseadas na Responses API. Esse planejamento evidencia o comprometimento com a qualidade e a continuidade dos serviços oferecidos.

Panorama da Ferramenta de Busca de Arquivos

A ferramenta File Search integra os assistentes ao fornecer conhecimento oriundo de arquivos externos, possibilitando a inclusão de informações proprietárias e de outras fontes especializadas. Por meio de um processo automatizado, documentos são analisados e organizados em partes que facilitam a recuperação de conteúdo relevante. Essa capacidade é fundamental para que os assistentes consigam responder a consultas complexas com base em dados específicos.

Utilizando técnicas de parsing, chunking e embedding, a ferramenta transforma documentos em representações vetoriais que podem ser pesquisadas tanto por semelhança quanto por palavras-chave. Essa abordagem híbrida assegura que os resultados obtidos sejam os mais adequados à consulta do usuário, elevando a qualidade da resposta gerada. Além disso, o uso de buscas vetoriais possibilita um acesso mais rápido a informações essenciais, otimizando o desempenho do assistente.

Ao combinar esses métodos, o File Search torna-se um componente estratégico para sistemas que dependem de fontes de conhecimento externas. A automatização da extração de dados e a aplicação de práticas recomendadas para recuperação de informações reforçam a confiabilidade dos resultados. Assim, a ferramenta se posiciona como uma solução completa para a busca e integração de dados relevantes no contexto de assistentes virtuais.

Habilitando o File Search para um Assistente

Para aproveitar as funcionalidades da ferramenta File Search, é necessário criar um novo assistente com a opção “file_search” habilitada no parâmetro de ferramentas (tools). Essa configuração permite que o assistente decida, de forma autônoma, quando acessar os conteúdos externos com base na interação com o usuário. A ativação do File Search é, portanto, um passo fundamental para integrar dados dinâmicos às respostas geradas.

Ao configurar o assistente, o desenvolvedor pode utilizar exemplos práticos como o Assistente de Análise Financeira, que se beneficia diretamente do acesso a demonstrações financeiras auditadas. Essa funcionalidade automatizada possibilita que o modelo analise documentos complexos sem que o usuário precise indicar manualmente as fontes. Dessa forma, o assistente se torna mais interativo e apto a compreender contextos diversificados durante as conversas.

A implementação envolve a utilização de snippets de código disponíveis em diversas linguagens, como Python, JavaScript e Bash. Essas amostras servem para ilustrar o processo de criação do assistente, garantindo que o parâmetro “file_search” esteja corretamente configurado. Ao seguir essas diretrizes, os desenvolvedores garantem que o modelo incorpore a funcionalidade de busca de arquivos de maneira eficaz e integrada.

Subindo Arquivos e Adicionando-os a um Vector Store

A funcionalidade do File Search depende da utilização de um Vector Store, que armazena e permite o acesso aos arquivos carregados. Inicialmente, os arquivos precisam ser enviados e organizados nesse repositório vetorial para que possam ser posteriormente buscados pelo assistente. Esse processo garante que todas as informações sejam devidamente estruturadas e facilmente acessíveis.

Após o upload dos arquivos, é essencial monitorar o status do Vector Store para confirmar que todos os documentos foram processados com sucesso. Esse acompanhamento deve ser feito por meio de polling, verificando se os arquivos saíram do estado “in_progress”. A garantia de que todos os dados estão totalmente processados é crucial para que o assistente possa realizar buscas precisas e sem interrupções.

Exemplos práticos incluem o envio de documentos como “edgar/goog-10k.pdf” e “edgar/brka-10k.txt”, representando informações financeiras e outras métricas relevantes. Para auxiliar nesse processo, o SDK da API oferece funções helper que facilitam tanto o upload dos arquivos quanto o monitoramento do seu processamento. Assim, a integração dos arquivos ao Vector Store torna-se uma etapa sistematizada e segura na utilização da ferramenta.

Anexando Vector Stores aos Assistentes e Threads

Os Vector Stores podem ser associados tanto aos assistentes quanto às threads através do parâmetro “tool_resources”, permitindo uma integração personalizada dos arquivos aos contextos desejados. Essa flexibilidade possibilita que os arquivos sejam utilizados de maneira segmentada ou conjunta, conforme a necessidade do fluxo de trabalho. Dessa forma, cada assistente pode ter um repositório de dados único, ou as threads podem compartilhar um Vector Store específico para recuperar informações contextuais.

Ao anexar arquivos a uma thread, o sistema cria automaticamente um novo Vector Store para aquele contexto ou atualiza o existente, incorporando os novos dados. Esse mecanismo assegura que as mensagens trocadas dentro da thread possam se beneficiar do conteúdo adicional disponível. A associação de Vector Stores às threads é especialmente útil para contextos colaborativos ou para a análise de conversas contínuas, onde o histórico de mensagens é relevante para a resposta final.

É fundamental, antes de criar uma execução (run), confirmar que o Vector Store está completamente processado e pronto para uso. A implementação de uma janela de espera de até 60 segundos para o Vector Store de threads ressalta a importância dessa validação, garantindo que os dados estejam disponíveis quando a busca é acionada. Essa etapa de verificação é determinante para evitar falhas durante o processamento das requisições.

Personalizando as Configurações do File Search

A ferramenta File Search oferece a possibilidade de personalizar a estratégia de chunking, que determina como os dados dos arquivos são divididos em partes antes de serem processados. Os parâmetros “max_chunk_size_tokens” e “chunk_overlap_tokens” são configuráveis, permitindo ajustar o tamanho e a sobreposição dos pedaços de texto. Essa personalização é vital para que o assistente obtenha resultados que respeitem o limite do contexto e que sejam suficientemente relevantes para a consulta.

Além do chunking, é possível ajustar o número de partes (chunks) que serão retornadas para o contexto do modelo, utilizando o parâmetro “file_search.max_num_results”. Essa configuração permite gerenciar melhor o orçamento de tokens, garantindo que somente as informações mais importantes sejam consideradas na resposta final. O controle sobre o número de resultados também contribui para otimizar o desempenho da busca, evitando sobrecarga de dados desnecessários.

Entretanto, é importante atentar para as limitações impostas nesses parâmetros, como o intervalo permitido para “max_chunk_size_tokens” (entre 100 e 4096 tokens) e a restrição de que “chunk_overlap_tokens” não deve exceder metade do tamanho máximo definido. Essas limitações asseguram que a personalização não comprometa a eficiência da ferramenta, mantendo um equilíbrio entre a quantidade de dados processados e a relevância das respostas geradas.

Gerenciando Custos com Políticas de Expiração

Os custos associados ao uso do File Search estão diretamente relacionados ao tamanho dos objetos armazenados no Vector Store, com uma cobrança de US$ 0,10/GB/dia após o primeiro gigabyte. Essa cobrança pode impactar significativamente os orçamentos, por isso, é fundamental que as políticas de expiração sejam configuradas para mitigar despesas desnecessárias. O gerenciamento adequado desses custos faz parte de uma estratégia abrangente de otimização dos recursos.

Para ajudar no controle desses custos, é possível definir políticas de expiração ao criar ou atualizar os Vector Stores. No caso dos Vector Stores associados a threads, há uma política padrão que expira o armazenamento 7 dias após o último uso. Essa medida garante que os dados não fiquem armazenados de forma indefinida, evitando custos desnecessários e incentivando a limpeza periódica do repositório.

Caso um Vector Store venha a expirar, as execuções vinculadas a ele poderão falhar, exigindo que o mesmo seja recriado a partir dos arquivos originais. Essa necessidade de reconfiguração reforça a importância de monitorar ativamente os prazos de expiração e, quando necessário, reanexar os dados ao thread apropriado. Dessa maneira, o gerenciamento de custos torna-se um processo contínuo que complementa a manutenção geral da infraestrutura.

Conclusão

A evolução da ferramenta File Search, com suas melhorias em fase beta e a futura migração para a Responses API, representa um avanço significativo no contexto das Assistants API. A integração de técnicas avançadas de processamento de documentos e a utilização de Vector Stores demonstram o comprometimento com a atualização e a melhoria contínua dos sistemas de busca. Essa mudança visa oferecer respostas mais contextualizadas e precisas, enriquecendo a experiência dos usuários.

A abordagem apresentada, que envolve a habilitação do File Search, o upload e processamento dos arquivos, a associação de Vector Stores e a personalização dos parâmetros, configura um ciclo completo de desenvolvimento e manutenção das funcionalidades. Ao gerenciar também o aspecto financeiro por meio de políticas de expiração, os desenvolvedores têm à disposição um conjunto robusto de ferramentas para otimizar o desempenho e os custos operacionais. Esse ciclo demonstra como a evolução tecnológica pode ser acompanhada por uma gestão eficiente dos recursos.

Por fim, a transição para a Responses API sinaliza implicações futuras que exigirão uma adaptação contínua dos desenvolvedores e equipes de integração. Com uma abordagem que une melhorias técnicas, personalização de processos e controle de custos, o panorama apresentado desafia a comunidade a se manter atualizada e alinhada com as melhores práticas de recuperação e uso de informações. Essa evolução marca um novo capítulo na forma como as ferramentas de busca em assistentes virtuais são concebidas e utilizadas.

Referências Bibliográficas

*Fonte: OpenAI. “Assistants File Search Beta”. Disponível em: https://platform.openai.com/docs/assistants/tools/file-search.

*Fonte: InfoWorld. “OpenAI’s Assistants API gets a boost”. Disponível em: https://www.infoworld.com/article/2336869/openais-assistants-api-gets-a-boost.html.

*Fonte: Medium. “OpenAI Assistants API v2: What’s New and Improved?”. Disponível em: https://medium.com/@woyera/openai-assistants-api-v2-whats-new-and-improved-a67c4f3936fc.

*Fonte: OpenAI Cookbook. “Assistants API Overview (Python SDK)”. Disponível em: https://cookbook.openai.com/examples/assistants_api_overview_python.

*Fonte: Microsoft Learn. “How to use Azure OpenAI Assistants file search”. Disponível em: https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/file-search.

*Fonte: Jonathan Flower’s Blog. “Retrieval Unleashed with OpenAI’s new Assistants API”. Disponível em: https://blog.jonathanflower.com/artificial-intelligence/retrieval-unleashed-with-openais-new-assistants-api/.

*Fonte: Mamezou Developer Portal. “Using the Newly Updated File Search (Vector Stores) in OpenAI Assistants API(v2)”. Disponível em: https://developer.mamezou-tech.com/en/blogs/2024/04/21/openai-file-search-intro/.

*Fonte: DIGIParasol. “OpenAI’s Assistants API update adds new file search tool and ability to set maximum token limits”. Disponível em: https://digiparasol.com/explore-learn/software-tech/news-analysis/openais-assistants-api-update-adds-new-file-search-tool-and-ability-to-set-maximum-token-limits/.

*Fonte: OpenAI Development Documentation. “Assistants File Search”. Disponível em: https://chatgpt.cadn.net.cn/docs_en/assistants_tools_file-search.

*Fonte: All Dev Stack. “OpenAI Assistants API Tutorial”. Disponível em: https://www.alldevstack.com/openai/assistants-api.html.

*Fonte: Hispread Documentation. “File Search”. Disponível em: https://hispread.readme.io/docs/file-search.

Melhorias na Assistants API: Ferramentas de Busca de Arquivos