Szybki start: spersonalizowany interfejs API REST do klasyfikacji tekstu

Skorzystaj z tego artykułu, aby rozpocząć tworzenie niestandardowego projektu klasyfikacji tekstu, w którym można trenować modele niestandardowe na potrzeby klasyfikacji tekstu. Model to oprogramowanie sztucznej inteligencji przeszkolone w celu wykonania określonego zadania. W przypadku tego systemu modele klasyfikują tekst i są szkolone przez uczenie się na podstawie oznakowanych danych.

Niestandardowa klasyfikacja tekstu obsługuje dwa typy projektów:

• Klasyfikacja pojedynczej etykiety — można przypisać pojedynczą klasę dla każdego dokumentu w zestawie danych. Na przykład skrypt filmowy można sklasyfikować tylko jako "Romans" lub "Komedia".
• Klasyfikacja wielu etykiet — można przypisać wiele klas dla każdego dokumentu w zestawie danych. Na przykład skrypt filmowy można sklasyfikować jako "Komedia" lub "Romans" i "Komedia".

W tym krótkim przewodniku możesz użyć udostępnionych przykładowych zestawów danych do utworzenia wielokrotnej klasyfikacji w celu klasyfikowania skryptów filmowych w jednej lub więcej kategorii. Alternatywnie można użyć zestawu danych klasyfikacji jednoetykietowej do klasyfikowania streszczeń naukowych artykułów w jednej ze zdefiniowanych domen.

Wymagania wstępne

• Subskrypcja platformy Azure — utwórz jedną bezpłatnie.

Tworzenie nowego języka platformy Azure w zasobie narzędzi Foundry Tools i koncie usługi Azure Storage

Zanim będzie można użyć niestandardowej klasyfikacji tekstu, musisz utworzyć zasób językowy, który zapewni poświadczenia potrzebne do utworzenia projektu i rozpoczęcia trenowania modelu. Potrzebujesz również konta usługi Azure Storage, na którym można przekazać zestaw danych używany podczas tworzenia modelu.

Tworzenie nowego zasobu w witrynie Azure Portal

1. Przejdź do Azure portal, aby utworzyć nowy zasób Azure Language w narzędziach Foundry.

2. W wyświetlonym oknie wybierz pozycję Niestandardowa klasyfikacja tekstu i niestandardowe rozpoznawanie nazwanych jednostek z funkcji niestandardowych. Wybierz pozycję Kontynuuj, aby utworzyć zasób w dolnej części ekranu.

   

3. Utwórz zasób języka, postępując zgodnie z poniższymi szczegółami.

   Nazwisko	Wartość wymagana
   Subskrypcja	Swoją subskrypcję platformy Azure.
   Grupa zasobów	Grupa zasobów, która będzie zawierać zasób. Możesz użyć istniejącej lub utworzyć nową.
   Region (Region)	Jeden z obsługiwanych regionów. Na przykład "Zachodnie stany USA 2".
   Nazwisko	Nazwa zasobu.
   Warstwa cenowa	Jedna z obsługiwanych warstw cenowych. Aby wypróbować usługę, możesz użyć warstwy Bezpłatna (F0).

   Jeśli zostanie wyświetlony komunikat "Twoje konto logowania nie jest właścicielem wybranej grupy zasobów konta magazynu", twoje konto musi mieć przypisaną rolę właściciela w grupie zasobów, zanim będzie można utworzyć zasób językowy. Skontaktuj się z właścicielem subskrypcji platformy Azure, aby uzyskać pomoc.

   Możesz określić właściciela subskrypcji platformy Azure, wyszukując grupę zasobów i korzystając z linku do skojarzonej subskrypcji. Następnie:

   1. Wybierz kartę Kontrola dostępu (Zarządzanie dostępem i tożsamościami)
   2. Wybieranie przypisań ról
   3. Filtruj według roli:właściciel.

4. W sekcji Niestandardowa klasyfikacja tekstu i niestandardowe rozpoznawanie nazwanych jednostek wybierz istniejące konto magazynu lub wybierz pozycję Nowe konto magazynu. Należy pamiętać, że te wartości ułatwiają rozpoczęcie pracy, a niekoniecznie wartości konta magazynu, których chcesz użyć w środowiskach produkcyjnych. Aby uniknąć opóźnień podczas kompilowania projektu, połącz się z kontami magazynu w tym samym regionie co zasób języka.

   Wartość konta magazynu	Zalecana wartość
   Nazwa konta magazynu	Dowolna nazwa
   Typ konta magazynowania	Standardowa LRS

5. Upewnij się, że zaznaczono powiadomienie o odpowiedzialnej sztucznej inteligencji . Wybierz pozycję Przejrzyj i utwórz w dolnej części strony.

Przekazywanie przykładowych danych do kontenera obiektów blob

Po utworzeniu konta usługi Azure Storage i połączeniu go z zasobem Language należy przekazać dokumenty z przykładowego zestawu danych do katalogu głównego kontenera. Te dokumenty są używane do trenowania modelu.

