Udostępnij za pomocą

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

Azure VoiceLive to zarządzana usługa, która umożliwia niskoopóźnione, wysokiej jakości interakcje mowy z mową dla agentów głosowych. Usługa konsoliduje funkcje rozpoznawania mowy, generatywnej sztucznej inteligencji oraz zamiany tekstu na mowę w jeden, zunifikowany interfejs, oferując kompleksowe rozwiązanie do tworzenia płynnych doświadczeń głosowych.

Użyj biblioteki klienta, aby:

  • Stwórz asystentów głosowych i agentów konwersacyjnych w czasie rzeczywistym
  • Buduj aplikacje mowy na mowy z minimalnym opóźnieniem
  • Integruj zaawansowane funkcje konwersacyjne, takie jak tłumienie hałasu i redukcja echa
  • Wykorzystaj wiele modeli AI (GPT-4o, GPT-4o-mini, Phi) do różnych zastosowań
  • Implementacja wywoływania funkcji i integracji narzędzi dla dynamicznych odpowiedzi
  • Tworz interakcje głosowe z awatarem z komponentami wizualnymi

Uwaga: Ten pakiet obsługuje zarówno środowiska przeglądarkowe, jak i Node.js. Połączenia WebSocket są wykorzystywane do komunikacji w czasie rzeczywistym.

Wprowadzenie

Obecnie obsługiwane środowiska

  • Wersje LTS systemu Node.js
  • Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta Azure VoiceLive za pomocą npm:

npm install @azure/ai-voicelive

Zainstaluj bibliotekę tożsamości

Klienci VoiceLive uwierzytelniają się za pomocą biblioteki Azure Identity. Zainstaluj go również:

npm install @azure/identity

Configure TypeScript

Użytkownicy TypeScript muszą mieć zainstalowane definicje typów węzłów:

npm install @types/node

Musisz też włączyć compilerOptions.allowSyntheticDefaultImports swoje tsconfig.json. Zwróć uwagę, że jeśli masz włączone compilerOptions.esModuleInterop, domyślnie allowSyntheticDefaultImports jest włączone.

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

Najważniejsze pojęcia

VoiceLiveClient

Główny interfejs do nawiązywania połączeń z usługą Azure VoiceLive. Użyj tego klienta do uwierzytelniania i tworzenia sesji do interakcji głosowych w czasie rzeczywistym.

VoiceLiveSession

Reprezentuje aktywne połączenie WebSocket do komunikacji głosowej w czasie rzeczywistym. Ten kurs obejmuje komunikację dwukierunkową, pozwalając przesyłać sygnały dźwiękowe i odbierać sygnały dźwiękowe, transkrypcje tekstu oraz inne zdarzenia w czasie rzeczywistym.

Konfiguracja sesji

Usługa wykorzystuje konfigurację sesji do sterowania różnymi aspektami interakcji głosowej:

  • Wykrywanie skrętu: Konfiguruj sposób, w jaki usługa wykrywa, kiedy użytkownicy zaczynają i przerywają mówienie
  • Przetwarzanie dźwięku: Włączenie tłumienia szumów i redukcji echa
  • Wybór głosu: Wybieraj spośród standardowych głosów Azure, głosów wysokiej rozdzielczości lub niestandardowych
  • Wybór modelu: Wybierz model AI (GPT-4o, GPT-4o-mini, warianty Phi), który najlepiej odpowiada Twoim potrzebom

Modele i możliwości

API VoiceLive obsługuje wiele modeli AI o różnych możliwościach:

Model Description Przypadek użycia
gpt-4o-realtime-preview GPT-4o z przetwarzaniem dźwięku w czasie rzeczywistym Wysokiej jakości konwersacyjna sztuczna inteligencja
gpt-4o-mini-realtime-preview Lekki wariant GPT-4o Szybkie i efektywne interakcje
phi4-mm-realtime Model Phi z wsparciem multimodalnym Opłacalne aplikacje głosowe

