Configuración

¿Para quién es esto? Administradores del sitio.

Tutor AI se configura a nivel de sitio. Con estas opciones puede encender el chat, decidir cómo se ve el tutor y dónde aparece, elegir qué información del curso puede usar y personalizar la forma en que conversa con los estudiantes. Tutor AI lee la licencia desde el Datacurso AI Provider; no hay ninguna conexión ni token que configurar en este plugin.

---

1) Abrir la configuración de Tutor AI

Solo necesita hacer esto una vez, con una cuenta que tenga acceso de administrador del sitio.

1. En el menú superior de Moodle, haga clic en Administración del sitio.
2. Abra la pestaña Extensiones. Verá una lista larga de secciones; cada una agrupa un tipo de complemento.

3. Desplácese hacia abajo hasta encontrar la sección Extensiones locales.
4. Haga clic en Tutor IA dentro de esa lista.

Se abre la página de configuración de Tutor AI. Está organizada en tres bloques, que se explican a continuación en el mismo orden en que aparecen en pantalla:

• General: encender el tutor y decidir cuánto tiempo se guardan las conversaciones.
• Avatar de Tutor-AI: la imagen del tutor y el lugar de la página donde aparece su botón.
• Personalización del tutor: el nombre, el saludo, las instrucciones del tutor y la información que puede usar.

Al terminar, haga clic en Guardar cambios al final de la página.

---

2) Ajustes generales

Ajuste	Nombre	Valor predeterminado	Descripción
Habilitar chat	local_dttutor/enabled	Sí	El interruptor principal para todo el sitio. Requerido: cuando está apagado, el tutor no aparece en ningún curso y la opción del curso (Más → Gestión de tutores de IA) no está disponible.
Habilitar al tutor en nuevos cursos	local_dttutor/enabled_by_default	No	Cuando está activado, cada curso nuevo empieza con el tutor ya encendido, así no hay que activarlo curso por curso. Los docentes pueden apagarlo en su propio curso si lo desean.
Los días se mantienen las conversaciones	local_dttutor/retention_days	7	Las conversaciones con más días que este número se eliminan, tanto en Moodle como en el servicio de IA. Siete días es lo que el propio servicio de IA las conserva, así que un número mayor aquí no hará que duren más. Escriba 0 para conservarlas hasta que se elimine el usuario, se elimine el curso o una solicitud de privacidad las borre.

Dos interruptores

Habilitar chat enciende el tutor para el sitio. Además, cada curso tiene su propio interruptor: salvo que Habilitar al tutor en nuevos cursos esté activado, el tutor empieza apagado en todos los cursos, y un docente (o cualquier usuario con moodle/course:update) debe encenderlo desde Más → Gestión de tutores de IA, donde también ve el estado del servicio, los créditos restantes y cuántas preguntas se hicieron en el curso. Ver Configuración del docente.

---

3) Avatar

El avatar es la imagen que se muestra en el botón flotante que los estudiantes pulsan para abrir el chat.

Ajuste	Nombre	Valor predeterminado	Descripción
Avatar de Tutor-AI	local_dttutor/avatar	Avatar 1	Elija uno de los 10 avatares integrados haciendo clic sobre él. Si no se selecciona ninguno o el archivo no existe, se usa el Avatar 1.
Avatar personalizado	local_dttutor/customavatar	Vacío	Arrastre y suelte aquí su propia imagen (por ejemplo, la mascota de su institución). Reemplaza al avatar integrado que haya elegido. Tamaño recomendado: 200×200 px. Formatos: PNG, JPG, JPEG, SVG. Tamaño máximo: 512KB.
Posición del avatar	local_dttutor/avatar_position_data	Esquina inferior derecha, se abre desde la derecha	Elija dónde se ubica el botón: Esquina inferior derecha, Esquina inferior izquierda o Posición personalizada (coordenadas X/Y exactas con valores CSS como 2rem, 20px, 5%). Lado de apertura del cajón define desde qué lado se desliza el panel del chat (izquierda o derecha), sin importar dónde esté el botón. La Vista previa en vivo de la derecha muestra el resultado mientras lo cambia.

---

4) Personalización del tutor

Ajuste	Nombre	Valor predeterminado	Descripción
Mensaje de bienvenida	local_dttutor/welcomemessage	¡hola! Soy {teachername}, tu asistente de IA. ¿Cómo puedo ayudarte hoy?	El primer mensaje que ven los estudiantes al abrir el chat.
Nombre del tutor	local_dttutor/tutorname	Tutor de IA	El nombre que aparece en la parte superior del chat. Escriba un nombre fijo (por ejemplo, Asistente IA) o use {teachername} para mostrar el nombre real del docente del curso.
Aviso personalizado	local_dttutor/custom_prompt	Vacío	Instrucciones que guían el comportamiento del tutor: tono, reglas o temas en los que debe mantenerse. Por ejemplo: "Sé muy respetuoso con los usuarios. Habla solo de manera profesional. Las respuestas deben ser lo más cortas posible."