Azure Portal

1. W witrynie Azure Portal przejdź do utworzonego konta magazynu i wybierz je, wybierając pozycję Konta magazynu i wpisując nazwę konta magazynu w polu Filtruj dla dowolnego pola.

   Jeśli grupa zasobów nie jest wyświetlana, upewnij się, że filtr Subskrypcja równa się jest ustawiony na Wszystkie.

2. Na koncie magazynu wybierz pozycję Kontenery z menu po lewej stronie, znajdującym się poniżej obszaru Magazyn danych. Na wyświetlonym ekranie wybierz pozycję + Kontener. Nadaj kontenerowi nazwę example-data i pozostaw domyślny poziom dostępu publicznego.

   

3. Po utworzeniu kontenera wybierz go. Następnie wybierz przycisk Przekaż , aby wybrać .txt pobrane wcześniej pliki i .json .

   

Pobieranie kluczy zasobów i punktu końcowego

• Przejdź do strony przeglądu zasobu w witrynie Azure Portal

• Z menu po lewej stronie wybierz pozycję Klucze i punkt końcowy. Punkt końcowy i klucz są używane dla żądań interfejsu API.

Tworzenie niestandardowego projektu klasyfikacji tekstu

Po skonfigurowaniu zasobu i kontenera magazynu utwórz nowy niestandardowy projekt klasyfikacji tekstu. Projekt to obszar roboczy umożliwiający tworzenie niestandardowych modeli uczenia maszynowego na podstawie danych. Projekt może być dostępny tylko dla Ciebie oraz innych osób, które mają dostęp do zasobu językowego platformy Azure.

Wyzwalanie zadania importowania projektu

Prześlij żądanie POST przy użyciu następującego adresu URL, nagłówków i treści JSON, aby zaimportować plik etykiet. Upewnij się, że plik etykiet jest zgodne z akceptowanym formatem.

Jeśli projekt o tej samej nazwie już istnieje, dane tego projektu zostaną zastąpione.

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

Nagłówki

Użyj następującego nagłówka, aby uwierzytelnić żądanie.

Treść

Użyj następującego kodu JSON w żądaniu. Zastąp wartości symboli zastępczych własnymi wartościami.

{
  "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"
                }
            }
        ]
    }
}

Po wysłaniu żądania interfejsu API otrzymasz odpowiedź wskazującą 202 , że zadanie zostało przesłane poprawnie. W nagłówkach odpowiedzi wyodrębnij operation-location wartość sformatowaną w następujący sposób:

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

{JOB-ID} służy do identyfikowania żądania, ponieważ ta operacja jest asynchroniczna. Ten adres URL służy do pobierania stanu zadania importu.

Możliwe scenariusze błędów dla tego żądania:

• Wybrany zasób nie ma odpowiednich uprawnień dla konta magazynu.
• Określona storageInputContainerName wartość nie istnieje.
• Jest używany nieprawidłowy kod języka lub jeśli typ kodu języka nie jest ciągiem.
• multilingual wartość jest ciągiem, a nie wartością logiczną.

Pobieranie stanu zadania importu

Użyj następującego żądania GET , aby uzyskać stan importowania projektu. Zastąp wartości symboli zastępczych własnymi wartościami.

Adres URL żądania

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

Nagłówki

Użyj następującego nagłówka, aby uwierzytelnić żądanie.

Szkolenie modelu

Zazwyczaj po utworzeniu projektu możesz zacząć oznaczać dokumenty , które masz w kontenerze połączonym z projektem. Na potrzeby tego przewodnika Szybki start zaimportowano przykładowy otagowany zestaw danych i zainicjowano projekt przy użyciu przykładowego pliku tagów JSON.

Rozpoczynanie trenowania modelu

Po zaimportowaniu projektu możesz rozpocząć trenowanie modelu.

Prześlij żądanie POST przy użyciu następującego adresu URL, nagłówków i treści JSON, aby przesłać zadanie szkoleniowe. Zastąp wartości symboli zastępczych własnymi wartościami.

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

Nagłówki

Użyj następującego nagłówka, aby uwierzytelnić żądanie.

Treść żądania

Użyj następującego kodu JSON w treści żądania. Model zostanie podany po zakończeniu {MODEL-NAME} trenowania. Tylko pomyślne zadania szkoleniowe będą tworzyć modele.

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

Po wysłaniu żądania interfejsu API otrzymasz odpowiedź wskazującą 202 , że zadanie zostało przesłane poprawnie. W nagłówkach odpowiedzi wyodrębnij location wartość sformatowaną w następujący sposób:

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

Element {JOB-ID} służy do identyfikowania żądania, ponieważ ta operacja jest asynchroniczna. Możesz użyć tego adresu URL, aby uzyskać stan trenowania.

Uzyskiwanie stanu zadania szkoleniowego

