Asistente de IA de Voz en Tiempo Real con Llamada a Funciones y Transmisión de Audio Bidireccional

Construimos un asistente de IA de voz en tiempo real impulsado por la API Gemini Live de Google con capacidades de audio nativas, llamada a funciones personalizada para cálculos específicos del dominio y un frontend en React con transmisión de audio basada en WebSocket.

Arquitectura

• Modelo de IA: Gemini con entrada/salida de audio nativa y llamada a funciones
• Backend: Python/FastAPI con endpoint WebSocket para audio bidireccional
• Pipeline de Audio: PyAudio para E/S de micrófono/altavoz con transmisión en tiempo real
• Frontend: React con Vite y Tailwind CSS para la interfaz de usuario de control de sesión
• Comunicación: WebSocket para mensajería JSON de baja latencia y transporte de audio binario
• Multimodal: Captura opcional de cámara y pantalla para contexto visual

Pipeline de Audio en Tiempo Real

Transmisión Bidireccional

El sistema mantiene flujos de audio continuos en ambas direcciones:

• Entrada: Audio de micrófono capturado a 16kHz mono, dividido en pequeños marcos y transmitido al modelo de IA en tiempo real
• Salida: Discurso generado por IA recibido a 24kHz y reproducido por los altavoces inmediatamente
• Sin Procesamiento por Lotes: Los fragmentos de audio se envían tal como se capturan — sin retrasos por acumulación
• Gestión de Interrupciones: El usuario puede interrumpir al asistente a mitad de respuesta de forma natural

Procesamiento de Audio

• Formato PCM de 16 bits tanto para entrada como para salida
• Tasas de muestreo separadas optimizadas para el habla (captura a 16kHz, reproducción a 24kHz)
• Tamaños de búfer pequeños para una latencia mínima
• Transmisión continua sin interrupciones de inicio/parada entre turnos

Integración de Llamada a Funciones

Cómo Funciona

El modelo de IA puede invocar funciones locales de Python a mitad de conversación cuando se necesitan cálculos específicos del dominio:

1. El usuario pronuncia una solicitud (ej., "Me salté el almuerzo hoy")
2. El modelo de IA transcribe y comprende la intención
3. El modelo determina que se necesita una llamada a una función y envía una solicitud estructurada
4. El backend extrae el nombre de la función, los argumentos y el ID de llamada
5. La función local ejecuta el cálculo de dominio
6. El resultado se envía de vuelta al modelo como una respuesta estructurada
7. El modelo genera una respuesta de voz en lenguaje natural que incorpora el resultado

Funciones de Dominio

El sistema admite la llamada a funciones centradas en la nutrición para escenarios como:

• Comidas Perdidas — Redistribuye los macronutrientes perdidos entre las comidas restantes
• Comida No Planificada — Ajusta las próximas comidas para compensar la ingesta inesperada
• Sustituciones de Comidas — Intercambia ingredientes manteniendo los objetivos de macros
• Seguimiento de Actividad — Estima el gasto calórico y ajusta el búfer nutricional

Cada función utiliza una base de datos de macros con perfiles nutricionales por alimento y realiza cálculos dinámicos con una ligera variación estocástica para respuestas de sensación natural.

Seguridad en la Ejecución

• La entrada del micrófono se pausa durante la ejecución de la función para evitar superposiciones
• Los marcos de audio pendientes se descartan para evitar un contexto obsoleto
• Las respuestas de error se devuelven de forma elegante si la ejecución de la función falla
• La transmisión normal se reanuda inmediatamente después de la finalización de la función

Arquitectura de Backend

Servidor WebSocket FastAPI

• Un único endpoint WebSocket para toda la comunicación con el cliente
• Gestión del ciclo de vida de la sesión (inicio, parada, comprobaciones de salud ping/pong)
• Una sesión activa a la vez con bloqueo de sesión
• Middleware CORS para entornos de desarrollo
• Endpoint de comprobación de salud para monitorización

Gestión de Sesiones

• Las sesiones se crean al conectar el cliente con selección de modo (solo audio, cámara o pantalla)
• Las tareas asíncronas en segundo plano gestionan la captura, el procesamiento y la reproducción de audio de forma concurrente
• Desconexión elegante con limpieza de recursos
• Validación de clave API y propagación de errores

Entrada Multimodal (Opcional)

Más allá de la voz, el sistema admite contexto visual opcional:

• Modo Cámara — Transmite fotogramas de la webcam (1fps) para contexto visual en las conversaciones
• Modo Pantalla — Captura el contenido de la pantalla para discutir información mostrada
• Las imágenes se redimensionan y comprimen antes de la transmisión
• El contexto visual mejora la capacidad de la IA para proporcionar respuestas relevantes

Interfaz de Frontend

• Control de Sesión — Iniciar/detener la escucha con indicadores de estado claros
• Visualización de Estado — Conexión en tiempo real y estado de la sesión (inactivo, conectando, activo, error)
• Soporte de Tema — Modo claro/oscuro con persistencia
• Guía Interactiva — Demostración paso a paso para usuarios nuevos
• Gestión de WebSocket — Lógica de reconexión automática

Configuración del Modelo de IA

• Modalidad de audio nativa (sin pipeline STT/TTS separado)
• Selección de voz configurable entre múltiples voces preestablecidas
• Instrucciones del sistema que definen la personalidad del asistente, el estilo de respuesta y el manejo del idioma
• Definiciones de herramientas para todas las funciones disponibles con esquemas de parámetros
• Detección automática de idioma con respuesta en el mismo idioma

Características Clave

1. Latencia Inferior al Segundo — El modelo de audio nativo elimina la sobrecarga del pipeline STT/TTS
2. Audio Bidireccional en Tiempo Real — Transmisión continua con < 50ms por fragmento
3. Llamada a Funciones — Cálculos específicos del dominio ejecutados a mitad de conversación
4. Interrupción Natural — Los usuarios pueden interrumpir al asistente de forma natural sin comandos especiales
5. Multilenguaje — Detección automática de idioma con respuestas en el mismo idioma
6. Entrada Multimodal — Contexto opcional de cámara y pantalla para comprensión visual
7. Gestión de Sesiones — Control del ciclo de vida de la sesión con bloqueo y limpieza de recursos
8. Cálculos de Macros — Ajustes nutricionales dinámicos con perfiles de macros por alimento
9. Recuperación de Errores — Manejo elegante de fallos de funciones e interrupciones de red
10. Extensible — Nuevas funciones añadidas mediante la definición de esquema y manejador — sin cambios de arquitectura