快速入门：对话语言理解

• Azure 订阅 - 创建试用订阅。

1. 转到 Language Studio，然后使用 Azure 帐户登录。

2. 在出现的“选择语言资源”窗口中，找到你的 Azure 订阅，然后选择你的语言资源。 如果没有资源，可新建一个。

   Expandir tabla

   实例详细信息	所需的值
   Azure 订阅	Azure 订阅。
   Azure 资源组	你的 Azure 资源组名称。
   Azure 资源名称	你的 Azure 资源名称。
   位置	语言资源支持的区域之一。 例如“中国北部 2”。
   定价层	语言资源的有效定价层之一。 可以使用免费 (F0) 层来试用该服务。

   

选择语言资源后，请创建对话语言理解项目。 项目是一个基于数据构建自定义 ML 模型的工作区。 只有你和对所使用的语言资源具有访问权限的其他人才能访问你的项目。

对于本快速入门，可以下载并导入此示例项目文件。 此项目可以基于用户输入预测所需的命令，例如：阅读电子邮件、删除电子邮件，以及将文档附加到电子邮件。

1. 在 Language Studio 的“理解问题和对话语言”部分下，选择“对话语言理解”。

   

2. 随后你会转到“对话语言理解项目”页。 在“新建项目”按钮旁边，选择“导入”。

   

3. 在显示的窗口中，上传要导入的 JSON 文件。 请确保该文件遵循受支持的 JSON 格式。

上传完成后，你将进入“架构定义”页。 对于本快速入门，架构已经生成，并且语句已标有意向和实体。

通常，在创建项目后，你应该生成架构并标记语句。 对于本快速入门，我们已导入一个生成了架构和标记了语句的现成项目。

若要训练模型，需要启动训练作业。 成功训练作业的输出是已训练的模型。

若要在 Language Studio 中开始训练模型，请执行以下操作：

1. 在左侧菜单中，选择“训练模型”。

2. 从顶部菜单中选择“启动训练作业”。

3. 选择“训练新模型”，然后在文本框中输入新模型名称。 但要将现有模型替换为已针对新数据训练的模型，请选择“覆盖现有模型”，然后选择现有模型。 覆盖已训练的模型是不可逆的，但这在部署新模型之前不会影响已部署的模型。

4. 选择训练模式。 可以选择“标准训练”以加快训练速度，但此模式仅适用于英语。 或者，可以选择其他语言和多语言项目支持的“高级训练”，但此模式需要更长的训练时间。 详细了解训练模式。

5. 选择一种数据拆分方法。 可以选择“从训练数据中自动拆分测试集”，系统将根据指定的百分比在训练集和测试集之间拆分语句。 或者，可以选择“使用手动拆分训练和测试数据”，仅当在标记语句期间已将语句添加到测试集时才会启用此选项。

6. 选择“训练”按钮。

   

7. 从列表中选择训练作业 ID。 出现一个面板，在该面板中可以检查此作业的训练进度、作业状态和其他详细信息。

   Nota

   • 只有成功完成的训练作业才会生成模型。
   • 训练时间从几分钟到几个小时不等，具体取决于语句数量。
   • 一次只能运行一个训练作业。 在运行的作业完成之前，无法在同一项目中启动其他训练作业。
   • 用于训练模型的机器学习会定期更新。 如果要在以前的配置版本上进行训练，请在“启动训练作业”页中单击“单击此处进行更改”，然后选择以前的版本。

一般情况下，在训练模型后，你会查看其评估详细信息。 在本快速入门中，你只需部署模型，使其在 Language Studio 中可供试用，你也可以调用预测 API。

若要要从 Language Studio 中部署模型，请执行以下操作：

1. 在左侧菜单中，选择“部署模型”。

2. 选择“添加部署”以启动“添加部署”向导。

   

3. 选择“创建新部署名称”以创建新的部署，并从下面的下拉列表中分配一个已训练的模型。 还可选择“覆盖现有部署名称”，有效地替换现有部署使用的模型。

   Nota

   覆盖现有部署不需要更改预测 API 调用，但产生的结果将基于新分配的模型。

   

4. 从“模型”下拉列表中选择已训练的模型。

5. 选择“部署”以启动部署作业。

6. 部署成功后，旁边将显示到期日期。 部署到期是指已部署的模型将无法用于预测，这通常发生在训练配置到期后的 12 个月。

若要在 Language Studio 中测试已部署的模型，请执行以下操作：

