Apri una connessione

Il servizio Speech to Text utilizza il protocollo WSS (WebSocket Secure) per rendere il metodo /v1/recognize disponibile al seguente endpoint:

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

dove {location} indica dove viene ospitata la tua applicazione:

• us-south per Dallas
• us-east per Washington, DC
• eu-de per Francoforte
• au-syd per Sydney
• jp-tok per Tokyo
• eu-gb per Londra
• kr-seo per Seul

E {instance_id} è l'identificatore unico dell'istanza del servizio.

Gli esempi nella documentazione abbreviano wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id} con {ws_url}. Tutti gli esempi di WebSocket chiamano il metodo come {ws_url}/v1/recognize.

Un client WebSocket chiama il metodo /v1/recognize con i seguenti parametri di query per stabilire una connessione autenticata con il servizio. È possibile specificare questi aspetti della richiesta solo come parametri di query dell' WebSocket URL.

access_token (stringaobbligatoria )

Passa un token di accesso valido per stabilire una connessione autenticata con il servizio. Devi stabilire la connessione prima di che il token di accesso scada. Passa un token di accesso solo per stabilire una connessione autenticata. Dopo aver stabilito una connessione, puoi mantenerla attiva a tempo indefinito. Rimani autenticato finché mantieni la connessione aperta. Non devi aggiornare il token di accesso per una connessione attiva che va oltre l'ora di scadenza del token. Una volta stabilita una connessione, questa può rimanere attiva anche dopo l'eliminazione del token o delle sue credenziali.

• IBM Cloud Trasmetti un token di accesso Identity and Access Management (IAM) per autenticarti con il servizio. Passa un token di accesso IAM invece di passare una chiave API con la chiamata. Per ulteriori informazioni, vedere Autenticazione a IBM Cloud.
• IBM Cloud Pak for Data Software Hub IBM Passa un token di accesso come faresti con il Authorization intestazione di una richiesta HTTP. Per ulteriori informazioni, vedere Autenticazione a IBM Cloud Pak for Data.

model (stringafacoltativa )

Specifica il modello di lingua che deve essere utilizzato per la trascrizione. Se non si specifica un modello, il servizio utilizza per default en-US_BroadbandModel. Per ulteriori informazioni, vedi

• Lingue e modelli vocali di grandi dimensioni
• Modelli e lingue di generazione precedente
• Modelli e lingue di nuova generazione
• Utilizzo del modello predefinito

language_customization_id (stringafacoltativa )

Specifica il GUID (globally unique identifier) di un modello di lingua personalizzato che deve essere utilizzato per tutte le richieste inviate sulla connessione. Il modello di base di un modello di lingua personalizzato deve corrispondere al valore del parametro model. Se si include l'ID di un modello linguistico personalizzato, è necessario effettuare la richiesta con le credenziali dell'istanza del servizio che possiede il modello personalizzato. Per impostazione predefinita, non viene utilizzato alcun modello di lingua personalizzato. Per ulteriori informazioni, vedi Utilizzo di un modello di lingua personalizzato per il riconoscimento vocale.

acoustic_customization_id (stringafacoltativa )

Specifica il GUID di un modello acustico personalizzato che deve essere usato per tutte le richieste inviate sulla connessione. Il modello di base di un modello acustico personalizzato deve corrispondere al valore del parametro model. Se si include un ID di modello acustico personalizzato, è necessario effettuare la richiesta con le credenziali dell'istanza del servizio che possiede il modello personalizzato. Per impostazione predefinita, non viene utilizzato alcun modello acustico personalizzato. Per ulteriori informazioni, consulta Utilizzo di un modello acustico personalizzato per il riconoscimento vocale.

base_model_version (stringafacoltativa )

Specifica la versione del modello (model) di base che deve essere utilizzato per tutte le richieste inviate tramite la connessione. Il parametro è concepito principalmente per l'utilizzo con i modelli personalizzati che sono stati aggiornati a un nuovo modello di base. Il valore predefinito dipende dal fatto che il parametro sia utilizzato con o senza un modello personalizzato. Per ulteriori informazioni, vedi Esecuzione di richieste di riconoscimento vocale con i modelli personalizzati di cui è stato eseguito l'upgrade.

x-watson-metadata (stringafacoltativa )

