Azure VoiceLive client library for JavaScript - version 1.1.0

Azure VoiceLive, ses ajanları için düşük gecikmeli ve yüksek kaliteli konuşma-konuşma etkileşimlerini sağlayan yönetilen bir hizmettir. Hizmet, konuşma tanıma, üretken yapay zeka ve metinden sese işlevlerini tek, birleşik bir arayüzde birleştirerek kesintisiz, ses odaklı deneyimler yaratmak için uçtan uca bir çözüm sunuyor.

İstemci kitaplığını kullanarak:

• Gerçek zamanlı sesli asistanlar ve konuşma ajanları oluşturun
• En az gecikmeyle konuşma-konuşma uygulamaları oluşturun
• Gürültü bastırma ve yankı engelleme gibi gelişmiş konuşma özelliklerini entegre edin
• Farklı kullanım alanları için birden fazla yapay zeka modelinden (GPT-Realtime, GPT-Realtime-Mini, Phi) yararlanın
• Dinamik yanıtlar için fonksiyon çağrısı ve araç entegrasyonunu uygulayın
• Görsel bileşenlerle avatar özellikli sesli etkileşimler oluşturun

Not: Bu paket hem tarayıcı hem de Node.js ortamlarını destekler. WebSocket bağlantıları gerçek zamanlı iletişim için kullanılır.

Başlangıç Yapmak

Şu anda desteklenen ortamlar

• Node.js LTS sürümleri
• Safari, Chrome, Edge ve Firefox'un en son sürümleri

Prerequisites

• Azure aboneliği
• Voice Live API erişimine sahip bir Azure Yapay Zeka Atölyesi kaynağı

Paketi yükle

Azure VoiceLive client library npm kullanılarak kurulum:

npm install @azure/ai-voicelive

Kimlik kütüphanesini kur

VoiceLive istemcileri, Azure Identity Library kullanılarak kimlik doğrulaması yapar. Onu da kurun:

npm install @azure/identity

TypeScript'i Yapılandır

TypeScript kullanıcılarının Node tipi tanımlarının kurulması gerekir:

npm install @types/node

Ayrıca compilerOptions.allowSyntheticDefaultImports programınızı etkinleştirmeniz tsconfig.json. Eğer etkinleştirdiyseniz compilerOptions.esModuleInterop, varsayılan olarak allowSyntheticDefaultImports etkinleştirilmiş olduğunu unutmayın.

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için önce bir paketleyici kullanmanız gerekir. Bunun nasıl yapılacağının ayrıntıları için lütfenpaketleme belgelerimize bakın.

Kilit kavramlar

VoiceLiveClient

Azure VoiceLive hizmetine bağlantı kurmak için birincil arayüz. Bu istemciyi gerçek zamanlı sesli etkileşimler için kimlik doğrulama ve oturumlar oluşturmak için kullanın.

VoiceLiveSession

Gerçek zamanlı sesli iletişim için aktif bir WebSocket bağlantısını temsil eder. Bu sınıf, çift yönlü iletişimi yöneterek ses girişi gönderip ses çıkışı, metin transkripsiyonları ve diğer olayları gerçek zamanlı olarak almanızı sağlar.

Oturum Yapılandırması

Hizmet, sesli etkileşimin çeşitli yönlerini kontrol etmek için oturum yapılandırmasını kullanır:

• Turn Detection: Kullanıcıların konuşmaya başlayıp durduğunda servisin nasıl algıladığını yapılandırın
• Ses İşleme: Gürültü bastırma ve yankı engelleme etkinleştirin
• Ses Seçimi: Standart Azure sesleri, özel sesler, avatar senkronizasyonu sesleri veya önizleme Azure gerçek zamanlı yerel sesler arasından seçin
• Model Seçimi: İhtiyaçlarınıza en uygun yapay zeka modelini (GPT-Realtime, GPT-Realtime-Mini, Azure-Realtime, Phi varyantları) seçin

Modeller ve Yetenekler

VoiceLive API, farklı yeteneklere sahip birden fazla yapay zeka modelini destekler:

Model	Description	Kullanım Örneği
gpt-realtime	Gerçek zamanlı ses işleme modeli	Yüksek kaliteli konuşma yapay zekası
gpt-realtime-mini	Hafif gerçek zamanlı model	Hızlı ve verimli etkileşimler
azure-realtime	Azure-native realtime model	Yerel sesler ve WebRTC senaryoları
phi4-mm-realtime	Multimodal destekli Phi modeli	Maliyet etkin ses uygulamaları

Konuşma Geliştirmeleri

VoiceLive API, Azure'a özgü iyileştirmeler sunar:

