NEXUS CORE
NEXUS CORE
Agente conversacional RAG 100% on-premise — Architecture brief. 100% on-premise conversational RAG agent — Architecture brief.
Universidad Ricardo Palma · 2025–2026 · Construido individualmente end-to-end
100%
on-premiseon-premise
30
sesiones concurrentesconcurrent sessions
7s
latencia p50p50 latency
~239
clases Java (+54 de prueba)Java classes (+54 test)
01 contextocontext
Asistente de IA conversacional para una universidad peruana que responde consultas de docentes y alumnos sobre normativa y documentación interna mediante RAG, ejecutado íntegramente on-premise (sin enviar datos a APIs comerciales) por requisitos de privacidad y cumplimiento. Construido end-to-end de forma individual: arquitectura, investigación, desarrollo y evaluación.
Conversational AI assistant for a Peruvian university that answers faculty and student questions about internal policies and documentation via RAG, running entirely on-premise (no data sent to commercial APIs) for privacy and compliance reasons. Built end-to-end single-handedly: architecture, research, development and evaluation.
02 arquitectura & stackarchitecture & stack
- Backend
- Java 21, Spring Boot 4 (WebFlux reactivo + R2DBC), Spring AI, Spring Security 7 / OAuth2. ~239 clases + 54 de prueba (
Testcontainers,WireMock,k6). - Java 21, Spring Boot 4 (reactive WebFlux + R2DBC), Spring AI, Spring Security 7 / OAuth2. ~239 classes + 54 test classes (
Testcontainers,WireMock,k6). - DatosData
- PostgreSQL 16 +
pgvectorcomo única base relacional y vectorial (índice HNSW). Migraciones con Flyway. - PostgreSQL 16 +
pgvectoras the single relational and vector store (HNSW index). Flyway migrations. - DespliegueDeployment
- Docker Compose con overlays (GPU / Mac / dev / observabilidad). Portable sin cambios de código entre servidor NVIDIA y Apple Silicon.
- Docker Compose with overlays (GPU / Mac / dev / observability). Portable with no code changes between an NVIDIA server and Apple Silicon.
03 pipeline ragrag pipeline
- IngestaIngestion
- Chunking inteligente (~2000 caracteres, overlap 200) por párrafo/puntuación. Embeddings
BAAI/bge-m3(1024 dim) vía TEI. - Smart chunking (~2000 chars, 200 overlap) at paragraph/punctuation boundaries.
BAAI/bge-m3embeddings (1024-dim) via TEI. - Recuperación híbridaHybrid retrieval
- Vector (coseno) + BM25 full-text en español, fusionados con Reciprocal Rank Fusion (
k=60). Filtrado por rol/scope antes del retrieval (autorización fuera del LLM). - Vector (cosine) + Spanish BM25 full-text, fused with Reciprocal Rank Fusion (
k=60). Role/scope filtering before retrieval (authorization outside the LLM). - Reranking
BAAI/bge-reranker-v2-m3(top-20 → 10 → 6 chunks, umbral 0.3 con fallback).BAAI/bge-reranker-v2-m3(top-20 → 10 → 6 chunks, threshold 0.3 with fallback).- GeneraciónGeneration
- Citación inline obligatoria
[N]y guardrails anti-alucinación/anti-jailbreak en capas (regex + semántico + filtro de fuga). Tool-calling: ~7 herramientas en registro dinámico desde BD, filtradas por rol; flujos normal / crisis / continuación. - Mandatory inline citations
[N]and layered anti-hallucination/anti-jailbreak guardrails (regex + semantic + output-leak filter). Tool-calling: ~7 tools in a DB-driven dynamic registry, role-filtered; normal / crisis / continuation flows.
04 inferencia local & rendimientolocal inference & performance
- LLM
Qwen3-4B-Instructcuantizado AWQ INT4, servido con vLLM en NVIDIA A5000 24 GB (alternativa: Gemma vía Ollama en Apple Silicon). API OpenAI-compatible.Qwen3-4B-Instructquantized to AWQ INT4, served with vLLM on an NVIDIA A5000 24 GB (alternative: Gemma via Ollama on Apple Silicon). OpenAI-compatible API.- Rendimiento (medido)Performance (measured)
- 30 sesiones concurrentes de flujo completo a p50 7.0 s (36/36 sin fallos). Barrido empírico de
gpu-memory-utilization→ 0.78, logrando 12.4× de concurrencia KV (~101.6k tokens). - 30 full-flow concurrent sessions at p50 7.0 s (36/36, no failures). Empirical
gpu-memory-utilizationsweep → 0.78, reaching 12.4× KV concurrency (~101.6k tokens). - EvaluaciónEvaluation
- Golden set de ~43 consultas (admisión, académico, fuera-de-scope, jailbreak multi-idioma, crisis, redteam) con criterios contains/not-contains + latencia.
- Golden set of ~43 queries (admissions, academic, out-of-scope, multilingual jailbreak, crisis, redteam) with contains/not-contains criteria + latency.
05 seguridad & cumplimientosecurity & compliance
- AutorizaciónAuthorization
- Multi-rol (JWT multi-issuer; 4 roles con scopes, rate-limits y token-caps). Filtrado por rol previo al retrieval.
- Multi-role (multi-issuer JWT; 4 roles with scopes, rate-limits and token caps). Role filtering before retrieval.
- Auditoría & privacidadAudit & privacy
- Auditoría inviolable append-only con cadena de hashes
SHA-256; redacción de PII. - Tamper-evident append-only audit with a
SHA-256hash chain; PII redaction. - Compliance
- Ley N° 29733 (Perú), compatible GDPR / LGPD / CCPA; gestión de derechos del titular (DSR), consentimiento y retención.
- Peru's Law No. 29733, compatible with GDPR / LGPD / CCPA; data-subject rights (DSR), consent and retention management.
- ObservabilidadObservability
- OpenTelemetry + Prometheus + Grafana + Loki + Tempo; kill-switches por subsistema.
- OpenTelemetry + Prometheus + Grafana + Loki + Tempo; per-subsystem kill-switches.
06 estado & próximos pasosstatus & next steps
- EstadoStatus
- Arquitectura completa y validada en pruebas de carga; en fase pre-piloto, iniciando pruebas con usuarios.
- Architecture complete and validated under load testing; in pre-pilot, entering user testing.
- Próximos pasosNext steps
- Carga del corpus institucional, métricas automatizadas de recuperación (recall@k, faithfulness) y CI/CD.
- Institutional corpus loading, automated retrieval metrics (recall@k, faithfulness) and CI/CD.
El código es privado (proyecto institucional); este brief resume la arquitectura y los resultados. The source code is private (institutional project); this brief summarizes the architecture and results.