Associa un ID cliente a tutti i dati passati tramite la connessione. Il parametro accetta l'argomento customer_id={id}, dove id è una stringa casuale o generica che deve essere associata ai dati. Devi codificare in URL l'argomento nel parametro, ad esempio, customer_id%3dmy_customer_ID. Per impostazione predefinita, nessun ID cliente è associato ai dati. Per ulteriori informazioni, vedi Sicurezza delle informazioni.

x-watson-learning-opt-out (booleanofacoltativo )

IBM Cloud Indica se il servizio registra le richieste e i risultati inviati tramite la connessione. Per impedire che IBM acceda ai tuoi dati per miglioramenti del servizio generali, specifica true per il parametro. Per ulteriori informazioni, vedi Registrazione delle richieste.

Il seguente frammento di codice JavaScript apre una connessione con il servizio. La chiamata al metodo /v1/recognize passa i parametri di query access_token e model, per indirizzare il servizio all'utilizzo del modello a banda larga per lo spagnolo. Dopo aver stabilito la connessione, il client definisce i listener di eventi (onOpen, onClose e così via) per rispondere agli eventi dal servizio. Il client può utilizzare la connessione per più richieste di riconoscimento.

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

Il client può aprire più connessioni WebSocket simultanee al servizio. Il numero di connessioni simultanee è limitato solo dalla capacità del servizio, che generalmente non implica problemi per gli utenti.

Avvia una richiesta di riconoscimento

Per avviare una richiesta di riconoscimento, il client invia un messaggio di testo JSON al servizio sulla connessione stabilita. Il client deve inviare questo messaggio prima di inviare dell'audio per la trascrizione. Il messaggio deve includere il parametro action, ma di solito può omettere il parametro content-type:

action (stringaobbligatoria )

Specifica l'azione che deve essere eseguita:

• start inizia una richiesta di riconoscimento. Può anche specificare nuovi parametri per le richieste successive. Per ulteriori informazioni, vedi Invia ulteriori richieste e modifica i parametri della richiesta.
• stop indica che tutto l'audio di una richiesta è stato inviato. Per ulteriori informazioni, vedi Termina una richiesta di riconoscimento.

content-type (stringafacoltativa )

Identifica il formato (tipo MIME) dei dati audio per la richiesta. Il parametro è obbligatorio per i formati audio/alaw, audio/basic, audio/l16 e audio/mulaw. Per ulteriori informazioni, vedi Formati audio.

Il messaggio può anche includere dei parametri facoltativi per specificare altri aspetti di come la richiesta deve essere elaborata e le informazioni che devono essere restituite. Questi parametri aggiuntivi includono il parametro interim_results, che è disponibile solo con l'interfaccia WebSocket.

• Per ulteriori informazioni su tutte le funzioni di riconoscimento vocale, vedi Riepilogo dei parametri.
• Per ulteriori informazioni sul parametro interim_results, consultare Risultati provvisori.

Il seguente frammento di codice JavaScript invia i parametri di inizializzazione per la richiesta di riconoscimento sulla connessione WebSocket. Le chiamate vengono incluse nella funzione onOpen del client per garantire che siano inviate soltanto dopo che viene stabilita la connessione.

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

Se riceve la richiesta con successo, il servizio restituisce il seguente messaggio di testo per indicare che è listening. Lo stato listening indica che l'istanza del servizio è configurata (il messaggio JSON start era valido) ed è pronta ad accettare l'audio per una richiesta di riconoscimento.

{'state': 'listening'}

Se il client specifica un parametro di query o un campo JSON non valido per la richiesta di riconoscimento, la risposta JSON del servizio include un campo warnings. Il campo descrive tutti gli argomenti non validi. La richiesta ha esito positivo nonostante le avvertenze.

Invia l'audio e ricevi i risultati del riconoscimento

Dopo aver inviato il messaggio iniziale start, il client può iniziare a inviare dati audio al servizio. Il client non deve attendere che il servizio risponda al messaggio start con il messaggio listening. Una volta che è in ascolto, il servizio elabora tutto l'audio che è stato inviato prima del messaggio listening.

Il client deve inviare l'audio come dati binari. Il client può inviare un massimo di 100 MB di dati audio per ogni richiesta a send. Deve inviare almeno 100 byte di audio per ogni richiesta. Il client può inviare più richieste su una singola connessione WebSocket. Per informazioni sull'uso della compressione per massimizzare la quantità di audio che si può passare al servizio con una richiesta, vedere Limiti di dati e compressione.

