Partager via

Azure VoiceLive client library for JavaScript - version 1.0.0-beta.1

Azure VoiceLive est un service géré qui permet des interactions de parole-à-parole de haute qualité et à faible latence pour les agents vocaux. Le service regroupe la reconnaissance vocale, l’IA générative et les fonctionnalités de synthèse vocale en une interface unifiée, offrant une solution de bout en bout pour créer des expériences vocales fluides.

Utilisez la bibliothèque cliente pour :

  • Créer des assistants vocaux en temps réel et des agents conversationnels
  • Construisez des applications de reconnaissance vocale avec une latence minimale
  • Intégrer des fonctionnalités conversationnelles avancées comme la suppression du bruit et l’annulation d’écho
  • Exploitez plusieurs modèles d’IA (GPT-4o, GPT-4o-mini, Phi) pour différents cas d’utilisation
  • Implémenter l’appel de fonctions et l’intégration des outils pour des réponses dynamiques
  • Créer des interactions vocales activées par avatar avec des composants visuels

Note : Ce paquet prend en charge à la fois les environnements navigateur et Node.js. Les connexions WebSocket sont utilisées pour la communication en temps réel.

Mise en route

Environnements actuellement pris en charge

Prerequisites

Installer le package

Installez la bibliothèque client Azure VoiceLive en utilisant npm :

npm install @azure/ai-voicelive

Installer la bibliothèque d’identité

Les clients VoiceLive s’authentifient via la bibliothèque Azure Identity. Installez-le aussi :

npm install @azure/identity

Configurer TypeScript

Les utilisateurs de TypeScript doivent avoir installé des définitions de types de nœuds :

npm install @types/node

Vous devez aussi activer compilerOptions.allowSyntheticDefaultImports dans votre tsconfig.json. Notez que si vous avez activé compilerOptions.esModuleInterop, allowSyntheticDefaultImports est activé par défaut.

Offre groupée JavaScript

Pour utiliser cette bibliothèque cliente dans le navigateur, vous devez d’abord utiliser un bundler. Pour plus d’informations sur la procédure à suivre, reportez-vous à notre documentation de regroupement .

Concepts clés

VoiceLiveClient

L’interface principale pour établir des connexions avec le service Azure VoiceLive. Utilisez ce client pour authentifier et créer des sessions pour des interactions vocales en temps réel.

VoiceLiveSession

Représente une connexion WebSocket active pour la communication vocale en temps réel. Ce cours gère la communication bidirectionnelle, vous permettant d’envoyer des entrées audio et de recevoir des sorties audio, des transcriptions de texte et d’autres événements en temps réel.

Session Configuration

Le service utilise la configuration de session pour contrôler divers aspects de l’interaction vocale :

  • Détection de tournage : Configurez comment le service détecte quand les utilisateurs commencent ou cessent de parler
  • Traitement audio : Activez la suppression du bruit et l’annulation de l’écho
  • Sélection vocale : Choisissez parmi des voix Azure standard, des voix haute définition ou des voix personnalisées
  • Sélection des modèles : Sélectionnez le modèle IA (variantes GPT-40, GPT-4o-mini, Phi) qui correspond le mieux à vos besoins

Modèles et capacités

L’API VoiceLive prend en compte plusieurs modèles d’IA avec différentes capacités :

Model Descriptif Cas d’usage
gpt-4o-realtime-preview GPT-4o avec traitement audio en temps réel IA conversationnelle de haute qualité
gpt-4o-mini-realtime-preview Variante légère GPT-4o Interactions rapides et efficaces
phi4-mm-realtime Modèle Phi avec support multimodal Applications vocales économiques

Améliorations de conversation

L’API VoiceLive propose des améliorations spécifiques à Azure :

  • Azure Semantic VAD : Détection avancée de l’activité vocale qui supprime les mots de remplissage
  • Suppression du bruit : Réduction du bruit de fond environnemental
  • Annulation d’écho : Supprime l’écho de la voix du modèle
  • Détection de fin de tour : Permet des pauses naturelles sans interruption prématurée

Authentification avec Azure Active Directory

Le service VoiceLive s’appuie sur Azure Active Directory pour authentifier les requêtes vers ses API. Le package @azure/identity fournit divers types d’informations d’identification que votre application peut utiliser pour ce faire. Le README pour @azure/identity fournit plus de détails et d’exemples pour vous aider à démarrer.

Pour interagir avec le service Azure VoiceLive, vous devez créer une instance de la VoiceLiveClient classe, un point de terminaison de service et un objet de crédentiel. Les exemples présentés dans ce document utilisent un objet de certification nommé DefaultAzureCredential, qui convient à la plupart des scénarios, y compris les environnements de développement local et de production. Nous recommandons d’utiliser une identité gérée pour l’authentification dans les environnements de production.

Vous pouvez trouver plus d’informations sur les différentes méthodes d’authentification et leurs types de titres correspondants dans la documentation Azure Identity.

Voici un exemple rapide. Premièrement, importer DefaultAzureCredential et 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);

Authentification avec clé API

Pour les scénarios de développement, vous pouvez également authentifier en utilisant une clé 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

Les sections suivantes fournissent des extraits de code couvrant certaines des tâches courantes utilisant Azure VoiceLive. Les scénarios présentés ici sont les suivants :

Créer un assistant vocal basique

Cet exemple montre comment créer un assistant vocal simple capable de gérer les interactions de la voix à parole :

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",
});

Configuration des options de session

Vous pouvez personnaliser différents aspects de l’interaction vocale :

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",
});

Gestion des événements en temps réel

Le client VoiceLive fournit une communication pilotée par les événements pour des interactions en temps réel :

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);
}

Implémentation de l’appel de fonction

Activez votre assistant vocal pour appeler des fonctions et outils externes :

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",
      });
    }
  },
});

Résolution des problèmes

Erreurs et exceptions courantes

Erreurs d’authentification : Si vous recevez des erreurs d’authentification, vérifiez que :

  • Votre ressource Azure AI Foundry est correctement configurée
  • Votre clé API ou votre identifiant possède les autorisations nécessaires
  • L’URL du point de terminaison est correcte et accessible

Problèmes de connexion WebSocket : VoiceLive utilise des connexions WebSocket. Assurez-vous que :

  • Votre réseau permet des connexions WebSocket
  • Les règles de pare-feu permettent des connexions à *.cognitiveservices.azure.com
  • Les politiques du navigateur permettent l’accès au WebSocket et au microphone (pour l’utilisation du navigateur)

Problèmes audio : Pour des problèmes liés à l’audio :

  • Vérifier les permissions du microphone dans le navigateur
  • Vérifiez que les formats audio (PCM16, PCM24) sont pris en charge
  • Assurez-vous de bien configurer le contexte audio pour la lecture

Logging

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour voir un journal des messages et réponses WebSocket, fixez la variable d’environnement AZURE_LOG_LEVEL à info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Étapes suivantes

Vous pouvez trouver plus d’exemples de code via les liens suivants :

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

  • Last updated on