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

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

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

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

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

先决条件

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

获取资源密钥终结点

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

在 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 参考