Aracılığıyla paylaş

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

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-4o, GPT-4o-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

Önkoşullar

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.

Temel 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, yüksek çözünürlüklü sesler veya özel sesler arasından seçim yapabilirsiniz
  • Model Seçimi: İhtiyaçlarınıza en uygun yapay zeka modelini (GPT-4o, GPT-4o-mini, 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-4o-realtime-preview Gerçek zamanlı ses işleme ile GPT-4o Yüksek kaliteli konuşma yapay zekası
gpt-4o-mini-realtime-preview Hafif GPT-4o varyantı Hızlı ve verimli etkileşimler
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

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

Örnekler

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

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

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

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

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

Sorun giderme

Yaygın hatalar ve özel durumlar

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

  • Azure AI Foundry 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

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:

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.

  • Last updated on