CubeLabs

1. Introducción a los Agentes de Voz

Los agentes de voz son sistemas capaces de mantener conversaciones habladas con humanos. A diferencia de los chatbots tradicionales, procesan audio directamente: escuchan, entienden, razonan y responden con voz. Ejemplos conocidos incluyen Alexa, Siri y Google Assistant, pero hasta hace poco construir uno propio requería APIs cerradas y costosas.

El proyecto speech-to-speech de Hugging Face cambia eso: ofrece un pipeline open-source, modular y extensible que puedes ejecutar en tu propio hardware. Está compuesto por cuatro etapas encadenadas:

El pipeline se usa en producción dando voz a miles de robots Reachy Mini en Hugging Face. En este curso aprenderás a montarlo, configurarlo y desplegarlo paso a paso.

2. Arquitectura del Pipeline Speech-to-Speech

El pipeline es una cascada de cuatro componentes que se ejecutan en hilos independientes comunicados por colas. Cada componente es completamente intercambiable mediante flags de línea de comandos.

Flujo de datos

[Micrófono] → [VAD] → [STT] → [LLM] → [TTS] → [Altavoz]
                 ↑                           ↓
            Buffer de audio           Buffer de audio

Detalle del flujo:

1. VAD recibe chunks de audio en tiempo real y detecta los límites de las intervenciones del usuario (cuándo empieza y termina de hablar).
2. STT toma el segmento de audio completo y lo transcribe a texto, con soporte para transcripciones parciales en vivo.
3. LLM recibe el texto transcrito y genera una respuesta, que puede incluir llamadas a herramientas (tool calls).
4. TTS sintetiza la respuesta textual en audio y lo envía al cliente.

Modos de ejecución

3. Instalación y Primeros Pasos

El framework requiere Python 3.10+ y se instala con un solo comando pip. Vamos a ponerlo en marcha:

Instalación básica

pip install speech-to-speech

Esto instala el pipeline con los backends por defecto:

• Parakeet TDT para STT
• OpenAI-compatible API para el LLM
• Qwen3-TTS para salida de voz (backend GGML en Linux, MLX en Apple Silicon)
• Soporte para modo local y servidor realtime

Primer arranque (con API key de OpenAI)

export OPENAI_API_KEY="sk-..."
speech-to-speech

Esto inicia un servidor Realtime en ws://localhost:8765/v1/realtime usando Parakeet TDT para STT local, un LLM compatible con OpenAI y Qwen3-TTS para la salida de voz.

Hablar con el pipeline

Desde una segunda terminal, ejecuta el cliente integrado:

python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765

Instalación desde fuente

git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync

4. Voice Activity Detection (VAD) con Silero

El VAD es el primer componente del pipeline. Su trabajo es detectar cuándo una persona está hablando, determinar los límites de cada intervención y gestionar el turn-taking (quién habla en cada momento).

Silero VAD v5

El VAD por defecto es Silero VAD v5, un modelo pre-entrenado de alta calidad que funciona en CPU y GPU. Procesa el audio en chunks y devuelve una probabilidad de actividad de voz para cada uno.

Parámetros clave del VAD

Ajuste fino del VAD

speech-to-speech \
    --thresh 0.5 \
    --min_speech_ms 500 \
    --min_silence_ms 100 \
    --mode realtime

5. Speech-to-Text (STT): Parakeet, Whisper y alternativas

El STT convierte el audio segmentado por el VAD en texto. Es el puente entre el mundo del audio y el del lenguaje escrito.

Backends disponibles

Usar Whisper como STT

speech-to-speech \
    --stt whisper \
    --stt_model_name openai/whisper-medium \
    --mode realtime

Transcripción en vivo

El pipeline soporta transcripciones parciales que se envían al cliente mientras el usuario sigue hablando. Se activa con el flag:

--enable_live_transcription

6. Modelos de Lenguaje (LLM) para Respuestas

El LLM es el cerebro del pipeline: recibe el texto transcrito y genera una respuesta natural, incluyendo llamadas a herramientas si es necesario. Es el componente más intensivo en cómputo.

Backends de LLM

Ejemplo: LLM local con llama.cpp

Primero, sirve el modelo con llama.cpp:

llama-server -hf ggml-org/gemma-4-E4B-it-GGUF \
    -np 2 -c 65536 -fa on --swa-full

Luego, conecta el pipeline a ese servidor:

speech-to-speech \
    --model_name "ggml-org/gemma-4-E4B-it-GGUF" \
    --responses_api_base_url "http://127.0.0.1:8080/v1" \
    --responses_api_api_key "" \
    --responses_api_stream

