Schnellstart: Benutzerdefinierte REST-API für die Textklassifizierung

In diesem Artikel lernen Sie, wie Sie ein Projekt zur benutzerdefinierten Textklassifizierung erstellen, in dem Sie benutzerdefinierte Modelle für die Textklassifizierung trainieren können. Ein Modell ist KI-Software, die trainiert wird, um eine bestimmte Aufgabe zu erledigen. Für dieses System klassifizieren die Modelle Text und werden durch Lernen aus bezeichneten Daten trainiert.

Benutzerdefinierte Textklassifizierung unterstützt zwei Arten von Projekten:

• Klassifizierung mit einzelner Bezeichnung: Sie können jeder Datei In Ihrem Dataset eine einzelne Klasse zuweisen. Beispielsweise könnte ein Filmskript nur als "Romanze" oder "Komödie" klassifiziert werden.
• Klassifizierung mit mehreren Bezeichnungen: Sie können jedem Dokument in Ihrem Dataset mehrere Klassen zuweisen. Beispielsweise könnte ein Filmskript als "Comedy" oder "Romanze" und "Comedy" klassifiziert werden.

In dieser Schnellstartanleitung können Sie die Beispieldatensätze verwenden, die bereitgestellt werden, um eine Mehrbezeichnungsklassifizierung zu erstellen, um Filmskripts in einer oder mehreren Kategorien zu klassifizieren. Alternativ können Sie das Dataset für die Klassifizierung einzelner Bezeichnungen verwenden, um Abstracts von wissenschaftlichen Arbeiten in einer der definierten Domänen zu klassifizieren.

Voraussetzungen

• Azure-Abonnement – Erstellen eines kostenlosen Kontos

Erstellen Sie eine neue Ressource für Azure Language Services in Foundry Tools und ein Azure Storage-Konto.

Bevor Sie eine benutzerdefinierte Textklassifizierung verwenden können, müssen Sie eine Sprachressource erstellen, die Ihnen die Anmeldeinformationen gibt, die Sie zum Erstellen eines Projekts benötigen, und mit dem Training eines Modells beginnen. Sie benötigen auch ein Azure-Speicherkonto, in dem Sie Ihr Dataset hochladen können, das beim Erstellen Ihres Modells verwendet wird.

Erstellen einer neuen Ressource im Azure-Portal

1. Wechseln Sie zum Azure-Portal , um eine neue Azure Language in Foundry Tools-Ressource zu erstellen.

2. Wählen Sie im angezeigten Fenster in den benutzerdefinierten Features Benutzerdefinierte Textklassifizierung und benutzerdefinierte Erkennung benannter Entitäten aus. Wählen Sie Fahren Sie fort mit dem Erstellen einer Ressource am unteren Rand des Bildschirms aus.

   

3. Erstellen Sie eine Sprachressource mit den folgenden Details:

   Name	Erforderlicher Wert
   Abonnement	Ihr Azure-Abonnement.
   Ressourcengruppe	Eine Ressourcengruppe, die Ihre Ressource enthält. Sie können eine vorhandene verwenden oder eine neue erstellen.
   Region	Eine der unterstützten Regionen. Beispiel: „USA, Westen 2“.
   Name	Ein Name für Ihre Ressource.
   Tarif	Einer der unterstützten Preistarife. Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst auszuprobieren.

   Wenn Sie in einer Meldung darauf hingewiesen werden, dass Ihr Anmeldekonto kein Besitzer der Ressourcengruppe des ausgewählten Speicherkontos ist, muss Ihrem Konto eine Besitzerrolle für die Ressourcengruppe zugewiesen werden, bevor Sie eine Sprachressource erstellen können. Wenden Sie sich an den Besitzer des Azure-Abonnements, um Unterstützung zu erhalten.

   Sie können den Besitzer Ihres Azure-Abonnements ermitteln, indem Sie Ihre Ressourcengruppe durchsuchen und dem Link zum zugehörigen Abonnement folgen. Führen Sie dann folgende Schritte aus:

   1. Wählen Sie die Registerkarte Zugriffssteuerung (IAM) aus
   2. Wählen Sie Rollenzuweisungen aus
   3. Filtern Sie nach Rolle:Besitzer.

