Archive: System v4 - Estado al 2024-12-24
This commit is contained in:
ARCHITECT
247
v4-archive/deck/docs/ARQUITECTURA.md
Normal file
247
v4-archive/deck/docs/ARQUITECTURA.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# DECK - Arquitectura del Sistema
|
||||
|
||||
## Rol de DECK en el Ecosistema TZZR
|
||||
|
||||
DECK es el **servidor central** y **punto de iniciación** de todas las conexiones hacia los servicios de IA del ecosistema TZZR. Actúa como:
|
||||
|
||||
1. **Iniciador de conexiones**: Todas las llamadas a GRACE, PENNY y THE FACTORY se originan desde DECK
|
||||
2. **Gestor de contexto**: Envía la información de contexto necesaria con cada request
|
||||
3. **Router de despliegue**: Decide si usar servicios self-hosted o externos
|
||||
4. **Almacén de credenciales**: Gestiona las API keys a través de Vaultwarden/Key Vault
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ DECK │
|
||||
│ (Servidor Central) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ PostgreSQL │ │ NocoDB │ │ FileBrowser │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Vaultwarden │ │ Shlink │ │ Addy.io │ │
|
||||
│ │ (Key Vault) │ │ │ │ │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ DEPLOYMENT ROUTER │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ GRACE │ │ PENNY │ │ FACTORY │ │ │
|
||||
│ │ │ Connector │ │ Connector │ │ Connector │ │ │
|
||||
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
|
||||
│ └─────────┼────────────────┼────────────────┼──────────────┘ │
|
||||
└────────────┼────────────────┼────────────────┼──────────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌────────────────────────────────────────────────────┐
|
||||
│ SERVICIOS DE IA │
|
||||
├────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ SELF-HOSTED │ │ EXTERNAL │ │
|
||||
│ │ (RunPod/GPU) │ │ (APIs) │ │
|
||||
│ ├─────────────────┤ ├─────────────────┤ │
|
||||
│ │ Faster Whisper │ │ Groq API │ │
|
||||
│ │ Local LLM │ │ OpenRouter │ │
|
||||
│ │ Tesseract │ │ OpenAI │ │
|
||||
│ │ Embeddings │ │ Anthropic │ │
|
||||
│ └─────────────────┘ │ ElevenLabs │ │
|
||||
│ └─────────────────┘ │
|
||||
└────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Modos de Despliegue
|
||||
|
||||
DECK soporta tres modos de despliegue definidos en `config/deployment.yaml`:
|
||||
|
||||
### 1. EXTERNAL
|
||||
- Todas las llamadas van a proveedores externos (APIs)
|
||||
- Sin infraestructura propia de IA
|
||||
- Ideal para: Inicio rápido, bajo volumen
|
||||
|
||||
```yaml
|
||||
grace:
|
||||
mode: EXTERNAL
|
||||
external:
|
||||
providers_allowed: [groq, openrouter, openai, anthropic]
|
||||
```
|
||||
|
||||
### 2. SELF_HOSTED
|
||||
- Todas las llamadas van a infraestructura propia
|
||||
- Requiere RunPod/GPU configurado
|
||||
- Ideal para: Privacidad total, alto volumen, costos predecibles
|
||||
|
||||
```yaml
|
||||
grace:
|
||||
mode: SELF_HOSTED
|
||||
self_hosted:
|
||||
endpoint: "https://your-runpod-endpoint.runpod.net"
|
||||
timeout_ms: 30000
|
||||
```
|
||||
|
||||
### 3. SEMI (Recomendado)
|
||||
- Intenta self-hosted primero
|
||||
- Fallback automático a external si falla
|
||||
- Balance entre privacidad y disponibilidad
|
||||
|
||||
```yaml
|
||||
grace:
|
||||
mode: SEMI
|
||||
tier_preference:
|
||||
- SELF_HOSTED
|
||||
- EXTERNAL
|
||||
self_hosted:
|
||||
endpoint: "..."
|
||||
retry_on_failure: true
|
||||
external:
|
||||
providers_allowed: [groq, openrouter]
|
||||
```
|
||||
|
||||
## Flujo de una Request
|
||||
|
||||
```
|
||||
┌──────────┐ ┌──────────┐ ┌───────────────┐ ┌──────────────┐
|
||||
│ Cliente │────▶│ DECK │────▶│ Deployment │────▶│ Servicio │
|
||||
│ │ │ │ │ Router │ │ (IA) │
|
||||
└──────────┘ └────┬─────┘ └───────┬───────┘ └──────────────┘
|
||||
│ │
|
||||
│ 1. Recibe request │
|
||||
│ 2. Lee config/deployment.yaml
|
||||
│ 3. Obtiene credenciales de Vaultwarden
|
||||
│ 4. Construye S-CONTRACT request
|
||||
│ │
|
||||
│ ┌────────▼────────┐
|
||||
│ │ mode: SEMI │
|
||||
│ ├─────────────────┤
|
||||
│ │ 1. Try SELF_HOSTED
|
||||
│ │ 2. If fail → EXTERNAL
|
||||
│ └─────────────────┘
|
||||
```
|
||||
|
||||
## Estructura de Directorios
|
||||
|
||||
```
|
||||
deck/
|
||||
├── config/
|
||||
│ └── deployment.yaml # Configuración de modos de despliegue
|
||||
├── docker-compose.yml # Servicios principales
|
||||
├── docs/
|
||||
│ ├── ARQUITECTURA.md # Este documento
|
||||
│ └── ESPECIFICACION_SERVIDOR.md
|
||||
├── .env.example # Variables de entorno (incluye AI)
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Integración con S-CONTRACT v2.1
|
||||
|
||||
DECK construye requests siguiendo el S-CONTRACT v2.1 de `contratos-comunes`:
|
||||
|
||||
```json
|
||||
{
|
||||
"contract_version": "2.1",
|
||||
"profile": "FULL",
|
||||
"envelope": {
|
||||
"trace_id": "uuid-generado-por-deck",
|
||||
"idempotency_key": "sha256-del-contenido",
|
||||
"timestamp_init": "2025-12-18T10:00:00Z"
|
||||
},
|
||||
"routing": {
|
||||
"module": "ASR_ENGINE"
|
||||
},
|
||||
"deployment": {
|
||||
"mode": "SEMI",
|
||||
"tier_preference": ["SELF_HOSTED", "EXTERNAL"],
|
||||
"self_hosted": {
|
||||
"endpoint": "https://asr.runpod.net",
|
||||
"timeout_ms": 60000
|
||||
},
|
||||
"credentials_ref": "kv://deck/credentials/grace"
|
||||
},
|
||||
"payload": {
|
||||
"type": "audio",
|
||||
"encoding": "url",
|
||||
"content": "https://storage.tzzr.net/audio/file.mp3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Gestión de Credenciales
|
||||
|
||||
Las credenciales se almacenan en Vaultwarden y se referencian con URIs `kv://`:
|
||||
|
||||
| URI | Contenido |
|
||||
|-----|-----------|
|
||||
| `kv://deck/credentials/groq` | `{"api_key": "gsk_..."}` |
|
||||
| `kv://deck/credentials/openrouter` | `{"api_key": "sk-or-..."}` |
|
||||
| `kv://deck/credentials/runpod` | `{"api_key": "..."}` |
|
||||
| `kv://deck/credentials/grace` | `{"groq": "...", "openrouter": "..."}` |
|
||||
| `kv://deck/credentials/penny` | `{"groq": "...", "openai": "..."}` |
|
||||
| `kv://deck/credentials/factory` | `{"anthropic": "...", "openrouter": "..."}` |
|
||||
|
||||
## Servicios Actuales en DECK
|
||||
|
||||
| Servicio | Puerto | Descripción |
|
||||
|----------|--------|-------------|
|
||||
| PostgreSQL | 5432 | Base de datos principal |
|
||||
| NocoDB | 8080 | Interface de datos low-code |
|
||||
| FileBrowser | 8081 | Gestión de archivos |
|
||||
| Vaultwarden | 8082 | Key Vault / Gestor de contraseñas |
|
||||
| Shlink | 8083 | Acortador de URLs |
|
||||
| Addy.io | 8084 | Alias de correo |
|
||||
| Redis | 6379 | Cache y colas |
|
||||
|
||||
## Conectores de IA
|
||||
|
||||
### GRACE Connector
|
||||
- Procesa requests de módulos GRACE
|
||||
- Soporta todos los M-CONTRACTs (ASR, OCR, Classifier, etc.)
|
||||
- Maneja fallback chain según M-CONTRACT
|
||||
|
||||
### PENNY Connector
|
||||
- Conexión WebSocket para real-time voice
|
||||
- VAD integrado para detección de turnos
|
||||
- Barge-in para interrupciones
|
||||
|
||||
### FACTORY Connector
|
||||
- Procesos documentales largos
|
||||
- Batch processing
|
||||
- Pipelines multi-step
|
||||
|
||||
## Variables de Entorno Relevantes
|
||||
|
||||
```bash
|
||||
# Modo de despliegue
|
||||
DEPLOYMENT_MODE=SEMI
|
||||
|
||||
# Proveedores externos
|
||||
GROQ_API_KEY=gsk_...
|
||||
OPENROUTER_API_KEY=sk-or-...
|
||||
OPENAI_API_KEY=sk-...
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
|
||||
# Self-hosted (RunPod)
|
||||
RUNPOD_API_KEY=...
|
||||
GRACE_SELF_HOSTED_URL=https://...
|
||||
PENNY_RUNPOD_ENDPOINT=https://...
|
||||
ASR_RUNPOD_ENDPOINT=https://...
|
||||
```
|
||||
|
||||
## Monitoreo y Alertas
|
||||
|
||||
Configurado en `config/deployment.yaml`:
|
||||
|
||||
```yaml
|
||||
monitoring:
|
||||
latency:
|
||||
warn_threshold_ms: 5000
|
||||
error_threshold_ms: 15000
|
||||
cost:
|
||||
daily_budget_usd: 10.00
|
||||
alert_at_percent: 80
|
||||
```
|
||||
|
||||
## Próximos Pasos
|
||||
|
||||
1. Implementar el Deployment Router en código
|
||||
2. Integrar con Vaultwarden para credenciales
|
||||
3. Crear endpoints para GRACE/PENNY/FACTORY
|
||||
4. Dashboard de monitoreo de costos y latencia
|
||||
Reference in New Issue
Block a user