Informazioni su come creare progetti di classificazione del testo

  • 12 minuti

I progetti di classificazione personalizzata del testo sono l'area di lavoro per compilare il modello di classificazione, eseguirne il training, migliorarlo e distribuirlo. È possibile lavorare sul progetto in due modi, tramite Language Studio e tramite l'API REST. Language Studio è l'interfaccia utente grafica che verrà usata nel lab, ma l'API REST ha la stessa funzionalità. Indipendentemente dal metodo preferito, i passaggi per lo sviluppo del modello sono gli stessi.

Ciclo di vita del progetto di Lingua di Azure AI

Diagram that shows a life cycle with steps to define labels, tag data, train model, view model, improve model, deploy model, and classify text.

  • Definire le etichette: con le informazioni sui dati da classificare, identificare le possibili etichette in cui eseguire la classificazione. Nell'esempio dei videogiochi le nostre etichette sarebbero "Action", "Adventure", "Strategy" e così via.
  • Contrassegnare i dati: assegnare etichette ai dati esistenti, specificando una o più etichette a cui può essere associato ogni file. L'etichettatura dei dati è importante perché consente al modello di apprendere il modo in cui classificare i file futuri. La procedura consigliata consiste nel definire differenze chiare tra le etichette per evitare ambiguità e fornire esempi validi di ogni etichetta da cui il modello apprende. Ad esempio, il gioco "Quest for the Mine Brush" verrebbe etichettato come "Avventura" e "Flight Trainer" come "Azione".
  • Eseguire il training del modello: sottoporre a training il modello con i dati etichettati. Il training insegna al nostro modello quali tipi di riepiloghi di videogiochi devono essere etichettati in un genere specifico.
  • Visualizzare il modello: dopo il training del modello, visualizzare i risultati restituiti dal modello. Al modello viene assegnato un punteggio compreso tra 0 e 1, in base alla precisione e al richiamo dei dati testati. Prendere nota del genere che non ha ricevuto un punteggio elevato.
  • Migliorare il modello: migliorare il modello visualizzando quali classificazioni non sono riuscite a eseguire la valutazione rispetto all'etichetta corretta, esaminare la distribuzione delle etichette e individuare i dati da aggiungere per migliorare le prestazioni. Potrebbe risultare, ad esempio, che il modello combina i giochi "Adventure" e "Strategy". Provare a trovare altri esempi di ogni etichetta da aggiungere al set di dati per ripetere il training del modello.
  • Distribuire il modello: quando il modello si comporta nel modo desiderato, distribuirlo il modello per renderlo disponibile tramite l'API. Il modello potrebbe essere denominato "GameGenres" e, dopo la distribuzione, può essere usato per classificare i riepiloghi dei giochi.
  • Classificare il testo: usare il modello per classificare il testo. Il lab illustra come usare l'API ed è possibile visualizzare il riferimento API

Come dividere i set di dati per il training

Quando si etichettano i dati, è possibile specificare il set di dati che si intende associare a ciascun file:

  • Training: il set di dati di training viene usato per eseguire effettivamente il training del modello. I dati e le etichette forniti vengono inseriti nell'algoritmo di apprendimento automatico per indicare al modello quali sono i dati da classificare e con quale etichetta. Il set di dati di training sarà il più ampio tra i due set di dati: è consigliabile che includa circa l'80% dei dati etichettati.
  • Testing: il set di dati di testing viene etichettato con i dati usati per verificare il modello dopo il training. Azure acquisisce i dati dal set di dati di testing, li invia al modello e quindi confronta l'output con il modo in cui i dati sono stati etichettati per determinare il livello di prestazioni del modello. Il risultato di tale confronto rappresenta il modo in cui al modello viene assegnato un punteggio e consente di scoprire come migliorare le prestazioni predittive.