4. Wählen Sie im Abschnitt Benutzerdefinierte Textklassifizierung und benutzerdefinierte Erkennung benannter Entitäten ein vorhandenes Speicherkonto aus, oder wählen Sie Neues Speicherkonto aus. Beachten Sie, dass Ihnen diese Werte den Einstieg erleichtern sollen und nicht unbedingt die Speicherkontowerte darstellen, die in Produktionsumgebungen verwendet werden sollten. Um Wartezeit beim Erstellen Ihres Projekts zu vermeiden, sollten Sie eine Verbindung mit Speicherkonten in derselben Region herstellen, in der sich auch Ihre Sprachressource befindet.

   Speicherkontowert	Empfohlener Wert
   Speicherkontoname	Beliebiger Name
   Speicherkontotyp	Standardmäßiger LRS

5. Vergewissern Sie sich, dass der Hinweis Verantwortungsvolle KI markiert ist. Wählen Sie am unteren Rand der Seite die Option Bewerten + erstellen aus.

Hochladen von Beispieldaten in den Blobcontainer

Nachdem Sie ein Azure-Speicherkonto erstellt und mit Ihrer Sprachressource verbunden haben, müssen Sie die Dokumente aus dem Beispieldatensatz in das Stammverzeichnis Ihres Containers hochladen. Diese Dokumente werden verwendet, um Ihr Modell zu trainieren.

Azure-Portal

1. Navigieren Sie im Azure-Portal zu dem von Ihnen erstellten Speicherkonto, und wählen Sie es aus, indem Sie "Speicherkonten " auswählen und den Namen Ihres Speicherkontos in "Filter" für ein beliebiges Feld eingeben.

   Wenn Ihre Ressourcengruppe nicht angezeigt wird, stellen Sie sicher, dass der Filter "Abonnement gleich " auf "Alle" festgelegt ist.

2. Klicken Sie in Ihrem Speicherkonto im Menü auf der linken Seite unter Datenspeicher auf Container. Klicken Sie im angezeigten Bildschirm auf + Container. Geben Sie dem Container den Namen example-data, und übernehmen Sie den Standardwert für Öffentliche Zugriffsebene.

   

3. Nachdem Ihr Container erstellt wurde, wählen Sie ihn aus. Wählen Sie dann die Schaltfläche Hochladen aus, um die Dateien .txt und .json auszuwählen, die Sie zuvor heruntergeladen haben.

   

Abrufen Ihrer Ressourcenschlüssel und Endpunkte

• Navigieren Sie im Azure-Portal zur Übersichtsseite Ihrer Ressource.

• Wählen Sie im Menü auf der linken Seite Schlüssel und Endpunkte aus. Der Endpunkt und der Schlüssel werden für API-Anforderungen verwendet.

Erstellen eines Projekts zur benutzerdefinierten Textklassifizierung

Nachdem Ihre Ressource und der Speichercontainer konfiguriert wurden, erstellen Sie ein neues benutzerdefiniertes Textklassifizierungsprojekt. Ein Projekt ist ein Arbeitsbereich, in dem Sie Ihre benutzerdefinierten ML-Modelle auf Grundlage Ihrer Daten erstellen können. Auf Ihr Projekt kann nur von Ihnen und anderen Personen zugegriffen werden, die Zugriff auf die verwendete Azure-Sprachressource haben.

Auslösen des Importprojektauftrags

Übermitteln Sie eine POST-Anforderung mithilfe der folgenden URL, der Header und des JSON-Texts, um Ihre Bezeichnungsdatei zu importieren. Stellen Sie sicher, dass die Bezeichnungsdatei dem akzeptierten Format entspricht.

Wenn bereits ein Projekt mit demselben Namen existiert, werden die Daten dieses Projekts ersetzt.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

Header

Verwenden Sie den folgenden Header, um Ihre Anforderung zu authentifizieren.

Körper

Verwenden Sie den folgenden JSON-Code in Ihrer Anforderung. Ersetzen Sie die Platzhalterwerte durch eigene Werte.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customMultiLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customMultiLabelClassification",
    "classes": [
      {
        "category": "Class1"
      },
      {
        "category": "Class2"
      }
    ],
    "documents": [
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class1"
          },
          {
            "category": "Class2"
          }
        ]
      },
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class2"
          }
        ]
      }
    ]
  }
}

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customSingleLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customSingleLabelClassification",
        "classes": [
            {
                "category": "Class1"
            },
            {
                "category": "Class2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class2"
                }
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class1"
                }
            }
        ]
    }
}

