Verbindung öffnen

Der Speech to Text-Service verwendet das WSS-Protokoll (WSS = WebSocket Secure), um die Methode /v1/recognize am folgenden Endpunkt zur Verfügung zu stellen:

wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}/v1/recognize

Dabei gibt {location} an, an welcher Position Ihre Anwendung gehostet ist:

• us-south für Dallas
• us-east für Washington DC
• eu-de für Frankfurt
• au-syd für Sydney
• jp-tok für Tokio
• eu-gb für London
• kr-seo für Seoul

{instance_id} ist die eindeutige Kennung (ID) Ihrer Serviceinstanz.

In den Beispielen, die in der Dokumentation enthalten sind, wird wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id} mit {ws_url} abgekürzt. In allen WebSocket-Beispielen wird die Methode {ws_url}/v1/recognize aufgerufen.

Ein WebSocket-Client ruft die Methode /v1/recognize mit den folgenden Abfrageparametern auf, um eine authentifizierte Verbindung zum Service herzustellen. Diese Elemente der Anforderung können nur als Abfrageparameter der WebSocket-URL angegeben werden.

access_token (erforderliche Zeichenfolge)

Übergeben Sie ein gültiges Zugriffstoken, um eine authentifizierte Verbindung zum Service herzustellen. Sie müssen die Verbindung herstellen, bevor das Zugriffstoken abläuft. Ein Zugriffstoken muss nur übergeben werden, um eine authentifizierte Verbindung herzustellen. Nach dem Einrichten kann die Verbindung unbegrenzt offen gehalten werden. Sie bleiben authentifiziert, solange die Verbindung geöffnet ist. Das Zugriffstoken für eine Verbindung, die über die Tokenablaufzeit hinaus aktiv bleibt, muss nicht aktualisiert werden. Eine bestehende Verbindung kann auch nach dem Löschen des Tokens oder der zugehörigen Berechtigungsnachweise aktiv bleiben.

• IBM Cloud Übergeben Sie ein Identity and Access Management (IAM)-Zugriffstoken, um sich beim Dienst zu authentifizieren. Das IAM-Zugriffstoken wird in dem Aufruf anstelle eines API-Schlüssels übergeben. Weitere Informationen finden Sie unter Authentifizierung bei IBM Cloud.
• IBM Cloud Pak for DataIBM Software Hub Übergeben Sie ein Zugriffstoken wie den Authorization-Header einer HTTP-Anfrage. Weitere Informationen finden Sie unter "Authentifizierung bei IBM Cloud Pak for Data ".

model (optionale Zeichenfolge)

Gibt das Sprachmodell an, das für die Transkription verwendet werden soll. Wenn Sie kein Modell angeben, verwendet der Service standardmäßig en-US_BroadbandModel. Weitere Informationen finden Sie

• Große Sprachsprachen und Modelle
• Sprachen und Modelle der vorherigen Generation
• Sprachen und Modelle der nächsten Generation
• Standardmodell verwenden

language_customization_id (optionale Zeichenfolge)

Gibt die GUID (Globally Unique Identifier) eines angepassten Sprachmodells an, das für alle Anforderungen verwendet werden soll, die über die Verbindung gesendet werden. Das Basismodell des angepassten Sprachmodells muss mit dem Wert des Parameters model übereinstimmen. Wenn Sie die ID eines angepassten Sprachmodells angeben, muss die Anforderung mit Berechtigungsnachweisen der Serviceinstanz ausgeführt werden, die Eigner des angepassten Modells ist. Standardmäßig wird kein angepasstes Sprachmodell verwendet. Weitere Informationen finden Sie unter Angepasstes Sprachmodell für die Spracherkennung verwenden.

acoustic_customization_id (optionale Zeichenfolge)

