How ruben-quilez/maxi_bot works
A continuación se muestra una guía detallada para diseñar un diagrama de arquitectura que capture con precisión la estructura y flujo de datos de este sistema RAG. La idea es representar de manera clara y detallada los componentes principales y sus interacciones, utilizando formas, colores y direccionalidad que hagan evidente el flujo de información y las dependencias. La explicación se adapta específicamente al proyecto presentado.
Proyecto y propósito
• Tipo de proyecto: Este es un sistema de Retrieval Augmented Generation (RAG) que combina la generación de embeddings/respuestas mediante OpenAI y la búsqueda/almacenamiento en Qdrant, una base de datos vectorial.
• Propósito: Realizar consultas de preguntas, buscar respuestas relevantes en un dataset previamente cargado en Qdrant, y generar respuestas contextuales usando modelos de OpenAI.
Principales componentes del sistema
a. API / Backend:
• Ubicado en la carpeta “app”. Implementado con FastAPI (implicado en la definición de endpoints en endpoints.py, configuración en config.py y lógica en main.py y utils.py).
• Realiza la orquestación del flujo: recibe solicitudes, consulta Qdrant, obtiene embeddings de OpenAI y genera respuestas.
• Contenedor Docker definido con el Dockerfile (en app/Dockerfile) y administrado mediante Docker Compose.
b. Qdrant:
• Base de datos vectorial para almacenar y recuperar datos (ubicado en el directorio “qdrant” con subdirectorios para configuración y datos).
• Se despliega como servicio (contenedor) definido en docker-compose.yml.
c. Dataset y Script de carga:
• Archivo dataset.json como fuente de datos de preguntas y respuestas.
• El script “scripts/load_dataset.py” es el encargado de cargar estos datos en Qdrant. Se utiliza en la inicialización mediante el script init_service.sh.
d. Integración con OpenAI:
• Utilizado para generar embeddings y respuestas; la configuración se maneja en las variables de entorno (.env, en env.example) y a través del código en la aplicación (config.py, endpoints.py, etc.).
• Especificación de modelos (como text-embedding-3-large y gpt-4o-mini-2024-07-18).
Relaciones e interacciones
• El cliente (por ejemplo, a través de Swagger UI) realiza solicitudes HTTP a la API.
• La API procesa peticiones:
• Extrae y procesa la consulta.
• Realiza búsquedas en Qdrant para obtener datos relevantes basados en embeddings.
• Llama a la API de OpenAI para generar respuestas a partir de los prompts predefinidos (ubicados en “app/static/prompts”).
• El script de inicialización (init_service.sh) facilita la configuración del entorno, creación del entorno virtual, verificación de la existencia del dataset y carga inicial de datos en Qdrant.
• Docker Compose se utiliza para levantar conjuntamente los servicios de la API FastAPI y Qdrant, manteniendo la conexión vía QDRANT_HOST (ya sea "maxi_qdrant" en Docker o "localhost" en ejecución local).
Recomendaciones para el diagrama
• Componentes visuales:
• Dibujar bloques para cada uno de los principales módulos:
1. Cliente/Interfaz de Usuario (Swagger UI/Redoc o terminal).
2. API FastAPI (Backend).
3. Servicio OpenAI (externo, indicado como servicio de terceros).
4. Base de Datos Qdrant (vectorial).
5. Dataset y Scripts de inicialización.
• Incluir contenedores Docker para la API y Qdrant, representando el entorno de despliegue.
• Mostrar la dependencia de configuración (archivo .env y variables clave que se usan en la aplicación).
• Conexiones y flujo de datos:
• Utilizar flechas direccionales para mostrar:
• Flujo de solicitudes entrantes desde el Cliente a la API.
• La llamada de la API al servicio de OpenAI.
• La consulta y actualización de datos entre la API y Qdrant.
• Indicar en las flechas los protocolos o tipos de petición, por ejemplo, HTTP o API REST.
• Detalles técnicos:
• Etiquetar cada bloque con su función (p.ej., “API REST (FastAPI)”, “Base de Datos Qdrant”, “Servicio de OpenAI”).
• Usar colores distintos para diferenciar componentes internos (backend, base de datos) versus servicios externos.
• Incluir un bloque extra para el “Script de Inicialización / Carga de Dataset”, indicando su función en el proceso de configuración.
Pautas de detalle para un diagrama específico a este proyecto
• Asegurarse de dividir claramente entre backend (API) y base de datos (Qdrant). Aun siendo una aplicación de backend, enfatizar la integración con un servicio externo (OpenAI) que juega un papel crítico.
• Incluir las capas de infraestructura: contenedores Docker (Dockerfile en app, docker-compose.yml) y el proceso de inicialización (init_service.sh) que automatiza la configuración.
• Representar el flujo de datos en el proceso de Query: Desde la solicitud del usuario, generación de embeddings, consulta en Qdrant, hasta la respuesta generada.
• Destacar en el diagrama la interacción dual entre el sistema (por ejemplo, la misma API que maneja endpoints para consulta y adición de Q&A).
Elementos gráficos
• Etiquetas claras en cada componente.
• Flechas direccionadas para ilustrar el flujo de datos e interacciones.
• Uso de colores o formas (por ejemplo, rectángulos, cilindros para bases de datos) para distinguir entre servicios, bases de datos, componentes de terceros y scripts de administración.
Siguiendo estos lineamientos, se obtendrá un diagrama de arquitectura completo y ajustado a las necesidades del proyecto. Esto no solo ayudará a clarificar la estructura del sistema, sino que también facilitará la comunicación entre los equipos de desarrollo y operaciones, permitiendo entender rápidamente cómo se integran OpenAI, Qdrant y la API FastAPI en una solución RAG robusta y escalable.