L'interfaccia WebSocket impone una dimensione del frame massima di 4 MB. Il client può impostare la dimensione del frame massima su un valore inferiore a 4 MB. Se non è pratico impostare la dimensione del frame, il client può impostare la dimensione del messaggio massima su un valore inferiore di 4 MB e inviare i dati audio come una sequenza di messaggi. Per ulteriori informazioni su WebSocket frame, vedere IETF RFC 6455.

Il modo in cui il servizio invia i risultati di riconoscimenti su una connessione WebSocket dipende dal fatto che il client richieda o meno i risultati provvisori. Per ulteriori informazioni, vedi Come il servizio invia i risultati del riconoscimento.

Il seguente frammento di codice JavaScript invia i dati audio al servizio come un messaggio binario (blob):

websocket.send(blob);

Il seguente frammento riceve le ipotesi di riconoscimento che il servizio restituisce in modo asincrono. I risultati sono gestiti dalla funzione onMessage del client.

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

Il codice deve essere preparato per gestire i codici di ritorno dal servizio. Per ulteriori informazioni, vedi Codici di ritornoWebSocket.

Termina una richiesta di riconoscimento

Quando si finisce di inviare dati audio per una richiesta al servizio, il client deve segnalare il termine della trasmissione dell'audio binario al servizio in uno dei seguenti modi:

• Inviando un messaggio di testo JSON con il parametro action impostato sul valore stop:

  {action: 'stop'}
  

• Inviando un messaggio binario vuoto, uno in cui il blob specificato è vuoto:

  websocket.send(blob)
  

Se il client non segnala il completamento della trasmissione, la connessione può terminare senza che il servizio invii i risultati finali. Per ricevere i risultati finali tra più richieste di riconoscimento, il client deve indicare il termine della trasmissione per la richiesta precedente prima di inviare una richiesta successiva. Dopo aver restituito i risultati finali per la prima richiesta, il servizio restituisce un altro messaggio {"state":"listening"} al client. Questo messaggio indica che il servizio è pronto a ricevere un'altra richiesta.

Invia ulteriori richieste e modifica i parametri della richiesta

Mentre la connessione WebSocket è attiva, il client può continuare ad utilizzarla per inviare ulteriori richieste di riconoscimento con del nuovo audio. Per impostazione predefinita, il servizio continua ad utilizzare i parametri che sono stati inviati con il precedente messaggio start per tutte le richieste successive che vengono inviate tramite la stessa connessione.

Per modificare i parametri per le richieste successive, il client può inviare un altro messaggio start con i nuovi parametri dopo aver ricevuto i risultati finali del riconoscimento e un nuovo messaggio {"state":"listening"} dal servizio. Il client può modificare tutti i parametri ad eccezione di quelli che vengono specificati quando viene aperta la connessione (model, language_customization_id e così via).

Il seguente esempio invia un messaggio start con dei nuovi parametri per le successive richieste di riconoscimento che vengono inviate tramite la connessione. Il messaggio specifica lo stesso content-type dell'esempio precedente, ma indica al servizio di restituire le date/ore e le misure dell'attendibilità per le parole della trascrizione.

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

Mantieni una connessione attiva

Il servizio termina la sessione e chiude la connessione se si verifica un timeout di inattività o di sessione:

• Un timeout di inattività si verifica se l'audio è stato inviato dal client ma il servizio non rileva alcun discorso. Il timeout di inattività è di 30 secondi per impostazione predefinita. Puoi utilizzare il parametro inactivity_timeout per specificare un valore diverso, incluso -1 per impostare il timeout su infinito. Per ulteriori informazioni, vedi Timeout di inattività.
• Un timeout di sessione si verifica se il servizio non riceve dati dal client o non invia dei risultati provvisori per 30 secondi. Non puoi modificare la durata di questo timeout, ma puoi estendere la sessione inviando al servizio dei dati audio, incluso soltanto il silenzio, prima che si verifichi il timeout. Devi inoltre impostare inactivity_timeout su -1. Ti viene effettuato un addebito per la durata di tutti i dati che invii al servizio, incluso il silenzio che invii per estendere la sessione. Per ulteriori informazioni, vedi Timeout della sessione.