Ulepszenia konwersacyjne

API VoiceLive oferuje specyficzne dla Azure ulepszenia:

  • Azure Semantic VAD: Zaawansowane wykrywanie aktywności głosowej, które usuwa wypełniające słowa
  • Tłumienie hałasu: Redukuje hałas tła
  • Anulowanie echo: Usuwa echo z głosu modelu
  • Wykrywanie na końcu sturu: Pozwala na naturalne pauzy bez przedwczesnych przerw

Uwierzytelnianie za pomocą Azure Active Directory

Usługa VoiceLive polega na Azure Active Directory do uwierzytelniania żądań do swoich API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. Plik README dla @azure/identity zawiera więcej szczegółów i przykładów, które ułatwiają rozpoczęcie pracy.

Aby obsługiwać usługę Azure VoiceLive, musisz utworzyć instancję klasy VoiceLiveClient , punkt końcowy usługi oraz obiekt poświadczenia. Przykłady przedstawione w tym dokumencie wykorzystują obiekt poświadczenia o nazwie DefaultAzureCredential, który jest odpowiedni dla większości scenariuszy, w tym lokalnych środowisk deweloperskich i produkcyjnych. Zalecamy używanie zarządzanej tożsamości do uwierzytelniania w środowiskach produkcyjnych.

Więcej informacji o różnych sposobach uwierzytelniania i odpowiadających im typach danych można znaleźć w dokumentacji Azure Identity.

Oto szybki przykład. Po pierwsze, importujemy DefaultAzureCredential i 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);

Uwierzytelnianie za pomocą klucza API

W scenariuszach deweloperskich możesz także uwierzytelnić się za pomocą klucza 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);

Przykłady

Poniższe sekcje zawierają fragmenty kodu obejmujące niektóre z typowych zadań korzystających z Azure VoiceLive. Przedstawione tutaj scenariusze to:

Tworzenie podstawowego asystenta głosowego

Ten przykład pokazuje, jak stworzyć prostego asystenta głosowego, który obsługuje interakcje mowy z mową:

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

Konfiguracja opcji sesji

Możesz dostosować różne aspekty interakcji głosowej:

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

Obsługa zdarzeń w czasie rzeczywistym

Klient VoiceLive zapewnia komunikację opartą na zdarzeniach dla interakcji w czasie rzeczywistym:

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

Implementacja wywoływania funkcji

Włącz asystenta głosowego do wywoływania zewnętrznych funkcji i narzędzi:

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

Rozwiązywanie problemów

Typowe błędy i wyjątki

Błędy uwierzytelniania: Jeśli otrzymasz błędy uwierzytelniania, sprawdź, że:

  • Twój zasób Azure AI Foundry jest poprawnie skonfigurowany
  • Twój klucz API lub dane uwierzytelniające mają wymagane uprawnienia
  • URL endpoint jest poprawny i dostępny

Problemy z połączeniem WebSocket: VoiceLive korzysta z połączeń WebSocket. Upewnij się, że:

  • Twoja sieć pozwala na połączenia WebSocket
  • Reguły zapory pozwalają na połączenia z *.cognitiveservices.azure.com
  • Polityki przeglądarki pozwalają na dostęp do WebSocket i mikrofonu (do korzystania z przeglądarki)

Problemy z dźwiękiem: W przypadku problemów związanych z dźwiękiem:

  • Sprawdź uprawnienia mikrofonu w przeglądarce
  • Sprawdź, czy obsługiwane są formaty audio (PCM16, PCM24)
  • Upewnij się, że odpowiedni kontekst audio do odtwarzania

Wycinka drzew

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby zobaczyć dziennik wiadomości i odpowiedzi WebSocket, ustaw zmienną środowiskową AZURE_LOG_LEVEL na .info Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Dalsze kroki

Więcej przykładów kodu znajdziesz pod następującymi linkami:

Contributing

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

  • Last updated on