Desarrollo de una Aplicación RAG con Nuxt y Gemini File Search: Guía Técnica Completa
La Generación Aumentada por Recuperación, conocida por sus siglas en inglés como RAG (Retrieval-Augmented Generation), representa uno de los paradigmas más sólidos en el desarrollo de aplicaciones de inteligencia artificial generativa. A diferencia de los modelos de lenguaje que operan exclusivamente sobre sus datos de entrenamiento estáticos, la arquitectura RAG permite inyectar contexto externo y actualizado directamente en el proceso de inferencia. En este tutorial se detalla cómo construir una aplicación RAG funcional utilizando el framework Nuxt y la API Gemini File Search de Google, cubriendo desde la configuración del entorno hasta la creación de una interfaz de usuario interactiva para realizar consultas sobre documentos propios.
La combinación de Nuxt como framework full-stack y la API Gemini de Google resulta especialmente potente para este tipo de proyectos. Nuxt ofrece una arquitectura unificada que permite gestionar tanto el frontend como el backend a través de sus server routes, eliminando la necesidad de mantener servicios separados. Por su parte, la API Gemini File Search abstrae la complejidad del pipeline RAG tradicional, ocupándose internamente de la división en fragmentos (chunking), la generación de embeddings y la recuperación semántica. Esta sinergia reduce considerablemente la complejidad operativa y el tiempo de desarrollo.
Fundamentos de la Arquitectura RAG
Para comprender el valor de esta implementación, es necesario revisar brevemente cómo funciona un sistema RAG en su forma canónica. El proceso se divide en dos fases principales: la fase de indexación y la fase de recuperación y generación. Durante la indexación, los documentos fuente se fragmentan en unidades de texto manejables denominadas chunks, se convierten en vectores numéricos mediante modelos de embeddings y se almacenan en una base de datos vectorial. En la fase de consulta, el texto introducido por el usuario se transforma también en un vector, se calcula su similitud semántica con los fragmentos almacenados y los más relevantes se incorporan como contexto adicional al prompt que se envía al modelo generativo.
Este enfoque resuelve dos limitaciones críticas de los LLMs (Large Language Models) convencionales. En primer lugar, elimina el problema del conocimiento desactualizado, ya que los documentos indexados pueden actualizarse en cualquier momento sin necesidad de reentrenar el modelo. En segundo lugar, reduce significativamente las alucinaciones, dado que el modelo dispone de referencias factuales concretas sobre las que basar sus respuestas. La API Gemini File Search encapsula toda la lógica vectorial, exponiendo una interfaz de alto nivel que simplifica la integración en aplicaciones web modernas.
Configuración Inicial del Entorno de Desarrollo
El primer paso consiste en inicializar un nuevo proyecto Nuxt e instalar las dependencias necesarias. Es imprescindible contar con Node.js en su versión LTS más reciente y un gestor de paquetes como npm, pnpm o bun. La estructura del proyecto seguirá las convenciones estándar de Nuxt, aprovechando el directorio server/ para definir los endpoints API y el directorio pages/ o components/ para la interfaz de usuario.
# Crear un nuevo proyecto Nuxt
npx nuxi@latest init rag-nuxt-gemini
cd rag-nuxt-gemini
# Instalar el SDK oficial de Google Generative AI
npm install @google/generative-ai
# Instalar dependencias adicionales para el manejo de archivos
npm install @google/generativeai formidable
La protección de las credenciales es un aspecto no negociable en cualquier proyecto que interactúe con APIs externas. La clave de API de Gemini debe almacenarse exclusivamente como variable de entorno y nunca exponerse en el código fuente ni en el repositorio de control de versiones. Nuxt gestiona estas variables a través del archivo .env en desarrollo y mediante la configuración del servidor en producción, accediendo a ellas de forma segura desde el contexto del servidor.
# Archivo .env (añadir al .gitignore)
GEMINI_API_KEY=tu_clave_de_api_aqui
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
geminiApiKey: process.env.GEMINI_API_KEY, // Solo accesible en servidor
public: {
// Variables públicas (visibles en cliente) van aquí
}
}
})
Implementación de los Endpoints del Servidor
Nuxt permite definir endpoints API mediante el sistema de rutas del servidor ubicadas en server/api/. Para esta aplicación RAG se requieren tres endpoints principales: uno para la carga e indexación de archivos, otro para listar los archivos ya procesados y un tercero para ejecutar consultas sobre el corpus indexado. Cada uno de estos endpoints interactúa con la API de Gemini a través del SDK oficial, utilizando las credenciales protegidas del entorno de servidor.
// server/api/upload.post.ts
import { GoogleGenerativeAI } from '@google/generative-ai'
import { GoogleAIFileManager } from '@google/generative-ai/server'
export default defineEventHandler(async (event) => {
const config = useRuntimeConfig()
const fileManager = new GoogleAIFileManager(config.geminiApiKey)
// Leer el archivo del cuerpo de la petición multipart
const formData = await readMultipartFormData(event)
if (!formData || formData.length === 0) {
throw createError({ statusCode: 400, message: 'No se proporcionó ningún archivo' })
}
const file = formData[0]
const uploadResponse = await fileManager.uploadFile(file.data, {
mimeType: file.type || 'application/pdf',
displayName: file.filename || 'documento',
})
return {
success: true,
fileUri: uploadResponse.file.uri,
displayName: uploadResponse.file.displayName,
mimeType: uploadResponse.file.mimeType,
}
})
// server/api/query.post.ts
import { GoogleGenerativeAI } from '@google/generative-ai'
export default defineEventHandler(async (event) => {
const config = useRuntimeConfig()
const body = await readBody(event)
const { question, fileUris } = body
if (!question || !fileUris?.length) {
throw createError({ statusCode: 400, message: 'Se requiere pregunta y archivos indexados' })
}
const genAI = new GoogleGenerativeAI(config.geminiApiKey)
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' })
// Construir el prompt con las referencias a los archivos indexados
const contentParts = fileUris.map((uri: string) => ({
fileData: { mimeType: 'application/pdf', fileUri: uri }
}))
const result = await model.generateContent([
...contentParts,
{ text: `Basándote exclusivamente en los documentos proporcionados, responde: ${question}` }
])
return {
answer: result.response.text(),
tokensUsed: result.response.usageMetadata?.totalTokenCount
}
})
Construcción de la Interfaz de Usuario Interactiva
La capa de presentación de la aplicación debe ofrecer tres funcionalidades claramente diferenciadas: la carga de documentos, la visualización del corpus indexado y el panel de consultas. Utilizando las capacidades de composición reactiva de Vue 3 junto con las utilidades de data fetching de Nuxt como useFetch y $fetch, se puede construir una interfaz fluida y con gestión de estado coherente sin necesidad de bibliotecas adicionales de gestión de estado.
<!-- pages/index.vue -->
<template>
<div class="rag-app">
<section class="upload-section">
<h3>Indexar Documentos</h3>
<input type="file" accept=".pdf,.txt,.md" @change="handleFileUpload" />
<p v-if="uploadStatus">{{ uploadStatus }}</p>
</section>
<section class="query-section">
<h3>Realizar Consulta</h3>
<textarea v-model="userQuery" placeholder="Escribe tu pregunta..." />
<button @click="executeQuery" :disabled="isLoading || !indexedFiles.length">
{{ isLoading ? 'Procesando...' : 'Consultar' }}
</button>
<div v-if="answer" class="answer-box">
<strong>Respuesta:</strong>
<p>{{ answer }}</p>
</div>
</section>
</div>
</template>
<script setup lang="ts">
const indexedFiles = ref<Array<{ uri: string; name: string }>>([])
const userQuery = ref('')
const answer = ref('')
const isLoading = ref(false)
const uploadStatus = ref('')
async function handleFileUpload(event: Event) {
const input = event.target as HTMLInputElement
if (!input.files?.length) return
const formData = new FormData()
formData.append('file', input.files[0])
uploadStatus.value = 'Indexando documento...'
try {
const result = await $fetch('/api/upload', { method: 'POST', body: formData })
indexedFiles.value.push({ uri: result.fileUri, name: result.displayName })
uploadStatus.value = `✓ "${result.displayName}" indexado correctamente`
} catch (error) {
uploadStatus.value = 'Error al indexar el documento'
}
}
async function executeQuery() {
if (!userQuery.value.trim()) return
isLoading.value = true
answer.value = ''
try {
const result = await $fetch('/api/query', {
method: 'POST',
body: {
question: userQuery.value,
fileUris: indexedFiles.value.map(f => f.uri)
}
})
answer.value = result.answer
} finally {
isLoading.value = false
}
}
</script>
Consideraciones de Rendimiento y Buenas Prácticas
La gestión del ciclo de vida de los archivos en la API de Gemini es un aspecto crítico que a menudo se pasa por alto en implementaciones iniciales. Los archivos subidos tienen una duración limitada en los servidores de Google (actualmente 48 horas), por lo que una aplicación en producción debe implementar una estrategia de persistencia que almacene los URIs de los archivos indexados en una base de datos propia. De este modo, si un archivo caduca, el sistema puede detectarlo y solicitar al usuario que lo vuelva a cargar, o bien automatizar el proceso de re-indexación.
Desde el punto de vista de la seguridad, es fundamental validar exhaustivamente los archivos recibidos antes de enviarlos a la API. Se deben verificar el tipo MIME real del archivo mediante inspección de bytes (magic numbers), establecer límites de tamaño razonables y sanitizar los nombres de archivo para prevenir ataques de path traversal. Adicionalmente, implementar rate limiting en los endpoints del servidor protege tanto los recursos de la aplicación como la cuota de uso de la API de Gemini.
Para optimizar la experiencia en escenarios con documentos extensos, conviene considerar la implementación de procesamiento asíncrono. En lugar de bloquear la respuesta HTTP hasta que la indexación complete, el endpoint de carga puede retornar inmediatamente un identificador de tarea y exponer un endpoint de estado que el cliente pueda consultar mediante polling o WebSockets. Nuxt Server-Sent Events o las capacidades de streaming de la API de Gemini son opciones nativas que facilitan esta implementación sin infraestructura adicional.
"La arquitectura RAG no es simplemente una técnica de recuperación de información; es un mecanismo fundamental para fundamentar los modelos generativos en la realidad documental de cada organización, convirtiendo un LLM genérico en un experto específico de dominio."
Resumen del Stack Tecnológico Utilizado
- Framework frontend/backend: Nuxt 3 con Vue 3 y Composition API
- Modelo generativo: Gemini 1.5 Flash a través de la API de Google
- Gestión de archivos: Google AI File Manager (SDK oficial)
- Seguridad de credenciales: Variables de entorno con
runtimeConfigde Nuxt - Formatos de documentos soportados: PDF, TXT, Markdown y otros formatos compatibles con Gemini
- Comunicación cliente-servidor: Fetch API nativa mediante
$fetchyuseFetch
Próximos Pasos y Extensiones Posibles
- Integrar una base de datos como PostgreSQL con pgvector para persistir los metadatos de los archivos indexados.
- Implementar autenticación de usuarios para aislar los corpus documentales por cuenta.
- Añadir soporte para múltiples formatos de entrada: imágenes, hojas de cálculo y presentaciones.
- Incorporar un historial de conversación para habilitar consultas de seguimiento contextuales.
- Desplegar la aplicación en plataformas serverless compatibles con Nuxt como Vercel, Netlify Edge o Cloudflare Workers.
La construcción de una aplicación RAG con Nuxt y Gemini File Search demuestra cómo la convergencia entre frameworks web maduros y APIs de IA de alto nivel puede reducir drásticamente la barrera de entrada para desarrollar soluciones de inteligencia artificial generativa empresarial. Lo que hace apenas dos años requería equipos especializados en MLOps, infraestructura vectorial y orquestación de modelos, hoy puede implementarse por un equipo de desarrollo web con conocimientos estándar de JavaScript y TypeScript. Este democratización tecnológica abre un abanico de posibilidades para organizaciones de cualquier tamaño que deseen explotar el valor latente en su patrimonio documental.
