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

使用本文档开始 REST API 的编排工作流项目。 请按照以下步骤尝试使用示例。

先决条件

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

在 Azure 门户中创建语言资源

从 Azure 门户创建新资源

1. 转到 Azure 门户 创建新的 Azure 语言资源。

2. 选择“继续创建资源”

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

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

获取资源密钥和终结点

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

2. 在左侧菜单中，选择"密钥和终结点”。 终结点和密钥用于 API 请求。

   

创建业务流程工作流项目

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

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

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

请求的 URL

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

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

Headers

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

Body

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

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

生成架构

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

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

请求的 URL

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

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

Headers

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

Body

使用以下示例 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": "00001111-aaaa-2222-bbbb-3333cccc4444",
            "appVersion": "string",
            "slotName": "string"
          },
          "cluOrchestration": {
            "projectName": "string",
            "deploymentName": "string"
          },
          "qnaOrchestration": {
            "projectName": "string"
          }
        }
      }
    ],
    "utterances": [
      {
        "text": "Trying orchestration",
        "language": "{LANGUAGE-CODE}",
        "intent": "string"
      }
    ]
  }
}

训练模型

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

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

请求的 URL

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

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

Headers

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

请求主体

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

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "standard",
  "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 分钟。 可以使用以下请求持续轮询训练作业的状态，直到成功完成训练作业。

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

请求的 URL

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

Headers

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

响应正文

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

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

部署你的模型

一般情况下，在训练模型后，你会查看其评估详细信息。 在本快速入门中，你只需部署模型，并调用预测 API 来查询结果。

提交部署作业

使用以下 URL、标头和 JSON 正文创建 PUT 请求，开始部署业务流程工作流模型。

请求的 URL

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

Headers

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

请求主体

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

获取部署作业状态

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

请求的 URL

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

Headers

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

响应正文

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

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

Headers

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

请求主体

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

Headers

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

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

后续步骤

• 了解业务流程工作流