248 lines
10 KiB
Markdown
248 lines
10 KiB
Markdown
# 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
|