Come usare le funzionalità del servizio linguaggio in modo asincrono

  • Articolo

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

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

  • Collegamento di entità
  • Riepilogo dei documenti
  • Riepilogo conversazioni
  • Estrazione di frasi chiave
  • Rilevamento della lingua
  • Riconoscimento delle entità denominate (NER)
  • Rilevamento dei contenuti dei clienti
  • Analisi del sentiment e opinion mining
  • Analisi del testo per la sanità
  • Informazioni personali

Quando si inviano richieste asincrone, verranno addebitati addebiti 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, verrà conteggiato come invio di due record di testo e 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 vuole 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 riuscita restituirà un codice di risposta 202. L'oggetto 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 avere installata la 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 vuole 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 eliminati e non sono più disponibili per il recupero.

Rilevamento automatico della lingua

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

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. Questo limite di caratteri è superiore al limite per le richieste sincrone, per abilitare una velocità effettiva più elevata.

Se un documento supera il limite di caratteri, l'API rifiuterà l'intera richiesta e restituirà un 400 bad request errore se un documento all'interno supera le dimensioni massime.

Vedi anche