Bagikan melalui

Pustaka klien Azure VoiceLive untuk JavaScript - versi 1.0.0-beta.1

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-4o, GPT-4o-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 definisi tinggi, atau suara kustom
  • Pemilihan Model: Pilih model AI (varian GPT-4o, GPT-4o-mini, Phi) yang paling sesuai dengan kebutuhan Anda

Model dan Kemampuan

VoiceLive API mendukung beberapa model AI dengan kemampuan berbeda:

Model Description Kasus Penggunaan
gpt-4o-realtime-preview GPT-4o dengan pemrosesan audio real-time AI percakapan berkualitas tinggi
gpt-4o-mini-realtime-preview Varian GPT-4o ringan Interaksi yang cepat dan efisien
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

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

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

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

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

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

Penebangan kayu

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 selanjutnya

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