Pesquisa de arquivos

A API Gemini permite a geração aumentada por recuperação (RAG) com a ferramenta Pesquisa de arquivos. A Pesquisa de arquivos importa, divide e indexa seus dados para permitir a recuperação rápida de informações relevantes com base no comando de um usuário. Essas informações são fornecidas como contexto ao modelo, permitindo que ele dê respostas mais precisas e relevantes.

É possível usar a API uploadToFileSearchStore para fazer upload direto de um arquivo existente no seu repositório de pesquisa de arquivos ou fazer upload e importar um arquivo separadamente se quiser criar o arquivo ao mesmo tempo.

Fazer upload diretamente para a loja de pesquisa de arquivos

Este exemplo mostra como fazer upload direto de um arquivo para um armazenamento de arquivos:

from google import genai
from google.genai import types
import time

client = genai.Client()

# Create the file search store with an optional display name that shows in the grounding metadata
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

# Upload and import a file into the file search store, supply a unique file name which will be visible in citations
operation = client.file_search_stores.upload_to_file_search_store(
  file='path/to/your/file.txt',
  file_search_store_name='unique_file_name'
)

# Wait until import is complete
while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

# Ask a question about the file
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about Robert Graves""",
    config=types.GenerateContentConfig(
        tools=[
            file_search=(
                  file_search_store_names=[file_search_store.name]
            )
        ]
    )
)

print(response.text)

Como importar arquivos

Como alternativa, faça upload de um arquivo e importe-o para o armazenamento de arquivos:

from google import genai
from google.genai import types
import time

client = genai.Client()

# Upload the file using the Files API, supply a unique file name which will be visible in citations
sample_file = client.files.upload(file='sample.txt', config={'name': 'unique_file_name'})

# Create the file search store with an optional display name that shows in the grounding metadata
file_search_store = client.file_search_stores.create(config={'display_name': 'your-fileSearchStore-name'})

# Import the file into the file search store
operation = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name
)

# Wait until import is complete
while not operation.done:
    time.sleep(5)
    operation = client.operations.get(operation)

# Ask a question about the file
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Can you tell me about Robert Graves""",
    config=types.GenerateContentConfig(
        tools=[
            file_search=(
                  file_search_store_names=[file_search_store.name]
            )
        ]
    )
)

print(response.text)

Configuração de divisão

Quando você importa um arquivo para um repositório de pesquisa de arquivos, ele é automaticamente dividido em partes, incorporado, indexado e enviado por upload para o repositório. Se você precisar de mais controle sobre a estratégia de divisão, especifique uma configuração chunking_config para definir um número máximo de tokens por parte e um número máximo de tokens sobrepostos.

# Upload and import and upload the file into the file search store with a custom chunking configuration
operation = client.file_search_stores.upload_to_file_search_store(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name,
    config={
        'chunking_config': {
          'white_space_config': {
            'max_tokens_per_chunk': 200,
            'max_overlap_tokens': 20
          }
        }
    }
)

Para usar o armazenamento de pesquisa de arquivos, transmita-o como uma ferramenta para o método generateContent, conforme mostrado nos exemplos Upload e Import.

Como funciona

A Pesquisa de arquivos usa uma técnica chamada pesquisa semântica para encontrar informações relevantes para o comando do usuário. Ao contrário da pesquisa tradicional por palavras-chave, a pesquisa semântica entende o significado e o contexto da sua consulta.

Quando você importa um arquivo, ele é convertido em representações numéricas chamadas embeddings, que capturam o significado semântico do texto. Esses embeddings são armazenados em um banco de dados especializado de pesquisa de arquivos. Quando você faz uma consulta, ela também é convertida em um embedding. Em seguida, o sistema realiza uma pesquisa de arquivos para encontrar os trechos de documentos mais semelhantes e relevantes no repositório de pesquisa de arquivos.

Confira um resumo do processo para usar a API File Search uploadToFileSearchStore:

1. Criar um repositório de pesquisa de arquivos: um repositório de pesquisa de arquivos contém os dados processados dos seus arquivos. É o contêiner persistente para os embeddings em que a pesquisa semântica vai operar.

2. Fazer upload de um arquivo e importar para um repositório de pesquisa de arquivos: faça upload de um arquivo e importe os resultados para o repositório de pesquisa de arquivos ao mesmo tempo. Isso cria um objeto File temporário, que é uma referência ao seu documento bruto. Esses dados são divididos em partes, convertidos em embeddings de pesquisa de arquivos e indexados. O objeto File é excluído após 48 horas, enquanto os dados importados para o repositório de pesquisa de arquivos são armazenados indefinidamente até que você os exclua.

