Informazioni sulle risorse per la creazione di un modello di comprensione del linguaggio di conversazione

9 minuti

Per usare il servizio Language Understanding per sviluppare una soluzione NLP, è necessario creare una risorsa del linguaggio in Azure. Tale risorsa verrà usata sia per la creazione del modello che per l'elaborazione delle richieste di previsione dalle applicazioni client.

Suggerimento

Il lab di questo modulo illustra la creazione di un modello per la comprensione del linguaggio di conversazione. Per moduli più incentrati sulla classificazione del testo personalizzata e sul riconoscimento di entità denominate personalizzate, vedere i moduli di soluzione personalizzati nel percorso di apprendimento Sviluppare soluzioni in linguaggio naturale.

Creare il modello

Per le funzionalità che richiedono un modello per le previsioni, è necessario creare, eseguire il training e distribuire il modello prima di usarlo per eseguire una previsione. I processi di compilazione e training insegneranno al servizio Lingua di Azure AI cosa cercare.

Prima di tutto, è necessario creare la risorsa Lingua di Azure AI nel portale di Azure. Quindi:

Cercare i Servizi di Azure AI.
Trovare e selezionare Servizio di linguaggio.
Selezionare Crea in Servizio di linguaggio.
Compilare i dettagli necessari, scegliendo l'area geograficamente più vicina (per ottenere prestazioni ottimali) e assegnando un nome univoco.

Dopo aver creato la risorsa, saranno necessari una chiave e l'endpoint. È possibile trovarli sul lato sinistro in Chiavi ed endpoint nella pagina di panoramica della risorsa.

Usare Language Studio

Per un metodo più visivo di creazione, training e distribuzione del modello, è possibile usare Language Studio per eseguire ognuno di questi passaggi. Nella pagina principale è possibile scegliere di creare un progetto di comprensione del linguaggio di conversazione. Dopo aver creato il progetto, eseguire lo stesso processo precedente per creare, eseguire il training e distribuire il modello.

Il lab in questo modulo illustrerà l'uso di Language Studio per creare il modello. Per altre informazioni, vedere la guida introduttiva a Language Studio

Usare l'API REST

Uno dei modi per creare il modello prevede l'uso dell'API REST. La sequenza prevista include creazione del progetto, importazione dei dati, training, distribuzione e quindi uso del modello.

Queste attività vengono eseguite in modo asincrono. Sarà necessario inviare una richiesta all'URI appropriato per ogni passaggio e quindi inviare un'altra richiesta per ottenere lo stato del processo.

Ad esempio, se si vuole distribuire un modello per un progetto di comprensione del linguaggio di conversazione, occorre inviare il processo di distribuzione e quindi controllare lo stato del processo di distribuzione.

Authentication

Per ogni chiamata alla risorsa Lingua di Azure AI sarà necessario autenticare la richiesta specificando l'intestazione seguente.

Chiave	Valore
`Ocp-Apim-Subscription-Key`	Chiave della risorsa

Distribuzione della richiesta

Inviare una richiesta POST all'endpoint seguente.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}

