DeepTutor es un sistema de aprendizaje personalizado de código abierto que puede realizar preguntas, investigar y planificar estudios en torno a materiales, y generar archivos DOCX, PDF, PPTX y XLSX mediante la ejecución de código. Es adecuado para crear un asistente de aprendizaje personal, pero cuando se implementa localmente, los permisos de modelo, búsqueda, almacenamiento de archivos y ejecución de código deben manejarse al mismo tiempo.
Dirección del proyecto: HKUDS/DeepTutor
Respuesta rápida
Para la primera implementación, se recomienda utilizar la configuración de Docker Compose proporcionada por el repositorio en lugar de instalar directamente el backend en el host. La solución Compose entregará el código generado por el modelo a un Runner Sidecar independiente y con pocos privilegios, y la fuerza del aislamiento es mayor que la ejecución de procesos secundarios restringidos directamente en el host.
Preparación antes del despliegue:
- Docker y Docker Compose;
- Clave API de al menos un modelo compatible;
- Servicios opcionales de integración y búsqueda;
- Directorio
data/persistente; - Las direcciones de acceso solo se abren en redes confiables.
¿Dónde está el archivo de configuración?
La configuración de usuario de DeepTutor se encuentra en data/user/settings/. Los archivos comunes incluyen:
| Documentación | Propósito |
|---|---|
model_catalog.json |
LLM, incrustación, servicio de búsqueda y clave API |
system.json |
Puertos, CORS, SSL, directorio de archivos adjuntos y restricciones de carga |
auth.json |
Modificadores de inicio de sesión, nombres de usuario, hashes de contraseñas y configuración de sesión |
integrations.json |
Integración de PocketBase y Sidecar |
interface.json |
Preferencias de idioma, tema e interfaz |
Los funcionarios recomiendan modificar estos archivos a través de la página de configuración del navegador. Al editar JSON manualmente, no sobrescriba secciones enteras de la configuración existente. Haga una copia de seguridad y verifique primero si hay comas, comillas e ID de modelo.
¿Por qué deberíamos prestar atención a la ejecución del código?
Office Skills de DeepTutor hará que el modelo genere un script de Python, que luego se ejecuta a través de exec o code_execution. Esto permite generar archivos utilizando bibliotecas como python-docx, reportlab, openpyxl, etc., pero también significa que el modelo puede ejecutar código.
Cuando se ejecuta directamente localmente, el subproceso restringido predeterminado todavía está en el host; Docker Compose dará prioridad al uso de un Runner independiente. Si no necesita la función de generación de archivos de Office, puede cerrar la ejecución del subproceso del host:
|
|
También puede configurar sandbox_allow_subprocess como false en data/user/settings/system.json. Cuando está desactivada, las capacidades de generación de archivos que dependen de la ejecución de código no estarán disponibles.
Comprobaciones de implementación recomendadas
- Primero vincule solo
127.0.0.1y confirme que las llamadas de página y modelo sean normales; - Cargue un archivo pequeño sin privacidad para probar el análisis;
- Compruebe si Runner ejecuta el archivo generado en lugar del proceso host;
- Después de activar la autenticación, proporcione acceso LAN a través del proxy inverso;
- Limite el tamaño de carga, el directorio de archivos adjuntos y la fuente CORS;
- La clave API solo se coloca en la configuración del servidor y no se escribe en el repositorio público.
¿Cómo elegir entre los tres modos de funcionamiento?
La ejecución local de DeepTutor se puede dividir aproximadamente en ejecución directa, contenedor único y Docker Compose. Al elegir, no solo compare los comandos de instalación, sino también dónde se ejecuta el código de generación del modelo.
| Método | Ventajas | Principales riesgos | Escenarios adecuados |
|---|---|---|---|
| Ejecutar directamente localmente | Fácil de depurar y cambiar código rápidamente | Los procesos secundarios restringidos todavía están en la máquina host | Desarrollo y pruebas de datos confiables |
| Contenedor único | Dependencias concentradas | La ejecución de la aplicación y el código todavía están dentro del mismo límite del contenedor | Experiencia de usuario único |
| Docker componer | Corredor Independiente, aislamiento más claro | Más elementos de configuración y contenedores | Autohospedaje a largo plazo |
Siempre que esté activada la generación DOCX, PDF, PPTX o XLSX, se debe dar prioridad a Redactar. Incluso cuando se utiliza en una PC, no piense en “modelo no malicioso” como control de seguridad.
Planificación de recursos antes de la implementación
DeepTutor en sí no necesariamente ejecuta modelos grandes de forma nativa, pero el análisis, la incrustación, la generación de archivos y las tareas simultáneas de documentos aún consumen recursos. Se recomienda confirmar con antelación:
- En qué disco se encuentra el directorio de archivos adjuntos;
- Período de retención de archivos cargados y archivos generados;
- Si el Runner establece límites de CPU, memoria y proceso;
- Límites de costos y concurrencia para las API modelo;
- Buscar si el Proveedor tiene restricciones de región y cuota;
- Si es necesario habilitar la autenticación para múltiples usuarios.
Si el modelo local está conectado, la memoria de video y la duración del contexto deben calcularse por separado. Poder responder al chat no significa que los PDF largos, la recuperación y la generación de archivos puedan ejecutarse de manera estable bajo la misma configuración.
Orden correcto de configuración del modelo.
Primero configure el modelo de diálogo principal.
Agregue proveedor, dirección API, clave e ID de modelo en model_catalog.json o en la página de configuración. Primero pruebe la conexión con preguntas breves para asegurarse de que no haya errores 401, 404 o de nombre de modelo.
Configurar la incrustación nuevamente
La recuperación de la base de conocimientos requiere vectorización. El modelo de incrustación y el modelo de chat son dos tipos de configuraciones y no se pueden omitir solo porque el chat se realizó correctamente. Después de reemplazar el modelo de incrustación, es posible que sea necesario reconstruir el índice anterior; de lo contrario, las dimensiones o el espacio semántico serán inconsistentes.
Finalmente acceda a la búsqueda
Las búsquedas externas envían consultas a servicios de terceros. Primero aclare si los datos pueden salir de la red y luego configure el proveedor de búsqueda. Cuando trabaje con documentos internos, puede desactivar las búsquedas externas y utilizar únicamente materiales cargados.
Proceso de verificación después del primer inicio
Verificación 1: conversación normal
Haga una pregunta breve y sin herramientas y vea las devoluciones y registros del modelo. El propósito es confirmar el proveedor, la identificación del modelo y la conexión de red.
Verificación 2: Preguntas y respuestas sobre la información
Cargue un PDF breve sin privacidad, haga una pregunta cuya respuesta se pueda encontrar directamente en el texto y luego solicite el número de página o la base. Si la respuesta no coincide con el texto original, verifique el análisis, la incrustación y la recuperación en lugar de cambiar inmediatamente el modelo de chat.
Verificación 3: Generación de archivos
Haga que el sistema genere un DOCX de prueba que contenga solo encabezados y tablas, confirme el registro de Runner, el enlace de descarga y el archivo de salida. No utilice tablas o PPT complejos que contengan datos confidenciales la primera vez.
Verificación 4: reiniciar la recuperación
Después de reiniciar el contenedor, verifique si la configuración, las sesiones, los datos cargados y los archivos generados todavía están allí. Si el contenido desaparece, el volumen persistente no está asignado correctamente.
Proxy inverso y autenticación
Si necesita acceder desde la LAN o red pública, primero debe habilitar la autenticación en auth.json y luego configurar el proxy inverso HTTPS. También verifique sincrónicamente:
- Dirección API pública de
system.json; - CORS sólo permite nombres de dominio que realmente se utilizan;
- Propiedades de seguridad de las cookies;
- Tamaño de carga y tiempo de espera de solicitud;
- Si el proxy reenvía correctamente el WebSocket o la respuesta de streaming;
- Si la página de gestión está expuesta al mundo exterior.
No confíe únicamente en una URL difícil de adivinar para proteger su servicio. La red pública DeepTutor también tiene capacidades de ejecución de códigos, claves de modelos y documentos, y la certificación es el requisito mínimo.
Qué hacer una copia de seguridad
Como mínimo, haga una copia de seguridad de data/user/settings/, perfiles de usuario, bases de datos de sesiones y archivos adjuntos generados. Las claves API se pueden reinyectar mediante una administración segura de claves y no necesariamente tienen que ir a los archivos de respaldo normales.
Recomendaciones antes de actualizar:
- Detener nuevas tareas;
- Haga una copia de seguridad del directorio de persistencia;
- Registre la imagen actual o la versión enviada;
- Lea las instrucciones de migración de configuración;
- Realice las cuatro verificaciones nuevamente después de la actualización.
Tabla de comparación de errores comunes
| Fenómeno | Posibles causas | Instrucciones para solucionar problemas |
|---|---|---|
| La página es normal pero el modelo no responde | Clave, ID de modelo, errores de API Base | Registros de proveedores y códigos de estado HTTP |
| Capaz de chatear pero poca información Preguntas y respuestas | Análisis o incrustación no configurados | Texto del documento, indexación y resultados de recuperación |
| Error al generar archivos de Office | Runner, dependencias o permisos de directorio | Registros de sidecar y directorios de montaje |
| Los datos desaparecen después del reinicio | Error de volumen persistente | Redactar volumen y ruta de host |
| Interrupción de la transmisión después del proxy inverso | Almacenamiento en búfer, tiempo de espera o WebSocket | Configuración de proxy |
| La CPU sigue llena | Tareas de análisis, corredores o modelos locales | Lista de procesos y recursos de contenedores |
Preguntas frecuentes
¿Qué debo hacer si se puede abrir la página pero el modelo no responde?
Primero verifique si el proveedor, el ID del modelo, la dirección API y la clave de model_catalog.json coinciden y luego verifique el registro del contenedor para detectar errores 401, 404, tiempo de espera o longitud del contexto.
¿Por qué falla la generación de DOCX o PDF?
Confirme que la zona de pruebas no esté cerrada y verifique si Runner es normal, si existen los paquetes de Python requeridos y si se puede escribir en el directorio adjunto. Si solo funciona el chat pero Office Skills falla, el problema generalmente no está en la conexión del modelo.
¿Pueden varias personas compartir una implementación?
Se puede evaluar, pero primero se deben confirmar las capacidades de aislamiento de usuarios de la versión. Las claves de modelo, los datos cargados, las sesiones y los archivos generados no pueden distinguirse únicamente por la interfaz; Es más seguro utilizar servicios de usuario único antes de la verificación.
¿El uso de modelos locales no filtrará datos?
incierto. Las búsquedas externas, las incrustaciones, la telemetría y los proxies inversos aún pueden generar solicitudes salientes. Confirme el paradero real de cada Proveedor a través de registros de red.
¿Qué funciones se ven afectadas después de cerrar el proceso hijo?
El chat normal y la recuperación sin ejecución seguirán funcionando, pero la capacidad de generar archivos de Office, PDF, etc. a través de Python se verá afectada. Haga una lista de las habilidades que su equipo realmente necesita antes de cerrar.
¿Qué otras restricciones son necesarias para Runner?
Un Runner independiente es más seguro que un proceso secundario del host, pero aún es necesario configurar el contenedor en sí:
- Leer sólo el sistema de archivos raíz o minimizar los directorios de escritura;
- usuario no root;
- Docker Socket no está montado;
- No monte el directorio de inicio del host;
- Limitar CPU, memoria, número de procesos y tiempo de ejecución;
- Las redes externas están prohibidas de forma predeterminada o solo se permiten los objetivos necesarios;
- Utilice un directorio temporal independiente para cada tarea y límpielo a tiempo;
- El registro no muestra los documentos ni las credenciales cargados.
Si Runner tiene acceso a la base de datos de la aplicación, la clave del modelo o el Docker del host, su contenedor independiente pierde la mayor parte de su significado de aislamiento.
Ciclo de vida de los datos cargados
Antes de la implementación, es necesario aclarar dónde van los archivos desde la carga hasta la eliminación: caché temporal del navegador, directorio de archivos adjuntos de la aplicación, resultados del análisis, índice de vectores, registros de sesión, archivos generados y copias de seguridad. Después de que el usuario elimina el archivo original en la interfaz, también se debe probar si se eliminan otras copias simultáneamente.
Para los datos internos, se recomienda establecer un período de retención claro y escribir estrategias de copia de seguridad y eliminación en los documentos de operación y mantenimiento. Sólo porque el servicio se implementa localmente, no se pueden ignorar las copias de datos en registros, cachés e instantáneas.
Formulario de aceptación mínima antes de conectarse
| Proyecto | Pasar estándares |
|---|---|
| Modelo | Tanto preguntas y respuestas cortas como contexto largo disponibles |
| Buscar | Puede devolver el fragmento y la fuente correctos |
| Corredor | La generación de archivos se ejecuta en un contenedor separado |
| Persistencia | Los datos y la configuración seguirán existiendo después del reinicio |
| Autenticación | No se puede acceder a datos e interfaces sin iniciar sesión |
| Apoderado | HTTPS, transmisión de respuestas y cargas OK |
| Copia de seguridad | Capacidad de restaurar en una instancia de prueba separada |
| Eliminar | Los archivos originales, índices y productos generados se limpian según la política |
Solo cuando se verifiquen estos proyectos se podrá completar la implementación local que se puede utilizar durante mucho tiempo.
Resumen
El objetivo de la implementación de DeepTutor no es “ejecutar el contenedor”, sino configurar la configuración del modelo, la persistencia, la autenticación y los límites de ejecución del código. Para uso personal, también se debe usar primero el corredor independiente de Docker Compose, y la ejecución del subproceso del host debe cerrarse cuando no se necesita la generación de archivos.