318 lines
8.3 KiB
Markdown
318 lines
8.3 KiB
Markdown
# 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"*
|