Segnaposto	Valore	Esempio
`{ENDPOINT}`	Endpoint della risorsa Lingua di Azure AI	`https://<your-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	Nome del progetto. Per questo valore viene applicata la distinzione tra maiuscole e minuscole	`myProject`
`{DEPLOYMENT-NAME}`	Nome della distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole	`staging`
`{API-VERSION}`	Versione dell'API che si sta chiamando	`2022-05-01`

Includere la parte body seguente nella richiesta.

{
  "trainedModelLabel": "{MODEL-NAME}",
}

Segnaposto	Valore
`{MODEL-NAME}`	Nome del modello che verrà assegnato alla distribuzione. Per questo valore viene applicata la distinzione tra maiuscole e minuscole.

Se si invia correttamente la richiesta si riceverà una risposta 202 con un'intestazione di risposta operation-location. Questa intestazione includerà un URL con cui richiedere lo stato, formattato come segue:

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

Ottenere lo stato di una distribuzione

Inviare una richiesta GET all'URL dall'intestazione della risposta precedente. I valori saranno già compilati in base alla richiesta di distribuzione iniziale.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

Segnaposto	Valore
`{ENDPOINT}`	Endpoint per l'autenticazione della richiesta API
`{PROJECT-NAME}`	Nome per il progetto (con distinzione tra maiuscole e minuscole)
`{DEPLOYMENT-NAME}`	Nome per la distribuzione (con distinzione tra maiuscole e minuscole)
`{JOB-ID}`	ID per l'individuazione dello stato di training del modello, disponibile nel valore di intestazione descritto in precedenza nella richiesta di distribuzione
`{API-VERSION}`	Versione dell'API che si sta chiamando

Il corpo della risposta includerà i dettagli dello stato della distribuzione. Al termine della distribuzione, il valore del campo status sarà succeeded.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"String",
    "lastUpdatedDateTime":"String",
    "expirationDateTime":"String",
    "status":"running"
}

Per una procedura dettagliata completa di ogni passaggio con richieste di esempio, vedere Guida introduttiva: Comprensione del linguaggio di conversazione.

Eseguire query sul modello

Per eseguire query sul modello per una stima, è possibile usare GLI SDK in C# o Python oppure usare l'API REST.

Eseguire query con GLI SDK

Per eseguire query sul modello usando un SDK, è prima necessario creare il client. Dopo aver creato il client, usarlo per chiamare l'endpoint appropriato.

var languageClient = new TextAnalyticsClient(endpoint, credentials);
var response = languageClient.ExtractKeyPhrases(document);

language_client = TextAnalyticsClient(
            endpoint=endpoint, 
            credential=credentials)
response = language_client.extract_key_phrases(documents = documents)[0]

Altre funzionalità del linguaggio, ad esempio la comprensione del linguaggio conversazionale, richiedono la compilazione e l'invio della richiesta in modo diverso.

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = userText,
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};
Response response = await client.AnalyzeConversationAsync(RequestContent.Create(data));

result = client.analyze_conversation(
    task={
        "kind": "Conversation",
        "analysisInput": {
            "conversationItem": {
                "participantId": "1",
                "id": "1",
                "modality": "text",
                "language": "en",
                "text": query
            },
            "isLoggingEnabled": False
        },
        "parameters": {
            "projectName": cls_project,
            "deploymentName": deployment_slot,
            "verbose": True
        }
    }
)

Eseguire query usando l'API REST

Per eseguire query sul modello usando REST, creare una richiesta POST all'URL appropriato con il corpo appropriato specificato. Per le funzionalità predefinite, ad esempio il rilevamento della lingua o l'analisi del sentiment, si eseguirà una query sull'endpoint analyze-text.

Suggerimento

Tenere presente che ogni richiesta deve essere autenticata con la chiave della risorsa Lingua di Azure AI nell'intestazione Ocp-Apim-Subscription-Key

{ENDPOINT}/language/:analyze-text?api-version={API-VERSION}

Segnaposto	Valore
`{ENDPOINT}`	Endpoint per l'autenticazione della richiesta API
`{API-VERSION}`	Versione dell'API che si sta chiamando

All'interno del corpo di tale richiesta, è necessario specificare il parametro kind, che indica al servizio il tipo di funzionalità di comprensione del linguaggio richiesto.

Per il rilevamento della lingua, ad esempio, il corpo JSON sarà simile al seguente.

{
    "kind": "LanguageDetection",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "text": "This is a document written in English."
            }
        ]
    }
}

Altre funzionalità del linguaggio, ad esempio la comprensione del linguaggio conversazionale, richiedono che la richiesta venga instradata a un endpoint diverso. Ad esempio, la richiesta di comprensione del linguaggio di conversazione verrebbe inviata all'endpoint seguente.

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

Segnaposto	Valore
`{ENDPOINT}`	Endpoint per l'autenticazione della richiesta API
`{API-VERSION}`	Versione dell'API che si sta chiamando

Tale richiesta includerebbe un corpo JSON simile al seguente.

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Sample text"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

Segnaposto	Valore
`{PROJECT-NAME}`	Nome del progetto in cui è stato creato il modello
`{DEPLOYMENT-NAME}`	Nome della distribuzione

Risposta di esempio

La risposta di query da un SDK verrà restituita nell'oggetto , che varia a seconda della funzionalità , ad esempio in response.key_phrases o response.Value. L'API REST restituirà JSON simile al seguente.

{
    "kind": "KeyPhraseExtractionResults",
    "results": {
        "documents": [{
            "id": "1",
            "keyPhrases": ["modern medical office", "Dr. Smith", "great staff"],
            "warnings": []
        }],
        "errors": [],
        "modelVersion": "{VERSION}"
    }
}

Per altri modelli come la comprensione del linguaggio conversazionale, una risposta di esempio alla query sarà simile alla seguente.

{
  "kind": "ConversationResult",
  "result": {
    "query": "String",
    "prediction": {
      "topIntent": "intent1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text",
          "offset": 7,
          "length": 4,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Gli SDK per Python e C# restituiscono JSON molto simili alla risposta REST.

Per la documentazione completa sulle funzionalità, inclusi esempi e guide pratiche, vedere le pagine della documentazione di Lingua di Azure AI.