I client e i server WebSocket possono anche scambiare dei frame ping-pong per evitare timeout di lettura scambiando periodicamente piccole quantità di dati. Molti stack WebSocket si scambiano i frame ping-pong, ma alcuni non lo fanno. Per determinare se la tua implementazione utilizza i frame ping-pong, controlla la sua lista di funzioni. Non puoi determinare o gestire in modo programmatico i frame ping-pong.

Se il tuo stack WebSocket non implementa frame ping-pong e stai inviando file audio lunghi, si potrebbe verificare un timeout di lettura sulla tua connessione. Per evitare tali timeout, invia continuamente l'audio in streaming al servizio o richiedi i risultati provvisori dal servizio. Entrambi gli approcci possono garantire che la mancanza di frame ping-pong non causi la chiusura della tua connessione.

Per ulteriori informazioni sui frame ping-pong, vedere la sezione 5.5.2 Ping e la sezione 5.5.3 Pong di IETF RFC 6455.

Chiudi una connessione

Quando il client ha terminato di interagire con il servizio, può chiudere la connessione WebSocket. Dopo aver chiuso la connessione, il client non può più utilizzarla per inviare delle richieste o per ricevere dei risultati. Chiudere la connessione solo dopo che il client ha ricevuto tutti i risultati di una richiesta. La connessione si esaurisce e si chiude se il client non la chiude esplicitamente.

Il seguente frammento di codice JavaScript chiude una connessione aperta:

websocket.close();

Richiesta di esempio senza risultati provvisori

Il client disabilita i risultati provvisori impostando il parametro interim_results su false o omettendo il parametro da una richiesta (l'argomento predefinito per il parametro è false). Il client riceve un singolo oggetto JSON in risposta solo dopo aver inviato un messaggio stop.

L'oggetto risposta può contenere più risultati finali per espressioni separate dell'audio. Il servizio non invia il singolo oggetto di risposta fino a quando non riceve un messaggio stop per indicare che la trasmissione audio per la richiesta è completa. La struttura e il formato della risposta del servizio sono gli stessi indipendentemente dal fatto che tu utilizzi un modello di generazione precedente o successiva.

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

Richiesta di esempio con risultati provvisori

Il client richiede i seguenti risultati provvisori:

• Per i modelli di generazione precedente, impostando il parametro interim_results su true.
• Per i modelli di nuova generazione, impostando il parametro interim_results su true. È anche possibile impostare low_latency su true per abilitare sia i risultati intermedi che la bassa latenza per i modelli.
  • Per ulteriori informazioni sui modelli di nuova generazione che supportano la bassa latenza, consulta Modelli di nuova generazione supportati.

Il client riceve più oggetti JSON in risposta. Il servizio restituisce oggetti di risposta separati per ogni risultato intermedio e per ciascun risultato finale generato dall'audio. Il servizio invia almeno un risultato provvisorio per ogni risultato finale.

Il servizio invia le risposte non appena sono disponibili. Non attende che un messaggio stop invii i relativi risultati, anche se il messaggio stop è ancora richiesto per segnalare la fine della trasmissione per la richiesta. La struttura e il formato della risposta del servizio sono gli stessi indipendentemente dal fatto che tu utilizzi un modello di generazione precedente o successiva.

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

Primo scambio di esempio

Nel primo scambio, il client invia dell'audio che contiene la stringa Name the Mayflower. Il client invia un messaggio binario con una sola porzione di dati audio (audio/l16) PCM, per i quali indica la frequenza di campionamento richiesta. Il client non attende la risposta {"state":"listening"} dal servizio per iniziare ad inviare i dati audio e per indicare il termine della richiesta. L'invio dei dati riduce immediatamente la latenza perché l'audio è disponibile per il servizio non appena è pronto a gestire una richiesta di riconoscimento.

• Il client invia:

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

• Il servizio risponde:

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

Secondo scambio di esempio

Nel secondo scambio, il client invia dell'audio che contiene la stringa Second audio transcript. Il client invia l'audio in un solo messaggio binario e utilizza gli stessi parametri specificati nella prima richiesta.

• Il client invia:

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

• Il servizio risponde:

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

Terzo scambio di esempio

Nel terzo scambio, il client invia nuovamente dell'audio che contiene la stringa Name the Mayflower. Invia un messaggio binario con un singolo pezzo di dati audio PCM. Ma questa volta, il client invia un nuovo messaggio start che richiede i risultati provvisori dal servizio.

• Il client invia:

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

• Il servizio risponde:

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