Diseño Técnico — Fase 3

Abax-Memory v2.1.0
Arquitectura

Hardening incremental del motor de búsqueda semántica con pipeline two-stage,
caché de grafo y JWT, y unificación de API

Responsable: Solution Architect  |  Fecha: 2026-05-06  |  Audiencia: Comité Técnico  |  Clasificación: Interna — Aprobación

Basado en: documento-de-arquitectura.md — 13 ADRs, 4 epics, ~20 días de construcción

Agenda

Qué vas a ver

  1. Visión general — Stack, contexto C4, cambios vs v2.0.9
  2. Pipeline Two-Stage — Dense retrieval → Cross-encoder → Grafo
  3. Decisiones de diseño (13 ADRs) — Precisión, Velocidad, Eficiencia, API/DX
  4. Modelo de datos y Seguridad — Sin cambios JPA, cache JWT, rol admin
  5. Testing & Benchmarks — 9 benchmarks, A/B testing offline
  6. Próximos pasos — Gate Fase 3 → Fase 4 (Construcción)

Duración estimada: 25 minutos · Tipo: Decisión / Aprobación

Visión general

Stack Tecnológico y Contexto

TecnologíaVersiónRol en v2.1.0
Quarkus (JAX-RS / CDI / Panache)3.15.3Contenedor de aplicación
Java21Lógica de negocio
PostgreSQL16Almacenamiento relacional
Qdrant1.17Vector store (3072-dim)
Keycloak (OIDC)26Autenticación JWT + RBAC
OpenAI text-embedding-3-largeAPIGeneración de embeddings
OpenAI gpt-4o-miniAPIChat, extract, reranker cross-encoder
Caffeine NUEVO—Cache in-memory (grafo + JWT)

Diagrama de Contexto (C4)

API ConsumerCliente HTTP
AdminRol memory-admin
Abax-Memory v2.1.0 Motor de búsqueda semántica +
grafo de conocimiento multi-dominio

Pipeline Two-Stage · Cross-Encoder · Caffeine Cache · API Unificada

OpenAI APIEmbeddings + Chat + Reranker
QdrantVector DB 3072-dim
Keycloak 26Proveedor OIDC
PostgreSQL 16Relacional

Stack inalterado — restricción R-01. Caffeine es adición de librería Java compatible.

Pipeline de búsqueda

Two-Stage: Dense → Cross-Encoder → Grafo

STAGE 1
Dense Retrieval

top-20 candidatos
similitud coseno

→
STAGE 2
Cross-Encoder

Re-rank top-20 → top-5
gpt-4o-mini entailment

→
STAGE 3
Grafo (opt)

BFS multi-origen
top-3 seeds · depth N

→
STAGE 4
Fusión

Merge + Dedup
Ordenar score ↓

Latencia y Degradación

ComponenteTiempo estimadoDegradación graceful
Dense retrieval (Qdrant)~120msTimeout → HTTP 504
Cross-encoder (OpenAI)~200ms batch 20Timeout 2s → dense-only + WARN
Grafo BFS (N+1 PG)~320ms (miss) / ~85ms (hit)Cache Caffeine TTL 60s
JWT validation (Keycloak)50–200ms → ≤5ms (hit)Cache Caffeine; si KC caído → sirve de cache
Total p95 esperado≤ 500ms—
EP-V21-001 · Precisión del Motor

ADRs Clave: Precisión

ADR-001 Aceptado

Reranker Cross-Encoder con OpenAI gpt-4o-mini

  • Pipeline two-stage: dense top-20 → cross-encoder → top-5
  • Reutiliza ChatLanguageModel existente — sin nueva infraestructura
  • Timeout 2s, degradación graceful a dense-only si no disponible
  • Meta: top-1 accuracy ≥ 0.90, NDCG@10 ≥ 0.85
ADR-002 Aceptado

Aislamiento de Búsqueda Semántica Pura

  • expandGraph default cambia: true → false
  • Cuando false: solo dense + cross-encoder, sin grafo
  • El flag controla exclusivamente la activación del grafo
ADR-003 Aceptado

