Este es un agente de Inteligencia Artificial corporativo basado en el patrón RAG (Retrieval-Augmented Generation) diseñado para la empresa TechNova. Su propósito es responder preguntas de los colaboradores de forma precisa, basándose exclusivamente en los documentos internos de la empresa.
Important
🌐 ¡PROBAR DEMO EN VIVO!
El sistema se encuentra desplegado y listo para su evaluación. Puedes interactuar con el agente en tiempo real ingresando al siguiente enlace:
👉 https://techie-allura.viewdns.net/
- Descripción del Proyecto
- Estado del Proyecto
- Demostración de Funciones y Aplicaciones
- Ejemplos de Preguntas y Respuestas
- Evidencia de Funcionamiento
- Acceso al Proyecto
- Tecnologías Utilizadas
- Personas Contribuyentes
- Personas Desarrolladoras del Proyecto
- Licencia
Techie es una solución de IA empresarial diseñada para resolver el problema del acceso fragmentado a la información interna en TechNova. Muchas veces, los colaboradores pierden tiempo valioso buscando políticas corporativas, guías de soporte, precios o detalles de integración que están dispersos en múltiples formatos.
Para solucionar esto, Techie implementa una arquitectura RAG robusta que:
- Extrae e Ingiere contenido desde documentos multiformato en una carpeta local o remota.
- Indexa Vectorialmente la información usando embeddings multilingües avanzados.
- Recupera de Forma Híbrida (búsqueda vectorial en Chroma + Reranking con Cohere API) los fragmentos más relevantes.
- Genera Respuestas en Lenguaje Natural citando rigurosamente las fuentes exactas y controlando la alucinación a través de un umbral de confianza mínimo.
- Expone un Servidor Web API con FastAPI para servir una interfaz de chat moderna, rápida e interactiva junto a un panel de métricas para la administración y monitoreo.
El sistema está optimizado para ejecutarse en entornos serverless livianos de Oracle Cloud Infrastructure (OCI), minimizando los costos de infraestructura al no requerir GPUs dedicadas gracias al uso de modelos de lenguaje por API (Cohere).
El proyecto se encuentra en la versión v0.4.0 y está en Estado: Listo para Producción.
- Extracción multiformato (PDF, DOCX, XLSX, PPTX, HTML, CSV, JSON, MD) completada.
- Pipeline de ingesta inteligente con manifest de cambios (
manifest.json) implementado. - Indexación vectorial con Chroma DB e integración con API Cohere terminada.
- Reranking con Cohere y filtrado por metadatos (categoría) operativo.
- Interfaz de chat responsiva y panel de métricas implementados.
- Contenerización con Docker y soporte para despliegue en OCI Container Instances probado.
- Logging estructurado de Q&A y feedback de usuarios.
El agente Techie cuenta con las siguientes capacidades listas para su uso:
- Procesamiento de Documentos Multiformato: Ingiere y analiza de manera transparente archivos
.pdf,.docx,.xlsx,.pptx,.html,.csv,.jsony.mddepositados en la carpetadata/documents/. - Interfaz de Chat Interactiva:
- Banner de Advertencia de IA: Aclara permanentemente que las respuestas son generadas de forma automatizada.
- Chips de Citas / Fuentes: Muestra de qué archivos o URLs se obtuvo la información para que el usuario pueda validarla.
- Indicador de Confianza: Semáforo visual (verde, amarillo, rojo) según el puntaje de similitud del fragmento de origen.
- Sugerencias Dinámicas: Ofrece preguntas sugeridas de seguimiento generadas dinámicamente por el LLM o preguntas de arranque.
- Guía Flotante: Despliega pistas y plantillas de preguntas predeterminadas clasificadas por área corporativa (Comercial, Producto, Soporte, Datos, Legal).
- Prevención de Alucinaciones: Si la similitud máxima del mejor fragmento recuperado es inferior al umbral de seguridad
CONFIDENCE_MIN(por defecto0.4), el agente responde: "No encontré esa información en los documentos disponibles" en lugar de alucinar o inventar respuestas. - Mantenimiento y Observabilidad:
- Registra las preguntas y respuestas en
data/logs/qa.jsonl(incluye latencias, modelos, flags de no respuesta y confianza). - Permite recolectar feedback de los usuarios (👍/👎) en
data/feedback/feedback.jsonl. - Expone métricas agregadas en tiempo real en
/api/metricsy visualmente en/panel.
- Registra las preguntas y respuestas en
El agente Techie está entrenado para responder preguntas sobre la plataforma TechNova (gestión de proyectos, planes, soporte, APIs, etc.). A continuación se presentan ejemplos reales de preguntas que el agente puede responder y el tipo de respuestas generadas:
- Pregunta del Usuario:
¿Cuáles son los planes de pago disponibles en TechNova y qué descuento tienen?
- Respuesta generada por el Agente:
TechNova ofrece cuatro planes de pago además del plan gratuito:
- Starter: $5 USD/usuario/mes, para equipos pequeños de hasta 15 usuarios.
- Pro: $9 USD/usuario/mes, con usuarios ilimitados y acceso a la vista Gantt.
- Business: $18 USD/usuario/mes, con reportes avanzados y roles personalizados.
- Enterprise: Precio personalizado para grandes organizaciones, con SLA del 99.95% y CSM asignado.
Con el ciclo de pago anual, los planes tienen cerca de un 17% de descuento (se pagan 10 meses por año).
Fuentes citadas:
comercial/planes_y_precios.xlsx,producto/base_conocimiento.md
- Pregunta del Usuario:
¿Cómo contacto al equipo de soporte y cuánto tardan en responder?
- Respuesta generada por el Agente:
Puedes contactar a soporte escribiendo un correo a
soporte@technova.como utilizando el chat dentro de la aplicación.El tiempo de respuesta depende del plan contratado:
- Starter: 72 horas.
- Pro: 48 horas.
- Business: 8 horas.
- Enterprise: 1 hora (con SLA).
Fuentes citadas:
soporte/faq_soporte.html
- Pregunta del Usuario:
¿Cómo configuro la facturación automática para mi cuenta de Salesforce?
- Respuesta generada por el Agente (Anti-alucinación activa):
No encontré esa información en los documentos disponibles.
Fuentes citadas: Ninguna (se activó el umbral de seguridad por falta de coincidencia en base vectorial).
Para verificar el correcto funcionamiento del agente Techie, se disponen los siguientes recursos como evidencia en la carpeta docs/images/:
https://techie-allura.viewdns.net/
En el siguiente enlace o reproductor puedes observar al agente interactuando en tiempo real:
Note
Si el video no se reproduce automáticamente en el visor de GitHub, puedes descargarlo o reproducirlo directamente desde la ruta local docs/images/demo_funcionamiento.mp4.
A continuación se muestran dos capturas de pantalla clave:
-
Interfaz del Chat en Ejecución: Detalle de la conversación donde se visualizan las fuentes citadas, las preguntas sugeridas de seguimiento y el nivel de confianza de la respuesta.
-
Panel de Métricas y Observabilidad: Vista de la pantalla de métricas de uso y rendimiento para la administración corporativa de la IA.
-
Publicación en Oracle Cloud Infrastructure: Vista del monitoreo de la instancia donde se deployó la aplicación (en OCI).
- Python >= 3.10
- Cuenta en Cohere para obtener una API Key gratuita o de producción.
- Docker (opcional, para despliegue contenerizado).
-
Clona el repositorio:
git clone https://github.com/gregory-mc/Agente-RAG-AluraChallenge.git cd Agente-RAG-AluraChallenge -
Crea y activa un entorno virtual de Python:
python -m venv .venv source .venv/bin/activate # En Windows usa: .venv\Scripts\activate
-
Instala las dependencias:
pip install -r requirements.txt
Copia el archivo de plantilla .env.example como .env:
cp .env.example .envEdita .env y coloca tu API Key de Cohere:
COHERE_API_KEY=tu_api_key_real_aqui-
Colocar documentos: Agrega tus archivos corporativos en la carpeta
data/documents/(se proveen algunos archivos de ejemplo de la empresa ficticia TechNova). -
Ejecutar Ingesta: Procesa e indexa los documentos en la base de datos vectorial Chroma DB:
python -m rag ingest
Nota: La ingesta es inteligente. Si vuelves a correrla, solo reindexará los archivos modificados o nuevos analizando su hash.
-
Iniciar Servidor Web: Arranca la aplicación FastAPI:
python -m rag serve
Abre tu navegador en
http://localhost:8000para chatear con Techie. Visitahttp://localhost:8000/panelpara ver el panel de métricas.
Para correr el proyecto completo de manera aislada en un contenedor Docker local:
docker compose up --buildEl despliegue está automatizado mediante un pipeline de CI/CD con GitHub Actions (.github/workflows/deploy-ocir.yml):
- CI/CD: Cada push a la rama
mainconstruye la imagen Docker y la sube a OCI Container Registry (OCIR). - Infraestructura: La imagen se despliega de forma serverless en OCI Container Instances.
- Seguridad: La variable
COHERE_API_KEYse lee de forma segura desde OCI Vault sin exponer la clave en el repositorio ni en la imagen.
- Lenguaje: Python >= 3.10
- Framework Web API: FastAPI y Uvicorn
- Base de Datos Vectorial: Chroma DB
- Procesamiento de LLM & Embeddings: Cohere API (Modelos:
embed-multilingual-v3.0,rerank-multilingual-v3.0ycommand-r-08-2024) - Librerías de Extracción:
- PDF:
pypdf - Word:
python-docx - Excel:
openpyxl - PowerPoint:
python-pptx - HTML:
beautifulsoup4+lxml - Texto plano, JSON, CSV, MD: Nativos de Python
- PDF:
- Monitoreo: JSON Lines Logs (observabilidad nativa para cloud aggregators)
- Contenerización y CI/CD: Docker, Docker Compose y GitHub Actions
- Infraestructura Cloud: Oracle Cloud Infrastructure (OCI Container Registry, OCI Container Instances, OCI Vault, OCI VCN)
A continuación se presenta una vista simplificada y amigable sobre cómo se procesan las preguntas del usuario y cómo interactúan las tecnologías principales:
El siguiente diagrama detalla técnicamente las interacciones de componentes y la comunicación en los entornos local y cloud:
graph TD
%% Ingestion Flow
subgraph Ingestion ["1. Canalización de Ingesta (Local/CI)"]
Docs[Documentos Corporativos <br> PDF, Word, Excel, CSV, etc.] --> Ext[Extractores de Contenido <br> pypdf, python-docx, openpyxl, bs4]
Ext --> Chk[Chunking & Limpieza <br> chunk_size: 1000, overlap: 150]
Chk --> EmbApi[API de Cohere <br> embed-multilingual-v3.0]
EmbApi --> Chroma[(ChromaDB <br> Base de Datos Vectorial)]
end
%% Query & Generation Flow
subgraph RAG ["2. Pipeline de Consulta RAG (API / Web)"]
User([Usuario / Cliente]) <-->|Pregunta / Respuesta| WebUI[Interfaz de Chat Web <br> FastAPI / static files]
WebUI <-->|API ask| Agent[RagAgent Orquestador]
Agent -->|1. Búsqueda Vectorial| Chroma
Chroma -->|Candidatos vectoriales| Agent
Agent -->|2. Rerank| RerankApi[API de Cohere <br> rerank-multilingual-v3.0]
RerankApi -->|Top K Reordenados| Agent
Agent -->|3. Validar Confianza| Conf{¿Similitud >= Umbral?}
Conf -->|No| NoAns[Respuesta Estándar <br> Evita Alucinaciones]
Conf -->|Sí| GenApi[API de Cohere <br> Command-R]
GenApi -->|4. Respuesta con Citas| Agent
NoAns --> WebUI
end
%% Observability
subgraph Obs ["3. Observabilidad & Mantenimiento"]
WebUI -->|Métricas & Log| LogFile[(qa.jsonl & feedback.jsonl)]
WebUI -->|Feedback 👍/👎| LogFile
LogFile --> Metrics[Endpoint /api/metrics]
end
%% Deployment
subgraph Cloud ["4. Despliegue en la Nube (OCI)"]
GitHub[GitHub Repo] -->|Push a main| GHA[GitHub Actions CI/CD]
GHA -->|Construye Dockerfile| OCIR[OCI Container Registry]
OCIR -->|Despliega| OCI_CI[OCI Container Instance]
OCI_CI -->|Ejecuta| WebUI
Vault[OCI Vault] -->|Secreto: COHERE_API_KEY| OCI_CI
end
classDef default fill:#1A1E24,stroke:#3C4454,stroke-width:1px,color:#E1E5EC;
classDef cloud fill:#0C2340,stroke:#265A88,stroke-width:2px,color:#FFF;
classDef api fill:#2D1B4E,stroke:#6C3E9C,stroke-width:2px,color:#FFF;
class Ingestion,RAG,Obs default;
class Cloud cloud;
class EmbApi,RerankApi,GenApi api;
Agradecemos el soporte y los lineamientos proporcionados por los siguientes programas para hacer posible este desarrollo:
- Alura Latam
- Oracle Next Education (ONE)
Este proyecto está bajo la Licencia MIT. Para más detalles, consulta el archivo LICENSE (o términos estándar de la licencia MIT).