快速入门：业务流程工作流

项目
01/02/2024

参考本文开始使用 Language Studio 和 REST API 创建业务流程工作流项目。请按照以下步骤尝试使用示例。

先决条件

Azure 订阅 - 创建试用订阅。
一个对话语言理解项目。

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

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

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

创建业务流程工作流项目

创建语言资源后，就可以创建业务流程工作流项目了。项目是一个基于数据构建自定义 ML 模型的工作区。只有你和对所使用的语言资源具有访问权限的其他人才能访问你的项目。

对于本快速入门，请先完成对话语言理解快速入门，以创建稍后要使用的对话语言理解项目。

在 Language Studio 中，找到标记为“了解问题和会话语言”的部分，然后选择“业务流程工作流”。
这会将你转到“业务流程工作流项目”页。选择“创建新项目”。为了创建项目，你将需要提供以下详细信息：

值	描述
名称	项目名称。
说明	可选项目说明。
语句主要语言	项目的主要语言。训练数据应主要使用此语言。

完成后，选择“下一步”，并查看详细信息。选择“创建项目”以完成过程。现在应会看到项目中的“生成架构”屏幕。

生成架构

完成对话语言理解快速入门并创建业务流程项目后，下一步是添加意向。

若要连接到前面创建的对话语言理解项目，请执行以下操作：

在业务流程项目的“生成架构”页中，选择“添加”以添加意向。
在出现的窗口中，为意向命名。
选择“是的，我想将其连接到现有项目”。
从连接服务下拉列表中，选择“对话语言理解”。
从项目名称下拉列表中，选择你的对话语言理解项目。
选择“添加意向”以创建意向。

训练模型

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

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

在左侧菜单中，选择“训练作业”。
从顶部菜单中选择“启动训练作业”。
然后选择“训练新模型”并在文本框中键入模型名称。还可以通过选择“覆盖现有模型”选项并从下拉菜单中选择要覆盖的模型来覆盖现有模型。覆盖已训练的模型是不可逆的，但这在部署新模型之前不会影响已部署的模型。

如果已使项目能够在标记语句时手动拆分数据，会看到两个数据拆分选项：
- 从训练数据自动拆分测试集：标记的语句将根据选择的百分比在训练集和测试集之间随机拆分。默认拆分百分比为 80% 用于训练，20% 用于测试。若要更改这些值，请选择要更改的集并键入新值。
注意

如果选择“自动从训练数据拆分测试集”选项，则只有训练集中的语句会按照提供的百分比拆分。
- 手动拆分训练和测试数据：在项目的标记步骤期间，将每个语句分配到训练集或测试集。
注意

只有在向标记数据页中的测试集中添加语句时，才启用“手动拆分训练和测试数据”选项。否则，它处于禁用状态。
选择“训练”按钮。

注意

只有成功完成的训练作业才会生成模型。
训练时间从几分钟到几个小时不等，具体取决于标记数据的大小。
一次只能运行一个训练作业。在运行的作业完成之前，无法在同一项目中启动其他训练作业。

部署模型

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

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

在左侧菜单中，选择“部署模型”。
选择“添加部署”，以开始新部署作业。
选择“创建新部署”以创建新的部署，并从下面的下拉列表中分配已训练的模型。还可以通过选择“覆盖现有部署”选项来覆盖现有部署，然后从下面的下拉列表中选择要为其分配的已训练的模型。

注意

覆盖现有部署不需要更改预测 API 调用，但产生的结果将基于新分配的模型。
如果要连接一个或多个 LUIS 应用程序或对话语言理解项目，必须指定部署名称。
- 自定义问答或未链接意向不需要任何配置。
- 必须将 LUIS 项目发布到在业务流程部署过程中配置的槽位，还必须将自定义问答 KB 发布到其生产槽位。
选择“部署”以提交部署作业
部署成功后，旁边将显示到期日期。部署到期是指已部署的模型将无法用于预测，这通常发生在训练配置到期后的 12 个月。

测试模型

部署模型后，可以开始使用该模型通过预测 API 进行预测。对于本快速入门，你将使用 Language Studio 提交语句、获取预测并可视化结果。

通过 Language Studio 测试模型

在左侧菜单中，选择“测试部署”。
选择要测试的模型。只能测试分配给部署的模型。
从部署名称下拉列表中，选择你的部署名称。
在文本框中，输入要测试的语句。
从顶部菜单中选择“运行测试”。
运行测试后，在结果中应会看到模型的响应。可以在实体卡片视图中查看结果，或以 JSON 格式查看结果。

清理资源

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

先决条件

Azure 订阅 - 创建试用订阅。

在 Azure 门户中创建语言资源

从 Azure 门户创建新资源

要创建新的 Azure AI 语言资源，请转到 Azure 门户。
选择“继续创建资源”
创建包含以下详细信息的语言资源。

实例详细信息必需的值

区域受支持的区域之一。

名称语言资源的名称。

定价层受支持的定价层之一。

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

