Perpustakaan klien Azure VoiceLive untuk JavaScript - versi 1.1.0

Azure VoiceLive adalah layanan terkelola yang memungkinkan interaksi ucapan-ke-ucapan latensi rendah dan berkualitas tinggi untuk agen suara. Layanan ini mengkonsolidasikan pengenalan suara, AI generatif, dan fungsionalitas text-to-speech ke dalam satu antarmuka terpadu, memberikan solusi end-to-end untuk menciptakan pengalaman berbasis suara yang mulus.

Gunakan pustaka klien untuk:

  • Buat asisten suara dan agen percakapan real-time
  • Bangun aplikasi ucapan-ke-ucapan dengan latensi minimal
  • Integrasikan fitur percakapan canggih seperti peredam bising dan peredam gema
  • Manfaatkan beberapa model AI (GPT-Realtime, GPT-Realtime-Mini, Phi) untuk kasus penggunaan yang berbeda
  • Terapkan pemanggilan fungsi dan integrasi alat untuk respons dinamis
  • Membuat interaksi suara yang mendukung avatar dengan komponen visual

Catatan: Paket ini mendukung lingkungan browser dan Node.js. Koneksi WebSocket digunakan untuk komunikasi waktu nyata.

Memulai Langkah Pertama

Lingkungan yang didukung saat ini

Prasyarat

Pasang paketnya

Instal pustaka klien Azure VoiceLive menggunakan npm:

npm install @azure/ai-voicelive

Menginstal pustaka identitas

Klien VoiceLive mengautentikasi menggunakan Pustaka Identitas Azure. Instal juga:

npm install @azure/identity

Mengonfigurasi TypeScript

Pengguna TypeScript harus menginstal definisi jenis Node:

npm install @types/node

Anda juga perlu mengaktifkan compilerOptions.allowSyntheticDefaultImports di tsconfig.jsonAnda . Perhatikan bahwa jika Anda telah mengaktifkan compilerOptions.esModuleInterop, allowSyntheticDefaultImports diaktifkan secara default.

Bundel JavaScript

Untuk menggunakan pustaka klien ini di browser, pertama-tama Anda perlu menggunakan bunder. Untuk detail tentang cara melakukan ini, silakan lihat dokumentasi bundling kami.

Konsep Utama

VoiceLiveClient

Antarmuka utama untuk membuat koneksi ke layanan Azure VoiceLive. Gunakan klien ini untuk mengautentikasi dan membuat sesi untuk interaksi suara real-time.

Sesi Langsung Suara,

Mewakili koneksi WebSocket aktif untuk komunikasi suara waktu nyata. Kelas ini menangani komunikasi dua arah, memungkinkan Anda mengirim input audio dan menerima output audio, transkripsi teks, dan peristiwa lainnya secara real-time.

Konfigurasi Sesi

Layanan ini menggunakan konfigurasi sesi untuk mengontrol berbagai aspek interaksi suara:

  • Deteksi Giliran: Mengonfigurasi bagaimana layanan mendeteksi saat pengguna memulai dan berhenti berbicara
  • Pemrosesan Audio: Aktifkan peredam bising dan peredam gema
  • Pemilihan Suara: Pilih dari suara Azure standar, suara khusus, suara sinkronisasi avatar, atau pratinjau suara asli Azure realtime
  • Pemilihan Model: Pilih model AI (varian GPT-Realtime, GPT-Realtime-Mini, Azure-Realtime, Phi) yang paling sesuai dengan kebutuhan Anda

Model dan Kemampuan

VoiceLive API mendukung beberapa model AI dengan kemampuan berbeda:

Model Deskripsi Kasus Penggunaan
gpt-realtime Model pemrosesan audio waktu nyata AI percakapan berkualitas tinggi
gpt-realtime-mini Model real-time yang ringan Interaksi yang cepat dan efisien
azure-realtime Model realtime asli Azure Suara asli dan skenario WebRTC
phi4-mm-realtime Model Phi dengan dukungan multimoda Aplikasi suara yang hemat biaya

Peningkatan Percakapan

