Construcción de una aplicación RAG con Nuxt y Gemini File Search: Tutorial Completo
La inteligencia artificial generativa ha transformado radicalmente la forma en que los desarrolladores conciben las aplicaciones modernas. Sin embargo, uno de los desafíos más persistentes al trabajar con modelos de lenguaje de gran escala (LLMs) es su incapacidad inherente para acceder a información propietaria, documentos internos o datos actualizados más allá de su ventana de entrenamiento. Es precisamente aquí donde la técnica denominada RAG (Retrieval-Augmented Generation) emerge como una solución arquitectónica robusta, permitiendo que los modelos respondan con precisión basándose en fuentes de conocimiento específicas y controladas por el desarrollador.
En este tutorial, exploraremos en profundidad cómo construir una aplicación RAG funcional y completa utilizando Nuxt como framework full-stack y la API Gemini File Search de Google como motor de indexación y recuperación semántica. La combinación de estas dos tecnologías ofrece una base sólida para desarrollar sistemas de consulta documental inteligentes, capaces de responder preguntas concretas sobre el contenido de archivos de texto subidos por el usuario, sin depender de los datos genéricos con los que fue entrenado el modelo.
¿Qué es RAG y por qué es relevante en el desarrollo moderno?
RAG, o Generación Aumentada por Recuperación, es un patrón arquitectónico que combina dos etapas fundamentales: la recuperación de fragmentos relevantes desde una base de conocimiento indexada y la generación de respuestas coherentes por parte de un LLM que utiliza esos fragmentos como contexto. En lugar de depender exclusivamente del conocimiento parametrizado del modelo, el sistema consulta activamente un almacén vectorial o documental para enriquecer el prompt con información pertinente antes de formular la respuesta final.
Esta arquitectura resuelve varios problemas críticos en entornos empresariales: las alucinaciones del modelo se reducen drásticamente porque la respuesta se ancla en documentos reales, la información puede actualizarse sin necesidad de reentrenar el modelo, y es posible trabajar con datos sensibles o confidenciales que nunca formarán parte de un dataset público. Para comprender mejor el ecosistema técnico de esta solución, es fundamental manejar tres conceptos clave que estructuran toda la implementación:
- Chunk: Fragmento de texto extraído de un documento fuente. El proceso de chunking divide documentos extensos en unidades semánticas más pequeñas y manejables, optimizando la precisión de la recuperación.
- Store: Almacén o repositorio donde se persisten los chunks indexados, ya sea en forma de embeddings vectoriales o mediante índices estructurados compatibles con el motor de búsqueda utilizado.
- Tool: En el contexto de la API Gemini, una herramienta (tool) es una función declarada que el modelo puede invocar autónomamente para recuperar información adicional, integrándose de forma nativa en el flujo de razonamiento del LLM.
Prerrequisitos y configuración inicial del proyecto
Antes de iniciar la implementación, es necesario cumplir con un conjunto de prerrequisitos técnicos que garantizarán un entorno de desarrollo funcional. En primer lugar, se requiere tener instalado Node.js 18 o superior, ya que Nuxt 3 depende de las APIs modernas del entorno de ejecución. Además, se necesita una cuenta activa en Google AI Studio para obtener una clave de API de Gemini con acceso habilitado al servicio File Search. Por último, es recomendable contar con familiaridad básica en el modelo de rutas y el sistema de server-side rendering de Nuxt 3.
La inicialización del proyecto se realiza mediante el CLI oficial de Nuxt. Una vez creado el scaffolding base, se instalan las dependencias necesarias, siendo la más relevante el SDK oficial de Google Generative AI. La variable de entorno GEMINI_API_KEY debe configurarse en el archivo .env del proyecto y referenciarse dentro del objeto runtimeConfig en el archivo nuxt.config.ts, asegurando que la clave nunca quede expuesta en el bundle del cliente.
# Crear proyecto Nuxt
npx nuxi@latest init rag-nuxt-app
cd rag-nuxt-app
# Instalar dependencias necesarias
npm install @google/generative-ai
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
geminiApiKey: process.env.GEMINI_API_KEY,
},
})
Implementación del servidor: utilidades, almacenamiento e indexación
El núcleo del sistema RAG reside en la capa de servidor de Nuxt, aprovechando el directorio server/ que expone endpoints API nativos mediante el motor Nitro. El primer paso consiste en crear un módulo de utilidades dentro de server/utils/gemini.ts que encapsule la inicialización del cliente de Gemini y las funciones reutilizables para la subida de archivos y la creación de herramientas de búsqueda.
La función de indexación es el componente más crítico de la arquitectura. Cuando el usuario sube un documento de texto, el servidor lo transmite a la API de Gemini Files, la cual lo procesa, genera representaciones internas optimizadas para la búsqueda semántica y devuelve un identificador único (fileUri). Este identificador se almacena en un objeto de estado en memoria del servidor —o en una base de datos persistente en escenarios de producción— y es referenciado posteriormente durante las consultas. La implementación del endpoint de subida en server/api/upload.post.ts maneja la recepción del archivo mediante readMultipartFormData, una utilidad nativa de Nitro que simplifica el procesamiento de formularios multipart.
// server/utils/gemini.ts
import { GoogleGenerativeAI } from '@google/generative-ai'
export const initGemini = () => {
const config = useRuntimeConfig()
return new GoogleGenerativeAI(config.geminiApiKey)
}
export const createFileSearchTool = (fileUri: string) => ({
functionDeclarations: [{
name: 'search_document',
description: 'Recupera información relevante del documento indexado',
parameters: {
type: 'object',
properties: {
query: { type: 'string', description: 'Consulta de búsqueda' }
},
required: ['query']
}
}],
fileUri,
})
// server/api/upload.post.ts
export default defineEventHandler(async (event) => {
const formData = await readMultipartFormData(event)
const file = formData?.find(f => f.name === 'document')
if (!file) {
throw createError({ statusCode: 400, message: 'No se recibió ningún archivo' })
}
const genAI = initGemini()
const fileManager = genAI.getFileManager()
const uploadedFile = await fileManager.uploadFile(
Buffer.from(file.data),
{ mimeType: file.type || 'text/plain', displayName: file.filename || 'document.txt' }
)
// Persistir fileUri en store en memoria
useStorage().setItem('currentFile', uploadedFile.file.uri)
return { fileUri: uploadedFile.file.uri, status: 'indexed' }
})
Endpoint de consulta y razonamiento aumentado con Gemini
Una vez que el documento está indexado y su fileUri almacenado, el endpoint de consulta en server/api/query.post.ts implementa el flujo RAG completo. El proceso inicia recuperando el fileUri del store, construyendo la herramienta de búsqueda correspondiente y pasándola al modelo Gemini junto con la pregunta del usuario. Lo que distingue a este enfoque de una simple llamada al LLM es que el modelo tiene la capacidad de invocar la herramienta para acceder al contenido del archivo antes de formular su respuesta, garantizando que la información provenga directamente del documento subido.
El manejo del ciclo de razonamiento es fundamental: la API de Gemini puede devolver una respuesta que incluye llamadas a herramientas (functionCall), las cuales el servidor debe interceptar, ejecutar la lógica asociada —en este caso, la búsqueda en el archivo— y retornar el resultado al modelo en una segunda vuelta del ciclo. Este patrón de agentic loop permite al modelo construir respuestas complejas fundamentadas en evidencia documental real, elevando significativamente la fidelidad y precisión de las respuestas generadas.
// server/api/query.post.ts
export default defineEventHandler(async (event) => {
const { question } = await readBody(event)
const fileUri = await useStorage().getItem('currentFile') as string
if (!fileUri) {
throw createError({ statusCode: 404, message: 'No hay documentos indexados' })
}
const genAI = initGemini()
const model = genAI.getGenerativeModel({
model: 'gemini-1.5-flash',
tools: [{ codeExecution: {} }],
})
const result = await model.generateContent({
contents: [{
role: 'user',
parts: [
{ fileData: { mimeType: 'text/plain', fileUri } },
{ text: question }
]
}]
})
return { answer: result.response.text() }
})
Interfaz de usuario en Nuxt: flujo completo de carga y consulta
La capa frontend de la aplicación se implementa mediante un componente Vue 3 dentro de pages/index.vue, haciendo uso de las utilidades de composición reactiva como ref y useState nativas de Nuxt. La interfaz se divide en tres secciones funcionales claramente diferenciadas: el panel de carga de documentos, el indicador de estado de indexación y el formulario de consulta. Esta segmentación no es solo estética; responde a la necesidad de guiar al usuario a través del flujo secuencial que impone la arquitectura RAG: primero indexar, luego consultar.
El componente gestiona el estado de carga mediante variables reactivas que controlan los indicadores de progreso y los mensajes de retroalimentación. La subida del archivo se realiza utilizando la API nativa FormData del navegador, enviando el documento al endpoint /api/upload mediante $fetch, el cliente HTTP integrado en Nuxt. Una vez confirmada la indexación, el panel de consulta se habilita, permitiendo al usuario introducir preguntas en lenguaje natural que son dirigidas al endpoint /api/query. Las respuestas del modelo se renderizan en pantalla con soporte para markdown básico, mejorando la legibilidad de respuestas estructuradas.
"La verdadera potencia de RAG no radica únicamente en el modelo de lenguaje, sino en la calidad del pipeline de recuperación que alimenta su contexto. Un sistema de indexación preciso es la diferencia entre una respuesta útil y una alucinación bien redactada."
Consideraciones de producción y escalabilidad
La implementación presentada en este tutorial utiliza almacenamiento en memoria para persistir los identificadores de archivos, lo cual es adecuado para entornos de desarrollo y pruebas pero insuficiente para sistemas en producción. Para escalar esta solución, se recomienda adoptar una capa de persistencia como Redis o una base de datos relacional que asocie los fileUri a usuarios específicos, soporte múltiples documentos por sesión e implemente políticas de expiración alineadas con las restricciones de retención de la API de Gemini Files, que actualmente mantiene los archivos disponibles durante un máximo de 48 horas.
Adicionalmente, en escenarios con volúmenes documentales elevados, es recomendable implementar una estrategia de chunking explícita en el servidor antes de enviar los archivos a la API, segmentando documentos largos en fragmentos semánticamente coherentes de entre 500 y 1000 tokens. Esto mejora la precisión de la recuperación y reduce el riesgo de que el modelo reciba contextos demasiado extensos que degraden la calidad de la respuesta. La combinación de Nuxt como plataforma full-stack y Gemini File Search como motor de búsqueda semántica constituye una base tecnológica madura y capaz de sustentar aplicaciones RAG de nivel empresarial con una complejidad de implementación notablemente reducida.
- Reemplazar el store en memoria por Redis o una base de datos persistente.
- Implementar autenticación para asociar documentos a usuarios individuales.
- Agregar chunking explícito para documentos que superen los 10,000 tokens.
- Configurar un sistema de caché para consultas frecuentes sobre los mismos documentos.
- Monitorear el uso de la API con un sistema de logging estructurado para optimizar costos.
