Google File Search en Gemini API: guía práctica y completa de RAG

La llegada de File Search al ecosistema de la Gemini API ha cambiado las reglas del juego para quienes quieren crear aplicaciones con RAG sin peleas con la infraestructura. Con este servicio gestionado, Google automatiza el almacenamiento de archivos, el troceado (chunking), las embeddings y la inyección dinámica de contexto en tiempo de generación, de modo que puedes centrarte en construir producto y no en montar pipelines.

Más allá de la ingesta de documentos, File Search aporta búsqueda semántica avanzada, compatibilidad con formatos variados, citaciones automáticas y una estructura de precios sencilla. Y si necesitas información fresca de la web, la API también ofrece google_search para grounding con Google Search, con metadatos de verificación muy útiles para interfaces con citas trazables.

Qué es exactamente File Search en la Gemini API

File Search es una solución RAG totalmente gestionada integrada en Gemini API. En la práctica, subes tus archivos (o los importas desde el servicio de ficheros), y el sistema se encarga de trocearlos en fragmentos, generar embeddings, indexarlos en un File Search Store y usarlos como base para responder a las consultas del usuario mediante vector search.

El objetivo es que no tengas que lidiar con bases vectoriales, colas de indexación ni estrategias de chunking por tu cuenta. La herramienta se asienta sobre el modelo de embeddings de Google (por ejemplo, gemini-embedding-001) y se integra de forma nativa con generateContent, donde declaras el tool de File Search y la store a consultar.

Cómo funciona: del documento a la respuesta con contexto

El flujo conceptual es sencillo, aunque por debajo haya mucha chicha. Primero, tus documentos se convierten en representaciones numéricas (embeddings) que capturan el significado. Esos vectores se guardan en una store especializada. Luego, cuando mandas una consulta, la API convierte el prompt en otra embedding y ejecuta una búsqueda semántica para recuperar los trozos más relevantes.

Por último, en la llamada a generateContent con la herramienta de FileSearch, añades una FileSearchRetrievalResource que apunta a la store concreta. Con eso, el modelo sabe que debe recuperar contexto de tu store y usarlo para fundamentar su respuesta. Todo esto ocurre sin que tengas que programar la recuperación manual ni coser servicios externos.

Subir e importar documentos: dos caminos compatibles

Para llevar datos a tu store tienes dos opciones. Si quieres ir al grano, usa la API uploadToFileSearchStore para subir el archivo directamente e indexarlo en una sola operación. Si prefieres separar pasos, puedes subir el fichero con la Files API y después importarlo con importFile al File Search Store.

Cuando eliges subir e importar de golpe, se crea un File temporal como referencia al documento bruto; ese objeto se elimina a las 48 horas, pero los datos indexados permanecen en la store hasta que tú decidas borrarlos. Si usas Files API y luego importas, el pipeline pasa por almacenamiento de archivos antes de la fase de embeddings.

Control del chunking: precisión y solapamiento

Por defecto, la API decide una estrategia de troceado inteligente, pero si necesitas afinar, puedes especificar chunking_config con parámetros como máximo de tokens por fragmento y tokens de solapamiento. Con menos tokens por chunk ganarás granularidad en la búsqueda; con más, conservarás más contexto por fragmento.

Este control fino resulta útil en casos como código fuente, papers extensos o manuales técnicos, donde conviene ajustar el equilibrio entre precisión de recuperación y continuidad contextual.

File Search Stores: persistencia, alcance y gestión

Un File Search Store es el contenedor persistente donde viven las embeddings procesadas. A diferencia de los archivos crudos de la Files API (que desaparecen a las 48 horas), el contenido importado a la store se conserva hasta borrado explícito. Puedes crear varias stores para organizar tus dominios de conocimiento, y sus nombres son globalmente únicos.

La API de FileSearchStore te permite crear, listar, obtener y eliminar stores. Además, existe una API de Documentos para gestionar el contenido dentro de cada store, y puedes adjuntar metadata personalizada (pares clave-valor) a tus ficheros para filtrar búsquedas por subconjuntos. Para el filtro, se usa la sintaxis de listas de filtrado descrita en google.aip.dev/160.

Flujo detallado de uso con la API

