Istruzioni di avvio rapido: comprensione del linguaggio di conversazione

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito.

Accedere a Studio di linguaggio

1. Passare a Language Studio e accedere con l'account Azure.

2. Nella finestra Selezionare una risorsa Lingua visualizzata individuare la sottoscrizione di Azure e selezionare la risorsa Linguaggio. Se non si ha una risorsa, è possibile crearne una nuova.

   Dettagli dell'istanza	Valore obbligatorio
   Sottoscrizione di Azure	La sottoscrizione di Azure.
   Gruppo di risorse di Azure	Nome di gruppo di risorse di Azure.
   Nome risorsa di Azure	Nome della risorsa di Azure.
   Ufficio	Una delle regioni supportate per la risorsa Linguaggio. Ad esempio: "Stati Uniti occidentali 2".
   Piano tariffario	Uno dei piani tariffarivalidi per la risorsa Linguaggio. Per provare il servizio, è possibile usare il piano tariffario gratuito (F0).

   

Creare un progetto di comprensione del linguaggio di conversazione

Dopo aver selezionato una risorsa Linguaggio, creare un progetto di comprensione del linguaggio di conversazione. Un progetto è un'area di lavoro per la creazione di modelli di Machine Learning personalizzati sulla base dei propri dati. Al progetto può accedere solo l'utente e altri utenti che hanno accesso alla risorsa di Linguaggio usata.

Per queste istruzioni di avvio rapido, è possibile scaricare questo file di progetto di esempio e importarlo. Questo progetto è in grado di stimare i comandi previsti dall'input dell'utente, ad esempio la lettura e l'eliminazione di e-mail e l'allegare un documento a un'e-mail.

1. In Studio del linguaggio nella sezione Comprendere le domande e il linguaggio di conversazioneselezionare Comprensione del linguaggio di conversazione.

   

2. Verrà visualizzata la pagina dei Progetti di comprensione del linguaggio di conversazione. Accanto al pulsante Crea nuovo progetto selezionare Importa.

   

3. Nella finestra visualizzata caricare il file JSON da importare. Assicurarsi che il file segua il formato JSON supportato.

Al termine del caricamento verrà visualizzata la pagina Definizione schema. In questo avvio rapido lo schema è già compilato e le espressioni sono già etichettate con finalità ed entità.

Eseguire il training del modello

In genere, dopo aver creato un progetto è necessario compilare uno schema ed etichettare le espressioni. In questo avvio rapido è già stato importato un progetto pronto con lo schema compilato e le espressioni etichettate.

Per eseguire il training di un modello è necessario avviare un processo di training. L'output di un processo di training corretto è il modello sottoposto a training.

Per avviare il training del modello dallo Studio del linguaggio:

1. Selezionare Esegui training del modello nel menu a sinistra.

2. Selezionare Avvia un processo di training nel menu in alto.

3. Selezionare Esegui training di un nuovo modello e digitare il nome di un modello nuovo nella casella di testo. In alternativa, per sostituire un modello esistente con uno sottoposto a training sui nuovi dati, selezionare Sovrascrivi un modello esistente e poi selezionare un modello esistente. La sovrascrittura di un modello sottoposto a training è irreversibile, ma non influisce sui modelli distribuiti fino a quando non si distribuisce il nuovo modello.

4. Selezionare la modalità di training. È possibile scegliere Training standard per un training più rapido; anche se è disponibile solo in inglese. In alternativa, è possibile scegliere Training avanzato, che supporta altre lingue e progetti multilingue, ma comporta tempi di training più lunghi. Altre informazioni sulle modalità di training.

5. Selezionare il metodo di divisione dei dati. È possibile scegliere Divisione automatica del set di test dai dati di training: il sistema dividerà le espressioni tra il set di training e il set di test in base alle percentuali specificate. In alternativa, è possibile scegliere l’opzione Usa una divisione manuale dei dati di training e di testing che è abilitata solo se sono state aggiunte espressioni al set di test durante l’etichettatura delle espressioni.

