備份和復原對話式語言理解模型

當您在Azure 入口網站中建立語言資源時,您會指定要在 中建立的語言資源區域。 然後,您的資源和與其相關的所有作業都會在指定的 Azure 伺服器區域中進行。 遇到整個區域的網路問題很少見,但並非不可能。 如果您的解決方案必須一律可供使用,則您應該將其設計為容錯移轉到另一個區域。 這需要不同區域中的兩個 Azure AI 語言資源,以及跨區域同步處理 CLU 模型的能力。

如果您的應用程式或企業相依于使用 CLU 模型,建議您將專案的複本建立到另一個支援的區域。 因此,如果發生區域性中斷,您就可以在複寫專案的其他容錯移轉區域中存取模型。

複寫專案表示匯出專案中繼資料和資產,並將其匯入新專案。 這只會製作專案設定、意圖、實體和語句的複本。 您仍然需要定 部署 模型,才能搭配 執行時間 API 使用。

在本文中,您將瞭解如何使用匯出和匯入 API,將專案從一個資源複寫到另一個現有的不同支援地理區域中,以及讓專案保持同步,以及執行時間耗用量所需的變更指引。

必要條件

  • 不同 Azure 區域中的兩個 Azure AI 語言資源,分別位於不同的區域中。

取得您的資源金鑰端點

使用下列步驟來取得主要和次要資源的金鑰和端點。 這些步驟中將會使用這些專案。

移至Azure 入口網站中的 資源概觀 頁面。 從左側的功能表中,選取 [金鑰] 和 [ 端點 ]。 您將針對 API 要求使用端點和金鑰

A screenshot showing the key and endpoint page in the Azure portal.

提示

