Condividi tramite

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

Azure VoiceLive è un servizio gestito che consente interazioni speech-to-speech di alta qualità e bassa latenza per gli agenti vocali. Il servizio consolida il riconoscimento vocale, l'intelligenza artificiale generativa e le funzionalità di sintesi vocali in un'unica interfaccia unificata, offrendo una soluzione end-to-end per creare esperienze vocali fluide.

Usare la libreria client per:

  • Crea assistenti vocali in tempo reale e agenti conversazionali
  • Costruisci applicazioni di voce vocale con latenza minima
  • Integrare funzionalità conversazionali avanzate come la soppressione del rumore e la cancellazione dell'eco
  • Sfrutta più modelli di IA (GPT-4o, GPT-4o-mini, Phi) per diversi casi d'uso
  • Implementare chiamate di funzioni e integrazione di strumenti per risposte dinamiche
  • Crea interazioni vocali abilitate all'avatar con componenti visivi

Nota: Questo pacchetto supporta sia ambienti browser che Node.js. Le connessioni WebSocket sono utilizzate per la comunicazione in tempo reale.

Come iniziare

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto

Installa la libreria client Azure VoiceLive usando npm:

npm install @azure/ai-voicelive

Installa la libreria di identità

I client VoiceLive si autenticano utilizzando la Azure Identity Library. Installalo anche:

npm install @azure/identity

Configura TypeScript

Gli utenti di TypeScript devono avere installate definizioni di tipi di nodo:

npm install @types/node

Devi anche abilitare compilerOptions.allowSyntheticDefaultImports nel tuo tsconfig.json. Nota che se hai abilitato compilerOptions.esModuleInterop, allowSyntheticDefaultImports è abilitato di default.

Pacchetto JavaScript

Per usare questa libreria client nel browser, è prima necessario usare un bundler. Per informazioni dettagliate su come eseguire questa operazione, vedere la documentazione di creazione di bundle .

Concetti chiave

VoiceLiveClient

L'interfaccia principale per stabilire connessioni al servizio Azure VoiceLive. Usa questo client per autenticare e creare sessioni per interazioni vocali in tempo reale.

VoiceLiveSession

Rappresenta una connessione attiva WebSocket per la comunicazione vocale in tempo reale. Questo corso gestisce la comunicazione bidirezionale, permettendoti di inviare input audio e ricevere uscite audio, trascrizioni di testo e altri eventi in tempo reale.

Configurazione sessione

Il servizio utilizza la configurazione della sessione per controllare vari aspetti dell'interazione vocale:

  • Rilevamento delle Turne: Configura come il servizio rileva quando gli utenti iniziano e smettono di parlare
  • Elaborazione audio: Abilita la soppressione del rumore e la cancellazione dell'eco
  • Selezione delle voci: scegli tra voci Azure standard, voci in alta definizione o voci personalizzate
  • Selezione dei modelli: Seleziona il modello AI (varianti GPT-4o, GPT-4o-mini, Phi) che meglio si adatta alle tue esigenze

Modelli e Capacità

L'API VoiceLive supporta molteplici modelli di intelligenza artificiale con capacità differenti:

Model Description Caso d'uso
gpt-4o-realtime-preview GPT-4o con elaborazione audio in tempo reale Intelligenza artificiale conversazionale di alta qualità
gpt-4o-mini-realtime-preview Variante leggera GPT-4o Interazioni rapide ed efficienti
phi4-mm-realtime Modello Phi con supporto multimodale Applicazioni vocali economiche

Miglioramenti delle conversazioni

L'API VoiceLive offre miglioramenti specifici per Azure:

  • Azure Semantic VAD: Rilevamento avanzato dell'attività vocale che rimuove parole di riempitivo
  • Soppressione del rumore: Riduce il rumore di fondo ambientale
  • Cancellazione dell'eco: Rimuove l'eco dalla voce del modello
  • Rilevamento di fine turno: Permette pause naturali senza interruzioni premature

Autenticare con Azure Active Directory

Il servizio VoiceLive si affida ad Azure Active Directory per autenticare le richieste alle sue API. Il pacchetto @azure/identity offre diversi tipi di credenziali che l'applicazione può usare per eseguire questa operazione. Il file LEGGIMI per @azure/identity fornisce altri dettagli ed esempi per iniziare.

Per interagire con il servizio Azure VoiceLive, è necessario creare un'istanza della VoiceLiveClient classe, un endpoint di servizio e un oggetto credential. Gli esempi mostrati in questo documento utilizzano un oggetto credenziale chiamato DefaultAzureCredential, appropriato per la maggior parte degli scenari, inclusi ambienti di sviluppo e produzione locali. Raccomandiamo di utilizzare un'identità gestita per l'autenticazione negli ambienti di produzione.

Puoi trovare ulteriori informazioni sui diversi modi di autenticazione e sui relativi tipi di credenziali nella documentazione Azure Identity.

Ecco un esempio veloce. Innanzitutto, importare DefaultAzureCredential e 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);

Autenticazione con API Key

Per scenari di sviluppo, puoi anche autenticarti usando una chiave 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);

Esempi

Le sezioni seguenti forniscono estratti di codice che coprono alcune delle attività comuni che utilizzano Azure VoiceLive. Gli scenari trattati qui consistono in:

Creare un assistente vocale di base

Questo esempio mostra come creare un semplice assistente vocale in grado di gestire interazioni vocali:

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

Configurazione delle opzioni di sessione

Puoi personalizzare vari aspetti dell'interazione 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",
});

Gestione degli eventi in tempo reale

Il client VoiceLive fornisce comunicazione basata su eventi per interazioni in tempo reale:

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

Implementazione della chiamata di funzione

Abilita il tuo assistente vocale per chiamare funzioni e strumenti esterni:

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

Risoluzione dei problemi

Errori ed eccezioni comuni

Errori di autenticazione: Se ricevi errori di autenticazione, verifica che:

  • La tua risorsa Azure AI Foundry è configurata correttamente
  • La tua chiave API o credenziale ha i permessi necessari
  • L'URL dell'endpoint è corretto e accessibile

Problemi di connessione WebSocket: VoiceLive utilizza connessioni WebSocket. Assicurarsi che:

  • La tua rete consente connessioni WebSocket
  • Le regole firewall permettono connessioni a *.cognitiveservices.azure.com
  • Le politiche del browser consentono l'accesso a WebSocket e microfono (per l'uso del browser)

Problemi audio: Per problemi audio:

  • Verifica i permessi del microfono nel browser
  • Controlla che i formati audio (PCM16, PCM24) siano supportati
  • Assicurati di impostare correttamente il contesto audio per la riproduzione

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per vedere un registro dei messaggi e delle risposte WebSocket, imposta la AZURE_LOG_LEVEL variabile ambiente su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, vedere la documentazione del pacchetto @azure/logger.

Passaggi successivi

Puoi trovare altri esempi di codice tramite i seguenti link:

Contributing

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

  • Last updated on