Gibt die GUID eines angepassten Akustikmodells an, das für alle Anforderungen verwendet werden soll, die über die Verbindung gesendet werden. Das Basismodell des angepassten Akustikmodells muss mit dem Wert des Parameters model übereinstimmen. Wenn Sie die ID eines angepassten Akustikmodells angeben, muss die Anforderung mit den Berechtigungsnachweisen der Serviceinstanz ausgeführt werden, die Eigner des angepassten Modells ist. Standardmäßig wird kein angepasstes Akustikmodell verwendet. Weitere Informationen finden Sie unter Angepasstes Akustikmodell für die Spracherkennung verwenden.

base_model_version (optionale Zeichenfolge)

Gibt die Version des Basismodells (model) an, die für alle Anforderungen verwendet werden soll, die über die Verbindung gesendet werden. Dieser Parameter ist in erster Linie für die Verwendung mit angepassten Modellen bestimmt, für die ein Upgrade auf ein neues Basismodell durchgeführt wird. Der Standardwert ist davon abhängig, ob der Parameter mit oder ohne ein angepasstes Modell verwendet wird. Weitere Informationen finden Sie unter Spracherkennungsanforderungen mit aktualisierten angepassten Modellen erstellen.

x-watson-metadata (optionale Zeichenfolge)

Ordnet allen Daten die über die Verbindung gesendet werden, eine Kunden-ID zu. Der Parameter akzeptiert das Argument customer_id={id}; hierbei steht id für eine zufällige oder generische Zeichenfolge, die den Daten zugeordnet werden soll. Das Argument für den Parameter muss URL-codiert sein (z. B. customer_id%3dmy_customer_ID). Standardmäßig wird den Daten keine Kunden-ID zugeordnet. Weitere Informationen finden Sie im Abschnitt Informationssicherheit.

x-watson-learning-opt-out (optionaler boolescher Wert)

IBM Cloud Gibt an, ob der Dienst Protokolle über Anfragen und Ergebnisse erstellt, die über die Verbindung gesendet werden. Wenn Sie nicht zulassen möchten, dass Ihre Daten von IBM für die allgemeine Verbesserung des Service verwendet werden, geben Sie für diesen Parameter true an. Weitere Informationen finden Sie im Abschnitt Anforderungsprotokollierung.

Das folgende Snippet mit JavaScript-Code öffnet eine Verbindung zum Service. Der Aufruf der Methode /v1/recognize übergibt die Abfrageparameter access_token und model, wobei der zweite Parameter den Service anweist, das Breitbandmodell für Spanisch zu verwenden. Nach dem Herstellen der Verbindung definiert der Client die Ereignislistener (onOpen, onClose usw.), um auf Ereignisse vom Service zu antworten. Der Client kann die Verbindung für mehrere Erkennungsanforderungen verwenden.

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/recognize'
  + '?access_token=' + access_token
  + '&model=es-ES_BroadbandModel';
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

Der Client kann mehrere gleichzeitig aktive WebSocket-Verbindungen zum Service öffnen. Die Anzahl der gleichzeitig bestehenden Verbindungen ist nur durch die Kapazität des Service begrenzt, was für die Benutzer in der Regel keine Probleme darstellt.

Erkennungsanforderung einleiten

Um eine Erkennungsanforderung einzuleiten, sendet der Client über die bestehende Verbindung eine JSON-Textnachricht an den Service. Der Client muss diese Nachricht senden, bevor Audiodaten zum Transkribieren gesendet werden. Der Parameter action muss in der Nachricht enthalten sein. Der Parameter content-type kann in der Regel weggelassen werden:

action (erforderliche Zeichenfolge)

Gibt die Aktion an, die ausgeführt werden soll:

• start startet eine Erkennungsanforderung. Außerdem können neue Parameter für nachfolgende Anforderungen angegeben werden. Weitere Informationen finden Sie im Abschnitt Zusätzliche Anforderungen senden und Anforderungsparameter ändern.
• stop gibt an, dass alle Audiodaten für eine Anforderung gesendet wurden. Weitere Informationen finden Sie im Abschnitt Erkennungsanforderung beenden.

content-type (optionale Zeichenfolge)