Ajuste	Nombre	Valor predeterminado	Descripción
Envíe el material del curso al tutor de IA	local_dttutor/include_content	No	Cuando está activado, el tutor puede leer el contenido preparado por los docentes para basar sus respuestas en él: descripciones de actividades, páginas, capítulos visibles de libros, instrucciones de tareas, direcciones de URL, páginas de contenido de lecciones y los documentos que entrega el curso. Este texto se envía al servicio de IA de Datacurso y, desde allí, al proveedor del modelo de lenguaje. Nunca envía nada escrito por los estudiantes (mensajes de foros, entradas de glosario, registros de bases de datos, páginas wiki, entregas) ni las preguntas de cuestionarios o las páginas de preguntas de lecciones, y solo incluye material que el usuario ya puede abrir. Cuando está apagado, el material del curso se queda dentro de la plataforma y el tutor responde únicamente a partir de la estructura del curso.
Objetivo de tiempo de respuesta	local_dttutor/response_target_seconds	20	Cuántos segundos puede tardar una respuesta antes de que el sitio la considere lenta. Cada respuesta se cronometra y la medición se guarda en el registro de desarrollo; las que superan este límite también se registran en el registro de errores, para que pueda detectar lentitud. Escriba 0 para solo guardar la medición, sin límite.
Envíe las calificaciones del estudiante al tutor de IA	local_dttutor/include_grades	No	Cuando está activado, el tutor puede ver las calificaciones del estudiante que está conversando (solo las suyas en ese curso) y responder preguntas sobre ellas. Está apagado por defecto para compartir la menor cantidad posible de datos personales.

Placeholders

Los siguientes placeholders pueden usarse en el Nombre del tutor, el Mensaje de bienvenida y el Aviso personalizado. Cada uno se reemplaza automáticamente por información real:

Placeholder	Se reemplaza por
{teachername}	El nombre del primer docente del curso (si el curso no tiene docente, se usa "Tutor de IA").
{coursename}	El nombre completo del curso.
{username}	El nombre completo del usuario que está conversando.
{firstname}	El nombre (primer nombre) del usuario que está conversando.

Buenas prácticas para prompts

Mantenga el prompt corto y orientado a acciones. Empiece simple, observe preguntas reales de los estudiantes y luego refínelo. Hay plantillas disponibles en la Guía de Prompts.

---

5) Cómo obtiene el tutor su información

Tutor AI no usa una cuenta de servicio ni llama a los servicios web de Moodle. Para cada pregunta prepara el conocimiento del curso del usuario que conversa (estructura, actividades y fechas que puede ver y, si usted lo permite, el material del curso y sus propias calificaciones) y lo envía al servicio de IA de Datacurso junto con la pregunta. Cada solicitud se valida en el servidor: el usuario debe estar matriculado en el curso, tener local/dttutor:use, y el tutor debe estar habilitado en el sitio y en el curso.

• Si actualiza desde la 2.0.8 o anterior. La antigua cuenta de servicio tutoriabot_datacurso se desmatricula de todos los cursos y queda suspendida. Puede eliminarla cuando ya no la necesite en los registros antiguos.
• Límites de uso. Los límites de uso por plugin se configuran en el Datacurso AI Provider (Límites por plugin), no en Tutor AI. Cuando se alcanza un límite, los usuarios ven el mensaje "Se ha superado el límite de consumo permitido. Por favor, inténtelo de nuevo el …".

Ver Permisos para las capacidades involucradas.

---

6) Validar la configuración (verificación rápida)

1. Habilite el tutor en un curso de prueba desde Más → Gestión de tutores de IA.
2. Abra cualquier página de ese curso y confirme que el avatar flotante aparece.
3. Haga clic en el avatar para abrir el chat y haga una pregunta rápida para ver la respuesta en streaming.

Solución de problemas (Troubleshooting)

Esta sección lista los problemas más comunes al usar Tutor AI y cómo resolverlos.

---

El avatar no aparece en un curso

Causas más comunes:

• Habilitar chat está desactivado a nivel de sitio.
• El tutor no está habilitado en ese curso (el valor predeterminado por curso es desactivado, salvo que Habilitar al tutor en nuevos cursos esté activado).
• El rol del usuario no tiene local/dttutor:use en el curso.
• La página es una en la que el avatar nunca se muestra: páginas de cuestionarios (quiz), la página principal del sitio, diseños embebidos o emergentes (p. ej. iframes de H5P).
• El usuario está respondiendo un cuestionario de ese curso: el tutor vuelve cuando envía el intento o se agota su tiempo.
• El proveedor de IA está desactivado en la administración de IA de Moodle.

Qué hacer:

1. Revise Habilitar chat en Administración del sitio → Extensiones → Extensiones locales → Tutor IA.
2. Abra el curso y habilite el tutor desde Más → Gestión de tutores de IA.
3. Verifique la capacidad local/dttutor:use para el rol (ver Permisos).