Expansión de Grafo Multi-Origen

  • Default graphTopK=3 (antes 5)
  • entryPoints explícitos con máxima precedencia
  • Estrategias: single-best, top-k, threshold
  • Recall cross-dominio proyectado: 69.4% → ≥85%
ADR-004 Aceptado

Extracción de Entidades con OpenAI Real

  • POST /extract usa exclusivamente OpenAiLlmService
  • Sin API key → HTTP 503; error OpenAI → HTTP 502; timeout → HTTP 504
  • Nunca degrada a MockLlmService (regex)
EP-V21-002 · Velocidad y Latencia

ADRs Clave: Velocidad

ADR-005 Aceptado

Cache de Grafo con Caffeine

  • Clave: hash(entryPoints + depth + kinds)
  • TTL: 60s · Capacidad: 1,000 entradas · LRU
  • Invalidación por evento CDI en mutaciones de relaciones
  • Cache hit: ~85ms (vs ~320ms sin cache)
ADR-006 Aceptado

Diagnóstico de Latencia Qdrant

  • Fase de diagnóstico (semana 1) antes de mitigar
  • Hipótesis: cold start HNSW, lock contention, network, GC
  • Warm-up queries al iniciar (@Startup)
  • Meta: p95 ≤ 500ms en cold start, steady, escritura concurrente
ADR-007 Aceptado

Cache de Validación JWT

  • Clave: SHA-256 del token · TTL: exp − now
  • Cache hit ratio esperado ≥ 0.90
  • Invalidación por Keycloak Admin Events (logout, revoke)
  • Resiliencia: Keycloak caído + token en cache → request procede
EP-V21-003 · Eficiencia Operativa

ADRs Clave: Eficiencia

ADR-008 Propuesto

Diagnóstico y Resolución del Worker Inactivo

  • Hipótesis: Worker v1 inactivo; v2 no implementado
  • Procesamiento es 100% síncrono en POST /memories
  • Escenario A (probable): eliminar worker
  • Escenario B: reparar conexión a cola de mensajes
ADR-009 Aceptado

Unificación de Colecciones Qdrant

  • De 2 colecciones → 1: abax-memories
  • Script offline pre-deploy con snapshot
  • Verificación pre-migración: SQL para datos huérfanos
  • Eliminar hardcode "abax-memories-v2" del código
ADR-010 Aceptado

graphEntryStrategy Configurable

  • Almacenado en JSONB profiles.config — sin nueva columna
  • Estrategias: single-best, top-k, threshold
  • Resolución en runtime con cache de perfil (TTL 30s)
  • Sobrescribible por request vía header X-Graph-Strategy
EP-V21-004 · API y Developer Experience

ADRs Clave: API / DX

ADR-011 Aceptado

Headers X-Graph-Strategy

  • X-Graph-Strategy: none | single | top-k | threshold
  • X-Graph-K: 1–10 · X-Graph-Threshold: 0.0–1.0
  • Headers (no body) → separación de concerns HTTP
  • Precedencia: entryPoints body > headers > perfil dominio
ADR-012 Aceptado

Unificación de Endpoints

  • Endpoint canónico: POST /search
  • Parámetros: semanticWeight, lexicalWeight, rerank, expandGraph
  • /search/hybrid → deprecado con headers Deprecation: true
  • /search/semantic → se mantiene como shortcut
ADR-013 Aceptado

DELETE /admin/namespaces/{name}

  • Nuevo controller: AdminResourceV2
  • Autorización: rol memory-admin en JWT → sino HTTP 403
  • Transacción atómica PG + Qdrant (con mitigación de fallo parcial)
  • Respuesta: resumen con conteo de recursos eliminados
Modelo de datos

Entidades JPA sin cambios · Qdrant unificado

PostgreSQL — Sin cambios estructurales (R-04)

EntidadTablaCambios en v2.1.0
MemoryFragmentEntitymemoriesNinguno
RelationEntityrelationsNinguno
DomainProfileEntityprofilesJSONB config extendido con graphEntryStrategy EXTENDIDO
AuditRecordEntityaudit_recordsNinguno

Qdrant — Unificación

