Freigeben über

Azure VoiceLive Client-Bibliothek für JavaScript - Version 1.0.0-beta.1

Azure VoiceLive ist ein verwalteter Service, der Sprech-zu-Sprach-Interaktionen mit niedriger Latenz und hoher Qualität für Sprachagenten ermöglicht. Der Dienst vereint Spracherkennung, generative KI und Text-zu-Sprache-Funktionen in einer einzigen, einheitlichen Schnittstelle und bietet eine End-to-End-Lösung für nahtlose sprachgesteuerte Erlebnisse.

Verwenden Sie die Clientbibliothek für Folgendes:

  • Erstelle Echtzeit-Sprachassistenten und Konversationsagenten
  • Erstellen Sie Sprach-zu-Sprache-Anwendungen mit minimaler Latenz
  • Integrieren Sie fortschrittliche Konversationsfunktionen wie Lärmunterdrückung und Echounterdrückung
  • Nutzen Sie mehrere KI-Modelle (GPT-4o, GPT-4o-mini, Phi) für unterschiedliche Anwendungsfälle
  • Implementierung von Funktionsaufrufen und Toolintegration für dynamische Antworten
  • Erstellen Sie avatargesteuerte Sprachinteraktionen mit visuellen Komponenten

Hinweis: Dieses Paket unterstützt sowohl Browser- als auch Node.js-Umgebungen. WebSocket-Verbindungen werden für die Echtzeitkommunikation verwendet.

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

Installiere das Paket

Installation der Azure VoiceLive Client-Bibliothek mit npm:

npm install @azure/ai-voicelive

Installiere die Identitätsbibliothek

VoiceLive-Clients authentifizieren sich über die Azure Identity Library. Installieren Sie es auch:

npm install @azure/identity

TypeScript konfigurieren

TypeScript-Nutzer müssen Node-Typdefinitionen installiert haben:

npm install @types/node

Du musst auch in deinem tsconfig.jsonaktivieren compilerOptions.allowSyntheticDefaultImports . Beachte, dass wenn du aktiviert compilerOptions.esModuleInterophast, allowSyntheticDefaultImports standardmäßig aktiviert ist.

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.

Wichtige Begriffe

VoiceLiveClient

Die primäre Schnittstelle zum Herstellen von Verbindungen zum Azure VoiceLive-Dienst. Nutzen Sie diesen Client zur Authentifizierung und Erstellung von Sitzungen für Echtzeit-Sprachinteraktionen.

VoiceLiveSession

Stellt eine aktive WebSocket-Verbindung für Echtzeit-Sprachkommunikation dar. Dieser Kurs behandelt bidirektionale Kommunikation und ermöglicht es Ihnen, Audioein- und Audioausgaben, Texttranskriptionen und andere Ereignisse in Echtzeit zu senden und zu empfangen.

Sitzungskonfiguration

Der Dienst nutzt die Sitzungskonfiguration, um verschiedene Aspekte der Sprachinteraktion zu steuern:

  • Zugerkennung: Konfigurieren Sie, wie der Dienst erkennt, wann Nutzer anfangen und aufhören zu sprechen
  • Audioverarbeitung: Aktivieren Sie Rauschunterdrückung und Echounterdrückung
  • Sprachauswahl: Wählen Sie aus Standard-Azure-Stimmen, hochauflösenden Stimmen oder benutzerdefinierten Stimmen
  • Modellauswahl: Wählen Sie das KI-Modell (GPT-4o, GPT-4o-mini, Phi-Varianten), das am besten zu Ihren Bedürfnissen passt

Modelle und Fähigkeiten

Die VoiceLive API unterstützt mehrere KI-Modelle mit unterschiedlichen Funktionen:

Model Description Anwendungsfall
gpt-4o-realtime-preview GPT-4o mit Echtzeit-Audioverarbeitung Hochwertige konversationelle KI
gpt-4o-mini-realtime-preview Leichte GPT-4o-Variante Schnelle, effiziente Interaktionen
phi4-mm-realtime Phi-Modell mit multimodaler Unterstützung Kostengünstige Sprachanwendungen

Konversationsverbesserungen

