Erkunden der Azure Voice Live-API

Mit der VoIP-Live-API können Entwickler sprachfähige Anwendungen mit bidirektionaler Kommunikation in Echtzeit erstellen. Diese Einheit untersucht die Architektur, Konfiguration und Implementierung.

Wichtige Features der Voice Live-API

Die VoIP-Live-API bietet Echtzeitkommunikation mithilfe von WebSocket-Verbindungen. Es unterstützt erweiterte Features wie Spracherkennung, Text-zu-Sprache-Synthese, Avatarstreaming und Audioverarbeitung.

• JSON-formatierte Ereignisse verwalten Unterhaltungen, Audiodatenströme und Antworten.
• Ereignisse werden in Clientereignisse (die vom Client an Server gesendet werden) und Serverereignisse (die vom Server an den Client gesendet werden) unterteilt.

Zu den wichtigsten Features gehören:

• Echtzeitaudioverarbeitung mit Unterstützung für mehrere Formate wie PCM16 und G.711.
• Erweiterte Sprachoptionen, einschließlich OpenAI-Stimmen und benutzerdefinierte Azure-Stimmen.
• Avatarintegration mit WebRTC für Video und Animation.
• Integrierte Rauschminderung und Echounterdrückung.

Eine Tabelle mit unterstützten Modellen und Regionen finden Sie in der Übersicht über die Voice Live-API.

Herstellen einer Verbindung mit der Voice Live-API

Die VoIP-Live-API unterstützt zwei Authentifizierungsmethoden: Microsoft Entra (keyless) und API-Schlüssel. Microsoft Entra verwendet die tokenbasierte Authentifizierung für eine Microsoft Foundry-Ressource. Sie wenden ein abgerufenes Authentifizierungstoken mithilfe eines Bearer Tokens mit dem Authorization Header an.

Für die empfohlene schlüssellose Authentifizierung mit Microsoft Entra ID müssen Sie Ihrer Benutzerkonten oder einer verwalteten Identität die Rolle " Cognitive Services User " zuweisen. Sie generieren ein Token mithilfe der Azure CLI oder Azure SDKs. Das Token muss mit dem https://ai.azure.com/.default Bereich oder dem Legacybereich https://cognitiveservices.azure.com/.default generiert werden. Verwenden Sie das Token im Authorization Header der WebSocket-Verbindungsanforderung mit dem Format Bearer <token>.

Für den Schlüsselzugriff kann ein API-Schlüssel auf eine von zwei Arten bereitgestellt werden. Sie können einen api-key-Verbindungsheader für die Prehandshake-Verbindung verwenden. Diese Option ist in einer Browserumgebung nicht verfügbar. Sie können auch einen api-key Abfragezeichenfolgenparameter für den Anforderungs-URI verwenden. Abfragezeichenfolgenparameter werden bei Verwendung von https/wss verschlüsselt.

WebSocket-Endpunkt

Der zu verwendende Endpunkt hängt davon ab, wie Sie auf Ihre Ressourcen zugreifen möchten. Sie können über eine Verbindung mit dem AI Foundry-Projekt (Agent) oder über eine Verbindung mit dem Modell auf Ressourcen zugreifen.

• Projektverbindung: Der Endpunkt ist wss://<your-ai-foundry-resource-name>.services.ai.azure.com/voice-live/realtime?api-version=2025-10-01
• Modellverbindung: Der Endpunkt ist wss://<your-ai-foundry-resource-name>.cognitiveservices.azure.com/voice-live/realtime?api-version=2025-10-01.

Der Endpunkt ist für alle Modelle identisch. Der einzige Unterschied besteht aus dem erforderlichen model Abfrageparameter oder, wenn sie den Agent-Dienst, die Parameter und agent_id die project_id Parameter verwenden.

Voice Live-API-Ereignisse

Client- und Serverereignisse erleichtern die Kommunikation und Kontrolle innerhalb der VoIP-Live-API. Zu den wichtigsten Kundenereignissen gehören:

• session.update: Ändern von Sitzungskonfigurationen.
• input_audio_buffer.append: Fügen Sie dem Puffer Audiodaten hinzu.
• response.create: Antworten über Modellinferenz generieren.

Serverereignisse bieten Feedback und Statusaktualisierungen:

• session.updated: Sitzungskonfigurationsänderungen bestätigen.
• response.done: Geben Sie den Abschluss der Antwortgenerierung an.
• conversation.item.created: Benachrichtigen, wenn ein neues Unterhaltungselement hinzugefügt wird.

Eine vollständige Liste der Client-/Serverereignisse finden Sie in der Voice Live-API-Referenz.

Konfigurieren von Sitzungseinstellungen für die VoIP-Live-API

Häufig ist das erste Ereignis, das vom Anrufer in einer neu eingerichteten VoIP-Live-API-Sitzung gesendet wird, das session.update Ereignis. Dieses Ereignis steuert ein breites Eingabe- und Ausgabeverhalten. Sitzungseinstellungen können mithilfe des session.update Ereignisses dynamisch aktualisiert werden. Entwickler können Sprachtypen, Modalitäten, Wechselerkennung und Audioformate konfigurieren.

Beispielkonfiguration:

{
  "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"
  }
}

Echtzeitaudioverarbeitung mit der Voice-Live-API implementieren

Die Echtzeitaudioverarbeitung ist ein Kernfeature der VoIP-Live-API. Entwickler können Audiopuffer mithilfe bestimmter Clientereignisse anfügen, bestätigen und löschen.

• Audio anfügen: Fügen Sie dem Eingabepuffer Audiobytes hinzu.
• Audioverarbeitung: Verarbeiten des Audiopuffers für die Transkription oder Reaktionsgenerierung.
• Audio löschen: Entfernen Sie Audiodaten aus dem Puffer.

Rauschunterdrückung und Echounterdrückung können so konfiguriert werden, dass die Audioqualität verbessert wird. Beispiel:

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

Integrieren von Avatarstreaming mithilfe der Voice Live-API

Die VoIP-Live-API unterstützt webRTC-basiertes Avatarstreaming für interaktive Anwendungen. Entwickler können Video-, Animations- und Blendshape-Einstellungen konfigurieren.

• Verwenden Sie das session.avatar.connect Ereignis, um das SDP-Angebot des Kunden bereitzustellen.
• Konfigurieren Von Videoauflösungs-, Bitrate- und Codeceinstellungen.
• Definieren Sie Animationsausgaben wie Blendshapes und Visemen.

Beispielkonfiguration:

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