• Azure Semantic VAD: Dolgu kelimelerini kaldıran gelişmiş ses aktivitesi algılama
• Gürültü Bastırma: Çevresel arka plan gürültüsünü azaltır
• Yankı İptal: Modelin kendi sesindeki yankını kaldırır
• Tur Sonu Algılama: Doğal duraklamalara erken kesinti olmadan izin verir

Oturum Modları

VoiceLive, oturum oluşturmak için iki farklı mod sunar:

Model Modu (Ana Aktör olarak LLM)

Model modunda, LLM modeli birincil yapay zeka aktörüdür. Bir model adı belirlersiniz ve isteğe bağlı olarak fonksiyonlar veya MCP sunucuları gibi araçları yapılandırırsınız.

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

Ajan Modu (Ana Aktör Olarak Ajan)

Ajan modunda, bir Foundry ajanı birincil yapay zeka aktörüdür. Ajanın yapılandırması (araçlar, talimatlar, sıcaklık) Azure Yapay Zeka Atölyesi portalında yönetilir, oturum kodunda değil. Bu, aşağıdakiler için idealdir:

• Mevcut metin tabanlı ajanları sesle etkinleştirme
• Ajan yapılandırmasının merkezi olarak yönetilmesi gereken senaryolar
• Çalışma zamanı yapılandırması olmadan basitleştirilmiş entegrasyon

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

Azure Active Directory ile authenticating

VoiceLive servisi, API'lerine gelen isteği doğrulamak için Azure Active Directory'ye dayanır. @azure/identity paketi, uygulamanızın bunu yapmak için kullanabileceği çeşitli kimlik bilgisi türleri sağlar. @azure/identity için README, başlamanıza yönelik daha fazla ayrıntı ve örnek sağlar.

Azure VoiceLive servisiyle etkileşime girmek için sınıfın bir örneği VoiceLiveClient , bir hizmet uç noktası ve bir credential nesnesi oluşturmanız gerekir. Bu belgede gösterilen örnekler, yerel geliştirme ve üretim ortamları dahil olmak üzere çoğu senaryo için uygun olan , adlı DefaultAzureCredentialbir kimlik belgesi nesnesi kullanır. Üretim ortamlarında kimlik doğrulama için yönetilen bir kimlik kullanmanızı öneririz.

Farklı kimlik doğrulama yolları ve bunlara karşılık gelen kimlik bilgileri türleri hakkında daha fazla bilgiyi Azure Identity dokümantasyonunda bulabilirsiniz.

İşte hızlı bir örnek. İlk olarak, ithal DefaultAzureCredential ve 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);

API Anahtarı ile Doğrulama

Geliştirme senaryoları için, ayrıca bir API anahtarı kullanarak kimlik doğrulaması yapabilirsiniz:

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

Aşağıdaki bölümler, Azure VoiceLive kullanılarak kullanılan bazı yaygın görevleri kapsayan kod parçalarını sunmaktadır. Burada ele alınan senaryolar şunlardır:

• Temel bir sesli asistan oluşturmak
• Ajan tarafından desteklenen bir sesli asistan oluşturmak
• Oturum seçeneklerinin yapılandırılması
• Akış metin girişi
• Gerçek zamanlı olayların yönetimi
• Fonksiyon çağrısını uygulamak

Temel bir sesli asistan oluşturmak

Bu örnek, konuşmadan konuşmaya etkileşimleri yönetebilen basit bir sesli asistanın nasıl oluşturulacağını gösterir:

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

Ajan tarafından desteklenen bir sesli asistan oluşturmak

Bu örnek, bir Foundry ajanı tarafından desteklenen bir sesli asistan nasıl oluşturulacağını gösteriyor. Ajan modunda, ajanın yapılandırması Azure Yapay Zeka Atölyesi portalında yönetilir:

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

Oturum seçeneklerinin yapılandırılması

Sesli etkileşimin çeşitli yönlerini özelleştirebilirsiniz:

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

Modeldeki azure-realtime yerel sesleri önizlemek için, özel ses tipini kullanın:

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

Akış metin girişi

Ses göndermek yerine, metni olaylarla kademeli input_text.delta olarak bir konuşma öğesine aktarabilir ve tek input_text.done bir etkinlikle bitirebilirsiniz. Bu, metnin kendisi token-token üretildiğinde (örneğin başka bir modelden iletilirse) faydalıdır:

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

Gerçek zamanlı olayların yönetimi

VoiceLive istemcisi, gerçek zamanlı etkileşimler için olay odaklı iletişim sağlar:

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

Fonksiyon çağrısını uygulamak

Sesli asistanınızın dış fonksiyonları ve araçları aramasını sağlayın:

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

Sorun giderme

Yaygın hatalar ve özel durumlar