請記下主要和次要資源的金鑰和端點。 使用這些值來取代下列預留位置: {PRIMARY-ENDPOINT}{PRIMARY-RESOURCE-KEY}{SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 。 也請記下您的專案名稱、模型名稱和部署名稱。 使用這些值來取代下列預留位置: {PROJECT-NAME}{MODEL-NAME}{DEPLOYMENT-NAME}

匯出主要專案資產

首先,從主要資源中的專案匯出專案資產。

提交匯出作業

以您在 {PRIMARY-ENDPOINT}{PRIMARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

使用下列 URL、標頭和 JSON 主體建立 POST 要求,以匯出您的專案。

要求 URL

建立 API 要求時,請使用下列 URL。 以您自己的值取代下方的預留位置值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 EmailApp
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

傳送 API 要求之後,您會收到 202 指出成功的回應。 在回應標頭中,擷 operation-location 取值。 其格式如下:

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

JOB-ID 是用來識別您的要求,因為這項作業是非同步。 使用此 URL 以使用相同的驗證方法來取得匯出的專案 JSON。

取得匯出作業狀態

以您在 {PRIMARY-ENDPOINT}{PRIMARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

使用下列 GET 要求來查詢匯出作業的狀態。 您可以使用您從上一個步驟收到的 URL,或將下列預留位置值取代為您自己的值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/export/jobs/{JOB-ID}?api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 myProject
{JOB-ID} 尋找匯出作業狀態的識別碼。 這是您在 location 上一個步驟中收到的標頭值。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

機碼 描述
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。 {YOUR-PRIMARY-RESOURCE-KEY}

回應本文

{
  "resultUrl": "{Endpoint}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/export/jobs/xxxxxx-xxxxx-xxxxx-xx/result?api-version={API-VERSION}",
  "jobId": "xxxx-xxxxx-xxxxx-xxx",
  "createdDateTime": "2022-04-18T15:23:07Z",
  "lastUpdatedDateTime": "2022-04-18T15:23:08Z",
  "expirationDateTime": "2022-04-25T15:23:07Z",
  "status": "succeeded"
}

使用本文中金鑰的 URL resultUrl ,檢視此作業中匯出的資產。

取得匯出結果

使用 {RESULT-URL} 您從上一 個步驟收到的 來提交 GET 要求,以檢視匯出作業的結果。

標頭

使用下列標頭來驗證您的要求。

機碼 描述
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。 {PRIMARY-RESOURCE-KEY}

複製回應本文,因為您將使用它作為下一個匯入作業的本文。

匯入至新專案

現在,請繼續在次要區域中的新專案中匯入匯出的專案資產,以便進行複寫。

提交匯入作業

以您在 {SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

使用下列 URL、標頭和 JSON 主體提交 POST 要求,以匯入您的專案。

要求 URL

建立 API 要求時,請使用下列 URL。 將預留位置值取代為您自己的值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值會區分大小寫,而且必須符合您要匯入支 JSON 檔案中的專案名稱。 EmailAppDemo
{API-VERSION} 您要呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

本文

您傳送的 JSON 本文類似於下列範例。 如需 JSON 物件的詳細資訊,請參閱參考文件

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "{PROJECT-NAME}",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "intent1"
      },
      {
        "category": "intent2"
      }
    ],
    "entities": [
      {
        "category": "entity1"
      }
    ],
    "utterances": [
      {
        "text": "text1",
        "dataset": "{DATASET}",
        "intent": "intent1",
        "entities": [
          {
            "category": "entity1",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "text2",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "intent": "intent2",
        "entities": []
      }
    ]
  }
}

按鍵 預留位置 範例
{API-VERSION} 您要呼叫的 API 版本 2023-04-01
projectName {PROJECT-NAME} 專案的名稱。 此值區分大小寫。 EmailAppDemo
language {LANGUAGE-CODE} 字串,指定專案中所用語句的語言代碼。 如果您的專案是多語系專案,請選擇 大部分語句的語言代碼 en-us
multilingual true 布林值,可讓您在資料集中具有多種語言的檔。 部署模型時,您可以以任何支援的語言 (包含不在您的定型文件中的語言) 查詢模型。 true
dataset {DATASET} 如需在測試和定型集之間分割資料的資訊,請參閱 如何定型模型 。 此欄位 Train 的可能值為 和 Test Train

成功要求時,API 回應會包含 operation-location 標頭,其中包含可用來檢查匯入工作狀態的 URL。 其格式如下所示:

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

取得匯入作業狀態

以您在 {SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

當您傳送成功的專案匯入要求時,檢查匯入作業狀態的完整要求 URL (包括端點、專案名稱和作業識別碼) 會包含在回應的 operation-location 標頭中。

使用下列 GET 要求來查詢匯入作業的狀態。 您可以使用您在上一個步驟中收到的 URL,或以您自己的值取代下列預留位置值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 myProject
{JOB-ID} 用於尋找匯出作業狀態的識別碼。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

機碼 描述
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。 {YOUR-PRIMARY-RESOURCE-KEY}

回應本文

傳送要求之後,您會收到下列回應。 請持續輪詢此端點,直到狀態參數變更為「成功」為止。

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

定型您的模型

匯入專案之後,您只會複製專案的資產和中繼資料和資產。 您仍然需要將模型定型,這會在您的帳戶上使用。

提交訓練作業

以您在 {SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

使用下列 URL、標頭和 JSON 主體建立 POST 要求,以提交定型作業。

要求 URL

建立 API 要求時,請使用下列 URL。 將預留位置值取代為您自己的值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 EmailApp
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

要求本文

在您的要求中使用下列物件。 定型完成後,模型會以您用於 modelLabel 參數的值命名。

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "{TRAINING-MODE}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}
按鍵 預留位置 範例
modelLabel {MODEL-NAME} 您的模型名稱。 Model1
trainingConfigVersion {CONFIG-VERSION} 定型組態模型版本。 根據預設,會使用最新的 模型版本 2022-05-01
trainingMode {TRAINING-MODE} 要用於定型的定型模式。 支援的模式是 標準訓練、更快速的訓練 ,但僅適用于其他語言和多語系專案支援的英文和 進階訓練 ,但涉及較長的訓練時間。 深入瞭解模型定型 standard
kind percentage 分割方法。 可能的值為 percentagemanual 。 如需詳細資訊,請參閱 如何定型模型 percentage
trainingSplitPercentage 80 要包含在定型集中的標記資料百分比。 建議值為 80 80
testingSplitPercentage 20 要包含在測試集中的標記資料百分比。 建議值為 20 20

注意

trainingSplitPercentage只有在 設定為 percentage 且這兩個百分比的總和應等於 100 時 Kind ,才需要 和 testingSplitPercentage

傳送 API 要求之後,您會收到 202 指出成功的回應。 在回應標頭中,擷 operation-location 取值。 其格式如下:

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

您可以使用此 URL 來取得定型作業狀態。

取得訓練狀態

以您在 {SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

當您傳送成功的訓練要求時,檢查作業狀態的完整要求 URL (包括端點、專案名稱和作業識別碼) 包含在回應的 operation-location 標頭中。

使用下列 GET 要求來取得模型定型進度的狀態。 以您自己的值取代下方的預留位置值。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
預留位置 範例
{YOUR-ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 EmailApp
{JOB-ID} 用來尋找模型定型狀態的識別碼。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

回應本文

傳送要求之後,您會收到下列回應。 請持續輪詢此端點, 直到狀態 參數變更為「成功」為止。

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "trainingMode": "{TRAINING-MODE}",
    "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": "xxxxx-xxxxx-xxxx-xxxxx-xxxx",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}
Key 範例
modelLabel 模型名稱 Model1
trainingConfigVersion 定型組態版本。 根據預設,會 使用最新版本 2022-05-01
trainingMode 您選取的 訓練模式 standard
startDateTime 開始訓練的時間 2022-04-14T10:23:04.2598544Z
status 訓練作業的狀態 running
estimatedEndDateTime 定型作業完成的估計時間 2022-04-14T10:29:38.2598544Z
jobId 您的訓練作業識別碼 xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
createdDateTime 定型作業建立日期和時間 2022-04-14T10:22:42Z
lastUpdatedDateTime 定型作業上次更新的日期和時間 2022-04-14T10:23:45Z
expirationDateTime 定型作業到期日期和時間 2022-04-14T10:22:42Z

部署模型

這是您透過執行時間預測 API 讓定型模型可供使用表單耗用量 的步驟。

提示

使用與主要專案相同的部署名稱,以方便維護和對系統進行最少的變更,以處理重新導向流量。

提交部署作業

以您在 {SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

使用下列 URL、標頭和 JSON 主體建立 PUT 要求,以開始部署對話式語言理解模型。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 myProject
{DEPLOYMENT-NAME} 部署的名稱。 此值區分大小寫。 staging
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

要求本文

{
  "trainedModelLabel": "{MODEL-NAME}",
}
按鍵 預留位置 範例
trainedModelLabel {MODEL-NAME} 模型名稱會指派給您的部署。 您只能指派已成功定型的模型。 此值區分大小寫。 myModel

傳送 API 要求之後,您會收到 202 指出成功的回應。 在回應標頭中,擷 operation-location 取值。 其格式如下:

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

您可以使用此 URL 來取得部署作業狀態。

取得部署狀態

以您在 {SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 第一個步驟中取得的 和 取代下列要求的預留位置。

當您傳送成功的部署要求時,檢查作業狀態的完整要求 URL (包括端點、專案名稱和作業識別碼) 會包含在回應的 operation-location 標頭中。

使用下列 GET 要求來取得部署作業的狀態。 將預留位置值取代為您自己的值。

要求 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 myProject
{DEPLOYMENT-NAME} 部署的名稱。 此值區分大小寫。 staging
{JOB-ID} 用來尋找模型定型狀態的識別碼。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

回應本文

傳送要求之後,您會收到下列回應。 請持續輪詢此端點, 直到狀態 參數變更為「成功」為止。

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

呼叫執行時間的變更

在您的系統中,在您呼叫 執行時間 API 檢查從提交工作 API 傳回的回應碼的步驟中。 如果您在提交要求時觀察到一 致的 失敗,這可能表示主要區域中發生中斷。 失敗一旦並不表示中斷,可能是暫時性問題。 請重試透過您已建立的次要資源提交作業。 針對第二個要求使用您的 {YOUR-SECONDARY-ENDPOINT} 和 次要金鑰,如果您已遵循上述步驟,而且 {DEPLOYMENT-NAME} 會是相同的, {PROJECT-NAME} 因此要求本文不需要變更。

如果您還原為使用次要資源,您將觀察到延遲略有增加,因為部署模型的區域有所差異。

檢查您的專案是否同步

維護這兩個專案的新鮮度是程式的重要部分。 您需要經常檢查主要專案是否有任何更新,以便將它們移至次要專案。 如此一來,如果您的主要區域失敗,而且您進入次要區域,您應該預期類似的模型效能,因為它已經包含最新的更新。 設定專案同步檢查的頻率是一個重要選擇,建議您每天進行這項檢查,以確保次要模型中的資料新鮮度。

取得專案詳細資料

使用下列 URL 來取得專案詳細資料,本文中傳回的其中一個索引鍵會指出專案上次修改日期。 重複下列步驟兩次,一個用於您的主要專案,另一個用於次要專案,並比較兩者傳回的時間戳記,以檢查它們是否同步。

使用下列 GET 要求來取得專案詳細資料。 您可以使用您從上一個步驟收到的 URL,或將下列預留位置值取代為您自己的值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}
預留位置 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 myProject
{API-VERSION} 您正在呼叫的 API 版本 2023-04-01

標頭

使用下列標頭來驗證您的要求。

機碼 描述
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。 {YOUR-PRIMARY-RESOURCE-KEY}

回應本文

{
  "createdDateTime": "2022-04-18T13:53:03Z",
  "lastModifiedDateTime": "2022-04-18T13:53:03Z",
  "lastTrainedDateTime": "2022-04-18T14:14:28Z",
  "lastDeployedDateTime": "2022-04-18T14:49:01Z",
  "projectKind": "Conversation",
  "projectName": "{PROJECT-NAME}",
  "multilingual": true,
  "description": "This is a sample conversation project.",
  "language": "{LANGUAGE-CODE}"
}

使用 {SECONDARY-ENDPOINT}{SECONDARY-RESOURCE-KEY} 重複複寫專案的相同步驟。 比較從這兩個專案傳回的 lastModifiedDateTime 。 如果您的主要專案比次要專案更快速修改,您必須重複匯出、匯入、 型和 部署 模型的步驟

下一步

在本文中,您已瞭解如何使用匯出和匯入 API,將專案複寫至其他區域中的次要語言資源。 接下來,探索 API 參考檔,以查看撰寫 API 的其他功能。