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
Duración estimada: 25 minutos · Tipo: Decisión / Aprobación
| Tecnología | Versión | Rol en v2.1.0 |
|---|---|---|
| Quarkus (JAX-RS / CDI / Panache) | 3.15.3 | Contenedor de aplicación |
| Java | 21 | Lógica de negocio |
| PostgreSQL | 16 | Almacenamiento relacional |
| Qdrant | 1.17 | Vector store (3072-dim) |
| Keycloak (OIDC) | 26 | Autenticación JWT + RBAC |
| OpenAI text-embedding-3-large | API | Generación de embeddings |
| OpenAI gpt-4o-mini | API | Chat, extract, reranker cross-encoder |
| Caffeine NUEVO | — | Cache in-memory (grafo + JWT) |
Pipeline Two-Stage · Cross-Encoder · Caffeine Cache · API Unificada
Stack inalterado — restricción R-01. Caffeine es adición de librería Java compatible.
top-20 candidatos
similitud coseno
Re-rank top-20 → top-5
gpt-4o-mini entailment
BFS multi-origen
top-3 seeds · depth N
Merge + Dedup
Ordenar score ↓
| Componente | Tiempo estimado | Degradación graceful |
|---|---|---|
| Dense retrieval (Qdrant) | ~120ms | Timeout → HTTP 504 |
| Cross-encoder (OpenAI) | ~200ms batch 20 | Timeout 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 | — |
ChatLanguageModel existente — sin nueva infraestructuraexpandGraph default cambia: true → falsefalse: solo dense + cross-encoder, sin grafographTopK=3 (antes 5)entryPoints explícitos con máxima precedenciasingle-best, top-k, thresholdPOST /extract usa exclusivamente OpenAiLlmServiceMockLlmService (regex)hash(entryPoints + depth + kinds)@Startup)exp − nowPOST /memoriesabax-memories"abax-memories-v2" del códigoprofiles.config — sin nueva columnasingle-best, top-k, thresholdX-Graph-StrategyX-Graph-Strategy: none | single | top-k | thresholdX-Graph-K: 1–10 · X-Graph-Threshold: 0.0–1.0POST /searchsemanticWeight, lexicalWeight, rerank, expandGraph/search/hybrid → deprecado con headers Deprecation: true/search/semantic → se mantiene como shortcutAdminResourceV2memory-admin en JWT → sino HTTP 403| Entidad | Tabla | Cambios en v2.1.0 |
|---|---|---|
| MemoryFragmentEntity | memories | Ninguno |
| RelationEntity | relations | Ninguno |
| DomainProfileEntity | profiles | JSONB config extendido con graphEntryStrategy EXTENDIDO |
| AuditRecordEntity | audit_records | Ninguno |
| Atributo | v2.0.9 | v2.1.0 |
|---|---|---|
| Colección activa | abax-memories-v2 (hardcode) | abax-memories (configurable) CAMBIO |
| Colección legacy | abax-memories-v1 | Eliminada (offline pre-deploy) ELIMINADA |
| Dimensionalidad | 3072 | 3072 (sin cambios) |
| Métrica | Cosine | Cosine (sin cambios) |
{
"defaultKind": "fact",
"defaultSensitivity": "internal",
"graphEntryStrategy": {
"strategy": "top-k",
"graphK": 3,
"graphThreshold": null
}
}
| Clave | SHA-256 del token |
| TTL | exp − now (máx 1h) |
| Invalidación | Keycloak Admin Events (≤5s) |
| Resiliencia | KC caído + cache hit → request OK |
| Autorización | Claim JWT realm_access.roles ⊃ memory-admin |
| Sin rol | HTTP 403 — "Admin role required" |
| Atomicidad | Transacción PG (todo o nada) |
| Auditoría | AuditRecord con conteo de eliminados |
| Benchmark | Dataset | Métrica | Meta v2.1.0 | v2.0.9 |
|---|---|---|---|---|
| SciFact | 5,183 docs / 300 q | NDCG@10 | ≥ 0.85 | 0.7771 |
| SciFact | 5,183 docs / 300 q | Recall@10 | ≥ 0.90 | 0.9006 |
| ABM-MULTI-01 | 50 queries cross-dominio | Recall con grafo | ≥ 85% | 69.4% |
| Suite multi-dominio | 100 queries ground truth | Top-1 accuracy | ≥ 0.90 | ~0.78 |
| Escenario | Condición | Meta p95 |
|---|---|---|
| Cold start | Tras deploy, primera query | ≤ 1s; ≤ 500ms tras 10 q |
| Steady state | 5 min post-deploy, carga continua | ≤ 500ms |
| Escritura concurrente | 10 writes + 300 queries simultáneas | ≤ 500ms |
| Cache JWT | 100 requests mismo token | ≤ 5ms (requests 2–100) |
| Cache grafo | 3 queries idénticas con grafo | ≥ 50% reducción (q2–3 vs q1) |
Comparación offline (no runtime): 100 queries ejecutadas con rerank: false y rerank: true. Resultados documentados en ADR-001 y dashboard de benchmarks.
| Semana | Actividades principales |
|---|---|
| 1 | Cross-Encoder (ADR-001) + Diagnóstico Qdrant (ADR-006) + Diagnóstico Worker (ADR-008) |
| 2 | Cache Grafo (ADR-005) + Cache JWT (ADR-007) + Aislamiento Semántico (ADR-002) |
| 3 | Grafo Multi-Origen (ADR-003) + API Unificada (ADR-012) + graphEntryStrategy (ADR-010) |
| 4 | DELETE Namespace (ADR-013) + Extract OpenAI (ADR-004) + Migración Qdrant (ADR-009) + Benchmarks |
Abax-Memory v2.1.0 aplica hardening incremental sobre v2.0.9:
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