VoiceLive API menyediakan penyempurnaan khusus Azure:

  • Azure Semantic VAD: Deteksi aktivitas suara tingkat lanjut yang menghapus kata pengisi
  • Peredam Kebisingan: Mengurangi kebisingan latar belakang lingkungan
  • Pembatalan Gema: Menghapus gema dari suara model sendiri
  • Deteksi Akhir Belokan: Memungkinkan jeda alami tanpa gangguan prematur

Mode Sesi

VoiceLive mendukung dua mode berbeda untuk membuat sesi:

Mode Model (LLM sebagai Aktor Utama)

Dalam mode model, model LLM adalah aktor AI utama. Anda menentukan nama model dan secara opsional mengonfigurasi alat seperti fungsi atau server MCP.

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

// Model mode - LLM is the main actor
const session = await client.startSession("gpt-realtime");

Mode Agen (Agen sebagai Aktor Utama)

Dalam mode agen, agen Foundry adalah aktor AI utama. Konfigurasi agen (alat, instruksi, suhu) dikelola di portal Azure AI Foundry, bukan dalam kode sesi. Ini sangat ideal untuk:

  • Agen berbasis teks yang ada yang memungkinkan suara
  • Skenario di mana konfigurasi agen harus dikelola secara terpusat
  • Integrasi yang disederhanakan tanpa konfigurasi runtime
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);

// Agent mode - Foundry agent is the main actor
const session = await client.startSession({
  agent: {
    agentName: "my-agent",
    projectName: "my-foundry-project",
  },
});

Mengautentikasi dengan Azure Active Directory

Layanan VoiceLive mengandalkan Azure Active Directory untuk mengautentikasi permintaan ke API-nya. Paket @azure/identity menyediakan berbagai jenis kredensial yang dapat digunakan aplikasi Anda untuk melakukan ini. README untuk @azure/identity menyediakan detail dan sampel selengkapnya untuk memulai Anda.

Untuk berinteraksi dengan layanan Azure VoiceLive, Anda perlu membuat instans VoiceLiveClient kelas, titik akhir layanan , dan objek kredensial. Contoh yang ditampilkan dalam dokumen ini menggunakan objek kredensial bernama DefaultAzureCredential, yang sesuai untuk sebagian besar skenario, termasuk pengembangan lokal dan lingkungan produksi. Sebaiknya gunakan identitas terkelola untuk autentikasi di lingkungan produksi.

Anda dapat menemukan informasi selengkapnya tentang berbagai cara mengautentikasi dan jenis kredensial yang sesuai di dokumentasi Azure Identity.

Berikut adalah contoh singkatnya. Pertama, impor DefaultAzureCredential dan 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);

Autentikasi dengan API Key

Untuk skenario pengembangan, Anda juga dapat mengautentikasi menggunakan kunci 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);

Examples

Bagian berikut menyediakan cuplikan kode yang mencakup beberapa tugas umum menggunakan Azure VoiceLive. Skenario yang dibahas di sini terdiri dari:

Membuat asisten suara dasar

Contoh ini menunjukkan cara membuat asisten suara sederhana yang dapat menangani interaksi ucapan-ke-ucapan:

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-realtime-mini");

// 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,
    prefixPaddingInMs: 300,
    silenceDurationInMs: 500,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

Membuat asisten suara yang didukung agen

Contoh ini menunjukkan cara membuat asisten suara yang didukung oleh agen Foundry. Dalam mode agen, konfigurasi agen dikelola di portal Azure AI Foundry:

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 with an agent as the main actor
const session = await client.startSession({
  agent: {
    agentName: "your-agent-name",
    projectName: "your-foundry-project",
  },
});

// Subscribe to events - audio settings can still be configured
const subscription = session.subscribe({
  onResponseAudioDelta: async (event, context) => {
    // Handle audio from the agent
    playAudioChunk(event.delta);
  },
  onResponseTextDelta: async (event, context) => {
    console.log("Agent:", event.delta);
  },
});

// Send audio data from microphone
function sendAudioChunk(audioBuffer: ArrayBuffer) {
  session.sendAudio(audioBuffer);
}