6. Selezionare il pulsante Esegui il training.

   

7. Selezionare l'ID processo di training dall'elenco. Sarà visualizzato un riquadro in cui è possibile verificare lo stato del training, lo stato del processo e altri dettagli sul processo.

   Nota

   • Solo i processi di training completati correttamente genereranno modelli.
   • Il training può richiedere da un paio di minuti a un paio d’ore, in base al numero di espressioni.
   • È possibile eseguire un solo processo di training alla volta. Non è possibile avviare altri processi di training nello stesso progetto fino al completamento del processo in esecuzione.
   • L'apprendimento automatico usato per eseguire il training dei modelli viene aggiornato regolarmente. Per eseguire il training su una precedente versione di configurazione selezionare Selezionare qui per modificare nella pagina Avvia un processo di training e scegliere una versione precedente.

Distribuire il modello

In genere dopo il training di un modello, si esaminano i relativi dettagli di valutazione. In questo avvio rapido si distribuirà solo il modello e lo si renderà disponibile per la prova in Studio del linguaggio; in alternativa, è possibile effettuare la chiamata all' API di stima.

Per distribuire un modello all’interno di Studio di linguaggio:

1. Selezionare Distribuzione di un modello nel menu a sinistra.

2. Selezionare Aggiungi distribuzione per avviare la procedura guidata Aggiungi distribuzione.

   

3. Selezionare Crea un nuovo nome di distribuzione per creare una nuova distribuzione e assegnare un modello sottoposto a training dall'elenco a discesa seguente. In alternativa, selezionare Sovrascrivi un nome di distribuzione esistente per sostituire effettivamente il modello usato da una distribuzione esistente.

   Nota

   La sovrascrittura di una distribuzione esistente non richiede modifiche alla chiamata API di previsione, ma i risultati ottenuti saranno basati sul modello appena assegnato.

   

4. Selezionare un modello sottoposto a training dall'elenco a discesa Modello.

5. Fare clic su Distribuisci per avviare il processo di distribuzione.

6. Al termine della distribuzione verrà visualizzata una data di scadenza. La scadenza della distribuzione indica quando il modello non potrà essere usato per la stima, ossia generalmente dodici mesi dopo la scadenza di una configurazione di training.

Testa modello distribuito

Per testare i modelli distribuiti da Studio di linguaggio:

1. Selezionare Test delle distribuzioni nel menu a sinistra.

2. Per i progetti multilingue, nell'elenco a discesa Seleziona linguaggio di testo selezionare la lingua dell'espressione di cui si esegue il test.

3. Nell'elenco a discesa Nome distribuzione selezionare il nome della distribuzione corrispondente al modello da testare. È possibile testare solo i modelli assegnati alle distribuzioni.

4. Nella casella di testo immettere un'espressione da testare. Ad esempio, se è stata creata un'applicazione per espressioni correlate alla posta elettronica, è possibile immettere Elimina questo messaggio di posta elettronica.

5. Nella parte superiore della pagina selezionare Esegui il test.

6. Dopo aver eseguito il test, nel risultato dovrebbe essere visualizzata la risposta del modello. È possibile visualizzare i risultati nella visualizzazione delle schede delle entità o visualizzarli in formato JSON.

Pulire le risorse

Quando il progetto non è più necessario, è possibile eliminare il progetto usando Language Studio. Selezionare Progetti nel menu di spostamento a sinistra, selezionare il progetto da eliminare, quindi selezionare Elimina nel menu in alto.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito.

Creare una nuova risorsa dal portale di Azure

1. Accedere al portale di Azure per creare una nuova risorsa di Lingua di Azure AI.

2. Selezionare Crea una nuova risorsa

3. Nella finestra visualizzata cercare Servizio di linguaggio

4. Selezionare Crea.

5. Creare una risorsa linguistica con i dettagli seguenti.

   Dettagli dell'istanza	Valore obbligatorio
   Area	Una delle regioni supportate per la risorsa Linguaggio.
   Nome	Nome obbligatorio per la risorsa Linguaggio
   Piano tariffario	Uno dei piani tariffari supportati per la risorsa Linguaggio.

