Tworzenie kopii zapasowych i odzyskiwanie niestandardowych modeli klasyfikacji tekstu

Podczas tworzenia zasobu języka należy określić region, w którym ma zostać utworzony. Od tego czasu zasób i wszystkie powiązane z nim operacje odbywają się w określonym regionie serwera platformy Azure. Problem z siecią, który dotyczy całego regionu, zdarza się rzadko, ale nie jest niemożliwy. Jeśli rozwiązanie musi być zawsze dostępne, należy zaprojektować je w trybie failover w innym regionie. Tryb failover wymaga dwóch zasobów narzędzi Azure Language in Foundry Tools w różnych regionach oraz możliwości synchronizowania modeli niestandardowych między regionami.

Jeśli aplikacja lub firma zależy od użycia niestandardowego modelu klasyfikacji tekstu, zalecamy utworzenie repliki projektu w innym obsługiwanym regionie. Dzięki temu, jeśli wystąpi awaria regionalna, możesz uzyskać dostęp do modelu w innym regionie pracy awaryjnej, w którym został zreplikowany projekt.

Replikowanie projektu oznacza wyeksportowanie metadanych i zasobów projektu i zaimportowanie ich do nowego projektu. Replikacja tworzy tylko kopię ustawień projektu i oznakowane dane. Nadal musisz wytrenować i wdrożyć modele, które będą dostępne do użycia z interfejsami API przewidywania.

W tym artykule dowiesz się, jak używać interfejsów API eksportu i importowania do replikowania projektu z jednego zasobu do innego istniejącego w różnych obsługiwanych regionach geograficznych. Udostępniamy również wskazówki dotyczące utrzymywania synchronizacji projektów i aktualizacji wymaganych do użycia w środowisku uruchomieniowym.

Wymagania wstępne

• Dwa zasoby językowe w różnych regionach świadczenia usługi Azure. Utwórz zasób języka i połącz je z kontem usługi Azure Storage. Zalecamy połączenie obu zasobów językowych z tym samym kontem magazynowym. Mimo że ten krok może spowodować nieco większe opóźnienie podczas importowania projektu i trenowanie modelu.

Uzyskiwanie punktu końcowego kluczy zasobów

Wykonaj poniższe kroki, aby uzyskać klucze i punkt końcowy zasobów podstawowych i pomocniczych.

• 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.

Eksportowanie zasobów projektu podstawowego

Rozpocznij od wyeksportowania zasobów projektu z projektu w zasobie podstawowym.

Przesyłanie zadania eksportu

Zastąp symbole zastępcze w poniższym żądaniu swoim {PRIMARY-ENDPOINT} i {PRIMARY-RESOURCE-KEY} uzyskanym w pierwszym kroku.

Utwórz żądanie POST przy użyciu następującego adresu URL, nagłówków i treści JSON w celu wyeksportowania projektu.

Adres URL żądania

Podczas tworzenia żądania interfejsu API użyj następującego adresu URL. Zastąp wartości zastępcze własnymi wartościami.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&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 treści żądania, określając, że chcesz wyeksportować wszystkie zasoby.

{
  "assetsToExport": ["*"]
}

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}/export/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} służy do identyfikowania żądania, ponieważ ta operacja jest asynchroniczna. Użyj tego adresu URL, aby uzyskać stan zadania eksportu.

Uzyskiwanie stanu zadania eksportu

Zastąp symbole zastępcze w poniższym żądaniu swoim {PRIMARY-ENDPOINT} i {PRIMARY-RESOURCE-KEY} uzyskanym w pierwszym kroku.

Użyj następującego żądania GET , aby uzyskać stan eksportowania zasobów projektu. Zastąp wartości zastępcze własnymi wartościami.

Adres URL żądania

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

Nagłówki

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

Treść odpowiedzi

{
  "resultUrl": "{RESULT-URL}",
  "jobId": "string",
  "createdDateTime": "2021-10-19T23:24:41.572Z",
  "lastUpdatedDateTime": "2021-10-19T23:24:41.572Z",
  "expirationDateTime": "2021-10-19T23:24:41.572Z",
  "status": "unknown",
  "errors": [
    {
      "code": "unknown",
      "message": "string"
    }
  ]
}

Użyj adresu URL z klucza resultUrl w treści wiadomości i wyświetl wyeksportowane zasoby z tego zadania.

Pobieranie wyników eksportu

Prześlij żądanie GET przy użyciu {RESULT-URL} otrzymanego z poprzedniego kroku, aby wyświetlić wyniki zadania eksportu.

Nagłówki

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

Skopiuj treść odpowiedzi do użycia jako treść na potrzeby następnego zadania importu.

Importowanie do nowego projektu

Teraz zaimportuj wyeksportowane zasoby projektu w nowym projekcie w regionie pomocniczym, aby można je było replikować.

Przesyłanie zadania importu

Zastąp symbole zastępcze w poniższym żądaniu swoimi {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY}, które uzyskałeś w pierwszym kroku.

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 zastępcze 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

Zastąp symbole zastępcze w poniższym żądaniu swoimi {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY}, które uzyskałeś w pierwszym kroku.

Użyj następującego żądania GET , aby uzyskać stan importowania projektu. Zastąp wartości zastępcze 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