Gibt das Format (MIME-Typ) der Audiodaten für die Anforderung an. Dieser Parameter ist für die Formate audio/alaw, audio/basic, audio/l16 und audio/mulaw erforderlich. Weitere Informationen finden Sie unter Audioformate.

Die Nachricht kann außerdem optionale Parameter enthalten, die andere Aspekte für die Verarbeitung der Anforderung sowie die zurückzugebenden Informationen angeben. Zu diesen zusätzlichen Parameter gehört der Parameter interim_results, der nur mit der WebSocket-Schnittstelle verfügbar ist.

• Weitere Informationen zu allen Spracherkennungsfunktionen finden Sie in der Parameterübersicht.
• Weitere Informationen zum Parameter interim_results finden Sie unter Zwischenergebnisse.

Das folgende Snippet mit JavaScript-Code sendet Initialisierungsparameter für die Erkennungsanforderung über die WebSocket-Verbindung. Die Aufrufe sind in der Funktion onOpen des Clients enthalten, um sicherzustellen, dass sie erst gesendet werden, nachdem die Verbindung hergestellt wurde.

function onOpen(evt) {
  var message = {
    action: 'start',
    content-type: 'audio/l16;rate=22050'
  };
  websocket.send(JSON.stringify(message));
}

Wenn die Anforderung erfolgreich empfangen wird, gibt der Service die folgende Textnachricht zurück, um anzuzeigen, dass es sich um listening handelt: Der Status listening gibt an, dass die Serviceinstanz konfiguriert ist (die JSON-Nachricht start war gültig) und Audiodaten für eine Erkennungsanforderung empfangen werden können.

{'state': 'listening'}

Wenn der Client einen ungültigen Abfrageparameter oder ein ungültiges JSON-Feld für die Erkennungsanforderung angibt, enthält die JSON-Antwort ein Feld warnings. In dem Feld werden alle ungültigen Argumente beschrieben. Die Anforderung wird ungeachtet der Warnungen erfolgreich ausgeführt.

Audiodaten senden und Erkennungsergebnisse empfangen

Nach dem Senden der ursprünglichen Nachricht start, kann der Client mit dem Senden von Audiodaten an den Service beginnen. Der Client wartet nicht, bis der Service die Nachricht start mit der Nachricht listening beantwortet hat. Sobald der ervice empfangsbereit ist, werden alle Audiodaten verarbeitet, die vor dem Ausgeben der Nachricht listening gesendet wurden.

Der Client muss die Audiodaten als binäre Daten senden. Der Client kann maximal 100 MB Audiodaten pro Anforderung send-Anforderung senden. Für jede Anforderung muss der Client mindestens 100 Byte an Audiodaten senden. Der Client kann mehrere Anforderungen über eine einzelne WebSocket-Verbindung senden. Informationen zur Verwendung der Komprimierung, um die Menge der Audiodaten zu maximieren, die mit einer Anforderung an den Service übergeben werden kann, finden Sie unter Datengrenzwerte und Komprimierung.

Für die WebSocket-Schnittstelle gilt eine maximale Rahmengröße von 4 MB. Der Client kann als maximale Rahmengröße einen Wert kleiner als 4 MB festlegen. Wenn das Festlegen der Rahmengröße nicht sinnvoll ist, kann der Client die maximale Nachrichtengröße auf einen Wert kleiner als 4 MB festlegen und die Audiodaten als eine Folge von Nachrichten senden. Weitere Informationen zu WebSocket-Frames finden Sie unter IETF RFC 6455.

Wie der Service Erkennungsergebnisse über eine WebSocket-Verbindung sendet, hängt davon ab, ob der Client Zwischenergebnisse anfordert. Weitere Informationen finden Sie unter Senden von Erkennungsergebnissen durch den Service.

Das folgende Snippet mit JavaScript-Code sendet Audiodaten als binäre Nachricht (BLOB) an den Service:

websocket.send(blob);

Das folgende Codesnippet empfängt vom Service zurückgegebene Erkennungshypothesen asynchron. Die Ergebnisse werden von der Funktion onMessage des Clients verarbeitet.

function onMessage(evt) {
  console.log(evt.data);
}