Mengonfigurasi opsi sesi

Anda dapat menyesuaikan berbagai aspek interaksi suara:

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

// 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,
    prefixPaddingInMs: 200,
    silenceDurationInMs: 300,
  },
  inputAudioFormat: "pcm16",
  outputAudioFormat: "pcm16",
});

Untuk pratinjau suara asli pada azure-realtime model, gunakan jenis suara khusus:

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("azure-realtime");

await session.updateSession({
  voice: {
    type: "azure-realtime-native",
    name: "ava",
  },
});

Input teks streaming

Alih-alih mengirim audio, Anda dapat mengalirkan teks ke item percakapan secara bertahap dengan input_text.delta event dan mengakhiri dengan satu input_text.done event. Ini berguna ketika teks itu sendiri diproduksi token demi token (misalnya, diteruskan dari model lain):

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-realtime-mini");

// Create the conversation item that the streamed text is appended to
const itemId = "user-message-1";
await session.addConversationItem({
  type: "message",
  role: "user",
  id: itemId,
  content: [{ type: "input_text", text: "" }],
});

// Stream the text in chunks as `input_text.delta` events
for (const chunk of ["Tell me ", "a fun fact ", "about the ocean."]) {
  await session.sendEvent({
    type: "input_text.delta",
    id: itemId,
    delta: chunk,
  });
}

// Signal that the streamed text is complete with a single `input_text.done` event
await session.sendEvent({
  type: "input_text.done",
  id: itemId,
});

// Ask the model to respond to the streamed text
await session.sendEvent({ type: "response.create" });

Menangani peristiwa real-time

Klien VoiceLive menyediakan komunikasi berbasis peristiwa untuk interaksi real-time:

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-realtime-mini");

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

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

Menerapkan pemanggilan fungsi

Aktifkan asisten suara Anda untuk memanggil fungsi dan alat eksternal:

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-realtime-mini");

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

Troubleshooting

Kesalahan umum dan pengecualian

Kesalahan Autentikasi: Jika Anda menerima kesalahan autentikasi, verifikasi bahwa:

  • Sumber daya Azure AI Foundry Anda dikonfigurasi dengan benar
  • Kunci API atau kredensial Anda memiliki izin yang diperlukan
  • URL endpoint benar dan dapat diakses

Masalah Koneksi WebSocket: VoiceLive menggunakan koneksi WebSocket. Pastikan bahwa:

  • Jaringan Anda mengizinkan koneksi WebSocket
  • Aturan firewall mengizinkan koneksi ke *.cognitiveservices.azure.com
  • Kebijakan browser mengizinkan WebSocket dan akses mikrofon (untuk penggunaan browser)

Masalah Audio: Untuk masalah terkait audio:

  • Memverifikasi izin mikrofon di browser
  • Periksa apakah format audio (PCM16, PCM24) didukung
  • Pastikan pengaturan konteks audio yang tepat untuk pemutaran

Telemetri / Pelacakan Terdistribusi

VoiceLive SDK mendukung pelacakan terdistribusi melalui @azure/core-tracing paket. Pelacakan no-op secara default — tidak ada rentang yang dibuat kecuali Anda ikut serta dengan mendaftarkan penyedia pelacakan yang kompatibel dengan OpenTelemetry.

Cara kerjanya

Saat pelacakan diaktifkan, SDK secara otomatis membuat rentang untuk siklus hidup sesi:

connect (parent span — open for the entire session lifetime)
├── send session.update
├── send conversation.item.create
├── send response.create
├── recv session.created
├── recv response.done          ← turn count incremented, token usage recorded
├── send response.cancel        ← interruption count incremented
├── recv error                  ← error event recorded
└── close                       ← session-level counters finalized

Atribut rentang mengikuti Konvensi Semantik GenAI OpenTelemetry (gen_ai.system, gen_ai.operation.name, , gen_ai.request.modeldll.) ditambah ekstensi khusus VoiceLive (gen_ai.voice.session_id, gen_ai.voice.turn_count, , gen_ai.voice.audio_bytes_sent...). Metrik tingkat sesi digabungkan ke connect rentang saat sesi berakhir.

