3.5 KiB
3.5 KiB
Plan Técnico: Arquitectura RAG Embebida y Asistente UdeCi (SDD-010)
1. Arquitectura Técnica de la Solución (4 Capas)
1.1 Capa de Esquemas y Contratos (backend/schemas/ai_chat.py)
- Extender
ChatResponsepara soportar sugerencias de acciones / botones opcionales:quick_options: Optional[List[str]] = Field(default_factory=list, description="Lista de opciones o preguntas de seguimiento en botones")
RAGReindexResponse(BaseModel):status: strindexed_chunks: intmessage: str
1.2 Capa de Persistencia y Base de Datos (backend/app/models/knowledge_chunk.py)
- Modelo SQLAlchemy 2.0
KnowledgeChunk:id: Integer primary keytitle: String(150), nullable=Falsecontent: Text, nullable=Falserole: String(50), index=True (ej. 'alumno', 'docente', 'bedelia', 'general')keywords: String(255), index=Truecategory: String(50), default='manual'created_at: DateTime
- Métodos de búsqueda semántica local:
- Búsqueda híbrida ponderada (palabras clave + coincidencia contextual normalizada + filtro estricto de rol
role IN (:role, 'general')).
- Búsqueda híbrida ponderada (palabras clave + coincidencia contextual normalizada + filtro estricto de rol
1.3 Capa de Lógica RAG y Routers FastAPI (backend/routers/ai_chat.py)
RAGService:search_relevant_chunks(query: str, user_role: str, limit: int = 3) -> List[KnowledgeChunk]: Realiza la consulta filtrada en SQLite y extrae los 3 fragmentos más relevantes.reindex_default_knowledge() -> int: Ingesta y particiona los manuales de Bedelía (9 pasos, matriz de conflictos, optimizador genético, sheets, Moodle), Docentes (aulas, actas Gradebook, Meet) y Alumnos (cartelera, materias, notas).
- Prompt Dinámico RAG:
- Inyecta únicamente los fragmentos recuperados.
- Instruye a UdeCi a responder de forma breve (2 a 3 oraciones o pasos directos), en tono cordial institucional, y a proponer 2 o 3 opciones en formato de botones
[Opción 1 | Opción 2]. - Temperatura fijada en
0.1para eliminar alucinaciones.
- Endpoints:
POST /api/chat/(y/api/v1/chat/): Procesa la consulta mediante RAG + Llama.cpp.POST /api/chat/rag/reindex: Endpoint administrativo para reindexar la base de conocimiento.
1.4 Capa de Frontend BFF y UI (Widget UdeCi)
frontend/views/partials/ai_chat_widget.html:- Reemplazo total de nombres técnicos por UdeCi · Tutor Virtual UniCABA.
- Barra de opciones rápidas con botones/chips según el rol del usuario.
frontend/public/js/ai-chat-widget.js:- Renderizado de chips de botones interactivos debajo de los mensajes.
- Al hacer clic en cualquier chip, envía automáticamente la pregunta al chat.
- Parseo automático de opciones devueltas por UdeCi para renderizarlas como botones de seguimiento.
2. Plan de Pruebas Automatizadas (backend/tests/test_rag_udeci.py)
- Validación de partición e indexación de fragmentos en
KnowledgeChunk. - Verificación de filtrado estricto por rol: un alumno nunca recibe fragmentos con
role='bedelia'. - Verificación de búsqueda semántica retornando los fragmentos oficiales pertinentes.
- Verificación de formato de respuesta breve con botones de opciones
quick_options. - Ejecución del 100% de la suite de pruebas (
pytest tests -v).
3. Plan de Despliegue en Producción
- Cero errores estáticos (
py_compile). - Suite completa de tests en verde.
- Bump semántico a
v3.8.25enpackage.json,app.js,__init__.py,setup.py,CHANGELOG.mdyMEMORY.md. git push origin devy despliegue SSH a LXC10.0.0.217con reinicio de servicios y smoke test.