Nachdem Sie Ihre API-Anforderung gesendet haben, erhalten Sie eine 202 Antwort, die angibt, dass der Auftrag ordnungsgemäß übermittelt wurde. Extrahieren Sie in den Antwortheadern den operation-location wie folgt formatierten Wert:

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

{JOB-ID} wird verwendet, um Ihre Anforderung zu identifizieren, da es sich um einen asynchronen Vorgang handelt. Sie verwenden diese URL, um den Status des Importauftrags abzurufen.

Mögliche Fehlerszenarios für diese Anforderung:

• Die ausgewählte Ressource verfügt nicht über die richtigen Berechtigungen für das Speicherkonto.
• Das angegebene storageInputContainerName-Element ist nicht vorhanden.
• Ein ungültiger Sprachcode wird verwendet, oder der Sprachcodetyp ist keine Zeichenfolge.
• Der Wert multilingual ist eine Zeichenfolge und kein boolescher Wert.

Abrufen des Importauftragsstatus

Verwenden Sie die folgende GET-Anforderung, um den Status Ihres Importprojekts abzurufen. Ersetzen Sie die Platzhalterwerte durch eigene Werte.

Anfrage-URL

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

Header

Verwenden Sie den folgenden Header, um Ihre Anforderung zu authentifizieren.

Trainieren Ihres Modells

Nachdem Sie ein Projekt erstellt haben, beginnen Sie in der Regel damit, die Dokumente zu markieren, die im mit Ihrem Projekt verknüpften Container vorhanden sind. Für diesen Schnellstart haben Sie ein markiertes Beispieldataset importiert und Ihr Projekt mit der JSON-Beispieltagsdatei initialisiert.

Beginnen mit dem Trainieren Ihres Modells

Nachdem das Projekt importiert wurde, können Sie mit dem Trainieren Ihres Modells beginnen.

Übermitteln Sie eine POST-Anforderung mithilfe der folgenden URL, der Header und des JSON-Texts, um einen Trainingsauftrag zu übermitteln. Ersetzen Sie die Platzhalterwerte durch eigene Werte.

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

Header

Verwenden Sie den folgenden Header, um Ihre Anforderung zu authentifizieren.

Anforderungstext

Verwenden Sie den folgenden JSON-Code im Anforderungstext. Das Modell wird als {MODEL-NAME} bezeichnet, nachdem das Training abgeschlossen ist. Nur erfolgreiche Trainingsaufträge generieren Modelle.

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

Nachdem Sie Ihre API-Anforderung gesendet haben, erhalten Sie eine 202 Antwort, die angibt, dass der Auftrag ordnungsgemäß übermittelt wurde. Extrahieren Sie in den Antwortheadern den location wie folgt formatierten Wert:

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

{JOB-ID} wird verwendet, um Ihre Anforderung zu identifizieren, da es sich um einen asynchronen Vorgang handelt. Sie können diese URL zum Abrufen des Trainingsstatus verwenden.

Abrufen des Trainingsauftragsstatus

Das Training kann zwischen 10 und 30 Minuten dauern. Sie können die folgende Anforderung verwenden, um den Status des Trainingsauftrags bis zum erfolgreichen Abschluss abzufragen.

Verwenden Sie die folgende GET-Anforderung, um den Trainingsstatus Ihres Modells abzufragen. Ersetzen Sie die Platzhalterwerte durch eigene Werte.

Anfrage-URL

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

Header

Verwenden Sie den folgenden Header, um Ihre Anforderung zu authentifizieren.

Antworttext

Sobald Sie die Anforderung gesendet haben, erhalten Sie die folgende Antwort.

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "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": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

Bereitstellen Ihres Modells

Im Allgemeinen überprüfen Sie nach dem Trainieren eines Modells seine Auswertungsdetails und nehmen bei Bedarf Verbesserungen vor. In diesem Schnellstart stellen Sie einfach Ihr Modell bereit und stellen es zur Verfügung, um es in Language Studio auszuprobieren. Alternativ können Sie die Vorhersage-API aufrufen.

Übermitteln des Bereitstellungsauftrags