Die VoiceLive API bietet Azure-spezifische Verbesserungen:

  • Azure Semantic VAD: Fortschrittliche Sprachaktivitätserkennung, die Füllwörter entfernt
  • Lärmunterdrückung: Reduziert Umgebungsgeräusche
  • Echounterdrückung: Entfernt das Echo aus der eigenen Stimme des Modells
  • End-of-Zug-Erkennung: Ermöglicht natürliche Pausen ohne vorzeitige Unterbrechung

Authentifizierung mit Azure Active Directory

Der VoiceLive-Dienst verlässt sich auf Azure Active Directory, um Anfragen an seine APIs zu authentifizieren. Das @azure/identity-Paket bietet eine Vielzahl von Anmeldeinformationstypen, die Ihre Anwendung verwenden kann, um dies zu tun. Die README für @azure/identity enthält weitere Details und Beispiele für die ersten Schritte.

Um mit dem Azure VoiceLive-Dienst zu interagieren, müssen Sie eine Instanz der Klasse VoiceLiveClient , einen Service-Endpunkt und ein Credential-Objekt erstellen. Die in diesem Dokument gezeigten Beispiele verwenden ein Zugangsdatenobjekt namens DefaultAzureCredential, das für die meisten Szenarien, einschließlich lokaler Entwicklungs- und Produktionsumgebungen, geeignet ist. Wir empfehlen, eine verwaltete Identität für die Authentifizierung in Produktionsumgebungen zu verwenden.

Weitere Informationen zu verschiedenen Authentifizierungsmethoden und deren entsprechenden Zugangsdaten finden Sie in der Azure Identity-Dokumentation.

Hier ist ein schnelles Beispiel. Zuerst importieren DefaultAzureCredential Sie und 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);

Authentifizierung mit API-Schlüssel

Für Entwicklungsszenarien kann man sich auch mit einem API-Schlüssel authentifizieren:

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

Die folgenden Abschnitte enthalten Codeschnipsel, die einige der gängigen Aufgaben mit Azure VoiceLive abdecken. Die hier behandelten Szenarien sind:

Erstellung eines einfachen Sprachassistenten

Dieses Beispiel zeigt, wie man einen einfachen Sprachassistenten erstellt, der Sprach-zu-Sprach-Interaktionen bewältigen kann:

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

Konfiguration von Sitzungsoptionen

Du kannst verschiedene Aspekte der Sprachinteraktion anpassen:

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

Umgang mit Echtzeitereignissen

Der VoiceLive-Client bietet ereignisgesteuerte Kommunikation für Echtzeit-Interaktionen:

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

Implementierung von Funktionsaufrufen

Ermöglichen Sie Ihrem Sprachassistenten, externe Funktionen und Werkzeuge aufzurufen:

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

Problembehandlung

Allgemeine Fehler und Ausnahmen

Authentifizierungsfehler: Wenn Sie Authentifizierungsfehler erhalten, überprüfen Sie, dass:

  • Ihre Azure AI Foundry-Ressource ist korrekt konfiguriert
  • Ihr API-Schlüssel oder Ihre Zugangsdaten verfügen über die notwendigen Berechtigungen
  • Die Endpunkt-URL ist korrekt und zugänglich

WebSocket-Verbindungsprobleme: VoiceLive verwendet WebSocket-Verbindungen. Stellen Sie Folgendes sicher:

  • Dein Netzwerk erlaubt WebSocket-Verbindungen
  • Firewall-Regeln erlauben Verbindungen zu *.cognitiveservices.azure.com
  • Browser-Richtlinien erlauben WebSocket- und Mikrofonzugriff (für Browsernutzung)

Audioprobleme: Für audiobezogene Probleme:

  • Überprüfen Sie die Mikrofonberechtigungen im Browser
  • Überprüfen Sie, ob Audioformate (PCM16, PCM24) unterstützt werden
  • Stellen Sie die richtige Audiokontext-Einstellung für die Wiedergabe sicher.

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll der WebSocket-Nachrichten und -Antworten zu sehen, setzen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf info. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Weitere Codebeispiele finden Sie über die folgenden Links:

Contributing

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

  • Last updated on