tzzr/system-docs

Fork 0

Files

ARCHITECT 1b392803fd Archive: System v4 - Estado al 2024-12-24

2025-12-24 17:28:34 +00:00

8.3 KiB

Raw Blame History

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:

{
  "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:

{
  "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:

{
  "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:

# 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"

8.3 KiB Raw Blame History