Ottenere le chiavi e l’endpoint di una risorsa

1. Accedere alla pagina di panoramica della risorsa nel portale di Azure.

2. Nel menu sul lato sinistro, scegliere Chiavi ed endpoint. Si useranno l'endpoint e la chiave per le richieste API

   

Importare un nuovo progetto di esempio CLU

Dopo aver creato una risorsa Linguaggio, creare un progetto Comprensione del linguaggio di conversazione Un progetto è un'area di lavoro per la creazione di modelli di Machine Learning personalizzati sulla base dei propri dati. Al progetto può accedere solo l'utente e altri utenti che hanno accesso alla risorsa di Linguaggio usata.

Per queste istruzioni di avvio rapido, è possibile scaricare questo progetto di esempio e importarlo. Questo progetto è in grado di stimare i comandi previsti dall'input dell'utente, ad esempio la lettura e l'eliminazione di e-mail e l'allegare un documento a un'e-mail.

Attivare il processo di importazione del progetto

Inviare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per importare il progetto.

Richiesta URL

Usare l'URL seguente per la creazione della richiesta API. Sostituire i valori segnaposto con i propri valori.

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Corpo

Il corpo JSON inviato è simile all'esempio seguente. Per altri dettagli sull'oggetto JSON, vedere la documentazione di riferimento.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "{PROJECT-NAME}",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "intent1"
      },
      {
        "category": "intent2"
      }
    ],
    "entities": [
      {
        "category": "entity1"
      }
    ],
    "utterances": [
      {
        "text": "text1",
        "dataset": "{DATASET}",
        "intent": "intent1",
        "entities": [
          {
            "category": "entity1",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "text2",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "intent": "intent2",
        "entities": []
      }
    ]
  }
}

Quando una richiesta ha esito positivo, la risposta API conterrà un'intestazione operation-location con un URL che è possibile usare per controllare lo stato del processo di importazione. È formattata come segue:

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

Ottenere lo stato del processo di importazione

Quando si invia una richiesta di importazione di progetto con esito positivo, l'URL completo della richiesta per verificare lo stato del processo di importazione (incluso l'endpoint, il nome del progetto e l'ID processo) è contenuto nell'intestazione operation-location della risposta.

Usare la richiesta GET seguente per eseguire un query dello stato del processo di importazione. È possibile usare l'URL ricevuto dal passaggio precedente oppure sostituire i valori segnaposto con i propri valori.

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Corpo della risposta

Dopo aver inviato la richiesta, si otterrà la risposta seguente. Mantenere il polling di questo endpoint fino a quando il parametro dello stato diventa "succeeded".

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

Avviare il training di un modello

In genere, dopo aver creato un progetto, è necessario compilare uno schema ed contrassegnare espressioni. Per queste istruzioni di avvio rapido è già stato importato un progetto pronto con lo schema compilato e le espressioni con tag.

Creare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per inviare un processo di training.

Richiesta URL

Usare l'URL seguente per la creazione della richiesta API. Sostituire i valori segnaposto con i propri valori.

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Corpo della richiesta

Usare l’oggetto seguente nella richiesta. Il modello verrà denominato dopo il valore usato per il parametro modelLabel al termine del training.

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "{TRAINING-MODE}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}

Dopo aver inviato la richiesta API, si riceverà una risposta 202 indicante l'esito positivo. Nelle intestazioni della risposta, estrarre il valore operation-location. Il formato sarà simile al seguente:

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

È possibile usare questo URL per ottenere lo stato del processo di training.

Ottenere lo stato del processo di training

Il completamento del training può richiedere tempo, a volte tra 10 e 30 minuti. È possibile usare la richiesta seguente per mantenere il polling dello stato del processo di training fino a quando viene completato correttamente.

