Megosztás a következőn keresztül:

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

Az Azure VoiceLive egy menedzselt szolgáltatás, amely alacsony késleltetésű, magas minőségű beszéd-beszéd interakciókat tesz lehetővé hangügynökök számára. A szolgáltatás egyetlen, egységes interfészben egyesíti a beszédfelismerést, generatív mesterséges intelligenciát és szöveg-beszéd funkciókat, végponttól végpontig megoldást nyújtva a zökkenőmentes, hangvezérelt élmények létrehozásához.

Az ügyfélkódtár használatával:

  • Valós idejű hangasszisztensek és beszélgetős ügynökök létrehozása
  • Minimális késleltetéssel való beszéd-beszéd alkalmazások építése
  • Integráld a fejlett beszélgetési funkciókat, mint a zajelnyomás és a visszhangszűltés
  • Több AI modellt (GPT-4o, GPT-4o-mini, Phi) különböző felhasználási esetekre használjunk
  • Funkcióhívás és eszközintegráció megvalósítása dinamikus válaszokhoz
  • Avatar-kompatibilis hanginterakciók létrehozása vizuális komponensekkel

Megjegyzés: Ez a csomag mind böngészős, mind Node.js környezetet támogat. A WebSocket kapcsolatokat valós idejű kommunikációra használják.

Kezdő lépések

Jelenleg támogatott környezetek

Előfeltételek

A csomag telepítése

Telepítsd az Azure VoiceLive klienskönyvtárát npm segítségével:

npm install @azure/ai-voicelive

Telepítsd az identitáskönyvtárat

A VoiceLive kliensek az Azure Identity Library segítségével autentikálnak. Telepítsd is:

npm install @azure/identity

Konfiguráld a TypeScript

A TypeScript felhasználóknak Node típus definíciókat kell telepíteniük:

npm install @types/node

A tsconfig.jsonis be kell kapcsolnod compilerOptions.allowSyntheticDefaultImports a . Fontos megjegyezni, hogy ha engedélyezted compilerOptions.esModuleInterop, akkor allowSyntheticDefaultImports alapértelmezés szerint engedélyezve van.

JavaScript-csomag

Ahhoz, hogy ezt az ügyfélkódtárat a böngészőben használhassa, először egy kötegelőt kell használnia. Ennek részleteiért tekintse meg a csomagküldő dokumentációt.

Főbb fogalmak

VoiceLiveClient

Ez az elsődleges interfész az Azure VoiceLive szolgáltatáshoz való kapcsolatok kialakításához. Használd ezt az ügyfél hitelesítésére és beszélgetések létrehozására valós idejű hanginterakciókhoz.

VoiceLiveSession

Aktív WebSocket kapcsolatot képvisel valós idejű hangkommunikációhoz. Ez az osztály kétirányú kommunikációt kezel, lehetővé téve hangbemenet küldését és hangkimenet, szövegátiratok és egyéb események fogadását valós időben.

Munkamenet-konfiguráció

A szolgáltatás a hangkommunikáció különböző aspektusainak vezérlésére használja a session konfigurációt:

  • Körzelés-észlelés: Konfiguráld, hogyan érzékeli a szolgáltatás a felhasználók, amikor elkezdenek és abbahagyják a beszédet
  • Hangfeldolgozás: Hangelékcsökkentés és visszhangszűltés engedélyezése
  • Hangválasztás: Válassz szabványos Azure hangok, nagyfelbontású hangok vagy egyedi hangok közül
  • Modell kiválasztása: Válaszd ki azt az AI modellt (GPT-4o, GPT-4o-mini, Phi változatok), amely leginkább megfelel az igényeidnek

Modellek és képességek

A VoiceLive API több, különböző képességekkel rendelkező AI modellt támogat:

Model Description Használati eset
gpt-4o-realtime-preview GPT-4o valós idejű hangfeldolgozással Magas minőségű beszélgető AI
gpt-4o-mini-realtime-preview Könnyű GPT-4o változat Gyors, hatékony interakciók
phi4-mm-realtime Phi modell multimodális támogatással Költséghatékony hangalkalmazások

Kommunikációs fejlesztések

