Compartir a través de

Azure VoiceLive client library for JavaScript - versión 1.0.0-beta.1

Azure VoiceLive es un servicio gestionado que permite interacciones de voz a voz de baja latencia y alta calidad para agentes de voz. El servicio consolida el reconocimiento de voz, la IA generativa y las funcionalidades de texto a voz en una única interfaz unificada, proporcionando una solución integral para crear experiencias fluidas impulsadas por voz.

Use la biblioteca cliente para:

  • Crear asistentes de voz en tiempo real y agentes conversacionales
  • Construye aplicaciones de voz a voz con latencia mínima
  • Integra funciones conversacionales avanzadas como supresión de ruido y cancelación de eco
  • Aprovecha múltiples modelos de IA (GPT-4o, GPT-4o-mini, Phi) para diferentes casos de uso
  • Implementar la llamada a funciones e integración de herramientas para respuestas dinámicas
  • Crea interacciones de voz habilitadas por avatar con componentes visuales

Nota: Este paquete es compatible tanto con navegadores como Node.js entornos de la historia. Las conexiones WebSocket se utilizan para la comunicación en tiempo real.

Cómo empezar

Entornos admitidos actualmente

Prerrequisitos

Instalar el paquete

Instala la biblioteca cliente de Azure VoiceLive usando npm:

npm install @azure/ai-voicelive

Instala la biblioteca de identidad

Los clientes VoiceLive se autentican usando la Azure Identity Library. Instálala también:

npm install @azure/identity

Configurar TypeScript

Los usuarios de TypeScript necesitan tener instaladas definiciones de tipos de nodo:

npm install @types/node

También necesitas activar compilerOptions.allowSyntheticDefaultImports en tu tsconfig.json. Ten en cuenta que si tienes activado compilerOptions.esModuleInterop, allowSyntheticDefaultImports está activado por defecto.

Paquete de JavaScript

Para usar esta biblioteca cliente en el explorador, primero debe usar un agrupador. Para obtener más información sobre cómo hacerlo, consulte nuestra documentación de agrupación de .

Conceptos clave

VoiceLiveClient

La interfaz principal para establecer conexiones al servicio Azure VoiceLive. Utiliza este cliente para autenticar y crear sesiones para interacciones de voz en tiempo real.

VoiceLiveSession

Representa una conexión activa WebSocket para comunicación de voz en tiempo real. Esta clase gestiona la comunicación bidireccional, permitiéndote enviar entrada de audio y recibir salida de audio, transcripciones de texto y otros eventos en tiempo real.

Configuración de sesión

El servicio utiliza la configuración de sesión para controlar varios aspectos de la interacción de voz:

  • Detección por turno: Configura cómo detecta el servicio cuándo los usuarios empiezan y dejan de hablar
  • Procesamiento de audio: Activar la supresión de ruido y la cancelación de eco
  • Selección de voz: Elige entre voces estándar de Azure, voces en alta definición o voces personalizadas
  • Selección de modelos: Selecciona el modelo de IA (variantes GPT-4o, GPT-4o-mini, Phi) que mejor se adapte a tus necesidades

Modelos y capacidades

La API de VoiceLive soporta múltiples modelos de IA con diferentes capacidades:

Modelo Description Caso de uso
gpt-4o-realtime-preview GPT-4o con procesamiento de audio en tiempo real IA conversacional de alta calidad
gpt-4o-mini-realtime-preview Variante ligera GPT-4o Interacciones rápidas y eficientes
phi4-mm-realtime Modelo Phi con soporte multimodal Aplicaciones de voz rentables

Mejoras conversacionales

La API de VoiceLive ofrece mejoras específicas de Azure:

  • Azure Semantic VAD: Detección avanzada de actividad de voz que elimina palabras de relleno
  • Supresión de ruido: Reduce el ruido de fondo ambiental
  • Cancelación de eco: Elimina el eco de la voz del modelo
  • Detección al final del turno: Permite pausas naturales sin interrupciones prematuras

Autenticar con Azure Active Directory

El servicio VoiceLive depende de Azure Active Directory para autenticar las solicitudes en sus APIs. El paquete @azure/identity proporciona una variedad de tipos de credenciales que la aplicación puede usar para hacerlo. El LÉAME para @azure/identity proporciona más detalles y ejemplos para empezar.

Para interactuar con el servicio Azure VoiceLive, necesitas crear una instancia de la VoiceLiveClient clase, un endpoint de servicio y un objeto de credenciales. Los ejemplos mostrados en este documento utilizan un objeto de credencial llamado DefaultAzureCredential, que es apropiado para la mayoría de los escenarios, incluidos entornos de desarrollo y producción local. Recomendamos utilizar una identidad gestionada para la autenticación en entornos de producción.

Puedes encontrar más información sobre las diferentes formas de autenticación y sus tipos de credenciales correspondientes en la documentación de Azure Identity.

Aquí tienes un ejemplo rápido. Primero, importar DefaultAzureCredential y VoiceLiveClient:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();

// Build the URL to reach your AI Foundry resource
const endpoint = "https://your-resource.cognitiveservices.azure.com";