Quando si invia una richiesta di training con esito positivo, l'URL completo della richiesta per verificare lo stato del processo (incluso l'endpoint, il nome del progetto e l'ID processo) è contenuto nell'intestazione operation-location della risposta.

Usare la seguente richiesta GET per ottenere lo stato dello stato di avanzamento del training del modello. Sostituire i valori segnaposto seguenti con i propri valori.

Richiesta URL

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Testo della risposta

Dopo aver inviato la richiesta, si otterrà la risposta seguente. Continuare il polling di questo endpoint fino a quando il parametro dello stato diventa "succeeded".

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "trainingMode": "{TRAINING-MODE}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx-xxxx",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

Distribuire il modello

In genere dopo il training di un modello, esaminare i relativi dettagli di valutazione. In queste istruzioni di avvio rapido si distribuirà semplicemente il modello e si chiamerà l'API di stima per eseguire query sui risultati.

Invia processo di distribuzione

Creare una richiesta PUT usando l'URL, le intestazioni e il corpo JSON seguenti per iniziare a distribuire un modello di comprensione del linguaggio di conversazione.

Richiesta URL

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Corpo della richiesta

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

Dopo aver inviato la richiesta API, si riceverà una risposta 202 indicante l'esito positivo. Nelle intestazioni della risposta, estrarre il valore operation-location. Il formato sarà simile al seguente:

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

È possibile usare questo URL per ottenere lo stato del processo di distribuzione.

Ottieni stato del processo di distribuzione

Quando si invia una richiesta di distribuzione con esito positivo, l'URL completo della richiesta per verificare lo stato del processo (incluso l'endpoint, il nome del progetto e l'ID processo) è contenuto nell'intestazione operation-location della risposta.

Usare la richiesta GET seguente per ottenere lo stato del processo di distribuzione. Sostituire i valori segnaposto con i propri valori.

Richiesta URL

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Testo della risposta

Dopo aver inviato la richiesta, si otterrà la risposta seguente. Mantenere il polling di questo endpoint fino a quando il parametro dello stato diventa "succeeded".

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Eseguire query sul modello

Dopo aver distribuito il modello, è possibile iniziare a usarlo per creare previsioni usando l'API di stima.

Al termine della distribuzione, è possibile iniziare a eseguire query sul modello distribuito per le stime.

Creare una richiesta POST usando l'URL, le intestazioni e il corpo JSON seguenti per iniziare a testare un modello di comprensione del linguaggio di conversazione.

Richiesta URL

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Corpo della richiesta

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

Dopo aver inviato la richiesta, si otterrà la risposta seguente per la previsione

Corpo della risposta

{
  "kind": "ConversationResult",
  "result": {
    "query": "Text1",
    "prediction": {
      "topIntent": "inten1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        },
        {
          "category": "intent3",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text1",
          "offset": 29,
          "length": 12,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Risposta dell'API per un progetto di conversazioni

In un progetto di conversazione si otterranno stime sia per le finalità che per le entità presenti all'interno del progetto.

• Le finalità e le entità includono un punteggio di attendibilità compreso tra 0,0 e 1,0 associato al grado di attendibilità con cui il modello esegua la previsione di un determinato elemento nel progetto.
• La finalità di punteggio più alto è contenuta all'interno del proprio parametro.
• Nella risposta verranno visualizzate solo le entità stimate.
• Le entità indicano:
  • Il testo dell'entità estratta
  • La posizione iniziale indicata da un valore di offset
  • La lunghezza del testo dell'entità denotata da un valore di lunghezza.

Pulire le risorse

Quando il progetto non è più necessario, è possibile eliminarlo usando le API.

Creare una richiesta ELIMINA usando l'URL, le intestazioni e il corpo JSON seguenti per eliminare un progetto di comprensione del linguaggio di conversazione.

Richiesta URL

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

Intestazioni

Usare l'intestazione seguente per autenticare la richiesta.

Dopo aver inviato la richiesta API, si riceverà una risposta 202 che indica l'esito positivo, che significa che il progetto è stato eliminato.