Instalación y Configuración de DeepTutor: Guía Completa de Cero a Funcionando

La instalación es la única parte de la experiencia con DeepTutor que tiene una barra técnica más alta—una vez que la superas, todo lo demás es solo aprendizaje.

Este artículo tiene un objetivo: tener DeepTutor funcionando antes de que termines de leer. Ya sea que sea la primera vez que auto-hospedas un servicio o hayas configurado decenas de cosas, encuentra la sección que corresponde a tu situación y sigue los pasos.

Requisitos del Sistema

Antes de empezar, confirma que tu máquina cumple estos requisitos mínimos:

También necesitarás una clave API para un backend LLM (OpenAI, Anthropic, etc.), o un entorno Ollama local.

Método 1: Docker (Recomendado para Principiantes)

Docker es el enfoque más rápido—unos pocos comandos, sin gestión manual de dependencias.

Paso 1: Clonar el repositorio

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

Paso 2: Copiar la plantilla de variables de entorno

cp .env.example .env

Paso 3: Configurar el backend LLM

Abre .env en un editor de texto y encuentra estos campos:

# Elige tu proveedor LLM (openai / anthropic / ollama)
LLM_PROVIDER=openai
 
# Introduce la clave API correspondiente
OPENAI_API_KEY=sk-your-api-key-here
 
# Selecciona el modelo
LLM_MODEL=gpt-4o

Si usas Anthropic:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
LLM_MODEL=claude-3-5-sonnet-20241022

Si quieres usar Ollama local (sin clave API requerida):

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
LLM_MODEL=llama3.2

Paso 4: Iniciar los servicios

docker compose up -d

El primer lanzamiento descargará imágenes Docker—espera de 3 a 10 minutos dependiendo de la velocidad de tu conexión. Una vez completado, abre tu navegador y navega a:

http://localhost:3000

Si ves la pantalla de bienvenida de DeepTutor, has terminado.

Método 2: Instalación Nativa (Para Desarrolladores)

¿Prefieres ejecutar el código fuente directamente sin Docker? Aquí está cómo hacerlo.

Paso 1: Clonar y entrar al directorio

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

Paso 2: Instalar dependencias del backend

# Crear entorno virtual
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
 
# Instalar paquetes Python
pip install -r requirements.txt

Paso 3: Instalar dependencias del frontend

cd frontend
npm install
cd ..

Paso 4: Configurar variables de entorno

cp .env.example .env
# Editar .env y completar la configuración LLM como arriba

Paso 5: Iniciar backend y frontend

Abre dos terminales y ejecuta:

# Terminal 1: Backend
python main.py
 
# Terminal 2: Frontend
cd frontend && npm run dev

El frontend corre en http://localhost:3000 por defecto; la API del backend está en http://localhost:8000.

Configuración Inicial: Primera Vez en la Interfaz

Una vez instalado, hay algunas cosas que vale la pena configurar antes de empezar a aprender.

1. Construir tu perfil de aprendizaje

En el primer inicio de sesión, DeepTutor te guiará a través de tus preferencias básicas de aprendizaje:

• Objetivos de aprendizaje: ¿Qué quieres aprender? (ej., "Dominar el análisis de datos con Python," "Alcanzar IELTS 7.0")
• Nivel actual: Auto-evalúate como principiante / intermedio / avanzado
• Preferencia de estilo de aprendizaje: Explicación directa vs. cuestionamiento guiado (socrático)

Esta información se almacena en la memoria persistente de DeepTutor e influye en el tono de todas las interacciones futuras. Cuanto más detalle proporciones, menos recalibración necesitarás después.

2. Elegir tu modelo LLM

Puedes ajustar el modelo en la interfaz de configuración. Recomendaciones:

• Chat diario y quizzes: gpt-4o-mini o claude-3-5-haiku (rápido, rentable)
• Deep Solve y Deep Research: gpt-4o o claude-3-5-sonnet (mayor precisión)
• Privacidad primero: llama3.2 (completamente local, pero rendimiento menor)

3. Crear tu primera Base de Conocimientos (opcional)

Si tienes materiales de aprendizaje a mano, puedes configurar una base de conocimientos en esta etapa. Sube PDFs o archivos Markdown—DeepTutor construirá índices semánticos en segundo plano, normalmente completando en unos pocos minutos.

El uso detallado de la Base de Conocimientos se cubre en el Artículo 5 de esta serie.

Solución de Problemas Comunes

P: Docker inició pero localhost:3000 no abre

Verifica si los contenedores están corriendo:

docker compose ps

Si el estado de backend o frontend no es Up, revisa los logs:

docker compose logs backend
docker compose logs frontend

La causa más común es una clave API incorrecta o vacía en .env.

P: Subí un PDF pero no pasa nada

La indexación de la base de conocimientos es asíncrona—los archivos grandes pueden tardar unos minutos. Si aún no está completo después de diez minutos, activa la re-indexación desde la página de configuración.

P: Uso Ollama pero la conversación es muy lenta

Confirma que Ollama está corriendo en el puerto correcto y que OLLAMA_BASE_URL está configurado correctamente. En macOS con Apple Silicon, asegúrate de que Ollama esté usando aceleración Metal.

P: Errores de permisos con Docker en Windows

Asegúrate de que Docker Desktop tenga habilitado el backend WSL 2, y que tu directorio de trabajo esté bajo C:\Users\ en lugar de otra unidad.

Actualizar DeepTutor

DeepTutor se desarrolla activamente—se recomiendan actualizaciones regulares:

# Método Docker
git pull
docker compose pull
docker compose up -d
 
# Método de instalación nativa
git pull
pip install -r requirements.txt  # Solo necesario cuando se agregan nuevas dependencias

Qué Sigue

Tu entorno está funcionando. El siguiente paso es familiarizarte con los cinco modos de aprendizaje—Chat, Deep Solve, Quiz, Research y Math Animator—cada uno diseñado para diferentes situaciones y estrategias.

Lectura adicional: Los Cinco Modos de DeepTutor Explicados: Chat, Deep Solve, Quiz, Research, Math Animator