Archive: System v4 - Estado al 2024-12-24
This commit is contained in:
ARCHITECT
317
v4-archive/contratos-comunes/docs/PENNY.md
Normal file
317
v4-archive/contratos-comunes/docs/PENNY.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# PENNY - Arquitectura de Asistente de Voz
|
||||
**Version:** 1.0
|
||||
**Estado:** Especificacion Tecnica
|
||||
|
||||
---
|
||||
|
||||
# 1. Modos de Operacion
|
||||
|
||||
PENNY soporta dos modos de operacion seleccionables al inicio de sesion:
|
||||
|
||||
| Modo | Latencia | Costo | Privacidad |
|
||||
|------|----------|-------|------------|
|
||||
| `SELF_HOSTED` | 2-4s | ~$0.01/min | Total |
|
||||
| `EXTERNAL` | ~300ms | ~$0.08/min | APIs externas |
|
||||
|
||||
---
|
||||
|
||||
# 2. Modo SELF_HOSTED (Modelos Locales)
|
||||
|
||||
Pipeline secuencial con modelos autoalojados en RunPod:
|
||||
|
||||
```
|
||||
Audio entrada
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| Silero VAD | Detecta actividad de voz
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| Faster Whisper | ASR: Voz a texto (~500-1500ms)
|
||||
| Large V3 |
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| Qwen 2.5 7B | LLM: Genera respuesta (~500-2000ms)
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
| XTTS-v2 | TTS: Texto a voz (~500-1500ms)
|
||||
+------------------+
|
||||
|
|
||||
v
|
||||
Audio salida
|
||||
```
|
||||
|
||||
**Latencia total**: 2-4 segundos
|
||||
**Modelos requeridos** (~20GB en Network Volume):
|
||||
- Silero VAD (~1MB)
|
||||
- Faster Whisper Large V3 (~3GB)
|
||||
- Qwen 2.5 7B Instruct (~15GB)
|
||||
- XTTS-v2 (~2GB)
|
||||
|
||||
---
|
||||
|
||||
# 3. Modo EXTERNAL: Arquitectura Portavoz + Cerebro
|
||||
|
||||
Para lograr latencia conversacional (<500ms), se usa una arquitectura hibrida donde:
|
||||
|
||||
- **GPT-4o Realtime** actua como "portavoz" - maneja la voz en tiempo real
|
||||
- **Claude** actua como "cerebro" - analiza en paralelo y alimenta contexto
|
||||
|
||||
## 3.1 Concepto
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------------+
|
||||
| PRINCIPIO PORTAVOZ + CEREBRO |
|
||||
| |
|
||||
| "GPT es rapido pero limitado. Claude es inteligente pero lento. |
|
||||
| Usamos GPT como frontend de voz mientras Claude piensa detras." |
|
||||
+---------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
GPT-4o Realtime responde instantaneamente con la informacion que tiene.
|
||||
Claude analiza la conversacion en paralelo y actualiza el contexto de GPT.
|
||||
|
||||
## 3.2 Flujo de Operacion
|
||||
|
||||
```
|
||||
PENNY EXTERNAL
|
||||
|
|
||||
+-------------------+-------------------+
|
||||
| |
|
||||
v v
|
||||
+--------------------+ +--------------------+
|
||||
| GPT-4o Realtime | | Claude |
|
||||
| | | |
|
||||
| - Maneja voz | <------ | - Analiza contexto |
|
||||
| - Responde rapido | contexto | - Busca en KB |
|
||||
| - ~300ms latencia | | - Prepara info |
|
||||
+--------------------+ +--------------------+
|
||||
| |
|
||||
v |
|
||||
Audio respuesta |
|
||||
| |
|
||||
+---------------------------------------+
|
||||
|
|
||||
Actualiza system
|
||||
prompt de GPT
|
||||
```
|
||||
|
||||
## 3.3 Ciclo de Conversacion
|
||||
|
||||
```
|
||||
TURNO 1:
|
||||
Usuario habla -> GPT-4o transcribe + responde (con contexto inicial)
|
||||
-> Claude recibe transcripcion
|
||||
-> Claude analiza, busca en knowledge base
|
||||
-> Claude prepara contexto enriquecido
|
||||
|
||||
TURNO 2:
|
||||
Usuario habla -> GPT-4o responde (ahora con contexto de Claude)
|
||||
-> Claude sigue analizando...
|
||||
-> Claude actualiza contexto
|
||||
|
||||
TURNO N:
|
||||
El ciclo continua. GPT siempre tiene el ultimo contexto de Claude.
|
||||
```
|
||||
|
||||
## 3.4 Componentes
|
||||
|
||||
### GPT-4o Realtime (Portavoz)
|
||||
- **Funcion**: Frontend de voz con latencia minima
|
||||
- **API**: OpenAI Realtime API
|
||||
- **Latencia**: ~300ms end-to-end
|
||||
- **Responsabilidades**:
|
||||
- Transcripcion de voz (ASR integrado)
|
||||
- Generacion de respuesta
|
||||
- Sintesis de voz (TTS integrado)
|
||||
- **Limitaciones**: Contexto limitado, razonamiento superficial
|
||||
|
||||
### Claude (Cerebro)
|
||||
- **Funcion**: Analisis profundo en segundo plano
|
||||
- **API**: Anthropic Messages API
|
||||
- **Latencia**: 1-3s (no bloquea la conversacion)
|
||||
- **Responsabilidades**:
|
||||
- Analizar intencion del usuario
|
||||
- Buscar en knowledge base
|
||||
- Preparar datos relevantes
|
||||
- Generar instrucciones para GPT
|
||||
- Detectar cuando GPT necesita correccion
|
||||
|
||||
## 3.5 Actualizacion de Contexto
|
||||
|
||||
Claude genera un "folio" que se inyecta en el system prompt de GPT:
|
||||
|
||||
```json
|
||||
{
|
||||
"context_update": {
|
||||
"timestamp": "2025-12-18T10:30:00Z",
|
||||
"user_intent": "Consulta sobre factura pendiente",
|
||||
"relevant_data": {
|
||||
"factura_id": "F-2024-1234",
|
||||
"importe": 1500.00,
|
||||
"vencimiento": "2025-01-15",
|
||||
"estado": "pendiente"
|
||||
},
|
||||
"suggested_response_elements": [
|
||||
"Confirmar importe de la factura",
|
||||
"Mencionar fecha de vencimiento",
|
||||
"Ofrecer opciones de pago"
|
||||
],
|
||||
"tone_guidance": "profesional pero cercano",
|
||||
"warnings": [
|
||||
"Cliente tiene 2 facturas mas pendientes - no mencionar a menos que pregunte"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Este contexto se traduce a instrucciones en el system prompt de GPT:
|
||||
|
||||
```
|
||||
[CONTEXTO ACTUALIZADO - Turno 3]
|
||||
El usuario pregunta por una factura. Datos relevantes:
|
||||
- Factura F-2024-1234 por 1500 EUR
|
||||
- Vence el 15 de enero 2025
|
||||
- Estado: pendiente
|
||||
|
||||
En tu respuesta:
|
||||
- Confirma el importe
|
||||
- Menciona la fecha de vencimiento
|
||||
- Ofrece opciones de pago
|
||||
|
||||
Tono: profesional pero cercano
|
||||
Nota: El cliente tiene otras facturas pendientes, no las menciones a menos que pregunte.
|
||||
```
|
||||
|
||||
## 3.6 Manejo de Errores y Correcciones
|
||||
|
||||
Si Claude detecta que GPT dio informacion incorrecta:
|
||||
|
||||
```json
|
||||
{
|
||||
"correction_needed": true,
|
||||
"correction_type": "factual_error",
|
||||
"what_gpt_said": "La factura vence manana",
|
||||
"correct_info": "La factura vence el 15 de enero",
|
||||
"inject_correction": true
|
||||
}
|
||||
```
|
||||
|
||||
GPT recibe instruccion de corregirse naturalmente:
|
||||
```
|
||||
[CORRECCION NECESARIA]
|
||||
En tu respuesta anterior mencionaste que la factura vence manana.
|
||||
La fecha correcta es el 15 de enero.
|
||||
Corrige esto de forma natural en tu proxima respuesta, sin disculparte excesivamente.
|
||||
```
|
||||
|
||||
## 3.7 Configuracion de Sesion
|
||||
|
||||
Request de inicio de sesion PENNY EXTERNAL:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "session_start",
|
||||
"mode": "EXTERNAL",
|
||||
|
||||
"portavoz": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-realtime",
|
||||
"voice": "alloy",
|
||||
"language": "es",
|
||||
"initial_system_prompt": "Eres un asistente de voz profesional..."
|
||||
},
|
||||
|
||||
"cerebro": {
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"analysis_depth": "standard",
|
||||
"knowledge_base_ref": "kb://empresa/documentos",
|
||||
"update_frequency": "every_turn"
|
||||
},
|
||||
|
||||
"context": {
|
||||
"user_id": "uuid",
|
||||
"session_purpose": "atencion_cliente",
|
||||
"available_actions": ["consultar_factura", "programar_pago", "transferir_humano"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3.8 Costos Estimados
|
||||
|
||||
| Componente | Costo por minuto |
|
||||
|------------|------------------|
|
||||
| GPT-4o Realtime (audio) | ~$0.06 |
|
||||
| Claude Sonnet (analisis) | ~$0.02 |
|
||||
| **Total** | **~$0.08/min** |
|
||||
|
||||
Para una conversacion de 5 minutos: ~$0.40
|
||||
|
||||
---
|
||||
|
||||
# 4. Seleccion de Modo en DECK
|
||||
|
||||
DECK presenta la opcion al usuario al iniciar sesion de voz:
|
||||
|
||||
```yaml
|
||||
# deck/config/penny.yaml
|
||||
|
||||
penny:
|
||||
default_mode: SELF_HOSTED
|
||||
allow_user_selection: true
|
||||
|
||||
modes:
|
||||
SELF_HOSTED:
|
||||
label: "Privado (modelos locales)"
|
||||
description: "Mayor privacidad, latencia 2-4s"
|
||||
endpoint: "wss://api.runpod.ai/v2/${PENNY_ENDPOINT}/ws"
|
||||
|
||||
EXTERNAL:
|
||||
label: "Rapido (APIs externas)"
|
||||
description: "Conversacion fluida, latencia ~300ms"
|
||||
portavoz_provider: "openai"
|
||||
cerebro_provider: "anthropic"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 5. Comparativa de Modos
|
||||
|
||||
| Aspecto | SELF_HOSTED | EXTERNAL |
|
||||
|---------|-------------|----------|
|
||||
| Latencia | 2-4s | ~300ms |
|
||||
| Costo/min | ~$0.01 | ~$0.08 |
|
||||
| Privacidad | Total | Datos a OpenAI/Anthropic |
|
||||
| Calidad respuesta | Buena (Qwen 7B) | Excelente (Claude) |
|
||||
| Experiencia | Aceptable | Conversacional |
|
||||
| Cold start | 15-30s (primer uso) | Inmediato |
|
||||
| Dependencias | RunPod | OpenAI + Anthropic APIs |
|
||||
|
||||
---
|
||||
|
||||
# 6. Casos de Uso Recomendados
|
||||
|
||||
**SELF_HOSTED**:
|
||||
- Datos sensibles / confidenciales
|
||||
- Uso interno empresarial
|
||||
- Demostraciones sin conexion externa
|
||||
- Minimizar costos en alto volumen
|
||||
|
||||
**EXTERNAL**:
|
||||
- Atencion al cliente en tiempo real
|
||||
- Demos a inversores / clientes
|
||||
- Conversaciones donde la fluidez importa
|
||||
- Usuarios impacientes
|
||||
|
||||
---
|
||||
|
||||
**Fin del Documento PENNY - Version 1.0**
|
||||
|
||||
*Sistema PENNY - "Portavoz + Cerebro"*
|
||||
Reference in New Issue
Block a user