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

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

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

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

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

先决条件

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

获取资源密钥终结点

使用以下步骤获取主要资源和辅助资源的密钥和终结点。

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

导出主要项目资产

首先，从主资源的项目中导出项目资产。

提交导出作业

将以下请求中的占位符替换为在第一步中获取的 {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}

标头

使用以下标头对请求进行身份验证。

发送 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}

标头

使用以下标头对请求进行身份验证。

响应体

{
  "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，并查看此任务中的导出资产。

获取导出结果

使用你从上一步骤收到的 提交 GET 请求，以查看导出作业的结果。

标头

使用以下标头对请求进行身份验证。

复制响应正文以用作下一个导入作业的正文。

导入到新项目

现在将导出的项目资产导入次要区域的新项目中，以便完成复制。

提交导入作业

将以下请求中的占位符替换为你的 {SECONDARY-ENDPOINT} 和你在第一步中获取的 {SECONDARY-RESOURCE-KEY}。

使用以下 URL、标头和 JSON 正文提交 POST 请求，以导入项目。

请求的 URL

创建 API 请求时，请使用以下 URL。 将占位符中的值替换为您自己的值。

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

标头

使用以下标头对请求进行身份验证。

身体

所发送的 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 响应包含 URL operation-location 标头，可用于检查导入作业的状态。 标头的格式如下例所示：

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

标头

使用以下标头对请求进行身份验证。

响应体

发送请求后，会收到以下响应。 继续轮询此终结点，直到状态参数更改为“成功”。

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

标头

使用以下标头对请求进行身份验证。

请求主体

在请求中使用以下对象。 训练完成后，模型将根据用于 modelLabel 参数的值来命名。

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "{TRAINING-MODE}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}

发送 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}

标头

使用以下标头对请求进行身份验证。

响应正文

发送请求后，会收到以下响应。 继续轮询该端点，直到状态参数变为“已成功”。

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

部署你的模型

此步骤将已训练的模型通过运行时预测 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}

标头

使用以下标头对请求进行身份验证。

请求主体

{
  "trainedModelLabel": "{MODEL-NAME}",
}

发送 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}

标头

使用以下标头对请求进行身份验证。

响应正文

发送请求后，你将获取以下响应。 继续轮询该端点，直到状态参数变为“已成功”。

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

标头

使用以下标头对请求进行身份验证。

响应体

{
  "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 的其他作用。

• 编写 REST API 参考

• 运行时预测 REST API 参考