Tworzenie kopii zapasowych i odzyskiwanie niestandardowych modeli NER

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. Rzadko zdarza się, ale nie niemożliwe, aby napotkać problem z siecią, który ma wpływ na cały region. Jeśli rozwiązanie musi być zawsze dostępne, należy zaprojektować go w trybie failover w innym regionie. Ten proces wymaga dwóch zasobów usługi Azure Language in Foundry Tools w różnych regionach i synchronizowania modeli niestandardowych między nimi.

Jeśli twoja aplikacja lub firma zależy od użycia niestandardowego modelu NER, zalecamy utworzenie repliki projektu w innym obsługiwanym regionie. Jeśli wystąpi awaria regionalna, możesz uzyskać dostęp do modelu w innym regionie trybu failover, w którym został zreplikowany projekt.

Replikowanie projektu oznacza wyeksportowanie metadanych i zasobów projektu oraz zaimportowanie ich do nowego projektu. Ten krok powoduje utworzenie kopii ustawień projektu i otagowanych danych. 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.

Wymagania wstępne

• Dwa zasoby językowe w różnych regionach świadczenia usługi Azure. Utwórz zasoby i połącz je z kontem usługi Azure Storage. Zalecamy połączenie każdego z zasobów językowych z różnymi kontami magazynu. Każde konto magazynu powinno znajdować się w tych samych regionach, w których znajdują się oddzielne zasoby językowe. Możesz skorzystać z przewodnika szybkiego startu, aby utworzyć kolejny zasób językowy i konto magazynowe.

Pobierz punkt końcowy kluczy zasobów

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

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

2. 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 ze swojego głównego zasobu.

Przesyłanie zadania eksportu

Zastąp symbole zastępcze w poniższym żądaniu swoimi {PRIMARY-ENDPOINT} i {PRIMARY-RESOURCE-KEY} uzyskanymi 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.

Tekst główny

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 wartość operation-location 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. Ten adres URL służy do pobierania stanu zadania eksportu.

Uzyskiwanie stanu zadania eksportu

Zastąp symbole zastępcze w poniższym żądaniu swoimi {PRIMARY-ENDPOINT} i {PRIMARY-RESOURCE-KEY} uzyskanymi 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 i wyświetl wyeksportowane zasoby 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, aby użyć jej jako treści 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 {SECONDARY-ENDPOINT}, {SECONDARY-RESOURCE-KEY} i {SECONDARY-CONTAINER-NAME}, 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.

Tekst główny

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}",
        "projectKind": "CustomEntityRecognition",
        "description": "Trying out custom NER",
        "language": "{LANGUAGE-CODE}",
        "multilingual": true,
        "storageInputContainerName": "{CONTAINER-NAME}",
        "settings": {}
    },
    "assets": {
    "projectKind": "CustomEntityRecognition",
        "entities": [
            {
                "category": "Entity1"
            },
            {
                "category": "Entity2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 500,
                        "labels": [
                            {
                                "category": "Entity1",
                                "offset": 25,
                                "length": 10
                            },
                            {
                                "category": "Entity2",
                                "offset": 120,
                                "length": 8
                            }
                        ]
                    }
                ]
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 100,
                        "labels": [
                            {
                                "category": "Entity2",
                                "offset": 20,
                                "length": 5
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Po wysłaniu żądania interfejsu API otrzymasz odpowiedź wskazującą 202 , że zadanie zostało przesłane poprawnie. W nagłówkach odpowiedzi wyodrębnij wartość operation-location. Oto przykład formatu:

{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 przechowywania.
• 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ą.

Pobierz status 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 jest przedstawiany jako {MODEL-NAME} po zakończeniu trenowania. Tylko pomyślne zadania szkoleniowe tworzą 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 wartość location sformatowaną w następujący sposób:

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

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

Sprawdź stan szkolenia

Zastąp symbole zastępcze w poniższym żądaniu swoimi {SECONDARY-ENDPOINT} i {SECONDARY-RESOURCE-KEY} uzyskanymi 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

W tym kroku udostępnisz wytrenowany model do użycia za pomocą interfejsu API przewidywania środowiska uruchomieniowego.

Prześlij zadanie wdrożenia

Zastąp symbole zastępcze w poniższym żądaniu swoim {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 wartość operation-location 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}

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

Pobierz stan 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ź. Kontynuuj sondowanie tego punktu końcowego, aż parametr status zmieni się na "sukces". 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. Jednorazowe niepowodzenie nie oznacza awarii — może to być przejściowy problem. 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 powró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 datę ostatniej 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 z nich, aby sprawdzić, czy nie są 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": "CustomEntityRecognition",
        "storageInputContainerName": "{CONTAINER-NAME}",
        "projectName": "{PROJECT-NAME}",
        "multilingual": false,
        "description": "Project description",
        "language": "{LANGUAGE-CODE}"
    }

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.

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