Pesquisa de arquivos do Google na API Gemini: um guia prático e completo por RAG

A chegada da Busca de Arquivos ao ecossistema de Gemini API Isso mudou completamente o jogo para quem quer criar aplicações RAG sem conflitos de infraestrutura. Com esse serviço gerenciado, O Google automatiza o armazenamento, o particionamento, a incorporação e a injeção dinâmica de contexto em arquivos. em tempo de geração, para que você possa se concentrar na criação do produto e não na configuração de fluxos de trabalho.

Além da ingestão de documentos, a Pesquisa de Arquivos oferece pesquisa semântica avançadaCompatibilidade com diversos formatos, citações automáticas e uma estrutura de preços simples.E se você precisar de informações atualizadas da web, a API também oferece isso. google_search para ancorar com a Busca do Google, com metadados de verificação muito úteis para interfaces com agendamentos rastreáveis.

O que exatamente é a Busca de Arquivos na API Gemini?

A Busca de Arquivos é uma Solução RAG totalmente gerenciada Integrado à API Gemini. Na prática, você carrega seus arquivos (ou os importa do serviço de arquivos) e o sistema cuida do resto. Dividir os arquivos em fragmentos, gerar embeddings e indexá-los em um repositório de busca de arquivos. e usá-las como base para responder às consultas dos usuários por meio de pesquisa de vetores.

O objetivo é que você não precise lidar com Bases vetoriais, filas de indexação ou estratégias de fragmentação por conta própria. A ferramenta é baseada no modelo de incorporação do Google (por exemplo, gemini-embedding-001) e integra-se nativamente com generateContentonde você declara o Ferramenta de busca de arquivos e a loja para verificar.

Como funciona: do documento à resposta contextual

O fluxo conceitual é simples, embora haja muita substância por trás dele. Primeiro, seus documentos se tornam representações numéricas (incorporações) que capturam o significado. Esses vetores são armazenados em um repositório especializado. Então, quando você envia uma consulta, a API converte o prompt em outro embedding e executa uma busca semântica para recuperar as peças mais relevantes.

Finalmente, na chamada para generateContent com a ferramenta de FileSearch, você adiciona um Recurso de recuperação de pesquisa de arquivos que aponta para a loja específica. Com isso, o modelo sabe que deve recuperar contexto da sua loja e use-a para apoiar sua resposta. Tudo isso acontece sem que você precise agendar uma recuperação manual ou usar serviços externos.

Carregar e importar documentos: dois caminhos compatíveis

Para trazer dados para sua loja, você tem duas opções. Se quiser ir direto ao ponto, use a API. uploadToFileSearchStore para Faça o upload do arquivo diretamente e indexe-o. em uma única operação. Se preferir etapas separadas, você pode fazer o upload do arquivo usando a API de Arquivos e depois... importe-o com importFile para o Repositório de Busca de Arquivos.

Ao optar por carregar e importar tudo de uma só vez, um File temporário como referência ao documento original; que O objeto é removido após 48 horas.No entanto, os dados indexados permanecem no armazenamento até que você decida excluí-los. Você usa a API de Arquivos. Em seguida, você importa; o pipeline passa pelo armazenamento de arquivos antes da fase de incorporação.

Controle de agrupamento: precisão e sobreposição

Por padrão, a API decide sobre uma estratégia de fatiamento inteligenteMas se precisar de ajustes finos, você pode especificar chunking_config com parâmetros como número máximo de fichas por fragmento y tokens sobrepostosCom menos tokens por bloco, você ganha granularidade na busca; com mais, você retém. mais contexto por fragmento.

Esse controle preciso é útil em casos como: Código-fonte, documentos extensos ou manuais técnicos.onde é aconselhável ajustar o equilíbrio entre a precisão da recuperação e a continuidade contextual.

Armazenamentos de busca de arquivos: persistência, escopo e gerenciamento

Um Repositório de Busca de Arquivos é o contêiner persistente onde residem os Repositórios de Busca de Arquivos. incorporações processadasAo contrário dos arquivos brutos da API Files (que desaparecem após 48 horas), o conteúdo importado para o armazenamento Ele é mantido até ser explicitamente excluído.Você pode criar vários repositórios para organizar seus domínios de conhecimento, e seus nomes são único no mundo.

A API de FileSearchStore permite que você Criar, listar, obter e excluir lojasAlém disso, existe uma API de Documentos para gerenciar o conteúdo em cada loja, e você pode anexar arquivos. metadados personalizados (pares chave-valor) para seus arquivos para filtrar pesquisas por subconjuntos. Para o filtro, a sintaxe usada é a seguinte: listas de filtros descrito em google.aip.dev/160.

Fluxo de utilização detalhado da API

