Sdílet prostřednictvím

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

Azure VoiceLive je spravovaná služba, která umožňuje nízkolatencní a vysoce kvalitní interakce řeči pro hlasové agenty. Služba konsoliduje funkce rozpoznávání řeči, generativní AI a převodu textu na řeč do jednoho jednotného rozhraní, které poskytuje komplexní řešení pro tvorbu plynulých hlasových zážitků.

Klientskou knihovnu použijte k:

  • Vytvořte hlasové asistenty a konverzační agenty v reálném čase
  • Vytvářet aplikace pro převod řeči na řeč s minimální latencí
  • Integrujte pokročilé konverzační funkce jako potlačení hluku a potlačení ozvěny
  • Využijte více AI modelů (GPT-4o, GPT-4o-mini, Phi) pro různé případy použití
  • Implementujte volání funkcí a integraci nástrojů pro dynamické odpovědi
  • Vytvářejte hlasové interakce s avatarem s vizuálními komponentami

Poznámka: Tento balíček podporuje jak prohlížečová, tak Node.js prostředí. WebSocket připojení se používá pro komunikaci v reálném čase.

Začínáme

Aktuálně podporovaná prostředí

Požadavky

Nainstalujte balíček

Nainstalujte knihovnu klienta Azure VoiceLive pomocí npm:

npm install @azure/ai-voicelive

Nainstalujte knihovnu identity

Klienti VoiceLive se autentizují pomocí Azure Identity Library. Nainstalujte ho také:

npm install @azure/identity

Configure TypeScript

Uživatelé TypeScriptu potřebují mít nainstalované definice typů uzlů:

npm install @types/node

Musíte také povolit compilerOptions.allowSyntheticDefaultImports své tsconfig.json. Všimněte si, že pokud máte zapnuté compilerOptions.esModuleInterop, allowSyntheticDefaultImports je ve výchozím nastavení povoleno.

JavaScriptový balíček

Pokud chcete tuto klientskou knihovnu použít v prohlížeči, musíte nejprve použít bundler. Podrobnosti o tom, jak to udělat, najdete v naší dokumentaci sdružování.

Klíčové koncepty

VoiceLiveClient

Hlavní rozhraní pro navazování spojení se službou Azure VoiceLive. Použijte tohoto klienta k autentizaci a vytváření relací pro hlasové interakce v reálném čase.

VoiceLiveSession

Představuje aktivní WebSocket spojení pro hlasovou komunikaci v reálném čase. Tento kurz se zabývá obousměrnou komunikací, což umožňuje odesílat zvukové vstupy a přijímat zvukové výstupy, textové transkripce a další události v reálném čase.

Konfigurace relace

Služba využívá konfiguraci relace k řízení různých aspektů hlasové interakce:

  • Detekce otáčení: Nastavte způsob, jakým služba detekuje, kdy uživatelé začínají a přestávají mluvit
  • Zpracování zvuku: Povolte potlačení šumu a potlačení ozvěny
  • Výběr hlasu: Vyberte si mezi standardními Azure hlasy, hlasy ve vysokém rozlišení nebo vlastními hlasy
  • Výběr modelu: Vyberte AI model (GPT-4o, GPT-4o-mini, Phi varianty), který nejlépe odpovídá vašim potřebám

Modely a schopnosti

API VoiceLive podporuje více AI modelů s různými schopnostmi:

Model Description Případ použití
gpt-4o-realtime-preview GPT-4o s reálným zpracováním zvuku Vysoce kvalitní konverzační AI
gpt-4o-mini-realtime-preview Lehká varianta GPT-4o Rychlé a efektivní interakce
phi4-mm-realtime Model Phi s multimodální podporou Nákladově efektivní hlasové aplikace

Konverzační vylepšení

API VoiceLive poskytuje specifická vylepšení pro Azure:

  • Azure Semantic VAD: Pokročilá detekce hlasové aktivity, která odstraňuje výplňová slova
  • Potlačení hluku: Snižuje okolní hluk
  • Echo Cancel: Odstraňuje echo z modelu
  • Detekce na konci tahu: Umožňuje přirozené pauzy bez předčasného přerušení

Autentizace pomocí Azure Active Directory

Služba VoiceLive spoléhá na Azure Active Directory k ověřování požadavků na svá API. Balíček @azure/identity poskytuje řadu typů přihlašovacích údajů, které může vaše aplikace použít k tomu. Soubor README pro @azure/identity poskytuje další podrobnosti a ukázky, které vám pomůžou začít.

Pro interakci se službou Azure VoiceLive je potřeba vytvořit instanci třídy VoiceLiveClient , koncový bod služby a objekt přihlašovacích údajů. Příklady uvedené v tomto dokumentu používají přihlašovací objekt s názvem DefaultAzureCredential, který je vhodný pro většinu scénářů, včetně lokálního vývojového a produkčního prostředí. Doporučujeme používat spravovanou identitu pro autentizaci v produkčních prostředích.

Více informací o různých způsobech autentizace a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci Azure Identity.

Tady je rychlý příklad. Nejprve importujeme DefaultAzureCredential a 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);

Autentizace pomocí API klíče

Pro vývojové scénáře se můžete také autentizovat pomocí API klíče:

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

Následující sekce poskytují úryvky kódu, které pokrývají některé běžné úkoly využívající Azure VoiceLive. Scénáře zde popsané zahrnují:

Vytvoření základního hlasového asistenta

Tento příklad ukazuje, jak vytvořit jednoduchého hlasového asistenta, který zvládne interakce mezi řečmi:

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

Konfigurace možností sezení

Můžete upravit různé aspekty hlasové interakce:

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

Řešení událostí v reálném čase

Klient VoiceLive poskytuje komunikaci řízenou událostmi pro interakce v reálném čase:

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

Implementace volání funkcí

Povolte svému hlasovému asistentovi volat externí funkce a nástroje:

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

Řešení problémů

Běžné chyby a výjimky

Chyby autentizace: Pokud obdržíte chyby při ověřování, ověřte, že:

  • Váš zdroj Azure AI Foundry je správně nakonfigurován
  • Váš API klíč nebo přihlašovací údaje mají potřebná oprávnění
  • URL koncového bodu je správná a přístupná

Problémy s připojením přes WebSocket: VoiceLive používá připojení přes WebSocket. Zajistěte následující:

  • Vaše síť umožňuje připojení přes WebSocket
  • Firewallová pravidla umožňují připojení k *.cognitiveservices.azure.com
  • Pravidla prohlížeče umožňují přístup k WebSocket a mikrofonu (pro použití prohlížeče)

Problémy se zvukem: U problémů souvisejících se zvukem:

  • Ověřte oprávnění mikrofonu v prohlížeči
  • Zkontrolujte, zda jsou podporovány audio formáty (PCM16, PCM24)
  • Ujistěte se o správné nastavení audio kontextu pro přehrávání

Logování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pro zobrazení logu zpráv a odpovědí WebSocketu nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Další kroky

Další ukázky kódu najdete na následujících odkazech:

Contributing

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

  • Last updated on