Übermitteln Sie eine PUT-Anforderung mithilfe der folgenden URL, der Header und des JSON-Texts, um einen Bereitstellungsauftrag zu übermitteln. Ersetzen Sie die Platzhalterwerte durch eigene Werte.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

Header

Verwenden Sie den folgenden Header, um Ihre Anforderung zu authentifizieren.

Anforderungstext

Verwenden Sie die folgende JSON-Datei im Textkörper Ihrer Anforderung. Verwenden Sie den Namen des Modells, das Sie der Bereitstellung zuweisen.

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

Nachdem Sie Ihre API-Anforderung gesendet haben, erhalten Sie eine 202 Antwort, die angibt, dass der Auftrag ordnungsgemäß übermittelt wurde. Extrahieren Sie in den Antwortheadern den operation-location wie folgt formatierten Wert:

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

{JOB-ID} wird verwendet, um Ihre Anforderung zu identifizieren, da es sich um einen asynchronen Vorgang handelt. Sie können den Bereitstellungsstatus über diese URL abrufen.

Abrufen des Auftragsstatus der Bereitstellung

Verwenden Sie die folgende GET-Anforderung, um den Status des Bereitstellungsauftrags abzurufen. Sie können die URL verwenden, die Sie im vorherigen Schritt erhalten haben, oder die Platzhalterwerte durch Ihre eigenen Werte ersetzen.

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

Header

Verwenden Sie den folgenden Header, um Ihre Anforderung zu authentifizieren.

Antworttext

Sobald Sie die Anforderung gesendet haben, erhalten Sie die folgende Antwort. Setzen Sie den Abruf dieses Endpunkts fort, bis der Parameter status zu „succeeded“ (erfolgreich) wechselt. Sie sollten einen 200-Code erhalten, der den Erfolg der Anforderung angibt.

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

Klassifizieren von Text

Nachdem Ihr Modell erfolgreich bereitgestellt wurde, können Sie es verwenden, um Ihren Text über die Vorhersage-API zu klassifizieren. Im zuvor heruntergeladenen Beispieldataset finden Sie einige Testdokumente, die Sie in diesem Schritt verwenden können.

Übermitteln einer Aufgabe für die benutzerdefinierte Textklassifizierung

Verwenden Sie diese POST-Anforderung, um eine Textklassifizierungsaufgabe zu starten.

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

Header

Körper

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomMultiLabelClassification",
      "taskName": "Multi Label Classification",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "Single Classification Label",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Antwort

Sie erhalten eine Antwort mit dem Statuscode 202, die auf Erfolg hinweist. Extrahieren Sie in den operation-location. operation-location weist dieses Format auf:

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Sie können diese URL verwenden, um den Abschlussstatus der Aufgabe abzufragen und die Ergebnisse abzurufen, wenn die Aufgabe abgeschlossen ist.

Abrufen der Ergebnisse der Aufgabe

Verwenden Sie die folgende GET-Anforderung, um den Status bzw. die Ergebnisse der Textklassifizierungsaufgabe abzufragen.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Header

Antworttext

Die Antwort ist ein JSON-Dokument mit den folgenden Parametern.

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

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

Bereinigen von Ressourcen

Wenn Sie Ihr Projekt nicht mehr benötigen, können Sie es mit der folgenden DELETE-Anforderung löschen. Ersetzen Sie die Platzhalterwerte durch eigene Werte.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

Header

Verwenden Sie den folgenden Header, um Ihre Anforderung zu authentifizieren.

Nachdem Sie Ihre API-Anforderung gesendet haben, erhalten Sie eine 202 Antwort, die den Erfolg angibt, was bedeutet, dass Ihr Projekt gelöscht wird. Ein erfolgreicher Aufruf enthält einen Operation-Location-Header, mit dem der Auftragsstatus überprüft wird.

Nächste Schritte

Nachdem Sie ein benutzerdefiniertes Textklassifizierungsmodell erstellt haben, können Sie:

• Verwenden der Runtime-API zum Klassifizieren von Text

Wenn Sie beginnen, eigene Projekte für die benutzerdefinierte Textklassifizierung zu erstellen, verwenden Sie die Anleitungsartikel, um ausführlichere Informationen zur Entwicklung Ihres Modells zu erhalten:

• Datenauswahl und Schemaentwurf
• Kennzeichnen von Daten
• Trainieren eines Modells
• Anzeigen der Modellauswertung