Eksplorowanie interfejsu API usługi Azure Voice Live

Ukończone

Interfejs API głosu na żywo umożliwia deweloperom tworzenie aplikacji z obsługą głosu przy użyciu komunikacji dwukierunkowej w czasie rzeczywistym. W tej lekcji omówiono jej architekturę, konfigurację i implementację.

Kluczowe funkcje interfejsu API Voice Live

Interfejs API Voice Live zapewnia komunikację w czasie rzeczywistym przy użyciu połączeń protokołu WebSocket. Obsługuje zaawansowane funkcje, takie jak rozpoznawanie mowy, synteza mowy, strumieniowanie awatara i przetwarzanie audio.

• Zdarzenia sformatowane w formacie JSON zarządzają konwersacjami, strumieniami audio i odpowiedziami.
• Zdarzenia są podzielone na kategorie zdarzeń klienta (wysyłanych z klienta do serwera) i zdarzeń serwera (wysyłanych z serwera do klienta).

Najważniejsze funkcje:

• Przetwarzanie audio w czasie rzeczywistym z obsługą wielu formatów, takich jak PCM16 i G.711.
• Zaawansowane opcje głosowe, w tym głosy OpenAI i niestandardowe głosy Azure.
• Integracja awatara przy użyciu narzędzia WebRTC do wideo i animacji.
• Wbudowana redukcja szumu i anulowanie echa.

Uwaga / Notatka

Interfejs API voice Live jest zoptymalizowany pod kątem zasobów firmy Microsoft Foundry. Zalecamy korzystanie z zasobów rozwiązania Microsoft Foundry w celu zapewnienia pełnej dostępności funkcji i najlepszego środowiska integracji rozwiązania Microsoft Foundry.

Aby zapoznać się z tabelą obsługiwanych modeli i regionów, zapoznaj się z omówieniem interfejsu API voice live.

Łączenie z Voice Live API

Interfejs API live głosowy obsługuje dwie metody uwierzytelniania: Microsoft Entra (bez klucza) i klucz API. Firma Microsoft Entra używa uwierzytelniania opartego na tokenach dla zasobu microsoft Foundry. Używasz pobranego tokenu uwierzytelniania, stosując token Bearer z nagłówkiem Authorization.

W przypadku zalecanego uwierzytelniania bez klucza przy użyciu identyfikatora Entra firmy Microsoft należy przypisać rolę użytkownika usług Cognitive Services do konta użytkownika lub tożsamości zarządzanej. Token jest generowany przy użyciu interfejsu wiersza polecenia platformy Azure lub zestawów SDK platformy Azure. Token musi zostać wygenerowany z zakresem https://ai.azure.com/.default lub starszym https://cognitiveservices.azure.com/.default zakresem. Użyj tokenu w Authorization nagłówku żądania połączenia protokołu WebSocket z formatem Bearer <token>.

W przypadku dostępu do klucza klucz interfejsu API można udostępnić na jeden z dwóch sposobów. Możesz użyć nagłówka api-key połączenia na połączeniu przed nawiązaniem handshake. Ta opcja nie jest dostępna w środowisku przeglądarki. Możesz też użyć parametru api-key ciągu zapytania w identyfikatorze URI żądania. Parametry ciągu zapytania są szyfrowane podczas korzystania z protokołu https/wss.

Uwaga / Notatka

api-key Nagłówek połączenia w połączeniu przed handshake nie jest dostępny w środowisku przeglądarki.

Punkt końcowy protokołu WebSocket

Punkt końcowy do użycia różni się w zależności od sposobu uzyskiwania dostępu do zasobów. Dostęp do zasobów można uzyskać za pośrednictwem połączenia z projektem AI Foundry (Agent) lub za pośrednictwem połączenia z modelem.

• Połączenie projektu: Punkt końcowy to wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01
• Połączenie modelu: Punkt końcowy to wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01.

Punkt końcowy jest taki sam dla wszystkich modeli. Jedyną różnicą jest wymagany model parametr zapytania lub, w przypadku korzystania z usługi Agent, agent_id parametry i project_id .

