Come usare le funzionalità del Servizio di linguaggio in modo asincrono

  • Articolo

Il Servizio di linguaggio consente di inviare richieste API in modo asincrono, usando l'API REST o la libreria client. È anche possibile includere più funzionalità differenti del Servizio di linguaggio nella richiesta, da eseguire contemporaneamente sui dati.

Attualmente, sono disponibili le seguenti funzionalità per l'uso asincrono:

  • Collegamento di entità
  • Riepilogo del documento
  • Riepilogo della conversazione
  • Estrazione frasi chiave
  • Rilevamento lingua
  • Riconoscimento delle entità denominate (NER)
  • Rilevamento dei contenuti dei clienti
  • Analisi del sentiment e opinion mining
  • Text Analytics for Health
  • Informazioni personali (PII)

Quando si inviano richieste asincrone, verranno addebitati importi in base al numero di record di testo inclusi nella richiesta, per ogni utilizzo di funzionalità. Ad esempio, se si invia un record di testo per l'analisi del sentiment e NER, il suddetto verrà conteggiato come invio di due record di testo, i quali verranno addebitati entrambi in base al piano tariffario.

Inviare un processo asincrono usando l'API REST

Per inviare un processo asincrono, esaminare la documentazione di riferimento per il corpo JSON che verrà inviato nella richiesta.

  1. Aggiungere i documenti all'oggetto analysisInput.
  2. Nell'oggetto tasks includere le operazioni da eseguire sui dati. Ad esempio, se si desidera eseguire l'analisi del sentiment, è necessario includere l'oggetto SentimentAnalysisLROTask.
  3. È possibile:
    1. Scegliere una versione specifica del modello usato nei dati.
    2. Includere funzionalità aggiuntive del Servizio di linguaggio nell'oggetto tasks da eseguire contemporaneamente sui dati.

Dopo aver creato il corpo JSON per la richiesta, aggiungere la chiave all'intestazione Ocp-Apim-Subscription-Key. Inviare quindi la richiesta API all'endpoint di creazione del processo. Ad esempio:

POST https://your-endpoint.cognitiveservices.azure.com/language/analyze-text/jobs?api-version=2022-05-01

Una chiamata con esito positivo restituirà un codice di risposta 202. Il operation-location nell'intestazione della risposta sarà l'URL che verrà usato per recuperare i risultati dell'API. Il valore sarà simile all'URL seguente:

GET {Endpoint}/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-05-01

Per ottenere lo stato e recuperare i risultati della richiesta, inviare una richiesta GET all'URL ricevuto nell'intestazione operation-location dalla risposta API precedente. Ricordarsi di includere la chiave in Ocp-Apim-Subscription-Key. La risposta includerà i risultati della chiamata API.

Inviare richieste API asincrone usando la libreria client

Prima di tutto, assicurarsi di disporre della libreria client per la lingua preferita. Per i passaggi relativi all'installazione della libreria client, vedere l'articolo di avvio rapido per la funzionalità che si desidera usare.

Successivamente, usare l'oggetto client per inviare chiamate asincrone all'API. Le chiamate al metodo da usare variano a seconda della lingua. Usare gli esempi disponibili e la documentazione di riferimento per iniziare.

Disponibilità dei risultati

Quando si usa questa funzionalità in modo asincrono, i risultati dell'API sono disponibili per 24 ore dal momento in cui la richiesta è stata inserita e viene indicata nella risposta. Dopo questo periodo di tempo, i risultati vengono rimossi e non sono più disponibili per il recupero.

Rilevamento lingua automatico

A partire dalla versione 2022-07-01-preview dell'API REST, è possibile richiedere il rilevamento automatico del linguaggio nei documenti. Impostando il parametro language su auto, il codice della lingua del testo rilevato verrà restituito come valore di lingua nella risposta. Il rilevamento della lingua non comporta addebiti aggiuntivi per la risorsa Linguaggio.

Limiti dei dati

Nota

  • Se è necessario analizzare documenti di dimensioni maggiori rispetto al limite consentito, è possibile suddividere il testo in blocchi di testo più piccoli prima di inviarli all'API.
  • Un documento è costituito da una singola stringa di caratteri di testo.

È possibile inviare fino a 125.000 caratteri in tutti i documenti contenuti nella richiesta asincrona, come misurato da StringInfo.LengthInTextElements. Tale limite di caratteri è superiore a quello per le richieste sincrone, così da consentire una velocità effettiva più elevata.

Se un documento supera il limite dei caratteri, l'API rifiuterà l'intera richiesta e restituirà un errore 400 bad request laddove un documento al suo interno superi le dimensioni massime.

Vedi anche