Ihr Code muss in der Lage sein, Rückgabecodes vom Service zu verarbeiten. Weitere Informationen finden Sie unter WebSocket-Rückgabecodes.

Erkennungsanforderung beenden

Wenn das Senden der Audiodaten für eine Anforderung an den Service abgeschlossen ist, muss der Client das Ende der binären Audiodatenübertragung zum Service auf eine der folgenden Arten kenntlich machen:

• Durch Senden einer JSON-Textnachricht, mit einem Parameter action, der auf den Wert stop gesetzt ist:

  {action: 'stop'}
  

• Durch Senden einer leeren binären Nachricht, in der das angegebene BLOB leer ist:

  websocket.send(blob)
  

Wenn der Client nicht signalisiert, dass die Übertragung abgeschlossen ist, kann das Zeitlimit der Verbindung überschritten werden, bevor der Service Endergebnisse sendet. Um zwischen mehreren Erkennungsanforderungen endgültige Ergebnisse zu empfangen, muss der Client das Ende der Übertragung für die vorherige Anforderung signalisieren, bevor die nächste Anforderung gesendet wird. Nachdem der Service die endgültigen Ergebnisse für die erste Anforderung zurückgegeben hat, gibt er eine weitere Nachricht {"state":"listening"} an den Client zurück. Diese Nachricht gibt an, dass der Service bereit ist, eine weitere Anforderung zu empfangen.

Weitere Anforderungen senden und Anforderungsparameter ändern

Solange die WebSocket-Verbindung aktiv ist, kann der Client die Verbindung nutzen, um weitere Erkennungsanforderungen mit neuen Audiodaten zu senden. Standardmäßig verwendet der Service die mit der vorherigen Nachricht start übergebenen Parameter für alle nachfolgenden Anforderungen, die über dieselbe Verbindung gesendet werden.

Um die Parameter für nachfolgende Anforderungen zu ändern, kann der Client eine weitere Nachricht start mit den neuen Parametern senden, nachdem er die Endergebnisse der Erkennung und eine neue Nachricht {"state":"listening"} vom Service empfangen hat. Der Client kann alle Parameter ändern, außer denen, die beim Öffnen der Verbindung angegeben wurden (model, language_customization_id usw.).

Im folgenden Beispiel wird eine Nachricht start mit neuen Parametern für nachfolgende Erkennungsanforderungen gesendet, die über die Verbindung übertragen werden. In der Nachricht wird derselbe Parameter content-type wie im vorherigen Beispiel angegeben, aber der Service wird angewiesen, Konfidenzwerte und Zeitmarken für die Wörter der Transkription zurückzugeben.

var message = {
  action: 'start',
  content-type: 'audio/l16;rate=22050',
  word_confidence: true,
  timestamps: true
};
websocket.send(JSON.stringify(message));

Verbindung offen halten

Der Service beendet die Sitzung und trennt die Verbindung, wenn eine Zeitlimitüberschreitung für Inaktivität oder Sitzungsdauer auftritt:

• Eine Inaktivitätszeitlimitüberschreitung tritt auf, wenn der Service in den vom Client gesendeten Audiodaten keine gesprochenen Äußerungen erkennen kann. Der Standardwert für das Inaktivitätszeitlimit sind 30 Sekunden. Mit dem Parameter inactivity_timeout können Sie einen anderen Wert angeben (z. B. auch den Wert -1 für ein unbegrenztes Zeitlimit). Weitere Informationen finden Sie im Abschnitt Inaktivitätszeitlimit.
• Eine Sitzungszeitlimitüberschreitung tritt auf, wenn der Service keine Daten vom Client empfängt oder 30 Sekunden lang keine Zwischenergebnisse sendet. Die Länge dieses Zeitlimits kann nicht geändert werden, aber Sie können die Sitzung aktiv halten, indem Sie einfach beliebige Audiodaten (z. B. Sprechpausen) an den Service senden, bevor das Zeitlimit abläuft. Außerdem müssen Sie den Parameter inactivity_timeout auf den Wert -1 setzen. Die Übertragungszeit für die Daten, die Sie an den Service senden (einschließlich der Sprechpausen, um eine Sitzung aktiv zu halten), wird Ihnen in Rechnung gestellt. Weitere Informationen finden Sie im Abschnitt zum Sitzungszeitlimit.