Durante la fase di training del modello, sono disponibili due opzioni per come eseguire il training.

  • Divisione automatica - Azure accetta tutti i dati, li suddivide in percentuali specificate in modo casuale e li applica al training del modello. Questa opzione è la migliore quando si dispone di un set di dati più vasto, i dati sono naturalmente più coerenti o la distribuzione dei dati copre ampiamente le classi.
  • Divisione manuale - Specificare manualmente i file da inserire in ogni set di dati. Quando si invia il processo di training, il servizio Lingua di Azure AI indica la divisione del set di dati e la distribuzione. Tale suddivisione viene usata meglio con set di dati più piccoli per garantire la corretta distribuzione delle classi e delle variazioni nei dati per eseguire correttamente il training del modello.

Per usare la divisione automatica, inserire tutti i file nel set di dati di training quando si assegnano etichette ai dati (questa è l'opzione predefinita). Per usare la divisione manuale, specificare quali file devono trovarsi nel set di dati di testing rispetto a quello di training durante l'etichettatura dei dati.

Opzioni di distribuzione

Lingua di Azure AI consente a ogni progetto di creare più modelli e più distribuzioni, ognuno con un nome univoco. I vantaggi includono la possibilità di eseguire queste operazioni:

  • Testare due modelli affiancati
  • Confrontare il modo in cui la divisione dei set di dati influisce sulle prestazioni
  • Distribuire più versioni del modello

Nota

Per ogni progetto esiste un limite di dieci nomi di distribuzione

Durante la distribuzione è possibile scegliere il nome del modello distribuito, che può quindi essere selezionato quando si invia un'attività di classificazione:

<...>
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "MyTaskName",
      "parameters": {
        "projectName": "MyProject",
        "deploymentName": "MyDeployment"
      }
    }
  ]
<...>

Tramite l'API REST

L'API REST disponibile per il servizio Lingua di Azure AI consente lo sviluppo da interfaccia della riga di comando dei progetti di Lingua di Azure AI nello stesso modo in cui Language Studio fornisce un'interfaccia utente per la compilazione di progetti. Language Studio viene esaminato ulteriormente nel lab di questo modulo.

Modello di uso dell'API

L'API per il servizio Lingua di Azure AI opera in modo asincrono per la maggior parte delle chiamate. In ogni passaggio si invia prima una richiesta al servizio e quindi si esegue un'ulteriore verifica tramite una chiamata successiva al servizio per ottenere lo stato o il risultato.

Per ogni richiesta, è necessaria un'intestazione per autenticarla:

Chiave valore
Ocp-Apim-Subscription-Key Chiave della risorsa Lingua di Azure AI

Invio della richiesta iniziale

L'URL a cui inviare la richiesta varia a seconda del passaggio, ma tutti sono preceduti dall'endpoint fornito dalla specifica risorsa Lingua di Azure AI.

Per eseguire il training di un modello, ad esempio, si crea un POST all'URL simile al seguente:

<YOUR-ENDPOINT>/language/analyze-text/projects/<PROJECT-NAME>/:train?api-version=<API-VERSION>
Segnaposto Valore Esempio
<YOUR-ENDPOINT> Endpoint per la richiesta API https://<your-custom-resource>.cognitiveservices.azure.com
<PROJECT-NAME> Nome del progetto (il valore fa distinzione tra maiuscole e minuscole) myProject

Il corpo seguente viene associato alla richiesta:

    {
        "modelLabel": "<MODEL-NAME>",
        "trainingConfigVersion": "<CONFIG-VERSION>",
        "evaluationOptions": {
            "kind": "percentage",
            "trainingSplitPercentage": 80,
            "testingSplitPercentage": 20
        }
    }
Chiave valore
<YOUR-MODEL> Nome del modello.
trainingConfigVersion Versione del modello da usare per eseguire il training del modello.
runValidation Valore booleano per eseguire la convalida sul set di test.
evaluationOptions Specifica le opzioni di valutazione.
kind Specifica il tipo di divisione dei dati. Può essere percentage se si usa una divisione automatica o set se si divide il set di dati manualmente
testingSplitPercentage Campo di tipo integer obbligatorio solo se type è una percentuale. Specifica la divisione dei dati di test.
trainingSplitPercentage Campo di tipo integer obbligatorio solo se type è una percentuale. Specifica la divisione dei dati di training.