Trenowanie może potrwać od 10 do 30 minut. Następujące żądanie umożliwia kontynuowanie sondowania stanu zadania szkoleniowego do momentu jego pomyślnego ukończenia.

Użyj następującego żądania GET , aby uzyskać stan postępu trenowania modelu. Zastąp wartości symboli zastępczych własnymi wartościami.

Adres URL żądania

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

Nagłówki

Użyj następującego nagłówka, aby uwierzytelnić żądanie.

Treść odpowiedzi

Po wysłaniu żądania otrzymasz następującą odpowiedź.

{
  "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"
}

Wdrażanie modelu

Zazwyczaj po trenowaniu modelu należy przejrzeć jego szczegóły oceny i w razie potrzeby wprowadzić ulepszenia. W tym przewodniku Szybki start wdrożysz model i udostępnisz go do wypróbowania w programie Language Studio lub możesz wywołać interfejs API przewidywania.

Przesyłanie zadania wdrożenia

Prześlij żądanie PUT przy użyciu następującego adresu URL, nagłówków i treści JSON, aby przesłać zadanie wdrożenia. Zastąp wartości symboli zastępczych własnymi wartościami.

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

Nagłówki

Użyj następującego nagłówka, aby uwierzytelnić żądanie.

Treść żądania

Użyj następującego kodu JSON w treści żądania. Użyj nazwy modelu, który chcesz przypisać do wdrożenia.

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

Po wysłaniu żądania interfejsu API otrzymasz odpowiedź wskazującą 202 , że zadanie zostało przesłane poprawnie. W nagłówkach odpowiedzi wyodrębnij operation-location wartość sformatowaną w następujący sposób:

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

Element {JOB-ID} służy do identyfikowania żądania, ponieważ ta operacja jest asynchroniczna. Możesz użyć tego adresu URL, aby uzyskać stan wdrożenia.

Pobieranie stanu zadania wdrożenia

Użyj następującego żądania GET , aby wykonać zapytanie dotyczące stanu zadania wdrożenia. Możesz użyć adresu URL otrzymanego z poprzedniego kroku lub zastąpić wartości symboli zastępczych własnymi wartościami.

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

Nagłówki

Użyj następującego nagłówka, aby uwierzytelnić żądanie.

Treść odpowiedzi

Po wysłaniu żądania otrzymasz następującą odpowiedź. Nie sonduj tego punktu końcowego , dopóki parametr stanu nie zmieni się na "powodzenie". Powinien zostać wyświetlony 200 kod wskazujący powodzenie żądania.

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

Klasyfikowanie tekstu

Po pomyślnym wdrożeniu modelu możesz zacząć używać go do klasyfikowania tekstu za pomocą interfejsu API przewidywania. W pobranym wcześniej przykładowym zestawie danych można znaleźć niektóre dokumenty testowe, których można użyć w tym kroku.

Przesyłanie niestandardowego zadania klasyfikacji tekstu

Użyj tego żądania POST , aby uruchomić zadanie klasyfikacji tekstu.

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

Nagłówki

Treść

{
  "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}"
      }
    }
  ]
}

Odpowiedź

Otrzymasz odpowiedź 202 wskazującą powodzenie. W nagłówkach odpowiedzi wyodrębnij element operation-location. operation-location jest sformatowany w następujący sposób:

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

Możesz użyć tego adresu URL, aby wykonać zapytanie dotyczące stanu ukończenia zadania i uzyskać wyniki po zakończeniu zadania.

Pobieranie wyników zadania

Użyj następującego żądania GET , aby wykonać zapytanie dotyczące stanu/wyników zadania klasyfikacji tekstu.

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

Nagłówki

Treść odpowiedzi

Odpowiedź będzie dokumentem JSON z następującymi parametrami.

{
  "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"
        }
      }
    ]
  }
}

Czyszczenie zasobów

Jeśli projekt nie jest już potrzebny, możesz go usunąć za pomocą następującego żądania DELETE . Zastąp wartości symboli zastępczych własnymi wartościami.

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

Nagłówki

Użyj następującego nagłówka, aby uwierzytelnić żądanie.

Po wysłaniu żądania API otrzymasz odpowiedź wskazującą 202 powodzenie, co oznacza, że projekt został usunięty. Wyniki pomyślnego wywołania z nagłówkiem Operation-Location służącym do sprawdzania stanu zadania.

Następne kroki

Po utworzeniu niestandardowego modelu klasyfikacji tekstu można wykonywać następujące czynności:

• Klasyfikowanie tekstu przy użyciu interfejsu API środowiska uruchomieniowego

Gdy zaczniesz tworzyć własne niestandardowe projekty klasyfikacji tekstu, skorzystaj z artykułów z instrukcjami, aby dowiedzieć się więcej na temat tworzenia modelu w bardziej szczegółowy sposób:

• Wybór danych i projekt schematu
• Tagowanie danych
• Szkolenie modelu
• Wyświetlanie oceny modelu