WebSocket-Clients und -Server können auch Ping-Pong-Rahmen austauschen, um Lesezeitlimits zu vermeiden, indem sie regelmäßig kleine Datenmengen austauschen. Viele, aber nicht alle WebSocket-Stacks tauschen Ping-Pong-Rahmen aus. Überprüfen Sie die Featureliste Ihrer Implementierung, um festzustellen, ob sie Ping-Pong-Rahmen verwendet. Sie können Ping-Pong-Rahmen nicht programmgesteuert ermitteln oder verwalten.

Wenn in Ihrem WebSocket-Stack keine Ping-Pong-Rahmen implementiert sind und Sie lange Audiodateien senden, kann es bei Ihrer Verbindung zu einer Lesezeitüberschreitung kommen. Um solche Zeitlimitüberschreitungen zu vermeiden, streamen Sie Audiodaten kontinuierlich an den Service oder fordern Sie Zwischenergebnisse von dem Service an. Mit jeder dieser Methoden kann sichergestellt werden, dass Ihre Verbindung nicht wegen fehlender Ping-Pong-Rahmen geschlossen wird.

Weitere Informationen zu Ping-Pong-Rahmen finden Sie in Abschnitt 5.5.2 Ping und Abschnitt 5.5.3 Pong von IETF RFC 6455.

Verbindung schließen

Wenn die Interaktion des Clients mit dem Service beendet ist, kann die WebSocket-Verbindung geschlossen werden. Nach dem Schließen der Verbindung, kann der Client über die Verbindung keine Anforderungen mehr senden und keine Ergebnisse mehr empfangen. Beenden Sie die Verbindung erst, nachdem der Client alle Ergebnisse für eine Anforderung empfangen hat. Die Verbindung wird automatisch beendet, sobald das Zeitlimit erreicht ist, sofern sie nicht vom Client explizit beendet wird.

Das folgende Snippet mit JavaScript-Code schließt eine bestehende Verbindung:

websocket.close();

Beispielanforderung ohne Zwischenergebnisse

Der Client inaktiviert Zwischenergebnisse, indem der Parameter interim_results auf false gesetzt wird, oder wenn der Parameter in einer Anforderung fehlt (das Standardargument für den Parameter ist false). Der Client empfängt ein einzelnes JSON-Objekt als Antwort, nachdem eine Nachricht stop gesendet wurde.

Das Antwortobjekt kann mehrere Endergebnisse für separate Äußerungen in den Audiodaten enthalten. Der Service sendet das einzelne Antwortobjekt erst, nachdem er eine Nachricht stop empfangen hat, die angibt, dass die Übertragung der Audiodaten für die Anforderung abgeschlossen ist. Struktur und Format der Antwort vom Service sind gleich, unabhängig davon, ob Sie ein Modell der vorherigen oder der nächsten Generation verwenden.

{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "one two "
        }
      ],
      "final": true
    },
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "three four "
        }
      ],
      "final": true
    }
  ]
}

Beispielanforderung mit Zwischenergebnissen

Der Client fordert Zwischenergebnisse wie folgt an:

• Modelle der vorherigen Generation: Durch Festlegen des Parameters interim_results auf true.
• Modelle der nächsten Generation: Durch Festlegen der beiden Parameter interim_results und low_latency auf true. Um Zwischenergebnisse für ein Modell der nächsten Generation zu empfangen, muss das Modell geringe Latenzzeit unterstützen und die Parameter interim_results und low_latency müssen auf true gesetzt werden.
  • Weitere Informationen dazu, welche Modelle der nächsten Generation geringe Latenzzeit unterstützen, finden Sie in Unterstützte Modelle der nächsten Generation.
  • Weitere Informationen zur Interaktion der Parameter interim_results und low_latency mit Modellen der nächsten Generation (einschließlich Beispielen für die verschiedenen Kombinationen der Parameter) finden Sie unter Zwischenergebnisse und geringe Latenzzeit anfordern.