En términos operativos, el proceso típico sigue tres pasos. Primero, creas el File Search Store. Después, subes e importas archivos (o subes y luego importas). Por último, preguntas al modelo con generateContent indicando la herramienta FileSearch y la store destino mediante FileSearchRetrievalResource.

En entornos JavaScript/TypeScript, una práctica habitual es usar operaciones concurrentes (por ejemplo, Promise.all) para cargar múltiples ficheros a la vez y monitorizar operation.done antes de continuar. También es común buscar la store por su displayName (humano-legible) si no recuerdas el identificador fileSearchStores/....

Gestión de documentos: encontrar, actualizar y eliminar

Dentro de una store, a veces interesa localizar un documento concreto por su displayName para administrarlo. Un detalle importante: los documentos son inmutables tras el indexado. Si necesitas actualizarlos, el patrón recomendado es borrar y volver a subir la versión nueva.

Como práctica operativa, muchos flujos automatizan este ciclo: buscar → eliminar → subir. Y cuando termines con los recursos (por ejemplo, en desarrollo), recuerda que hay un límite de 10 stores por proyecto, así que conviene realizar la limpieza si ya no los necesitas.

Citas y verificación: grounding en tus documentos

Una ventaja clave de File Search es que las respuestas del modelo pueden incluir citaciones automáticas que señalan los fragmentos de tus documentos usados para fundamentar la salida. Esta trazabilidad aparece en el atributo grounding_metadata de la respuesta y es crucial para auditoría, verificación y confianza en entornos empresariales.

De este modo, cuando el asistente responda, podrás mostrar referencias precisas a los trozos relevantes de tus ficheros, lo que facilita revisar afirmaciones y construir interfaces con citas en línea.

Formatos de archivo admitidos

File Search soporta una amplísima variedad de formatos. Entre los más comunes están 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, además de muchos lenguajes de programación y tipos de texto como text/plain, text/html, text/css, text/csv, text/markdown, text/javascript, text/yaml, etc.

También cubre numerosos tipos específicos (por ejemplo, código y scripts como application/x-php, application/x-powershell, application/x-sh, application/x-tex, application/x-zsh; y textuales 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 muchos otros). Si tu caso requiere un tipo poco habitual, lo más probable es que esté contemplado en la documentación oficial.

Límites de servicio y recomendaciones de arquitectura

Para mantener la estabilidad del servicio, la API establece límites claros: el tamaño máximo por archivo es 100 MB; el tamaño total agregado en stores depende del nivel de usuario: Free 1 GB, Tier 1 10 GB, Tier 2 100 GB y Tier 3 1 TB.

Como pauta de rendimiento, se recomienda mantener cada store por debajo de 20 GB para asegurar latencias óptimas. Ten en cuenta que el tamaño de una store se calcula en backend como el tamaño de entrada más las embeddings, que suelen multiplicar aproximadamente por tres el volumen de datos original.

Precios: simple y predecible

El modelo de cobro es directo: solo pagas por la creación de embeddings en el indexado, a un precio de 0,15 $ por cada 1 millón de tokens (según el coste del modelo de embeddings aplicable). El almacenamiento y la generación de embeddings en consulta no tienen coste adicional, y los tokens recuperados se facturan como tokens de contexto normales en generación.

Este esquema facilita presupuestar: el coste fuerte se concentra en la ingesta inicial (y en actualizaciones posteriores de documentos, si las hay), minimizando la sorpresa en consumos por volumen de consultas.

Modelos compatibles para File Search

La herramienta funciona con los modelos actuales de la familia Gemini. En los materiales de referencia se destaca la disponibilidad en Gemini 2.5 Pro y Gemini 2.5 Flash para File Search, con soporte de grounding, filtros por metadata y citaciones de cara a construir experiencias verificables.

En lo relativo a grounding con Google Search (tratado más abajo), hay un surtido más amplio de modelos con soporte, y se especifica que los modelos Experimentales y Preview no están incluidos.

Grounding con Google Search: información actual y citaciones web

Si además de tus documentos necesitas contenido web en tiempo real, puedes activar el tool google_search. El modelo gestiona todo el flujo: decidir si conviene buscar, generar y ejecutar consultas, procesar resultados, sintetizar y devolver una respuesta con metadatos de grounding (consultas, resultados y citaciones).

