Chatbot Uniputumayo
Asistente virtual "Guaca" con IA para la Universidad del Putumayo. Sistema RAG con soporte de voz y chat.
"Guaca" AI virtual assistant for Universidad del Putumayo. RAG system with voice and chat support.
$ git clone https://github.com/YANCARLOSOFICIAL/chatbot-uniputumayo.git
$ cd chatbot-uniputumayo
// puntos clave
// key points
- RAG sobre documentación oficial: el asistente responde citando los documentos de la universidad, no con conocimiento genérico del modelo.
- Voz y chat: entrada por voz (STT) y respuesta hablada (TTS) para usuarios que no quieren escribir.
- Modelo local con Ollama: sin costo por token en inferencia; el modelo corre en el servidor de la institución.
- Despliegue con Docker:
docker compose uplevanta backend, base de datos y frontend.
// README.md del repositorio
Descargado del repositorio en cada build. Downloaded from the repository on every build.Chatbot Uniputumayo- Institución Universitaria del Putumayo
Guaca es el asistente virtual basado en RAG (Retrieval-Augmented Generation) y LLM de la Institución Universitaria del Putumayo. Responde preguntas sobre programas académicos, sedes, requisitos de admisión y más, basándose únicamente en los documentos institucionales cargados.
Soporta interacción por texto y voz, respuestas en streaming (SSE), autenticación con JWT (usuarios registrados e invitados), un panel de administración completo, y permite alternar entre Ollama (local) y OpenAI (nube) como proveedores de IA.
Tabla de Contenidos
- Arquitectura
- Tecnologías
- Requisitos Previos
- Instalación
- Ejecución
- Uso
- API Endpoints
- Estructura del Proyecto
- Configuración
- Pipeline RAG y Caché
- Solución de Problemas
Arquitectura
El sistema utiliza una Arquitectura Orientada a Servicios (SOA) implementada como un monolito modular. Cada servicio se expone como un router independiente dentro de un único proceso FastAPI, lo que mantiene la separación lógica SOA sin la complejidad operacional de múltiples microservicios.
[Next.js 16 Frontend :3001]
|
[Nginx reverse proxy :80]
|
[FastAPI Gateway :8000]
|
+------+------+------+---------+--------+-------+-----------+
| | | | | | | |
[Auth] [Chat] [RAG] [LLM] [Documents] [Config] [Audio] [Analytics]
| | | | |
| [chat_ [rag_ [llm_ [document_
| service] service] service] service]
| |
| [Provider Factory]
| / \
| [Ollama] [OpenAI]
|
+──────────────┬──────────────────┐
▼ ▼
[PostgreSQL + pgvector] [Redis]
(datos, embeddings) (caché RAG/respuestas)
Servicios
| Servicio | Responsabilidad |
|---|---|
| Auth Service | Registro/login con JWT, gestión de roles (user/admin) |
| Chat Service | Orquestación del flujo: recibe mensaje → caché de respuestas → RAG → LLM → almacena → responde (soporta streaming SSE) |
| RAG Service | Búsqueda híbrida: similitud vectorial (pgvector/HNSW) + full-text keyword (Postgres FTS), con HyDE y diversidad de resultados |
| LLM Service | Capa de abstracción sobre Ollama y OpenAI (generación + embeddings) |
| Document Service | Ingesta de documentos: upload → extracción → chunking → embedding → almacenamiento; invalida cachés al subir/borrar |
| Config Service | Configuración runtime del proveedor LLM activo, persistida en BD (solo admin) |
| Audio Service | Text-to-Speech y Speech-to-Text |
| Analytics Service | Métricas de uso para el panel admin |
| Health | Monitoreo de salud del sistema (/health, /metrics) |
Tecnologías
Backend
| Tecnología | Uso |
|---|---|
| Python 3.11 | Lenguaje principal |
| FastAPI | Framework web async |
| SQLAlchemy 2 (async) | ORM |
| PostgreSQL 16 + pgvector | Base de datos relacional + búsqueda vectorial (índice HNSW) |
| Redis 7 | Caché persistente de RAG y de respuestas (opcional, con fallback en memoria) |
| Alembic | Migraciones de base de datos |
| Ollama | LLM local (qwen3:8b), embeddings (nomic-embed-text), visión (gemma4:e4b) |
| OpenAI SDK | LLM en la nube (gpt-5.4-mini y otros) |
| PyJWT + bcrypt | Autenticación JWT y hashing de contraseñas |
| slowapi | Rate limiting por IP |
| PyMuPDF / python-docx | Extracción de texto de PDF / DOCX |
| tiktoken | Conteo de tokens |
Frontend
| Tecnología | Versión | Uso |
|---|---|---|
| Next.js | 16 (App Router) | Framework React |
| React | 19 | UI |
| TypeScript | 5+ | Tipado estático |
| Tailwind CSS | 4 | Estilos utilitarios |
| lucide-react | — | Iconos |
| react-markdown + remark-gfm | — | Renderizado de respuestas del bot |
| next-themes | — | Modo claro/oscuro |
| Web Speech API | nativa | Reconocimiento y síntesis de voz (es-CO) |
Infraestructura
| Tecnología | Uso |
|---|---|
| Docker Compose | Orquestación completa (6 servicios: PostgreSQL, Redis, Ollama, Backend, Frontend, Nginx) |
| pgvector/pgvector:pg16 | Imagen Docker de PostgreSQL con pgvector |
| ollama/ollama | Imagen Docker de Ollama |
| redis:7-alpine | Caché en memoria compartida, LRU, 256 MB |
| Nginx | Reverse proxy unificando frontend y backend en puerto 80, con soporte SSE |
Requisitos Previos
- Docker Desktop (con Docker Compose)
- Git
- (Opcional) Python 3.11+ y Node.js 20+ para desarrollo local sin Docker
- (Opcional) API key de OpenAI para usar el proveedor en la nube
Instalación y Ejecución
Opción 1: Docker Compose (Recomendada)
Todo el proyecto está dockerizado. Un solo comando levanta todos los servicios:
# 1. Clonar el repositorio
git clone <url-del-repositorio>
cd chatbot-uniputumayo
# 2. (Opcional) Configurar variables de entorno
cp backend/.env.example .env
# Editar .env: OPENAI_API_KEY, JWT_SECRET y ADMIN_PASSWORD son las más importantes
# 3. Levantar todo
docker compose up --build -d
# 4. (Opcional) Descargar modelos de Ollama manualmente
# El backend ya los descarga automáticamente en segundo plano al iniciar,
# pero puedes forzarlo/verificarlo así:
docker exec iup-chatbot-ollama ollama pull qwen3:8b
docker exec iup-chatbot-ollama ollama pull nomic-embed-text
docker exec iup-chatbot-ollama ollama pull embeddinggemma
Esto levanta 6 servicios:
- PostgreSQL 16 con pgvector (puerto
5433) - Redis para caché de RAG y respuestas (puerto
6379) - Ollama para LLM local (puerto
11434) - Backend FastAPI con migraciones automáticas (puerto
8000) - Frontend Next.js (puerto
3001) - Nginx reverse proxy (puerto
80)
Nota: El backend descarga automáticamente los modelos de Ollama al iniciar (
qwen3:8b,nomic-embed-text,gemma4:e4b,embeddinggemma) si detecta que no están disponibles, sin bloquear el arranque.⚠️ Importante para producción:
JWT_SECRETyADMIN_PASSWORDtienen valores por defecto inseguros pensados solo para desarrollo local. Cámbialos siempre en.envantes de exponer el servicio fuera de tu máquina.
URLs de acceso (Docker)
| Servicio | URL |
|---|---|
| Aplicación completa (Nginx) | http://localhost |
| Frontend directo | http://localhost:3001 |
| Backend API directo | http://localhost:8000 |
| Swagger/OpenAPI Docs | http://localhost/docs |
| Health Check | http://localhost/api/v1/health |
Comandos útiles
# Ver logs de todos los servicios
docker compose logs -f
# Ver logs de un servicio específico
docker compose logs -f backend
# Reiniciar un servicio
docker compose restart backend
# Detener todo
docker compose down
# Detener todo y eliminar volúmenes (reset completo, borra BD/caché/modelos)
docker compose down -v
Opción 2: Desarrollo Local (sin Docker para backend/frontend)
Para desarrollo con hot-reload, puedes correr solo la infraestructura en Docker:
# Levantar PostgreSQL + Redis + Ollama con el compose de la raíz
docker compose up -d postgres redis ollama
Backend
cd backend
python -m venv venv
source venv/Scripts/activate # Windows Git Bash
# source venv/bin/activate # Linux/macOS
pip install -r requirements.txt
cp .env.example .env # Editar si es necesario
alembic upgrade head # Aplicar migraciones
uvicorn app.main:app --reload --port 8000
Frontend
cd frontend
npm install
npm run dev -- --port 3001
URLs de acceso (Desarrollo Local)
| Servicio | URL |
|---|---|
| Frontend | http://localhost:3001 |
| Backend API | http://localhost:8000 |
| Swagger Docs | http://localhost:8000/docs |
| Health Check | http://localhost:8000/api/v1/health |
Uso
1. Autenticación
- Invitados: el chat funciona sin cuenta (
/chat). Las conversaciones de invitado se guardan solo en el navegador y se limpian automáticamente del servidor tras 2 horas de inactividad. - Usuarios registrados:
/loginpara crear cuenta o iniciar sesión; el historial de conversaciones se guarda de forma persistente. - Administradores:
/admin/login. Se crea automáticamente un usuario admin al primer arranque conADMIN_EMAIL/ADMIN_PASSWORD(ver Configuración).
2. Subir documentos (Panel Admin)
- Ir a
/admin/documents - Seleccionar un archivo PDF, DOCX o TXT con información académica
- Completar los campos: Título, Facultad, Programa, Tipo (pensum, perfil, misión, reglamento, admisión, general)
- Clic en "Subir Documento"
- El sistema procesa automáticamente: extrae texto → limpia → divide en chunks → genera embeddings → almacena en pgvector. Subir o borrar un documento invalida la caché de respuestas para evitar servir información desactualizada.
3. Chatear
- Ir a
/chat - Crear una nueva conversación o escribir directamente
- Preguntar, por ejemplo:
- "¿Cuáles son los programas de ingeniería que ofrece la IUP?"
- "¿Cuál es el perfil profesional del ingeniero de sistemas?"
- "¿Cuáles son los requisitos de admisión?"
- La respuesta llega en streaming (token a token) y se basa únicamente en los documentos cargados, citando las fuentes consultadas
4. Usar voz
- Clic en el botón del micrófono (requiere Chrome/Edge)
- Hablar tu pregunta
- El avatar cambia de estado: escuchando → pensando → hablando
- La respuesta se reproduce por voz automáticamente (es-CO)
5. Configurar proveedor de IA (solo admin)
- Ir a
/admin/config - Ver el estado de los proveedores (Ollama / OpenAI) y configurar la API key de OpenAI
- Cambiar el proveedor/modelo activo — esta configuración es exclusiva del panel admin; el chat de usuario nunca muestra un selector de modelo
API Endpoints
Health
| Método | Endpoint | Descripción |
|---|---|---|
| GET | /api/v1/health |
Estado de salud del sistema (BD, Ollama, OpenAI) |
| GET | /api/v1/metrics |
Métricas básicas de uso |
Auth
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /api/v1/auth/register |
Registrar usuario (rate limit: 5/hora) |
| POST | /api/v1/auth/login |
Iniciar sesión, devuelve JWT (rate limit: 10/5min) |
| GET | /api/v1/auth/me |
Usuario autenticado actual |
| GET | /api/v1/auth/users |
Listar usuarios (admin) |
| PUT | /api/v1/auth/users/{id}/role |
Cambiar rol de un usuario (admin) |
Chat
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /api/v1/chat/conversations |
Crear conversación |
| GET | /api/v1/chat/conversations |
Listar conversaciones |
| GET | /api/v1/chat/conversations/{id} |
Obtener conversación |
| PATCH | /api/v1/chat/conversations/{id} |
Renombrar conversación |
| DELETE | /api/v1/chat/conversations/{id} |
Eliminar conversación |
| POST | /api/v1/chat/conversations/{id}/guest-close |
Hard-delete de conversación de invitado al cerrar pestaña |
| POST | /api/v1/chat/conversations/{id}/messages |
Enviar mensaje (orquesta caché + RAG + LLM) |
| POST | /api/v1/chat/conversations/{id}/messages/stream |
Enviar mensaje con respuesta en streaming (SSE) |
| GET | /api/v1/chat/conversations/{id}/messages |
Obtener mensajes |
RAG
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /api/v1/rag/search |
Búsqueda híbrida vectorial + full-text (solo admin) |
LLM
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /api/v1/llm/generate |
Generar texto con LLM (admin) |
| POST | /api/v1/llm/embed |
Generar embeddings (admin) |
| GET | /api/v1/llm/providers |
Listar proveedores disponibles |
| PUT | /api/v1/llm/config |
Actualizar proveedor/modelo por defecto (admin) |
| POST | /api/v1/llm/api-key |
Configurar API key de OpenAI (admin) |
| GET | /api/v1/llm/api-key-status |
Ver si hay API key configurada (admin) |
Documentos
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /api/v1/documents/upload |
Subir documento (multipart/form-data) |
| GET | /api/v1/documents/ |
Listar documentos |
| GET | /api/v1/documents/{id} |
Obtener documento |
| DELETE | /api/v1/documents/{id} |
Eliminar documento y sus chunks (invalida caché) |
| GET | /api/v1/documents/{id}/chunks |
Ver chunks de un documento |
| POST | /api/v1/documents/{id}/reindex |
Re-procesar documento |
Configuración
| Método | Endpoint | Descripción |
|---|---|---|
| GET | /api/v1/config/llm |
Ver configuración LLM actual (admin) |
Audio
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /api/v1/audio/tts |
Texto a voz |
| POST | /api/v1/audio/stt |
Voz a texto |
Analytics
| Método | Endpoint | Descripción |
|---|---|---|
| GET | /api/v1/analytics/overview |
Métricas de uso para el panel admin |
Estructura del Proyecto
chatbot-uniputumayo/
├── .gitignore
├── README.md
├── docker-compose.yml # Orquestación completa (6 servicios)
├── docker-compose.prod.yml # Variante de producción
│
├── nginx/
│ └── nginx.conf # Reverse proxy (incluye config SSE para streaming)
│
├── backend/
│ ├── Dockerfile
│ ├── entrypoint.sh # Migraciones + uvicorn
│ ├── requirements.txt
│ ├── .env.example
│ ├── alembic.ini
│ ├── alembic/versions/ # Migraciones
│ │
│ └── app/
│ ├── main.py # Gateway FastAPI - monta routers, seed de admin, índices
│ ├── config.py # Pydantic Settings - carga .env
│ ├── database.py # SQLAlchemy async engine + session
│ ├── auth.py # JWT, hashing, dependencias require_auth/require_admin
│ ├── runtime_config.py # Configuración LLM mutable en runtime
│ │
│ ├── models/ # Modelos SQLAlchemy (ORM)
│ │ ├── user.py
│ │ ├── conversation.py
│ │ ├── message.py
│ │ ├── document.py
│ │ ├── document_chunk.py # Chunks con embeddings (pgvector)
│ │ ├── retrieval_log.py
│ │ └── llm_configuration.py
│ │
│ ├── schemas/ # Pydantic schemas (request/response)
│ ├── services/
│ │ ├── chat_service.py # Orquestación: caché → RAG → prompt → LLM → store
│ │ ├── rag_service.py # Búsqueda híbrida vectorial + full-text
│ │ ├── llm_service.py # Abstracción sobre providers
│ │ ├── document_service.py # Pipeline de ingesta + invalidación de caché
│ │ └── llm_config_store.py # Persistencia de config LLM en BD
│ │
│ ├── providers/ # Implementaciones de LLM (Ollama, OpenAI) + factory
│ │
│ ├── routers/ # Endpoints REST
│ │ ├── health.py, auth.py, chat.py, rag.py, llm.py
│ │ └── documents.py, config.py, audio.py, analytics.py
│ │
│ ├── middleware/error_handler.py
│ │
│ └── utils/
│ ├── file_parsers.py # Extracción: PDF, DOCX, TXT
│ ├── text_processing.py
│ ├── chunking.py
│ ├── query_utils.py
│ ├── prompts.py
│ ├── rate_limit.py # slowapi por IP (respeta trusted_proxy_count)
│ └── cache.py # Caché de RAG y de respuestas (Redis o memoria)
│
└── frontend/
├── package.json
├── next.config.ts # Rewrite de /api/* hacia INTERNAL_API_URL
│
└── src/
├── app/
│ ├── layout.tsx, page.tsx (landing), globals.css
│ ├── chat/[conversationId]/page.tsx
│ └── admin/
│ ├── login/, documents/, config/, users/, conversations/, analytics/
│
├── components/
│ ├── chat/ # ChatContainer, MessageList, MessageBubble, ChatInput,
│ │ # ConversationSidebar, TypingIndicator, SourceCard,
│ │ # QuickReplies, MarkdownContent, GuacamayaAvatar
│ ├── admin/ # AdminSidebar, AdminHeader
│ └── ui/ # Toast, ThemeProvider, ThemeToggle, SiteFooter
│
├── hooks/ # useChat, useSpeechRecognition, useSpeechSynthesis
├── context/ # ChatContext (useReducer)
├── lib/ # api/client.ts, auth.ts, utils/cn.ts
└── types/ # chat.ts, avatar.ts
Configuración
Variables de Entorno del Backend (backend/.env)
| Variable | Default | Descripción |
|---|---|---|
DATABASE_URL |
postgresql+asyncpg://chatbot_user:chatbot_password@localhost:5433/chatbot_db |
Conexión a PostgreSQL |
OLLAMA_BASE_URL |
http://localhost:11434 |
URL del servidor Ollama |
OLLAMA_DEFAULT_MODEL |
qwen3:8b |
Modelo de chat en Ollama |
OLLAMA_EMBEDDING_MODEL |
nomic-embed-text |
Modelo de embeddings para RAG (768 dims) |
OLLAMA_VISION_MODEL |
gemma4:e4b |
Modelo de visión/documentos |
OPENAI_API_KEY |
(vacío) | API key de OpenAI (opcional) |
OPENAI_DEFAULT_MODEL |
gpt-5.4-mini |
Modelo de chat en OpenAI |
OPENAI_EMBEDDING_MODEL |
text-embedding-3-small |
Modelo de embeddings en OpenAI (1536 dims) |
DEFAULT_LLM_PROVIDER |
ollama |
Proveedor por defecto: ollama u openai |
DEFAULT_TEMPERATURE |
0.05 |
Casi determinista, para respuestas RAG factuales |
DEFAULT_MAX_TOKENS |
2048 |
Máximo de tokens en la respuesta |
CHUNK_SIZE / CHUNK_OVERLAP |
512 / 77 |
Tamaño y solapamiento de chunks (tokens) |
RAG_TOP_K |
5 |
Chunks a recuperar |
RAG_SCORE_THRESHOLD |
0.35 |
Umbral de similitud (nomic-embed-text puntúa ~0.4-0.65 en docs en español) |
RAG_CANDIDATES_MULTIPLIER |
3 |
Candidatos = top_k × multiplier, filtrados luego por diversidad |
RAG_HYDE_ENABLED |
true |
HyDE: embeder respuesta hipotética en vez de la query cruda |
RAG_DIVERSITY_ENABLED |
true |
Máx. 2 chunks por documento fuente |
EMBEDDING_PROVIDER |
ollama |
Proveedor de embeddings (independiente de DEFAULT_LLM_PROVIDER) |
EMBEDDING_DIMENSIONS |
768 |
768 con nomic-embed-text, 1536 con text-embedding-3-small — no cambiar sin migrar |
ANSWER_CACHE_ENABLED |
true |
Caché de respuestas completas por similitud semántica de preguntas |
ANSWER_CACHE_EMBEDDING_MODEL |
embeddinggemma |
Modelo dedicado para distinguir parafraseos (separado del embedding de RAG) |
ANSWER_CACHE_SIMILARITY_THRESHOLD |
0.65 |
Umbral coseno para considerar un acierto de caché |
ANSWER_CACHE_TTL_SECONDS |
2592000 (30 días) |
La invalidación real ocurre al subir/borrar documentos |
ANSWER_CACHE_MAX_ENTRIES |
1000 |
Límite de entradas en caché |
REDIS_URL |
(vacío) | Si se define, habilita caché persistente en Redis; si no, cae a memoria |
JWT_SECRET |
⚠️ inseguro por defecto | Cambiar siempre en producción |
JWT_ALGORITHM |
HS256 |
Algoritmo de firma JWT |
JWT_EXPIRE_MINUTES |
480 |
Expiración del token (8 horas) |
ADMIN_EMAIL / ADMIN_PASSWORD |
admin@iup.edu.co / ⚠️ inseguro por defecto |
Credenciales del admin sembrado al primer arranque — cambiar siempre en producción |
CORS_ORIGINS |
http://localhost:3000,http://localhost:3001 |
Orígenes permitidos (separados por coma) |
TRUSTED_PROXY_COUNT |
1 |
Saltos de reverse proxy confiables (nginx) para rate limiting por IP real |
MAX_UPLOAD_SIZE_MB |
50 |
Tamaño máximo de archivo para upload |
LOG_LEVEL |
info |
debug, info, warning, error |
Variables de Entorno del Frontend
| Variable | Descripción |
|---|---|
NEXT_PUBLIC_API_URL |
URL pública del backend (vacío en Docker → usa rutas relativas /api/*) |
INTERNAL_API_URL |
URL server-side que Next.js usa para el rewrite de /api/* (http://backend:8000 en Docker) |
Pipeline RAG y Caché
Flujo de Ingesta de Documentos
Documento (PDF/DOCX/TXT)
│
▼
1. Extracción de texto (PyMuPDF / python-docx / lectura directa)
│
▼
2. Limpieza y normalización (Unicode, headers/footers repetitivos)
│
▼
3. Chunking recursivo — 512 tokens, 15% de solapamiento
│
▼
4. Embeddings — nomic-embed-text (768d) u OpenAI (1536d), en lotes paralelos
│
▼
5. Almacenamiento en pgvector (índice HNSW, cosine similarity)
│
▼
6. Invalidación de la caché de respuestas (para no servir contestaciones desactualizadas)
Flujo de Consulta (Chat)
Pregunta del usuario
│
▼
1. Answer cache: ¿hay una respuesta previa semánticamente similar (≥0.65 coseno,
con embeddinggemma)? → si hay acierto, responde al instante sin tocar RAG/LLM
│ (si no hay acierto)
▼
2. RAG Service: búsqueda híbrida
- HyDE: genera una respuesta hipotética y la embede para buscar
- Similitud vectorial (pgvector/HNSW) + full-text keyword search (Postgres FTS)
- Filtra por score_threshold, aplica diversidad (máx. 2 chunks/doc)
- Retorna top_k chunks relevantes
│
▼
3. Construcción del prompt (system prompt anti-alucinación + contexto + historial)
│
▼
4. LLM Service genera la respuesta (Ollama o OpenAI), en streaming si se usa /messages/stream
│
▼
5. Almacenamiento del mensaje + metadata (tokens, provider, tiempo de respuesta)
y guardado en la answer cache para futuras preguntas similares
│
▼
6. Respuesta al frontend con las fuentes consultadas
Base de Datos
Diagrama de Tablas
┌─────────────┐ ┌──────────────────┐ ┌───────────────┐
│ users │────▶│ conversations │────▶│ messages │
│ │ │ │ │ │
│ id (UUID PK) │ │ id (UUID PK) │ │ id (UUID PK) │
│ email │ │ user_id (FK, ∅) │ │ conv_id (FK) │
│ password_hash│ │ title │ │ role │
│ display_name │ │ language │ │ content │
│ role │ │ is_active │ │ input_type │
│ is_active │ │ created_at │ │ tokens_used │
│ created_at │ └──────────────────┘ │ llm_provider │
└──────┬───────┘ │ llm_model │
│ │ response_time │
│ ┌──────────────────┐ └───────────────┘
└────────────▶│ documents │
│ │ ┌──────────────────┐
│ id (UUID PK) │────▶│ document_chunks │
│ title │ │ │
│ file_name │ │ id (UUID PK) │
│ file_type │ │ document_id (FK) │
│ faculty │ │ chunk_index │
│ program │ │ content │
│ document_type │ │ token_count │
│ ingestion_status │ │ embedding (768/ │
│ total_chunks │ │ 1536, HNSW idx) │
└──────────────────┘ └──────────────────┘
conversations.user_id es nullable — las conversaciones de invitado no tienen usuario asociado y se limpian automáticamente 2 horas después de creadas.
Solución de Problemas
Puerto 5432 ocupado
El proyecto ya usa el puerto 5433 para PostgreSQL (ver docker-compose.yml). Asegúrate de que DATABASE_URL use ese puerto en desarrollo local.
Puerto 3000 ocupado
npm run dev -- --port 3001
Ollama no responde
docker ps --filter "name=iup-chatbot-ollama"
docker logs iup-chatbot-ollama
docker exec iup-chatbot-ollama ollama list
docker exec iup-chatbot-ollama ollama pull qwen3:8b
En Docker Desktop para Windows, el contenedor de Ollama necesita DNS explícito (8.8.8.8, 8.8.4.4, ya configurado en docker-compose.yml) para poder alcanzar el registro de modelos.
Redis no disponible
Si REDIS_URL está vacío o Redis no responde, el sistema cae automáticamente a caché en memoria (RAG y respuestas), sin persistencia entre reinicios — no es un error fatal.
Error de migración "pgvector not defined"
# Agregar al inicio del archivo de migración:
import pgvector.sqlalchemy
# Y antes de crear tablas:
op.execute('CREATE EXTENSION IF NOT EXISTS vector')
op.execute('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"')
"different vector dimensions" al hacer una consulta
Ocurre si EMBEDDING_PROVIDER/EMBEDDING_DIMENSIONS cambió sin migrar la columna embedding existente. El backend registra un error explícito en el arranque (EMBEDDING DIMENSION MISMATCH) cuando detecta este desajuste — revisa los logs y re-embebe los documentos o revierte la configuración.
El chat no responde
- Verificar que el backend está corriendo: http://localhost:8000/api/v1/health
- Verificar que hay documentos subidos: http://localhost:8000/docs → GET
/api/v1/documents/ - Verificar el proveedor LLM: http://localhost:8000/api/v1/llm/providers
- Ver logs del backend (
docker compose logs -f backend)
Voz no funciona
- El reconocimiento de voz requiere Chrome o Edge (no funciona en Firefox)
- Se necesita permiso del micrófono en el navegador
- El idioma configurado es es-CO (español colombiano)
Licencia
Proyecto académico de la Institución Universitaria del Putumayo.