Der Client empfängt als Antwort mehrere JSON-Objekte. Der Service gibt separate Antwortobjekte für jedes Zwischenergebnis und für jedes Endergebnis zurück, das für die Audiodaten generiert wird. Der Service sendet mindestens ein Zwischenergebnis für jedes Endergebnis.

Der Service sendet Antworten, sobald sie verfügbar sind. Er wartet nicht darauf, dass eine Nachricht stop die eigenen Ergebnisse sendet. Dennoch muss die Nachricht stop das Ende der Datenübertragung für die Anforderung melden. Struktur und Format der Antwort vom Service sind gleich, unabhängig davon, ob Sie ein Modell der vorherigen oder der nächsten Generation verwenden.

{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "one "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "one two "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "one two "
        }
      ],
      "final": true
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "three "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "three four "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "three four "
        }
      ],
      "final": true
    }
  ]
}

Erster Beispielaustausch

Im ersten Austausch sendet der Client Audiodaten, in denen die Zeichenfolge Name the Mayflower enthalten ist. Der Client sendet eine binäre Nachricht mit einem einzigen Block von PCM-Audiodaten (audio/l16) und gibt die dafür erforderliche Abtastrate an. Der Client wartet nicht auf die Antwort {"state":"listening"} vom Service, bevor mit dem Senden der Audiodaten begonnen und das Ende der Anforderung signalisiert wird. Durch das sofortige Senden der Daten wird die Latenzzeit verringert, da die Audiodaten für den Service verfügbar sind, sobald er bereit ist, die Erkennungsanforderung zu verarbeiten.

• Der Client sendet Folgendes:

  {
    "action": "start",
    "content-type": "audio/l16;rate=22050"
  }
  <binary audio data>
  {
    "action": "stop"
  }
  

• Der Service antwortet wie folgt:

  {"state": "listening"}
  {"results": [{"alternatives": [{"transcript": "name the mayflower ",
               "confidence": 0.91}], "final": true}], "result_index": 0}
  {"state":"listening"}
  

Zweiter Beispielaustausch

Im zweiten Austausch sendet der Client Audiodaten, in denen die Zeichenfolge Second audio transcript enthalten ist. Der Client sendet die Audiodaten in einer einzigen binären Nachricht und verwendet die gleichen Parameter, die er in der ersten Anforderung angegeben hat.

• Der Client sendet Folgendes:

  <binary audio data>
  {
    "action": "stop"
  }
  

• Der Service antwortet wie folgt:

  {"results": [{"alternatives": [{"transcript": "second audio transcript ",
               "confidence": 0.99}], "final": true}], "result_index": 0}
  {"state":"listening"}
  

Dritter Beispielaustausch

Im dritten Austausch sendet der Client wieder Audiodaten, in denen die Zeichenfolge Name the Mayflower enthalten ist. Er sendet eine binäre Nachricht mit einem einzelnen Block mit PCM-Audiodaten. Diesmal sendet der Client jedoch eine neue Nachricht start, die Zwischenergebnisse vom Service anfordert.

• Der Client sendet Folgendes:

  {
    "action": "start",
    "content-type": "audio/l16;rate=22050",
    "interim_results": true
  }
  <binary audio data>
  {
    "action": "stop"
  }
  

• Der Service antwortet wie folgt:

  {"results": [{"alternatives": [{"transcript": "name "}],
               "final": false}], "result_index": 0}
  {"results": [{"alternatives": [{"transcript": "name may "}],
               "final": false}], "result_index": 0}
  {"results": [{"alternatives": [{"transcript": "name may flour "}],
               "final": false}], "result_index": 0}
  {"results": [{"alternatives": [{"transcript": "name the mayflower ",
               "confidence": 0.91}], "final": true}], "result_index": 0}
  {"state":"listening"}