Atributov2.0.9v2.1.0
Colección activaabax-memories-v2 (hardcode)abax-memories (configurable) CAMBIO
Colección legacyabax-memories-v1Eliminada (offline pre-deploy) ELIMINADA
Dimensionalidad30723072 (sin cambios)
MétricaCosineCosine (sin cambios)

DomainProfile JSONB extendido

{
  "defaultKind": "fact",
  "defaultSensitivity": "internal",
  "graphEntryStrategy": {
    "strategy": "top-k",
    "graphK": 3,
    "graphThreshold": null
  }
}
Seguridad

Cache JWT · Rol memory-admin · Headers sin impacto

1. Cache JWT (ADR-007)

ClaveSHA-256 del token
TTLexp − now (máx 1h)
InvalidaciónKeycloak Admin Events (≤5s)
ResilienciaKC caído + cache hit → request OK

2. DELETE namespace — Rol memory-admin (ADR-013)

AutorizaciónClaim JWT realm_access.roles ⊃ memory-admin
Sin rolHTTP 403 — "Admin role required"
AtomicidadTransacción PG (todo o nada)
AuditoríaAuditRecord con conteo de eliminados

3. Headers X-Graph-Strategy (ADR-011)

  • Sin impacto de seguridad
  • Son metadata de control de comportamiento
  • No exponen datos sensibles
  • No son vectores de ataque (validación estricta)
  • No requieren autorización adicional
Estrategia de Testing

Benchmarks de Precisión y Latencia

4 Benchmarks de Precisión

BenchmarkDatasetMétricaMeta v2.1.0v2.0.9
SciFact5,183 docs / 300 qNDCG@10≥ 0.850.7771
SciFact5,183 docs / 300 qRecall@10≥ 0.900.9006
ABM-MULTI-0150 queries cross-dominioRecall con grafo≥ 85%69.4%
Suite multi-dominio100 queries ground truthTop-1 accuracy≥ 0.90~0.78

5 Benchmarks de Latencia

EscenarioCondiciónMeta p95
Cold startTras deploy, primera query≤ 1s; ≤ 500ms tras 10 q
Steady state5 min post-deploy, carga continua≤ 500ms
Escritura concurrente10 writes + 300 queries simultáneas≤ 500ms
Cache JWT100 requests mismo token≤ 5ms (requests 2–100)
Cache grafo3 queries idénticas con grafo≥ 50% reducción (q2–3 vs q1)

A/B Testing del Reranker — Offline

Comparación offline (no runtime): 100 queries ejecutadas con rerank: false y rerank: true. Resultados documentados en ADR-001 y dashboard de benchmarks.

Gate Fase 3 → Fase 4

Próximos Pasos

Gate de Diseño Técnico — Checklist

✓ 13 ADRs documentados con contexto, alternativas y consecuencias
✓ Diagramas C4: Contexto, Contenedores, Componentes, Secuencia
✓ Modelo de datos validado — sin cambios JPA (R-04)
✓ Matriz de integraciones: 9 contratos documentados
✓ Estrategia de testing: 9 benchmarks + contract + integración
✓ 7 riesgos técnicos identificados con mitigación
✓ Estimación de complejidad: ~20 días de construcción
→ Pendiente: Aprobación del Comité Técnico

Si se aprueba — Fase 4: Construcción

SemanaActividades principales
1Cross-Encoder (ADR-001) + Diagnóstico Qdrant (ADR-006) + Diagnóstico Worker (ADR-008)
2Cache Grafo (ADR-005) + Cache JWT (ADR-007) + Aislamiento Semántico (ADR-002)
3Grafo Multi-Origen (ADR-003) + API Unificada (ADR-012) + graphEntryStrategy (ADR-010)
4DELETE Namespace (ADR-013) + Extract OpenAI (ADR-004) + Migración Qdrant (ADR-009) + Benchmarks
Decisión Solicitada

¿La arquitectura propuesta es correcta?

Abax-Memory v2.1.0 aplica hardening incremental sobre v2.0.9:

Apruebo la arquitectura · Necesito ajustes · No autorizo Fase 4

Documento completo: docs/entregables/v2.1/fase-3-diseno-tecnico/documento-de-arquitectura.md
13 ADRs · 4 diagramas C4 · 9 benchmarks · 7 riesgos · ~20 días