Búsqueda de archivos

La API de Gemini habilita la generación mejorada por recuperación ("RAG") a través de la herramienta File Search. La Búsqueda de archivos importa, divide en fragmentos y, luego, indexa tus datos para permitir la recuperación rápida de información pertinente según la instrucción del usuario. Luego, esta información se proporciona como contexto al modelo, lo que le permite brindar respuestas más precisas y pertinentes.

Puedes usar la API de uploadToFileSearchStore para subir directamente un archivo existente a tu tienda de búsqueda de archivos o subirlo y, luego, importarlo por separado si quieres crear el archivo al mismo tiempo.

Subir directamente a la tienda de búsqueda de archivos

En este ejemplo, se muestra cómo subir directamente un archivo a un almacén de archivos:

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)

Importación de archivos

También puedes subir un archivo existente e importarlo a tu almacén de archivos:

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)

Configuración de fragmentación

Cuando importas un archivo a un almacén de búsqueda de archivos, se divide automáticamente en fragmentos, se incorpora, se indexa y se sube a tu almacén de búsqueda de archivos. Si necesitas más control sobre la estrategia de fragmentación, puedes especificar un parámetro de configuración chunking_config para establecer una cantidad máxima de tokens por fragmento y una cantidad máxima de tokens superpuestos.

# 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 tu tienda de búsqueda de archivos, pásala como una herramienta al método generateContent, como se muestra en los ejemplos de Upload y Import.

Cómo funciona

La Búsqueda de archivos usa una técnica llamada búsqueda semántica para encontrar información pertinente para la instrucción del usuario. A diferencia de la búsqueda tradicional basada en palabras clave, la búsqueda semántica comprende el significado y el contexto de tu búsqueda.

Cuando importas un archivo, se convierte en representaciones numéricas llamadas embeddings, que capturan el significado semántico del texto. Estos embeddings se almacenan en una base de datos de búsqueda de archivos especializada. Cuando realizas una búsqueda, esta también se convierte en un embedding. Luego, el sistema realiza una búsqueda de archivos para encontrar los fragmentos de documentos más similares y relevantes en el almacén de búsqueda de archivos.

A continuación, se detalla el proceso para usar la API de File Search uploadToFileSearchStore:

1. Crea un almacén de búsqueda de archivos: Un almacén de búsqueda de archivos contiene los datos procesados de tus archivos. Es el contenedor persistente para los embeddings en los que operará la búsqueda semántica.

2. Sube un archivo y, luego, impórtalo a un almacén de búsqueda de archivos: Sube un archivo y, luego, importa los resultados a tu almacén de búsqueda de archivos de forma simultánea. Esto crea un objeto File temporal, que es una referencia a tu documento sin procesar. Luego, esos datos se dividen en fragmentos, se convierten en embeddings de búsqueda de archivos y se indexan. El objeto File se borra después de 48 horas, mientras que los datos importados en el almacén de búsqueda de archivos se almacenarán de forma indefinida hasta que decidas borrarlos.

3. Consulta con la Búsqueda de archivos: Por último, usas la herramienta FileSearch en una llamada a generateContent. En la configuración de la herramienta, especificas un FileSearchRetrievalResource, que apunta al FileSearchStore que deseas buscar. Esto le indica al modelo que realice una búsqueda semántica en ese almacén de búsqueda de archivos específico para encontrar información pertinente que fundamente su respuesta.

En este diagrama, la línea punteada que va de Documents a Embedding model (con gemini-embedding-001) representa la API de uploadToFileSearchStore (sin pasar por File storage). De lo contrario, usar la API de Files para crear y, luego, importar archivos por separado traslada el proceso de indexación de Documents a File storage y, luego, a Embedding model.

Almacenes de búsqueda de archivos

Un almacén de búsqueda de archivos es un contenedor para tus embeddings de documentos. Si bien los archivos sin procesar que se suben a través de la API de File se borran después de 48 horas, los datos que se importan a un almacén de búsqueda de archivos se almacenan de forma indefinida hasta que los borres de forma manual. Puedes crear varias tiendas de búsqueda de archivos para organizar tus documentos. La API de FileSearchStore te permite crear, enumerar, obtener y borrar para administrar tus tiendas de búsqueda de archivos. Los nombres de las tiendas de búsqueda de archivos tienen un alcance global.

Estos son algunos ejemplos de cómo administrar tus tiendas de búsqueda de archivos:

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

Metadatos de archivos

Puedes agregar metadatos personalizados a tus archivos para filtrarlos o proporcionar contexto adicional. Los metadatos son un conjunto de pares clave-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}
    ]
)

Esto resulta útil cuando tienes varios documentos en un almacén de búsqueda de archivos y deseas buscar solo un subconjunto de ellos.

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

Puedes encontrar orientación para implementar la sintaxis del filtro de lista para metadata_filter en google.aip.dev/160.

Citas

Cuando usas la Búsqueda de archivos, la respuesta del modelo puede incluir citas que especifican qué partes de los documentos que subiste se usaron para generar la respuesta. Esto ayuda con la verificación de datos.

Puedes acceder a la información de citas a través del atributo grounding_metadata de la respuesta.

print(response.candidates[0].grounding_metadata)

Modelos compatibles

Los siguientes modelos admiten la Búsqueda de archivos:

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

Tipos de archivos admitidos

La Búsqueda de archivos admite una amplia variedad de formatos de archivo, que se enumeran en las siguientes secciones.

Límites de frecuencia

La API de File Search tiene los siguientes límites para garantizar la estabilidad del servicio:

• Límite de tamaño de archivo o por documento: 100 MB
• Almacenamientos de búsqueda de archivos por proyecto: 10
• Tamaño total de los almacenamientos de búsqueda de archivos de proyectos (según el nivel del usuario):
  • Gratis: 1 GB
  • Nivel 1: 10 GB
  • Nivel 2: 100 GB
  • Nivel 3: 1 TB
• Recomendación: Limita el tamaño de cada almacén de búsqueda de archivos a menos de 20 GB para garantizar latencias de recuperación óptimas.

Precios

• A los desarrolladores se les cobra por las incorporaciones en el momento de la indexación según los precios de las incorporaciones existentes (USD 0.15 por 1 millón de tokens).
• El almacenamiento no tiene costo.
• Los embeddings de tiempo de consulta no tienen costo.
• Los tokens de documentos recuperados se cobran como tokens de contexto normales.