Po zaimportowaniu projektu, skopiowałeś tylko zasoby i metadane projektu. Wciąż musisz trenować swój model, co generuje koszty na twoim koncie.

Przesyłanie zadania szkoleniowego

Zastąp symbole zastępcze w poniższym żądaniu swoimi {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY}, które uzyskałeś w pierwszym kroku.

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 zastępcze 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.

Pobieranie stanu szkolenia

Zastąp symbole zastępcze w poniższym żądaniu swoimi {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY}, które uzyskałeś w pierwszym kroku.

Użyj następującego żądania GET , aby uzyskać stan postępu trenowania modelu. Zastąp wartości zastępcze 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

Wdrożenie to krok, w którym udostępniasz wytrenowany model do użytkowania za pośrednictwem interfejsu API predykcji czasu wykonywania.

Przesyłanie zadania wdrożenia

Zastąp symbole zastępcze w poniższym żądaniu swoimi {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY}, które uzyskałeś w pierwszym kroku.

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 zastępcze 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 wdrożenia

Zastąp symbole zastępcze w poniższym żądaniu swoimi {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY}, które uzyskałeś w pierwszym kroku.

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

Zmiany w wywoływaniu środowiska uruchomieniowego

W systemie, w kroku, w którym wywołujesz API przewidywania w środowisku uruchomieniowym, sprawdź kod odpowiedzi zwrócony przez interfejs API przesłanego zadania. Jeśli obserwujesz spójny błąd podczas przesyłania żądania, może to oznaczać awarię w regionie podstawowym. Jednorazowa awaria nie oznacza przerwy w działaniu; może to być problem przejściowy. Ponów próbę przesłania zadania za pomocą utworzonego zasobu pomocniczego. W przypadku drugiego żądania użyj wartości {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY}. Jeśli wykonano poprzednie kroki, {PROJECT-NAME} i {DEPLOYMENT-NAME} będą takie same, więc zmiany w treści żądania nie są wymagane.

Jeśli wrócisz do korzystania z zasobu pomocniczego, możesz zaobserwować niewielki wzrost opóźnienia ze względu na różnicę w regionach, w których wdrożono model.

Sprawdzanie, czy projekty nie są zsynchronizowane

Utrzymanie świeżości obu projektów jest ważną częścią procesu. Należy często sprawdzać, czy jakiekolwiek aktualizacje zostały wprowadzone do projektu podstawowego, aby przenieść je do projektu pomocniczego. W ten sposób, jeśli region podstawowy ulegnie awarii i przejdziesz do regionu pomocniczego, należy oczekiwać podobnej wydajności modelu, ponieważ zawiera on już najnowsze aktualizacje. Ustawienie częstotliwości sprawdzania, czy projekty są zsynchronizowane, jest ważnym wyborem, zalecamy wykonanie tej kontroli codziennie, aby zagwarantować świeżość danych w modelu pomocniczym.

Pobieranie szczegółów projektu

Użyj następującego adresu URL, aby uzyskać szczegóły projektu. Jeden z kluczy zwróconych w treści wskazuje ostatnią datę modyfikacji projektu. Powtórz następujący krok dwa razy: raz dla projektu podstawowego i ponownie dla projektu pomocniczego. Porównaj znacznik czasu zwrócony dla obu elementów, aby sprawdzić, czy nie są one zsynchronizowane.

Użyj następującego żądania GET , aby uzyskać szczegóły projektu. Zastąp wartości zastępcze własnymi wartościami.

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

Nagłówki

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

Treść odpowiedzi

    {
        "createdDateTime": "2021-10-19T23:24:41.572Z",
        "lastModifiedDateTime": "2021-10-19T23:24:41.572Z",
        "lastTrainedDateTime": "2021-10-19T23:24:41.572Z",
        "lastDeployedDateTime": "2021-10-19T23:24:41.572Z",
        "projectKind": "customMultiLabelClassification",
        "storageInputContainerName": "{CONTAINER-NAME}",
        "projectName": "{PROJECT-NAME}",
        "multilingual": false,
        "description": "Project description",
        "language": "{LANGUAGE-CODE}"
    }

Po wysłaniu żądania API otrzymasz odpowiedź 200 wskazującą powodzenie oraz treść odpowiedzi JSON ze szczegółami projektu.

Powtórz te same kroki dla replikowanego projektu przy użyciu parametrów {SECONDARY-ENDPOINT}i {SECONDARY-RESOURCE-KEY}. Porównaj zwrócone lastModifiedDateTime dane z obu projektów. Jeśli projekt podstawowy został zmodyfikowany wcześniej niż pomocniczy, należy powtórzyć kroki eksportowania, importowania, trenowania i wdrażania modelu.

Następne kroki

W tym artykule przedstawiono sposób używania interfejsów API eksportu i importowania do replikowania projektu do zasobu języka pomocniczego w innym regionie. Następnie zapoznaj się z dokumentacją referencyjną interfejsu API, aby zobaczyć, co jeszcze można zrobić za pomocą interfejsów API tworzenia.

• Dokumentacja interfejsu API REST tworzenia
• Dokumentacja interfejsu API REST przewidywania środowiska uruchomieniowego