La risposta alla richiesta precedente sarà 202, che indica l'esito positivo della richiesta. Nelle intestazioni di risposta individuare il valore di location, che avrà un aspetto simile all'URL seguente:

<ENDPOINT>/language/analyze-text/projects/<PROJECT-NAME>/train/jobs/<JOB-ID>?api-version=<API-VERSION>
Chiave valore
<JOB-ID> Identificatore della richiesta

Tale URL viene usato nel passaggio successivo per ottenere lo stato del training.

Ottenere lo stato del training

Per ottenere lo stato del training, usare l'URL dell'intestazione della risposta alla richiesta per inviare una richiesta GET, con la stessa intestazione che fornisce la chiave del servizio Lingua di Azure AI per l'autenticazione. Il corpo della risposta è simile al codice JSON seguente:

{
  "result": {
    "modelLabel": "<MODEL-NAME>",
    "trainingConfigVersion": "<CONFIG-VERSION>",
    "estimatedEndDateTime": "2023-05-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2023-05-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "<JOB-ID>",
  "createdDateTime": "2023-05-18T15:44:44Z",
  "lastUpdatedDateTime": "2023-05-18T15:45:48Z",
  "expirationDateTime": "2023-05-25T15:44:44Z",
  "status": "running"
}

Il training di un modello può richiedere tempo, quindi controllare periodicamente questo URL di stato fino a quando la risposta status non restituisce succeeded. Dopo aver completato il training, è possibile visualizzare, verificare e distribuire il modello.

Uso di un modello distribuito

L'uso del modello per classificare il testo segue lo stesso modello descritto in precedenza, con una richiesta POST che invia il processo e una richiesta GET per recuperare i risultati.

Inviare testo per la classificazione

Per usare il modello, inviare un POST all'endpoint di analisi all'URL seguente:

<ENDPOINT>/language/analyze-text/jobs?api-version=<API-VERSION>
Segnaposto Valore Esempio
<YOUR-ENDPOINT> Endpoint per la richiesta API https://<your-custom-resource>.cognitiveservices.azure.com

Importante

Ricordarsi di includere la chiave di risorsa nell'intestazione per Ocp-Apim-Subscription-Key

La struttura JSON seguente viene collegata alla richiesta:

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "<LANGUAGE-CODE>",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "<LANGUAGE-CODE>",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "<TASK-REQUIRED>",
      "taskName": "<TASK-NAME>",
      "parameters": {
        "projectName": "<PROJECT-NAME>",
        "deploymentName": "<DEPLOYMENT-NAME>"
      }
    }
  ]
}
Chiave valore
<TASK-REQUIRED> Attività richiesta. L'attività è CustomMultiLabelClassification per i progetti a più etichette o CustomSingleLabelClassification per i progetti a etichetta singola.
<LANGUAGE-CODE> Codice del linguaggio, ad esempio en-us.
<TASK-NAME> Nome dell'attività.
<PROJECT-NAME> Nome progetto.
<DEPLOYMENT-NAME> Nome distribuzione.

La risposta alla richiesta precedente sarà 202, che indica l'esito positivo della richiesta. Nelle intestazioni di risposta cercare il valore di operation-location, che avrà un aspetto simile all'URL seguente:

<ENDPOINT>/language/analyze-text/jobs/<JOB-ID>?api-version=<API-VERSION>
Chiave valore
<YOUR-ENDPOINT> Endpoint per la richiesta API
<JOB-ID> Identificatore della richiesta

Tale URL consente di ottenere i risultati dell'attività.

Ottenere i risultati della classificazione

Inviare una richiesta GET all'endpoint dalla richiesta precedente, con la stessa intestazione per l'autenticazione. Il corpo della risposta è simile al codice JSON seguente:

{
  "createdDateTime": "2023-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2023-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2023-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2022-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "<DOC-ID>",
              "class": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2022-04-01"
        }
      }
    ]
  }
}

Il risultato della classificazione si trova all'interno dell'oggetto results della matrice di elementi per ogni documento inviato.