获取资源密钥和终结点

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

创建业务流程工作流项目

要学习本快速入门，请先完成 CLU 快速入门以创建要在业务流程工作流中使用的 CLU 项目。

使用以下 URL、标头和 JSON 正文提交 PATCH 请求，以创建新项目。

请求 URL

创建 API 请求时，请使用以下 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 请求进行身份验证。

Body

使用以下示例 JSON 作为正文。

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Orchestration",
  "description": "Project description"
 }

密钥	占位符	值	示例
`projectName`	`{PROJECT-NAME}`	项目名称。此值区分大小写。	`EmailApp`
`language`	`{LANGUAGE-CODE}`	指定项目中所用语句的语言代码的字符串。如果你的项目是多语言项目，请选择大多数语句的语言代码。	`en-us`

生成架构

完成 CLU 快速入门并创建业务流程项目后，下一步是添加意向。

使用以下 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}`	项目名称。此值区分大小写。	`myProject`
`{API-VERSION}`	要调用的 API 的版本。	`2023-04-01`

头文件

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

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

正文

注意

每个意向只能是一种类型（CLU、LUIS 和 qna）

使用以下示例 JSON 作为正文。

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Orchestration",
    "settings": {
      "confidenceThreshold": 0
    },
    "projectName": "{PROJECT-NAME}",
    "description": "Project description",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Orchestration",
    "intents": [
      {
        "category": "string",
        "orchestration": {
          "kind": "luis",
          "luisOrchestration": {
            "appId": "00000000-0000-0000-0000-000000000000",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

密钥	占位符	值	示例
`api-version`	`{API-VERSION}`	要调用的 API 版本。此处使用的版本必须与 URL 中的 API 版本相同。	`2022-03-01-preview`
`projectName`	`{PROJECT-NAME}`	项目名称。此值区分大小写。	`EmailApp`
`language`	`{LANGUAGE-CODE}`	指定项目中所用语句的语言代码的字符串。如果你的项目是多语言项目，请选择大多数语句的语言代码。	`en-us`

训练模型

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

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

请求正文

在请求中使用以下对象。完成训练后，该模型将被命名为 MyModel。

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

键	占位符	值	示例
`modelLabel`	`{MODEL-NAME}`	模型名称。	`Model1`
`trainingMode`	`standard`	训练模式。业务流程中只有一种可用的训练模式，即 `standard`。	`standard`
`trainingConfigVersion`	`{CONFIG-VERSION}`	训练配置模型版本。默认情况下将使用最新的模型版本。	`2022-05-01`
`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 分钟。可以使用以下请求持续轮询训练作业的状态，直到成功完成训练作业。

使用以下 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。此信息包含在提交训练作业时收到的 `location` 标头值中。	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	要调用的 API 的版本。	`2023-04-01`

头文件

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

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

响应正文

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

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "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": "xxxxxx-xxxxx-xxxxxx-xxxxxx",
  "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`
`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 获取部署作业状态。

获取部署作业状态

使用以下 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。此信息包含在从对模型部署请求做出响应的 API 收到的 `location` 标头值中。	`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": {
      "text": "Text1",
      "participantId": "1",
      "id": "1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "directTarget": "qnaProject",
    "targetProjectParameters": {
      "qnaProject": {
        "targetProjectKind": "QuestionAnswering",
        "callingOptions": {
          "context": {
            "previousUserQuery": "Meet Surface Pro 4",
            "previousQnaId": 4
          },
          "top": 1,
          "question": "App Service overview"
        }
      }
    }
  }
}

响应正文

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

{
  "kind": "ConversationResult",
  "result": {
    "query": "App Service overview",
    "prediction": {
      "projectKind": "Orchestration",
      "topIntent": "qnaTargetApp",
      "intents": {
        "qnaTargetApp": {
          "targetProjectKind": "QuestionAnswering",
          "confidenceScore": 1,
          "result": {
            "answers": [
              {
                "questions": [
                  "App Service overview"
                ],
                "answer": "The compute resources you use are determined by the *App Service plan* that you run your apps on.",
                "confidenceScore": 0.7384000000000001,
                "id": 1,
                "source": "https://learn.microsoft.com/azure/app-service/overview",
                "metadata": {},
                "dialog": {
                  "isContextOnly": false,
                  "prompts": []
                }
              }
            ]
          }
        }
      }
    }
  }
}

清理资源

如果你不再需要项目，可以使用 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 门户中创建语言资源

从 Azure 门户创建新资源

获取资源密钥和终结点

创建业务流程工作流项目

请求 URL

头文件

Body

生成架构

请求 URL

头文件

正文

训练模型

请求 URL

头文件

请求正文

获取定型状态

请求 URL

头文件

响应正文

部署模型

提交部署作业

请求 URL

头文件

请求正文

获取部署作业状态

请求 URL

头文件

响应正文

查询模型

请求 URL

头文件

请求正文

响应正文

清理资源

请求 URL

头文件

后续步骤

其他资源