1. 在左侧菜单中，选择“测试部署”。

2. 对于多语言项目，请从“选择文本语言”下拉列表中选择要测试的语句的语言。

3. 从“部署名称”下拉列表中，选择要测试的模型对应的部署名称。 只能测试分配给部署的模型。

4. 在文本框中，输入要测试的语句。 例如，如果你为与电子邮件相关的语句创建了一个应用程序，则可以输入“删除此电子邮件”。

5. 在页面顶部，选择“运行测试”。

6. 运行测试后，在结果中应会看到模型的响应。 可以在实体卡片视图中查看结果，或以 JSON 格式查看结果。

如果不再需要项目，可以使用 Language Studio 删除项目。 在左侧导航菜单中选择“项目”，选择要删除的项目，然后选择顶部菜单中的“删除”。

• Azure 订阅 - 创建试用订阅。

1. 若要创建新的 Azure AI 语言资源，请登录 Azure 门户。

2. 选择“创建新资源”

3. 在出现的窗口中，搜索“语言服务”

4. 选择“创建”

5. 创建包含以下详细信息的语言资源。

   Expandir tabla

   实例详细信息	必需的值
   区域	语言资源支持的区域之一。
   名称	语言资源的所需名称
   定价层	语言资源支持的定价层之一。

1. 在 Azure 门户中，转到资源概述页面。

2. 在左侧菜单中，选择“密钥和终结点”。 你将为 API 请求使用终结点和密钥

   

创建语言资源后，请创建对话语言理解项目。 项目是一个基于数据构建自定义 ML 模型的工作区。 只有你和对所使用的语言资源具有访问权限的其他人才能访问你的项目。

对于本快速入门，可以下载并导入此示例项目。 此项目可以基于用户输入预测所需的命令，例如：阅读电子邮件、删除电子邮件，以及将文档附加到电子邮件。

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

创建 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 响应将包含一个 operation-location 标头，其中带有可用于检查导入作业状态的 URL。 它的格式如下：

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

发送成功的项目导入请求后，用于检查导入作业状态的完整请求 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"
}

通常，在创建项目后，应该生成架构并标记语句。 对于本快速入门，我们已导入一个生成了架构和标记了语句的现成项目。

使用以下 URL、标头和 JSON 正文创建 POST 请求以提交训练作业。

创建 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 获取训练作业状态。

训练可能需要一段时间才能完成 - 有时在 10 到 30 分钟之间。 可以使用以下请求持续轮询训练作业的状态，直到成功完成训练作业。

发送成功的训练请求后，用于检查作业状态的完整请求 URL（包括终结点、项目名称和作业 ID）会包含在响应的 operation-location 标头中。

使用以下 GET 请求来获取模型在训练过程中的状态。 请将以下占位符值替换为你自己的值。

{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 来查询结果。

使用以下 URL、标头和 JSON 正文创建 PUT 请求，开始部署对话语言理解模型。

{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 获取部署作业状态。

发送成功的部署请求后，用于检查作业状态的完整请求 URL（包括终结点、项目名称和作业 ID）会包含在响应的 operation-location 标头中。

使用以下 GET 请求来获取部署作业的状态。 将占位符值替换为你自己的值。

{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 进行预测。

部署成功后，可以开始查询已部署的模型以进行预测。

使用以下 URL、标头和 JSON 正文创建 POST 请求，开始测试对话语言理解模型。

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

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

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Text 1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

发送请求后，你将获得有关预测的以下响应

{
  "kind": "ConversationResult",
  "result": {
    "query": "Text1",
    "prediction": {
      "topIntent": "inten1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        },
        {
          "category": "intent3",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text1",
          "offset": 29,
          "length": 12,
          "confidenceScore": 1
        }
      ]
    }
  }
}

在会话项目中，你将获得对项目中的意图和实体的预测。

• 意图和实体包括一个介于 0.0 到 1.0 之间的置信度分数，该分数与模型对于预测项目中某个元素的信心程度相关。
• 评分最高的意图包含在其自己的参数内。
• 只有预测的实体才会显示在响应中。
• 实体指示：
  • 提取的实体的文本
  • 用偏移值表示的开始位置
  • 用长度值表示的实体文本的长度。

如果你不再需要项目，可以使用 API 删除该项目。

使用以下 URL、标头和 JSON 正文创建 DELETE 请求，以删除对话语言理解项目。

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

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

发送 API 请求后，将收到一个指示成功的 202 响应，这意味着项目已被删除。