Aktifkan pelacakan (Node.js, CommonJS — direkomendasikan)

Untuk aplikasi CommonJS, gunakan jembatan instrumentasi Azure SDK standar:

npm install @azure/opentelemetry-instrumentation-azure-sdk @opentelemetry/instrumentation @opentelemetry/sdk-trace-node

const {
  NodeTracerProvider,
  SimpleSpanProcessor,
  ConsoleSpanExporter,
} = require("@opentelemetry/sdk-trace-node");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { createAzureSdkInstrumentation } = require("@azure/opentelemetry-instrumentation-azure-sdk");

// 1. Configure an OpenTelemetry tracer provider
const provider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});
provider.register();

// 2. Register the Azure SDK instrumentation BEFORE requiring @azure/ai-voicelive
registerInstrumentations({
  instrumentations: [createAzureSdkInstrumentation()],
});

// 3. Use VoiceLive — spans are emitted automatically
const { VoiceLiveClient } = require("@azure/ai-voicelive");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new VoiceLiveClient(endpoint, new DefaultAzureCredential());
const session = client.createSession("gpt-realtime");
await session.connect(); // creates "connect" span

Aktifkan pelacakan (Node.js ESM dan browser)

createAzureSdkInstrumentation mengandalkan CommonJS require-hooks dan tidak menghasilkan rentang saat SDK dimuat sebagai ESM (yaitu "type": "module" paket atau bundler browser seperti Vite). Untuk lingkungan tersebut, daftarkan minimal Instrumenter langsung dariuseInstrumenter:@azure/core-tracing

import { useInstrumenter } from "@azure/core-tracing";
import { trace, context } from "@opentelemetry/api";

useInstrumenter({
  startSpan(name, spanOptions) {
    const ctx = spanOptions.tracingContext ?? context.active();
    const tracer = trace.getTracer(spanOptions.packageName ?? "@azure/ai-voicelive", spanOptions.packageVersion);
    const span = tracer.startSpan(name, { attributes: spanOptions.spanAttributes }, ctx);
    return {
      span: {
        end: () => span.end(),
        setStatus: (s) => { if (s.status === "error") span.setStatus({ code: 2, message: String(s.error ?? "") }); },
        setAttribute: (k, v) => span.setAttribute(k, v),
        isRecording: () => span.isRecording(),
        recordException: (e) => span.recordException(e),
      },
      tracingContext: trace.setSpan(ctx, span),
    };
  },
  withContext: (ctx, fn, ...args) => context.with(ctx, fn, undefined, ...args),
  parseTraceparentHeader: () => undefined,
  createRequestHeaders: () => ({}),
});

Ini menghasilkan bentang yang identik dengan jembatan CommonJS.

Sampel lengkap yang dapat dijalankan:

Atribut rentang

SDK menetapkan atribut mengikuti Konvensi Semantik GenAI:

Attribute Deskripsi
az.namespace Selalu Microsoft.CognitiveServices
gen_ai.system Selalu az.ai.voicelive
gen_ai.operation.name connect, send, recv, atau close
gen_ai.request.model Nama model (misalnya, gpt-realtime)
gen_ai.voice.session_id ID sesi suara dari session.created
gen_ai.voice.turn_count Total putaran respons selesai (rentang sambungan)
gen_ai.voice.interruption_count Jumlah response.cancel peristiwa (rentang sambungan)
gen_ai.voice.audio_bytes_sent Total byte audio yang dikirim (bentang sambungan)
gen_ai.voice.audio_bytes_received Total byte audio yang diterima (sambungkan renttang)
gen_ai.voice.first_token_latency_ms Waktu dari response.create ke delta audio/teks pertama
gen_ai.usage.input_tokens Jumlah token input dari response.done
gen_ai.usage.output_tokens Jumlah token keluaran dari response.done

Pengelogan

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log pesan dan respons WebSocket, atur variabel AZURE_LOG_LEVEL lingkungan ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/logger.

Langkah berikutnya

Anda dapat menemukan sampel kode lainnya melalui tautan berikut:

Contributing

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

  • Last updated on