Em termos operacionais, o processo típico segue três etapas. Primeiro, Você cria o Repositório de Pesquisa de Arquivos. Depois, Carregar e importar arquivos (Ou você carrega e depois importa). Finalmente, perguntas para o modelo com generateContent indicando a ferramenta FileSearch e a loja de destino através de FileSearchRetrievalResource.

Em ambientes JavaScript/TypeScript, uma prática comum é usar operações simultâneas (por exemplo, Promise.all) para carregar vários arquivos de uma só vez e monitorar operation.done Antes de prosseguir, é importante ressaltar que também é comum procurar a loja pelo seu nome. Nome em Exibição (legível para humanos) caso você não se lembre do identificador fileSearchStores/....

Gestão de documentos: localizar, atualizar e excluir

Dentro de uma loja, às vezes é útil localizar um documento específico por sua etiqueta. Nome em Exibição para gerenciá-lo. Um detalhe importante: os documentos. Eles são imutáveis após a indexação. Se precisar atualizá-los, o padrão recomendado é Apague e carregue novamente. a nova versão.

Como prática operacional, muitos fluxos de trabalho automatizam esse ciclo: Pesquisar → excluir → enviarE quando você terminar de usar os recursos (por exemplo, durante o desenvolvimento), lembre-se de que há um limite para... 10 lojas por projetoPortanto, é uma boa ideia limpá-los se você não precisar mais deles.

Citações e verificação: fundamentação em seus documentos

Uma das principais vantagens da Busca de Arquivos é que as respostas do modelo podem incluir citações automáticas que indicam os fragmentos dos seus documentos usados ​​para gerar a saída. Essa rastreabilidade aparece no atributo grounding_metadata da resposta e é crucial para auditoria, verificação e confiança em ambientes empresariais.

Dessa forma, quando o assistente responder, você poderá mostrar referências precisas às partes relevantes dos seus arquivos, facilitando a revisão de reivindicações e a construção de documentos. interfaces com citações em linha.

Formatos de arquivo suportados

A Pesquisa de Arquivos oferece suporte a grande variedade de formatosEntre os mais comuns estão application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX), application/vnd.openxmlformats-officedocument.presentationml.presentation (PPTX), application/json, application/xml, application/zip, além de muitas línguas ​​de programação y tipos de texto como text/plain, text/html, text/css, text/csv, text/markdown, text/javascript, text/yaml, etc.