// Create the VoiceLive client
const client = new VoiceLiveClient(endpoint, credential);

Autenticación con clave API

Para escenarios de desarrollo, también puedes autenticarte usando una clave API:

import { AzureKeyCredential } from "@azure/core-auth";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const endpoint = "https://your-resource.cognitiveservices.azure.com";
const credential = new AzureKeyCredential("your-api-key");

const client = new VoiceLiveClient(endpoint, credential);

Examples

Las siguientes secciones proporcionan fragmentos de código que cubren algunas de las tareas comunes que utilizan Azure VoiceLive. Los escenarios aquí cubiertos consisten en:

Creación de un asistente de voz básico

Este ejemplo muestra cómo crear un asistente de voz sencillo que pueda gestionar interacciones de voz a voz:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";

// Create the client
const client = new VoiceLiveClient(endpoint, credential);

// Create and connect a session
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Configure session for voice conversation
await session.updateSession({
  modalities: ["text", "audio"],
  instructions: "You are a helpful AI assistant. Respond naturally and conversationally.",
  voice: {
    type: "azure-standard",
    name: "en-US-AvaNeural",
  },
  turnDetection: {
    type: "server_vad",
    threshold: 0.5,
    prefixPaddingMs: 300,
    silenceDurationMs: 500,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

Configuración de opciones de sesión

Puedes personalizar varios aspectos de la interacción de voz:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-realtime-preview");

// Advanced session configuration
await session.updateSession({
  modalities: ["audio", "text"],
  instructions: "You are a customer service representative. Be helpful and professional.",
  voice: {
    type: "azure-custom",
    name: "your-custom-voice-name",
    endpointId: "your-custom-voice-endpoint",
  },
  turnDetection: {
    type: "server_vad",
    threshold: 0.6,
    prefixPaddingMs: 200,
    silenceDurationMs: 300,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

Gestión de eventos en tiempo real

El cliente VoiceLive proporciona comunicación orientada a eventos para interacciones en tiempo real:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Set up event handlers using subscription pattern
const subscription = session.subscribe({
  onResponseAudioDelta: async (event, context) => {
    // Handle incoming audio chunks
    const audioData = event.delta;
    // Play audio using Web Audio API or other audio system
    playAudioChunk(audioData);
  },

  onResponseTextDelta: async (event, context) => {
    // Handle incoming text deltas
    console.log("Assistant:", event.delta);
  },

  onInputAudioTranscriptionCompleted: async (event, context) => {
    // Handle user speech transcription
    console.log("User said:", event.transcript);
  },
});

// Send audio data from microphone
function sendAudioChunk(audioBuffer: ArrayBuffer) {
  session.sendAudio(audioBuffer);
}

Implementación de la llamada a funciones

Activa tu asistente de voz para llamar a funciones y herramientas externas:

import { DefaultAzureCredential } from "@azure/identity";
import { VoiceLiveClient } from "@azure/ai-voicelive";

const credential = new DefaultAzureCredential();
const endpoint = "https://your-resource.cognitiveservices.azure.com";
const client = new VoiceLiveClient(endpoint, credential);
const session = await client.startSession("gpt-4o-mini-realtime-preview");

// Define available functions
const tools = [
  {
    type: "function",
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state or country",
        },
      },
      required: ["location"],
    },
  },
];

// Configure session with tools
await session.updateSession({
  modalities: ["audio", "text"],
  instructions:
    "You can help users with weather information. Use the get_weather function when needed.",
  tools: tools,
  toolChoice: "auto",
});

// Handle function calls
const subscription = session.subscribe({
  onResponseFunctionCallArgumentsDone: async (event, context) => {
    if (event.name === "get_weather") {
      const args = JSON.parse(event.arguments);
      const weatherData = await getWeatherData(args.location);

      // Send function result back
      await session.addConversationItem({
        type: "function_call_output",
        callId: event.callId,
        output: JSON.stringify(weatherData),
      });

      // Request response generation
      await session.sendEvent({
        type: "response.create",
      });
    }
  },
});

Solución de problemas

Errores y excepciones habituales

Errores de autenticación: Si recibes errores de autenticación, verifica que:

  • Tu recurso Azure AI Foundry está correctamente configurado
  • Tu clave o credencial de API tiene los permisos necesarios
  • La URL del endpoint es correcta y accesible

Problemas de conexión con WebSocket: VoiceLive utiliza conexiones WebSocket. Asegúrate de que:

  • Tu red permite conexiones WebSocket
  • Las reglas de cortafuegos permiten conexiones a *.cognitiveservices.azure.com
  • Las políticas del navegador permiten el acceso a WebSocket y micrófono (para uso en navegador)

Problemas de audio: Para problemas relacionados con el audio:

  • Verifica los permisos del micrófono en el navegador
  • Comprueba que los formatos de audio (PCM16, PCM24) estén soportados
  • Asegúrate de configurar correctamente el contexto de audio para la reproducción

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de mensajes y respuestas WebSocket, se asigna la AZURE_LOG_LEVEL variable de entorno a info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.

Pasos siguientes

Puedes encontrar más ejemplos de código a través de los siguientes enlaces:

Contributing

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.

  • Last updated on