---

"El Tutor IA está apagado en este sitio." (error_tutor_disabled_site)

Causa: Habilitar chat está desactivado.

Qué hacer: Active Habilitar chat en la configuración de Tutor AI.

---

"El Tutor IA no está disponible porque el proveedor de IA está desactivado en este sitio." (error_provider_disabled)

Causa: El Datacurso AI Provider está desactivado en la administración de IA de Moodle.

Qué hacer: Active el proveedor en Administración del sitio → General → IA → Proveedores de IA (en Moodle 5.0 o posterior, active su instancia del proveedor).

---

"El Tutor IA no está disponible mientras tienes un intento de cuestionario abierto." (error_quiz_in_progress)

Causa: El usuario está respondiendo un cuestionario del curso. Es intencional, para que el tutor no pueda ayudar durante un examen.

Qué hacer: Nada. El tutor vuelve cuando se envía el intento o se agota su tiempo.

---

"Falta la configuración de la API. Por favor, revise su configuración." (error_api_not_configured)

Causa: El Datacurso AI Provider no está configurado.

Qué hacer: Complete la configuración del Datacurso AI Provider (ver Prerrequisitos).

---

"El Tutor IA no está disponible para este curso." (error_tutor_not_available)

Causa: El tutor está apagado en ese curso, el usuario no está matriculado o no tiene local/dttutor:use, o la página pertenece a una actividad que el usuario no puede ver.

Qué hacer: Habilite el tutor desde Más → Gestión de tutores de IA y revise la matriculación y el rol del usuario.

---

Errores de licencia o créditos

• "Su licencia no permite el acceso al servicio Tutor IA." (error_license_not_allowed): la licencia configurada en el proveedor no incluye Tutor AI. Verifique el estado de la licencia o actualice el plan.
• "No hay suficientes créditos de IA disponibles para procesar su solicitud…" (error_insufficient_tokens): el sitio no tiene créditos de IA. Agregue créditos desde el Datacurso AI Provider.
• "Se ha superado el límite de consumo permitido. Por favor, inténtelo de nuevo el …" (error_ratelimit_exceeded): se alcanzó un límite de uso por plugin configurado en el Datacurso AI Provider. Espere hasta la hora indicada o ajuste el límite en el proveedor.

---

Tutor AI abre, pero nunca llegan respuestas (no hay respuesta en streaming)

Causas más comunes:

• La red bloquea conexiones de streaming (SSE).
• El proveedor no está licenciado o no está respondiendo.

Qué hacer:

1. Confirme que Datacurso AI Provider está licenciado (license key configurada).
2. Pruebe desde otra red/entorno para descartar bloqueo de SSE.

---

Las respuestas tardan demasiado

Qué hacer:

1. Si la página de ajustes muestra el aviso Fallos del servicio de IA, busque el evento de fallo del servicio de IA en los registros del sitio para ver qué falló (licencia, créditos, límite de uso o servicio caído).
2. Revise el registro de errores: allí quedan las respuestas que tardan más que el Objetivo de tiempo de respuesta.
3. Consulte el registro de desarrollo para ver qué paso (abrir la conversación, reunir el conocimiento del curso, generar el texto o guardar los mensajes) toma más tiempo.

---

Las respuestas no están relacionadas con el curso (demasiado genéricas)

Causas más comunes:

• El Aviso personalizado es muy amplio o está vacío.
• Envíe el material del curso al tutor de IA está apagado, por lo que el tutor solo conoce la estructura del curso.

Qué hacer:

1. Vaya a la configuración de Tutor AI y escriba en Aviso personalizado unas instrucciones cortas y enfocadas al curso.
2. Active Envíe el material del curso al tutor de IA si su institución permite compartir ese contenido con el servicio de IA.

Tip: Use las plantillas de la Guía de Prompts.

---

El tutor no puede responder preguntas sobre calificaciones

Causa: Envíe las calificaciones del estudiante al tutor de IA está apagado (valor predeterminado).

Qué hacer:

1. Active Envíe las calificaciones del estudiante al tutor de IA. Cada estudiante solo puede ver sus propias calificaciones.

---

Las conversaciones antiguas desaparecieron

Causa: Las conversaciones se eliminan después del número de días definido en Los días se mantienen las conversaciones.

Qué hacer:

1. Es el comportamiento esperado. Escriba 0 si las conversaciones deben conservarse hasta que se elimine el usuario o el curso. Tenga en cuenta que el propio servicio de IA las conserva siete días.

---

Los placeholders del prompt no funcionan

Tutor AI soporta estos placeholders en el nombre del tutor, el mensaje de bienvenida y el aviso personalizado:

• {teachername}
• {coursename}
• {username}
• {firstname}

Qué hacer:

1. Confirme que está usando el placeholder exactamente como se muestra (minúsculas, llaves, sin $a->).
2. Mantenga los placeholders dentro del campo del ajuste (no modifique la sintaxis).