Ejemplo: API de proveedor

speech-to-speech \
    --mode local \
    --llm_backend responses-api \
    --model_name "Qwen/Qwen3.5-9B:together" \
    --responses_api_base_url "https://router.huggingface.co/v1" \
    --responses_api_api_key "$HF_TOKEN" \
    --responses_api_stream \
    --enable_live_transcription

7. Text-to-Speech (TTS) con Qwen3-TTS y alternativas

El TTS convierte la respuesta textual del LLM en audio sintetizado. El pipeline ofrece múltiples backends de TTS, cada uno con diferentes perfiles de calidad, velocidad y requisitos de hardware.

Backends de TTS disponibles

Usar Qwen3-TTS con parámetros personalizados

speech-to-speech \
    --tts qwen3 \
    --qwen3_tts_model_name Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
    --qwen3_tts_speaker Aiden \
    --qwen3_tts_language auto \
    --qwen3_tts_backend ggml \
    --qwen3_tts_non_streaming_mode True

Usar Kokoro-82M

pip install "speech-to-speech[kokoro]"
speech-to-speech --tts kokoro

Usar Pocket TTS con clonación de voz

speech-to-speech \
    --tts pocket \
    --pocket_tts_voice jean \
    --pocket_tts_device cpu

8. Modo Realtime Server con API OpenAI

El modo realtime expone el pipeline como un servidor WebSocket que implementa el protocolo OpenAI Realtime. Esto significa que cualquier cliente que hable ese protocolo — incluyendo el SDK oficial de OpenAI — puede conectarse a tu servidor self-hosted.

Arrancar el servidor Realtime

export OPENAI_API_KEY="sk-..."
speech-to-speech --mode realtime

Esto expone el endpoint ws://localhost:8765/v1/realtime.

Conectar con el SDK de OpenAI

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8765/v1",
    websocket_base_url="ws://localhost:8765/v1",
    api_key="not-needed",
)

with client.realtime.connect(model="local") as conn:
    conn.send({
        "type": "session.update",
        "session": {
            "type": "realtime",
            "instructions": "Eres un asistente de voz amigable y conciso."
        }
    })

    for event in conn:
        print(event.type)

Eventos del protocolo Realtime

El servidor implementa los eventos principales del protocolo:

9. Modo Local y Conexión por Socket

El pipeline ofrece modos alternativos para diferentes escenarios de uso, desde una conversación directa en tu máquina hasta despliegues remotos con cliente ligero.

Modo Local: hablar directamente

Usa el micrófono y los altavoces de tu máquina para una conversación natural:

speech-to-speech --mode local

En Mac con Apple Silicon, usa la configuración optimizada:

speech-to-speech --local_mac_optimal_settings

Esto activa automáticamente:

• --device mps para usar MPS en todos los modelos
• Parakeet TDT para STT
• MLX LM como backend de LLM
• Qwen3-TTS con MLX a 6-bit
• Modo local

Modo WebSocket: cliente personalizado

speech-to-speech --mode websocket --ws_host 0.0.0.0 --ws_port 8765

Los clientes envían audio PCM raw a 16 kHz, int16, mono y reciben audio generado.

Modo Socket: servidor remoto

En el servidor:

speech-to-speech --mode socket --recv_host 0.0.0.0 --send_host 0.0.0.0

En el cliente:

python scripts/listen_and_play.py --host <IP-del-servidor>

10. Despliegue con Docker y Casos de Uso Reales

El pipeline incluye Docker Compose para despliegues reproducibles. Además, se usa en producción a gran escala: es el backend conversacional de miles de robots Reachy Mini de Hugging Face.

Despliegue con Docker

Instala el NVIDIA Container Toolkit y ejecuta:

docker compose up

El compose inicia:

• Un servidor llama.cpp con Gemma 4
• El servidor TCP socket del pipeline
• Puertos expuestos: 8080, 12345, 12346

Casos de uso reales

Ejemplo completo: stack 100% local

# Terminal 1: llama.cpp con Gemma 4
llama-server -hf ggml-org/gemma-4-E4B-it-GGUF \
    -np 2 -c 65536 -fa on --swa-full

# Terminal 2: Pipeline con Gemma 4 local
speech-to-speech \
    --mode realtime \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --model_name "ggml-org/gemma-4-E4B-it-GGUF" \
    --responses_api_base_url "http://127.0.0.1:8080/v1" \
    --responses_api_api_key "" \
    --responses_api_stream \
    --enable_live_transcription

# Terminal 3: Cliente Python
python scripts/listen_and_play_realtime.py \
    --host 127.0.0.1 --port 8765