Cuando el grounding se realiza correctamente, la respuesta incluye groundingMetadata con campos como webSearchQueries (consultas empleadas), searchEntryPoint (HTML y CSS necesarios para las sugerencias de búsqueda, con requisitos de uso detallados en los Términos del Servicio), groundingChunks (fuentes web con uri y title) y groundingSupports (fragmentos que enlazan segmentos de texto del modelo con índices de groundingChunks para construir citaciones en línea).

Precios y modelos en grounding con Google Search

El uso de google_search se factura por cada solicitud que activa esa herramienta, incluso si el modelo lanza varias consultas internas para una misma petición; todo ello cuenta como un único uso facturable. Entre los modelos compatibles para este tool se listan Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.5 Flash-Lite, Gemini 2.0 Flash, Gemini 1.5 Pro y Gemini 1.5 Flash.

Para modelos anteriores de la 1.5 existe el tool heredado google_search_retrieval con modo dynamic, donde configuras un dynamic_threshold (0.0–1.0) y el modelo decide si realizar o no la búsqueda en función de su confianza en que necesita información reciente.

Casos de uso: de asistentes internos a soporte al cliente

File Search está orientado a entornos empresariales donde privacidad, exactitud y trazabilidad pesan. Sirve para asistentes de conocimiento que interrogan documentación propietaria, para automatizar soporte con respuestas citadas a manuales y políticas, o para acelerar búsqueda y revisión en sectores intensivos en información (legal, sanitario, financiero).

También acelera flujos de desarrollo y depuración al permitir conversar con bases de código o especificaciones técnicas. Su combinación con otras capacidades de Gemini (como ejecución de código o funciones) habilita integraciones ricas en procesos de cumplimiento, auditoría o analítica.

Operaciones y estado: trabajando con la API

La superficie REST expone métodos como fileSearchStores.create (crea una store vacía), fileSearchStores.delete (elimina una store), fileSearchStores.get (obtiene información de una store), fileSearchStores.list (enumera stores del usuario) e importFile (importa un File del servicio de ficheros a una store). Los endpoints de operations permiten consultar el estado de operaciones de larga duración, con cuerpos de solicitud que en varios casos van vacíos según la especificación.

En la ruta de subida directa (uploadToFileSearchStore) se expone un conjunto de operations específico para sondear el progreso. Este patrón es el habitual: lanzas la operación, compruebas periódicamente si ha terminado y, cuando finaliza, continúas con el flujo (por ejemplo, lanzar consultas RAG).

Buenas prácticas: filtros, etiquetado y latencia

Si prevés muchas consultas, etiqueta tus documentos con metadata y emplea metadataFilter para restringir la recuperación a subconjuntos relevantes. Mantener las stores dentro de la recomendación de tamaño ayuda a la latencia y a la estabilidad. Y si vas a cargar carpetas completas, aprovecha la subida concurrente para reducir tiempos de ingestión.

En escenarios técnicos, define estrategias de chunking acordes al contenido: por ejemplo, chunks más cortos y con solapado moderado para código (mejor precisión en funciones/clases), y chunks algo más largos en documentación narrativa para conservar contexto semántico.

Compatibilidad con otras herramientas de Gemini

Grounding con Google Search se puede combinar con URL context (para aportar URLs concretas) y con code execution o función de herramientas adicionales según el caso de uso. Así puedes mezclar conocimiento interno de File Search con información actualizada de la web, manteniendo siempre las citaciones y el rastro de fuentes.

Cuando diseñes la UX, aprovecha groundingSupports y groundingChunks para ofrecer citaciones clicables junto al texto del modelo. Es la forma más clara de que las personas usuarias verifiquen la procedencia de cada afirmación.

File Search en Gemini API ofrece un camino muy directo para dotar a tus aplicaciones de respuestas bien fundamentadas en tus propios datos, minimizando fricción operativa. Su combinación de coste predecible en el indexado, soporte de formatos variados, filtros por metadata, citaciones automáticas y grounding con Google Search conforma un stack listo para producción que quita hierro a la implantación de RAG en equipos de todos los tamaños.