Zdarzenia usługi Voice Live API

Zdarzenia klienta i serwera ułatwiają komunikację i kontrolę w interfejsie API na żywo głosowe. Kluczowe zdarzenia klienta obejmują:

• session.update: Modyfikowanie konfiguracji sesji.
• input_audio_buffer.append: Dodaj dane audio do buforu.
• response.create: Generuj odpowiedzi za pomocą wnioskowania modelu.

Zdarzenia serwera zawierają opinie i aktualizacje stanu:

• session.updated: Potwierdź zmiany konfiguracji sesji.
• response.done: wskazuje ukończenie generowania odpowiedzi.
• conversation.item.created: Powiadom o dodaniu nowego elementu konwersacji.

Dla pełnej listy zdarzeń klienta/serwera, odwiedź Voice Live API Reference.

Uwaga / Notatka

Właściwa obsługa zdarzeń zapewnia bezproblemową interakcję między klientem a serwerem.

Konfigurowanie ustawień sesji dla głosowego interfejsu API Live

Często pierwszym zdarzeniem wysyłanym przez wywołującego w nowo utworzonej sesji interfejsu API Voice Live jest zdarzenie session.update. To zdarzenie steruje szerokim zestawem zachowania danych wejściowych i wyjściowych. Ustawienia sesji można aktualizować dynamicznie przy użyciu session.update zdarzenia. Deweloperzy mogą konfigurować typy głosów, modalności, wykrywanie obrotu i formaty audio.

Przykładowa konfiguracja:

{
  "type": "session.update",
  "session": {
    "modalities": ["text", "audio"],
    "voice": {
      "type": "openai",
      "name": "alloy"
    },
    "instructions": "You are a helpful assistant. Be concise and friendly.",
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "turn_detection": {
      "type": "azure_semantic_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    },
    "temperature": 0.8,
    "max_response_output_tokens": "inf"
  }
}

Wskazówka

Użyj semantycznego VAD platformy Azure do inteligentnego wykrywania zmian i ulepszonego przepływu konwersacji.

Implementowanie przetwarzania dźwięku w czasie rzeczywistym z użyciem Voice Live API

Przetwarzanie dźwięku w czasie rzeczywistym jest podstawową funkcją API Voice Live. Deweloperzy mogą dołączać, zatwierdzać i czyścić bufory audio za pomocą określonych zdarzeń klienta.

• Dołącz dźwięk: Dodaj bajty audio do buforu wejściowego.
• Zatwierdź dźwięk: Przetwórz bufor dźwięku do transkrypcji lub generowania odpowiedzi.
• Wyczyść dźwięk: Usuń dane audio z buforu.

Redukcję szumu i anulowanie echa można skonfigurować w celu zwiększenia jakości dźwięku. Przykład:

{
  "type": "session.update",
  "session": {
    "input_audio_noise_reduction": {
      "type": "azure_deep_noise_suppression"
    },
    "input_audio_echo_cancellation": {
      "type": "server_echo_cancellation"
    }
  }
}

Uwaga / Notatka

Redukcja szumów poprawia dokładność vaD i wydajność modelu przez filtrowanie dźwięku wejściowego.

Integrowanie przesyłania strumieniowego awatara przy użyciu Voice Live API

Interfejs API głosu na żywo obsługuje przesyłanie strumieniowe awatarów opartych na protokole WebRTC dla aplikacji interaktywnych. Deweloperzy mogą konfigurować ustawienia wideo, animacji i blendshape.

• Użyj zdarzenia session.avatar.connect, aby przekazać ofertę SDP klienta.
• Konfigurowanie ustawień rozdzielczości, przepływności i kodeków wideo.
• Zdefiniuj dane wyjściowe animacji, takie jak blendshapes i visemes.

Przykładowa konfiguracja:

{
  "type": "session.avatar.connect",
  "client_sdp": "<client_sdp>"
}

Wskazówka

Użyj ustawień wideo o wysokiej rozdzielczości, aby zwiększyć jakość wizualizacji w interakcjach awatara.