Abrange também vários tipos específicos (por exemplo, código e scripts como application/x-php, application/x-powershell, application/x-sh, application/x-tex, application/x-zshE textual como text/x-python, text/x-java, text/x-ruby-script, text/x-rust, text/x-go, text/x-kotlin, text/x-sql, text/x-c, text/x-csharp, text/x-swift, text/x-tex, text/x-scss, text/x-tcl, text/x-asm(entre muitos outros). Se o seu caso exigir um tipo incomum, é muito provável que seja esse. contemplado na documentação oficial.

Limites de serviço e recomendações arquitetônicas

Para manter a estabilidade do serviço, a API estabelece limites claros: o O tamanho máximo do arquivo é de 100 MB.O tamanho total adicionado nas lojas depende do nível do usuário: 1 GB grátis, Nível 1 10 GB, Nível 2 100 GB y Nível 3 1 TB.

Como diretriz de desempenho, recomenda-se Mantenha cada loja com menos de 20 GB. Para garantir a latência ideal. Observe que o tamanho de um armazenamento é calculado no backend como o tamanho da entrada. mais os embeddingsque eles geralmente multiplicam aproximadamente por três o volume de dados original.

Preços: simples e previsíveis

O modelo de pagamento é direto: Você paga apenas pela criação de elementos incorporados na indexação.ao preço de US$ 0,15 por 1 milhão de tokens (dependendo do custo do modelo de incorporação aplicável). armazenamento e pela geração de embeddings na consulta Eles não têm custo adicional, e o tokens recuperados Eles são faturados como tokens de contexto normais no momento da geração.

Este esquema facilita o planejamento orçamentário: o custo principal está concentrado no ingestão inicial (e em atualizações subsequentes do documento, se houver), minimizando a surpresa no consumo. por volume de consultas.

Modelos compatíveis para pesquisa de arquivos

A ferramenta funciona com os modelos atuais da família Gemini. Os materiais de referência destacam sua disponibilidade em Gêmeos 2.5 Pró y Gêmeos 2.5 Flash para pesquisa de arquivos, com suporte para fundamentação, filtros de metadados e citações a fim de construir experiências verificáveis.

Em relação à integração com a Busca do Google (discutida abaixo), há uma gama mais ampla de modelos suportados, e especifica-se que o Modelos experimentais e de pré-visualização não incluso.

Fundamentação com a Busca do Google: informações atuais e citações da web

Se, além dos seus documentos, você precisar de... conteúdo da web em tempo realVocê pode ativar a ferramenta. google_searchO modelo gerencia todo o fluxoDecidir se é apropriado pesquisar, gerar e executar consultas, processar resultados, sintetizar e retornar uma resposta. com metadados de aterramento (consultas, resultados e citações).

Quando o aterramento é feito corretamente, a resposta inclui groundingMetadata com campos como Consultas de pesquisa na web (consultas utilizadas), searchEntryPoint (HTML e CSS são necessários para sugestões de pesquisa, com requisitos de uso detalhados nos Termos de Serviço) aterrando pedaços (fontes da web com uri y title) E Suportes de aterramento (fragmentos que ligam segmentos de texto do modelo com índices de groundingChunks para construir citações online).

Preços e modelos para aterramento usando a Busca do Google

A utilização de google_search fatura para cada solicitação que ativa essa ferramenta, mesmo que o modelo execute várias consultas internas para a mesma solicitação; tudo isso conta como uso único faturávelOs modelos compatíveis com esta ferramenta estão listados abaixo. Gêmeos 2.5 Pró, Gêmeos 2.5 Flash, Gemini 2.5 Flash-Lite, Gêmeos 2.0 Flash, Gêmeos 1.5 Pró y Gêmeos 1.5 Flash.

Para modelos anteriores à versão 1.5, existe uma ferramenta legada. google_search_retrieval com modo dinâmicoonde você configura um limite_dinâmico (0.0–1.0) e o modelo decide se realiza ou não a busca com base em seu confiança onde você precisa de informações atualizadas.

Casos de uso: de assistentes internos a suporte ao cliente.

A Busca de Arquivos é voltada para ambientes de negócios onde privacidade, precisão e rastreabilidade são importantes. É útil para profissionais do conhecimento que analisam documentação proprietária, por suporte automatizado com respostas extraídas de manuais e políticas, ou para acelerar pesquisar e revisar em setores que exigem grande quantidade de informação (jurídico, saúde, financeiro).

Também acelera os fluxos de desenvolvimento e aprimoramento Ao permitir a interação com bases de código ou especificações técnicas. Sua combinação com outras funcionalidades do Gemini (como execução de código ou função) possibilita integrações ricas em processos de conformidade, auditoria ou análise.

Operações e status: trabalhando com a API

A superfície REST expõe métodos como fileSearchStores.create (cria uma loja vazia), fileSearchStores.delete (remove uma loja), fileSearchStores.get (obtém informações de uma loja), fileSearchStores.list (lista lojas de usuários) e importFile (Isso importa) File (do serviço de arquivos para um armazenamento). Os pontos de extremidade de operações permitem que você verifique o status de operações de longo prazo, com formulários de inscrição que, em vários casos, vão vazio De acordo com a especificação.

Na rota direta de subida (uploadToFileSearchStoreUm conjunto de operações Projetado especificamente para avaliar o progresso. Este padrão é típico: lanças Operação, você verifica periodicamente, se tiver terminado e, quando completo, você continua com o fluxo (por exemplo, executando consultas RAG).

Melhores práticas: filtros, rotulagem e latência

Se você prevê muitas perguntas, etiquete seus documentos com metadados e empregar metadataFilter Para restringir a recuperação a subconjuntos relevantes. Mantenha os armazenamentos dentro do recomendação de tamanho Isso ajuda na latência e na estabilidade. E se você for cobrar pastas completasAproveita-se do aumento simultâneo para reduzir o tempo de ingestão.

Em cenários técnicos, defina estratégias de fragmentação apropriado ao conteúdo: por exemplo, trechos mais curtos com sobreposição moderada para código (maior precisão em funções/classes) e blocos um pouco mais longos em documentação narrativa para preservar o contexto semântico.

Compatibilidade com outras ferramentas Gemini

O aterramento com a Pesquisa do Google pode ser combinado com Contexto da URL (para fornecer URLs específicos) e com execução de código ou funções adicionais da ferramenta, dependendo do caso de uso. Isso permite que você combine e personalize. conhecimento privilegiado Pesquisa de arquivos com informação atualizada da internet, sempre mantendo citações e registros das fontes.

Ao projetar a experiência do usuário (UX), aproveite as seguintes vantagens: Suportes de aterramento y aterrando pedaços para oferecer citações clicáveis junto ao texto modelo. Esta é a forma mais clara para os usuários verificarem a origem de cada afirmação.

A busca de arquivos na API Gemini oferece uma maneira muito direta de equipar seus aplicativos com respostas bem fundamentadas em seus próprios dados, minimizando o atrito operacional. Sua combinação de Custos de indexação previsíveis, suporte para vários formatos, filtros de metadados, citações automáticas e integração com a Busca do Google. Isso cria uma estrutura pronta para produção que alivia a pressão sobre a implementação do RAG em equipes de todos os tamanhos.