Kimlik Doğrulama Hataları: Kimlik doğrulama hataları alırsanız, şunu doğrulayın:

• Azure Yapay Zeka Atölyesi kaynağınız doğru şekilde yapılandırılmıştır
• API anahtarınız veya kimlik bilgileriniz gerekli izinlere sahiptir
• Uç nokta URL'si doğru ve erişilebilir

WebSocket Bağlantı Sorunları: VoiceLive WebSocket bağlantıları kullanıyor. Şunlardan emin olun:

• Ağınız WebSocket bağlantılarına izin veriyor
• Güvenlik duvarı kuralları bağlantılara izin verir *.cognitiveservices.azure.com
• Tarayıcı politikaları WebSocket ve mikrofon erişimine izin verir (tarayıcı kullanımı için)

Ses Sorunları: Ses ile ilgili sorunlar için:

• Tarayıcıda mikrofon izinlerini doğrulayın
• Ses formatlarının (PCM16, PCM24) desteklenip desteklenmediğinden emin olun
• Oynatma için doğru ses bağlamı kurulumunu sağlayın

Telemetri / Dağıtık Takip

VoiceLive SDK, paket üzerinden @azure/core-tracing etmeyi destekler. Takip no-op varsayılan olarak — OpenTelemetry'ye uygun bir takip sağlayıcısı kaydettirmediğiniz sürece aralıklar oluşturulmaz.

Nasıl çalışır?

Takip etkin olduğunda, SDK oturum yaşam döngüsü için otomatik olarak aralıklar oluşturur:

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

Span özellikleri, OpenTelemetry GenAI Anlamsal Sözleşmelerini (gen_ai.system, gen_ai.operation.name, gen_ai.request.model, vb.) ve VoiceLive'a özgü uzantıları (gen_ai.voice.session_id, gen_ai.voice.turn_count, gen_ai.voice.audio_bytes_sent, ...) takip eder. Oturum seviyesindeki metrikler, oturum sona erdiğinde bu connect aralık üzerinde toplanır.

İzlemeyi etkinleştir (Node.js, CommonJS — önerilir)

CommonJS uygulamaları için standart Azure SDK instrumentation bridge'i kullanın:

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

İzlemeyi etkinleştir (ESM ve tarayıcılarNode.js)

createAzureSdkInstrumentation CommonJS gerekli kancalara dayanır ve SDK ESM olarak yüklendiğinde (örneğin "type": "module" paketler veya Vite gibi tarayıcı paketleyicileri) hiç span üretmez. Bu ortamlar için, doğrudan bir minimumu InstrumenteruseInstrumenter şu noktadan @azure/core-tracingkaydedin:

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: () => ({}),
});

Bu, CommonJS köprüsüyle aynı açıklıklar üretir.

Tam, çalıştırılabilir örnekler:

• Node.js (ESM):samples/telemetry/ — konsol dışa aktarıcısı ve Azure İzleyici varyantı.
• Browser (Vite):samples/telemetry-browser/ — sayfa içi genişlik görüntüleyici.

Span öznitelikleri

SDK, GenAI Anlamsal Sözleşmelerine uygun nitelikleri belirler:

Attribute	Description
az.namespace	Her zaman Microsoft.CognitiveServices
gen_ai.system	Her zaman az.ai.voicelive
gen_ai.operation.name	connect, send, recvveya close
gen_ai.request.model	Model adı (örneğin, gpt-realtime)
gen_ai.voice.session_id	Sesli oturum kimliği session.created
gen_ai.voice.turn_count	Toplam tamamlanmış yanıt turları (bağlantı aralığı)
gen_ai.voice.interruption_count	Etkinlik response.cancel sayısı (bağlantı aralığı)
gen_ai.voice.audio_bytes_sent	Gönderilen toplam ses baytları (bağlantı aralığı)
gen_ai.voice.audio_bytes_received	Alınan toplam ses baytları (bağlantı aralığı)
gen_ai.voice.first_token_latency_ms	İlk ses/metin deltasına kadar olan zaman response.create
gen_ai.usage.input_tokens	Giriş token sayısı response.done
gen_ai.usage.output_tokens	Çıkış token sayısı response.done

Ağaç kesimi

Loglamayı etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. WebSocket mesajları ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini .info Alternatif olarak, çalışma zamanında setLogLevel@azure/logger çağrılarak günlük tutma etkinleştirilebilir.

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki Adımlar

Daha fazla kod örneğini aşağıdaki bağlantılardan bulabilirsiniz:

• VoiceLive Örnekleri (JavaScript/TypeScript)
• VoiceLive Test Vakaları

Contributing

Bu kitaplığa katkıda bulunmak isterseniz kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.