A VoiceLive API Azure-specifikus fejlesztéseket kínál:

  • Azure Semantic VAD: Fejlett hangtevékenység-észlelés, amely eltávolítja a töltőszavakat
  • Zajcsökkentés: Csökkenti a környezeti háttérzajt
  • Visszhangkivonás: Eltávolítja a visszhangot a modell saját hangjából
  • Kör végi észlelés: Lehetővé teszi a természetes szüneteket idő előtti megszakítás nélkül

Authenticating with Azure Active Directory

A VoiceLive szolgáltatás Azure Active Directory segítségével hitelesíti az API-jai kéréseit. A @azure/identity csomag számos hitelesítő adattípust biztosít, amelyeket az alkalmazás használhat erre. A @azure/identity README további részleteket és mintákat tartalmaz az első lépésekhez.

Az Azure VoiceLive szolgáltatással való interakcióhoz létre kell hozni az osztály példányát VoiceLiveClient , egy szolgáltatásvégpontot és egy credential objektumot. A dokumentumban bemutatott példák egy , nevű hitelesítési objektumot DefaultAzureCredentialhasználnak, amely a legtöbb forgatókönyvhöz megfelelő, beleértve a helyi fejlesztési és gyártási környezeteket is. Azt javasoljuk, hogy menedzselt identitást használjunk hitelesítéshez termelési környezetekben.

További információt találsz a hitelesítés különböző módjairól és azok megfelelő hitelesítési típusairól az Azure Identity dokumentációban.

Íme egy gyors példa. Először is, importáljuk DefaultAzureCredential és 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);

Hitelesítés API kullyal

Fejlesztési helyzetekben API kulcs segítségével is hitelesíthetsz:

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

Példák

Az alábbi szakaszok kódrészleteket tartalmaznak, amelyek az Azure VoiceLive használatával gyakori feladatokat fedik le. Az itt bemutatott forgatókönyvek a következők:

Alapvető hangasszisztens létrehozása

Ez a példa bemutatja, hogyan lehet egyszerű hangasszisztenst létrehozni, amely képes kezelni a beszéd-beszéd interakciókat:

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

A szekció beállítások konfigurálása

A hanginterakció különböző aspektusait testreszabhatod:

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

Valós idejű események kezelése

A VoiceLive kliens eseményvezérelt kommunikációt biztosít valós idejű interakciókhoz:

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

Funkcióhívás megvalósítása

Engedd meg a hangasszisztensednek, hogy külső funkciókat és eszközöket hívjon:

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

Hibaelhárítás

Gyakori hibák és kivételek

Hitelesítési hibák: Ha hitelesítési hibákat kapsz, ellenőrizd, hogy:

  • Az Azure AI Foundry erőforrásod helyesen van konfigurálva.
  • Az API kulcsod vagy jogosultságod rendelkezik
  • A végpont URL-je helyes és hozzáférhető

WebSocket kapcsolati problémák: A VoiceLive WebSocket csatlakozásokat használ. Győződjön meg a következőkről:

  • A hálózatod lehetővé teszi a WebSocket csatlakozásokat
  • A tűzfal szabályai lehetővé teszik a csatlakozásokat a következőkhöz *.cognitiveservices.azure.com
  • A böngésző szabályzatok lehetővé teszik a WebSocket és mikrofon használatát (böngésző használat esetén)

Hangproblémák: Hanggal kapcsolatos problémák esetén:

  • Ellenőrizd a mikrofonengedélyeket a böngészőben
  • Ellenőrizd, hogy támogatott-e a hangformátumok (PCM16, PCM24)
  • Biztosítsd a megfelelő hangkontextus beállítást a lejátszáshoz

Logging

A naplózás engedélyezése segíthet a hibákról szóló hasznos információk feltárásában. Ahhoz, hogy lássuk a WebSocket üzenetek és válaszok naplóját, állítsuk be a AZURE_LOG_LEVEL környezeti változót .info Alternatívaként a naplózás futásidőben is engedélyezhető a setLogLevel hívásával a @azure/logger.

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentációit.

Következő lépések

További kódmintákat a következő linkeken találhatsz:

Közreműködés

Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód összeállításáról és teszteléséről.

  • Last updated on