Azure VoiceLive klientbibliotek för JavaScript - version 1.0.0-beta.1

Azure VoiceLive är en hanterad tjänst som möjliggör tal-till-tal-interaktioner med låg latens och hög kvalitet för röstagenter. Tjänsten samlar taligenkänning, generativ AI och text-till-tal-funktioner i ett enda, enhetligt gränssnitt och erbjuder en helhetslösning för att skapa sömlösa röststyrda upplevelser.

Använd klientbiblioteket för att:

Skapa röstassistenter och samtalsagenter i realtid
Bygg tal-till-tal-applikationer med minimal latens
Integrera avancerade konversationsfunktioner som brusreducering och ekoreducering
Utnyttja flera AI-modeller (GPT-4o, GPT-4o-mini, Phi) för olika användningsområden
Implementera funktionsanrop och verktygsintegration för dynamiska svar
Skapa avataraktiverade röstinteraktioner med visuella komponenter

Notera: Detta paket stöder både webbläsar- och Node.js-miljöer. WebSocket-anslutningar används för realtidskommunikation.

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox

Förutsättningar

En prenumeration på Azure
En Azure AI Foundry-resurs med Voice Live API-åtkomst

Installera paketet

Installera Azure VoiceLive-klientbiblioteket med npm:

npm install @azure/ai-voicelive

Installera identitetsbiblioteket

VoiceLive-klienter autentisera sig med Azure Identity Library. Installera den också:

npm install @azure/identity

Konfigurera TypeScript

TypeScript-användare behöver ha Node-typdefinitioner installerade:

npm install @types/node

Du behöver också aktivera compilerOptions.allowSyntheticDefaultImports i din tsconfig.json. Observera att om du har aktiverat compilerOptions.esModuleInteropär den allowSyntheticDefaultImports aktiverad som standard.

JavaScript-paket

Om du vill använda det här klientbiblioteket i webbläsaren måste du först använda en bundler. Mer information om hur du gör detta finns i vår paketeringsdokumentation.

Viktiga begrepp

VoiceLiveClient

Det primära gränssnittet för att etablera anslutningar till Azure VoiceLive-tjänsten. Använd denna klient för att autentisera och skapa sessioner för röstinteraktioner i realtid.

VoiceLiveSession

Representerar en aktiv WebSocket-anslutning för realtidskommunikation med röst. Denna kurs hanterar tvåvägskommunikation, vilket gör att du kan skicka ljudinmatning och ta emot ljudutgång, texttranskriptioner och andra händelser i realtid.

Sessionskonfiguration

Tjänsten använder sessionskonfiguration för att styra olika aspekter av röstinteraktion:

Svängdetektion: Konfigurera hur tjänsten känner av när användare börjar och slutar prata
Ljudbehandling: Aktivera brusreducering och ekoreducering
Röstval: Välj mellan vanliga Azure-röster, högupplösta röster eller anpassade röster
Modellval: Välj den AI-modell (GPT-4o, GPT-4o-mini, Phi-varianter) som bäst passar dina behov

Modeller och kapaciteter

VoiceLive API stödjer flera AI-modeller med olika funktioner:

Model	Description	Användningsfall
`gpt-4o-realtime-preview`	GPT-4o med realtidsljudbehandling	Högkvalitativ konversations-AI
`gpt-4o-mini-realtime-preview`	Lättviktsvariant GPT-4o	Snabba, effektiva interaktioner
`phi4-mm-realtime`	Phi-modell med multimodalt stöd	Kostnadseffektiva röstapplikationer

Konversationsförbättringar

VoiceLive API tillhandahåller Azure-specifika förbättringar:

Azure Semantic VAD: Avancerad röstaktivitetsdetektering som tar bort utfyllnadsord
Bullerdämpning: Minskar bakgrundsljud i miljön
Ekoborttagning: Tar bort eko från modellens egen röst
Slutdetektion: Tillåter naturliga pauser utan för tidig avbrott

Autentiering med Azure Active Directory

VoiceLive-tjänsten förlitar sig på Azure Active Directory för att autentisera förfrågningar till dess API:er. @azure/identity-paketet innehåller en mängd olika typer av autentiseringsuppgifter som programmet kan använda för att göra detta. I README för @azure/identity finns mer information och exempel för att komma igång.

För att interagera med Azure VoiceLive-tjänsten behöver du skapa en instans av VoiceLiveClient klassen, en tjänsteendpoint och ett legitimationsobjekt. Exemplen som visas i detta dokument använder ett referensobjekt som heter DefaultAzureCredential, vilket är lämpligt för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer. Vi rekommenderar att använda en hanterad identitet för autentisering i produktionsmiljöer.

Du kan hitta mer information om olika sätt att autentisera och deras motsvarande behörighetstyper i Azure Identity-dokumentationen.

Här är ett snabbt exempel. För det första, importera DefaultAzureCredential och 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);

Autentisering med API-nyckel

För utvecklingsscenarier kan du också autentisera dig med en API-nyckel:

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

Följande avsnitt ger kodutdrag som täcker några av de vanliga uppgifterna med Azure VoiceLive. De scenarier som behandlas här består av:

Skapa en grundläggande röstassistent
Konfigurera sessionsalternativ
Hantering av realtidshändelser
Implementering av funktionsanrop

Skapa en grundläggande röstassistent

Detta exempel visar hur man skapar en enkel röstassistent som kan hantera tal-till-tal-interaktioner:

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

Konfigurera sessionsalternativ

Du kan anpassa olika aspekter av röstinteraktionen:

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

Hantering av realtidshändelser

VoiceLive-klienten tillhandahåller händelsedriven kommunikation för interaktioner i realtid:

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

Implementering av funktionsanrop

Aktivera din röstassistent att kalla externa funktioner och verktyg:

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

Felsökning

Vanliga fel och undantag

Autentiseringsfel: Om du får autentiseringsfel, kontrollera att:

Din Azure AI Foundry-resurs är korrekt konfigurerad
Din API-nyckel eller inloggningsuppgifter har nödvändiga behörigheter
Endpoint-URL:en är korrekt och tillgänglig

WebSocket-anslutningsproblem: VoiceLive använder WebSocket-anslutningar. Se till att:

Ditt nätverk tillåter WebSocket-anslutningar
Brandväggsregler tillåter anslutningar till *.cognitiveservices.azure.com
Webbläsarpolicyer tillåter WebSocket- och mikrofonåtkomst (för webbläsaranvändning)

Ljudproblem: För ljudrelaterade problem:

Verifiera mikrofonbehörigheter i webbläsaren
Kontrollera att ljudformat (PCM16, PCM24) stöds
Säkerställ korrekt ljudkontextinställning för uppspelning

Loggning / Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. För att se en logg över WebSocket-meddelanden och svar, sätt miljövariabeln AZURE_LOG_LEVEL till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Nästa steg

Du kan hitta fler kodexempel via följande länkar:

Contributing

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Feedback

Var den här sidan till hjälp?

Last updated on 2025-11-18