共用方式為


備份和復原您的交談語言理解模型

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

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

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

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

必要條件

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

取得您的資源金鑰端點

使用下列步驟來取得主要和次要資源的索引鍵和端點。 這些將會用於下列步驟。

前往您位於 Azure 入口網站的資源概觀頁面。 在左側功能表中,選取 [金鑰和端點]。 您將使用 API 要求的端點和金鑰

顯示 Azure 入口網站中的金鑰和端點頁面的螢幕擷取畫面。

提示

記下主要和次要資源的索引鍵和端點。 使用這些值來取代下列預留位置:{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

標頭

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

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

使用本文中 resultUrl 索引鍵的 URL,以檢視從此作業匯出的資產。

取得匯出結果

使用您從上一個步驟收到的 {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

標頭

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

機碼
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} 如需在測試和定型集之間分割資料的相關資訊,請參閱如何定型模型。 此欄位的可能值為 TrainTest 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

標頭

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

機碼
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

注意

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

傳送 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

標頭

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

機碼
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"
}
機碼 範例
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

標頭

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

機碼
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

標頭

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

機碼
Ocp-Apim-Subscription-Key 資源的金鑰。 用於驗證 API 要求。

回應本文

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

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

呼叫執行階段的變更

在您的系統內,在您呼叫執行階段 API 的步驟中,檢查從提交工作 API 傳回的回應碼。 如果您觀察到提交要求時發生一致的失敗,這可能表示主要區域中發生中斷。 失敗一次並不表示中斷,可能是暫時性問題。 請重試透過您已建立的次要資源提交作業。 針對第二個要求,使用 {YOUR-SECONDARY-ENDPOINT} 和次要金鑰,如果您已遵循上述步驟,則 {PROJECT-NAME}{DEPLOYMENT-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 執行的其他動作。