快速入门：对话语言理解

项目
03/04/2024

参考本文通过 Language Studio 和 REST API 开始使用对话语言理解。请按照以下步骤尝试使用示例。

先决条件

Azure 订阅 - 创建试用订阅。

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

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

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

创建对话语言理解项目

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

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

在 Language Studio 的“理解问题和对话语言”部分下，选择“对话语言理解”。
随后你会转到“对话语言理解项目”页。在“新建项目”按钮旁边，选择“导入”。
在显示的窗口中，上传要导入的 JSON 文件。请确保该文件遵循受支持的 JSON 格式。

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

训练模型

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

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

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

在左侧菜单中，选择“训练模型”。
从顶部菜单中选择“启动训练作业”。
选择“训练新模型”，然后在文本框中输入新模型名称。但要将现有模型替换为已针对新数据训练的模型，请选择“覆盖现有模型”，然后选择现有模型。覆盖已训练的模型是不可逆的，但这在部署新模型之前不会影响已部署的模型。
选择训练模式。可以选择“标准训练”以加快训练速度，但此模式仅适用于英语。或者，可以选择其他语言和多语言项目支持的“高级训练”，但此模式需要更长的训练时间。详细了解训练模式。
选择一种数据拆分方法。可以选择“从训练数据中自动拆分测试集”，系统将根据指定的百分比在训练集和测试集之间拆分语句。或者，可以选择“使用手动拆分训练和测试数据”，仅当在标记语句期间已将语句添加到测试集时才会启用此选项。
选择“训练”按钮。
从列表中选择训练作业 ID。出现一个面板，在该面板中可以检查此作业的训练进度、作业状态和其他详细信息。
注意
- 只有成功完成的训练作业才会生成模型。
- 训练时间从几分钟到几个小时不等，具体取决于语句数量。
- 一次只能运行一个训练作业。在运行的作业完成之前，无法在同一项目中启动其他训练作业。
- 用于训练模型的机器学习会定期更新。如果要在以前的配置版本上进行训练，请在“启动训练作业”页中单击“单击此处进行更改”，然后选择以前的版本。

部署模型

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

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

在左侧菜单中，选择“部署模型”。
选择“添加部署”以启动“添加部署”向导。
选择“创建新部署名称”以创建新的部署，并从下面的下拉列表中分配一个已训练的模型。还可选择“覆盖现有部署名称”，有效地替换现有部署使用的模型。

注意

覆盖现有部署不需要更改预测 API 调用，但产生的结果将基于新分配的模型。
从“模型”下拉列表中选择已训练的模型。
选择“部署”以启动部署作业。
部署成功后，旁边将显示到期日期。部署到期是指已部署的模型将无法用于预测，这通常发生在训练配置到期后的 12 个月。

测试已部署的模型

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

在左侧菜单中，选择“测试部署”。
对于多语言项目，请从“选择文本语言”下拉列表中选择要测试的语句的语言。
从“部署名称”下拉列表中，选择要测试的模型对应的部署名称。只能测试分配给部署的模型。
在文本框中，输入要测试的语句。例如，如果你为与电子邮件相关的语句创建了一个应用程序，则可以输入“删除此电子邮件”。
在页面顶部，选择“运行测试”。
运行测试后，在结果中应会看到模型的响应。可以在实体卡片视图中查看结果，或以 JSON 格式查看结果。

清理资源

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

先决条件

Azure 订阅 - 创建试用订阅。

从 Azure 门户创建新资源

若要创建新的 Azure AI 语言资源，请登录 Azure 门户。
选择“创建新资源”
在出现的窗口中，搜索“语言服务”
选择“创建”
创建包含以下详细信息的语言资源。

实例详细信息必需的值

区域语言资源支持的区域之一。

名称语言资源的所需名称

定价层语言资源支持的定价层之一。

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

获取资源密钥和终结点

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

导入新的 CLU 示例项目

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

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

触发导入项目作业

使用以下 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}

获取导入作业状态

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

开始训练模型

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

使用以下 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 获取训练作业状态。

获取训练作业状态

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

发送成功的训练请求后，用于检查作业状态的完整请求 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 来查询结果。

提交部署作业

使用以下 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 获取部署作业状态。

获取部署作业状态

发送成功的部署请求后，用于检查作业状态的完整请求 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 进行预测。

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

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

请求 URL

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

占位符	值	示例
`{ENDPOINT}`	用于对 API 请求进行身份验证的终结点。	`https://<your-custom-subdomain>.cognitiveservices.azure.cn`
`{API-VERSION}`	要调用的 API 的版本。	`2023-04-01`

头文件

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

键	值
`Ocp-Apim-Subscription-Key`	资源密钥。用于对 API 请求进行身份验证。

请求正文

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

密钥	占位符	值	示例
`participantId`	`{JOB-NAME}`		`"MyJobName`
`id`	`{JOB-NAME}`		`"MyJobName`
`text`	`{TEST-UTTERANCE}`	你要预测其意向并从中提取实体的语句。	`"Read Matt's email`
`projectName`	`{PROJECT-NAME}`	项目名称。此值区分大小写。	`myProject`
`deploymentName`	`{DEPLOYMENT-NAME}`	部署的名称。此值区分大小写。	`staging`

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

响应正文

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

键	示例值	说明
query	"Read Matt's email"	提交以供查询的文本。
topIntent	"Read"	置信度分数最高的预测意向。
意向	[]	针对查询文本所预测的所有意向的列表，每个意向有一个置信度分数。
实体	[]	一个数组，包含从查询文本中提取的实体列表。

会话项目的 API 响应

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

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

清理资源

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

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

请求 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 请求进行身份验证。

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

后续步骤

了解实体组件

快速入门：对话语言理解

先决条件

登录到 Language Studio

创建对话语言理解项目

训练模型

部署模型

测试已部署的模型

清理资源

先决条件

从 Azure 门户创建新资源

获取资源密钥和终结点

导入新的 CLU 示例项目

触发导入项目作业

请求 URL

头文件

正文

获取导入作业状态

头文件

响应正文

开始训练模型

请求 URL

头文件

请求正文

获取训练作业状态

请求 URL

头文件

响应正文

部署模型

提交部署作业

请求 URL

头文件

请求正文

获取部署作业状态

请求 URL

头文件

响应正文

查询模型

请求 URL

头文件

请求正文

响应正文

会话项目的 API 响应

清理资源

请求 URL

头文件

后续步骤

其他资源