备份和恢复对话语言理解模型

项目
05/27/2024

在 Azure 门户中创建语言资源时，需要指定要在其中创建它的区域。此后，资源及其相关的所有操作都在指定的 Azure 服务器区域发生。有时我们会遇到影响整个区域的网络问题，这种情况比较罕见，但也不是没有可能。如果你的解决方案需要始终可用，则应将其设计为故障转移到另一个区域。这需要不同区域中的两个 Azure AI 语言资源，并能够跨区域同步 CLU 模型。

如果应用或业务依赖于 CLU 模型的使用，建议将项目副本创建到另一个受支持的区域。这样，如果发生区域性中断，则可以在复制项目的其他故障转移区域中访问模型。

复制项目意味着要导出项目元数据和资产，并将其导入到新项目中。这只会复制项目设置、意向、实体和语句。你仍然需要训练和部署模型，以便可与运行时 API 一起使用。

本文将介绍如何使用导出和导入 API 将项目从一个资源复制到另一个受支持的不同地理区域中的现有资源、有关如何使项目保持同步的指导，以及运行时消耗所需的更改。

先决条件

不同 Azure 区域中的两个 Azure AI 语言资源，每个都位于不同的区域。

获取资源密钥终结点

使用以下步骤获取主资源和辅助资源的密钥和终结点。在后续步骤中将会用到这些。

在 Azure 门户中，转到资源概述页面。在左侧菜单中，选择“密钥和终结点”。你将为 API 请求使用终结点和密钥

提示

请记下主资源和辅助资源的密钥和终结点。使用这些值来替换以下占位符：{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.cn`
`{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.cn`
`{PROJECT-NAME}`	项目名称。此值区分大小写。	`myProject`
`{JOB-ID}`	用于查找导出作业状态的 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.cn`
`{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}`	有关在测试集和训练集之间拆分数据的信息，请参阅如何训练模型。此字段的可能值为 `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（包括终结点、项目名称和作业 ID）会包含在响应的 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.cn`
`{PROJECT-NAME}`	项目名称。此值区分大小写。	`myProject`
`{JOB-ID}`	用于查找导入作业状态的 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.cn`
`{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`	拆分方法。可能的值为 `percentage` 或 `manual`。有关详细信息，请参阅如何训练模型。	`percentage`
`trainingSplitPercentage`	`80`	要包含在训练集中的已标记数据的百分比。建议的值为 `80`。	`80`
`testingSplitPercentage`	`20`	要包含在测试集中的已标记数据的百分比。建议的值为 `20`。	`20`

注意

仅当 Kind 设置为 percentage 时 trainingSplitPercentage 和 testingSplitPercentage 才是必需的，并且两个百分比的总和应等于 100。

当你发送 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（包括终结点、项目名称和作业 ID）会包含在响应的 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.cn`
`{PROJECT-NAME}`	项目名称。此值区分大小写。	`EmailApp`
`{JOB-ID}`	用于查找模型训练状态的 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`	训练作业 ID	`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.cn`
`{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（包括终结点、项目名称和作业 ID）会包含在响应的 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.cn`
`{PROJECT-NAME}`	项目名称。此值区分大小写。	`myProject`
`{DEPLOYMENT-NAME}`	部署名称。此值区分大小写。	`staging`
`{JOB-ID}`	用于查找模型训练状态的 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.cn`
`{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”的其他作用。

通过

备份和恢复对话语言理解模型

先决条件

获取资源密钥终结点

导出主要项目资产

提交导出作业

请求 URL

头文件

获取导出作业状态

头文件

响应正文

获取导出结果

头文件

导入到新项目

提交导入作业

请求 URL

头文件

正文

获取导入作业状态

头文件

响应正文

训练模型

提交训练作业

请求 URL

头文件

请求正文

获取定型状态

请求 URL

头文件

响应正文

部署模型

提交部署作业

请求 URL

头文件

请求正文

获取部署状态

请求 URL

头文件

响应正文

调用运行时方面的更改

检查项目是否不同步

获取项目详细信息

头文件

响应正文

后续步骤

其他资源