3. Consulta com a Pesquisa de arquivos: por fim, use a ferramenta FileSearch em uma chamada generateContent. Na configuração da ferramenta, especifique um FileSearchRetrievalResource, que aponta para o FileSearchStore que você quer pesquisar. Isso informa ao modelo para realizar uma pesquisa semântica nesse repositório específico de pesquisa de arquivos e encontrar informações relevantes para embasar a resposta.

Neste diagrama, a linha pontilhada de Documentos para Modelo de incorporação (usando gemini-embedding-001) representa a API uploadToFileSearchStore (ignorando o Armazenamento de arquivos). Caso contrário, usar a API Files para criar e importar arquivos separadamente move o processo de indexação de Documentos para Armazenamento de arquivos e, em seguida, para Modelo de incorporação.

Armazenamentos de pesquisa de arquivos

Um repositório de pesquisa de arquivos é um contêiner para seus embeddings de documentos. Os arquivos brutos enviados pela API File são excluídos após 48 horas, mas os dados importados para um repositório de pesquisa de arquivos são armazenados indefinidamente até que você os exclua manualmente. Você pode criar várias lojas de pesquisa de arquivos para organizar seus documentos. A API FileSearchStore permite criar, listar, receber e excluir para gerenciar seus armazenamentos de pesquisa de arquivos. Os nomes do armazenamento de pesquisa de arquivos têm escopo global.

Confira alguns exemplos de como gerenciar suas lojas de pesquisa de arquivos:

# Create a file search store (including optional display_name for easier reference)
file_search_store = client.file_search_stores.create(config={'display_name': 'my-file_search-store-123'})

# List all your file search stores
for file_search_store in client.file_search_stores.list():
    print(file_search_store)

# Get a specific file search store by name
my_file_search_store = client.file_search_stores.get(name='fileSearchStores/my-file_search-store-123')

# Delete a file search store
client.file_search_stores.delete(name='fileSearchStores/my-file_search-store-123', config={'force': True})

Metadados do arquivo

É possível adicionar metadados personalizados aos arquivos para ajudar a filtrá-los ou fornecer mais contexto. Os metadados são um conjunto de pares de chave-valor.

# Import the file into the file search store with custom metadata
op = client.file_search_stores.import_file(
    file_search_store_name=file_search_store.name,
    file_name=sample_file.name,
    custom_metadata=[
        {"key": "author", "string_value": "Robert Graves"},
        {"key": "year", "numeric_value": 1934}
    ]
)

Isso é útil quando você tem vários documentos em um repositório de pesquisa de arquivos e quer pesquisar apenas um subconjunto deles.

# Use the metadata filter to search within a subset of documents
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="""Tell me about the book 'I, Claudius'""",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                file_search=types.FileSearch(
                  file_search_store_names=[file_search_store.name],
                  metadata_filter = 'author=Robet Graves',
                  )
            )
        ]
    )
)

print(response.text)

As orientações sobre a implementação da sintaxe de filtro de lista para metadata_filter podem ser encontradas em google.aip.dev/160.

Citações

Ao usar a Pesquisa de arquivos, a resposta do modelo pode incluir citações que especificam quais partes dos documentos enviados foram usadas para gerar a resposta. Isso ajuda na checagem de fatos e na verificação.

Você pode acessar as informações de citação pelo atributo grounding_metadata da resposta.

print(response.candidates[0].grounding_metadata)

Modelos compatíveis

Os seguintes modelos são compatíveis com a Pesquisa de arquivos:

• gemini-2.5-pro
• gemini-2.5-flash

Tipos de arquivo compatíveis

A Pesquisa de arquivos é compatível com vários formatos de arquivo, listados nas seções a seguir.

Limites de taxas

A API File Search tem os seguintes limites para garantir a estabilidade do serviço:

• Tamanho máximo do arquivo / limite por documento: 100 MB
• Pesquisas de arquivos armazenadas por projeto: 10
• Tamanho total dos repositórios de pesquisa de arquivos do projeto (com base no nível do usuário):
  • Sem custo financeiro: 1 GB
  • Nível 1: 10 GB
  • Nível 2: 100 GB
  • Nível 3: 1 TB
• Recomendação: limite o tamanho de cada loja de pesquisa de arquivos a menos de 20 GB para garantir latências de recuperação ideais.

Preços

• Os desenvolvedores são cobrados por incorporações no momento da indexação com base nos preços de incorporação atuais (US$ 0,15 por 1 milhão de tokens).
• O armazenamento não tem custo financeiro.
• Os embeddings de tempo de consulta não têm custo financeiro.
• Os tokens de documentos recuperados são cobrados como tokens de contexto normais.