快速入門：協調流程工作流程

發行項
12/19/2023

本文可協助您透過 Language Studio 和 REST API 開始使用協調工作流程。請遵循下列步驟來試用範例。

必要條件

Azure 訂用帳戶 - 建立免費帳戶。
交談語言理解專案。

移至 Language Studio，並以您的 Azure 帳戶登入。

在出現的 [選擇語言資源] 視窗中，尋找您的 Azure 訂用帳戶，然後選擇您的語言資源。如果您沒有資源，可以建立新的資源。

執行個體詳細資料	必要值
Azure 訂用帳戶	您的 Azure 訂用帳戶。
Azure 資源群組	您的 Azure 資源群組。
Azure 資源名稱	您的 Azure 資源名稱。
Location	Azure 資源的有效位置。例如，「美國西部 2」。
定價層	Azure 資源支援的定價層。您可使用免費層 (F0) 來試用服務。

建立協調流程工作流程專案

建立語言資源後，請建立協調工作流程專案。專案是一個工作區域，可根據您的資料建置自訂 ML 模型。專案只能由您和其他具有所使用語言資源存取權的人員存取。

在本快速入門中，請完成交談語言理解快速入門，以建立稍後要使用的交談語言理解專案。

在 Language Studio 中，尋找標記為理解問題和交談語言的區段，並選取 [協調工作流程]。
這會將您引導至協調工作流程專案頁面。選取 [建立新專案]。若要建立專案，您必須提供下列詳細資料：

值	描述
Name	您專案的名稱。
描述	選擇性的專案描述。
語句主要語言	您專案的主要語言。您的定型資料主要應該是採用這種語言。

完成後請選取 [下一步]，並檢閱詳細資料。選取 [建立專案]，完成此流程。您現在應該會在專案中看到 [建置結構描述] 畫面。

建置結構描述

完成交談語言理解快速入門、並建立協調流程專案後，下一步則是新增意圖。

若要連線至先前建立的交談語言理解專案：

在協調流程專案的 [建置架構 ] 頁面中，選取 [ 新增]，以新增意圖。
在出現的視窗中，提供您的意圖名稱。
選取 [是，我想要將其連線至現有的專案]。
從已連線服務的下拉式清單中，選取 [交談語言理解]。
從專案名稱下拉式清單中，選取您的交談語言理解專案。
選取 [新增意圖 ] 以建立您的意圖。

定型模型

若要定型模型，則須啟動定型作業。成功定型作業的輸出即是定型的模型。

若要從 Language Studio 內開始定型模型：

從左側功能表中，選取 [定型工作]。
從頂端功能表中選取 [開始定型作業]。
選取 [定型新模型]，然後在文字方塊中輸入模型名稱。您也可以藉由選取此選項來覆寫現有的模型，然後從下拉式功能表中選擇您想要覆寫的模型。覆寫定型的模型是無法復原的，但在您部署新模型之前，不會影響已部署的模型。

如果您已在標記表達時啟用專案來手動分割資料，您會看到兩個資料分割選項：
- 從定型資料自動分割測試集：會根據選擇的百分比，在定型與測試集之間隨機性分割標記的表達。預設的百分比分割是 80% 用於定型，20% 用於測試。若要變更這些值，請選擇您要變更的集，然後輸入新的值。
注意

如果您選擇 [從定型資料自動分割測試集] 選項，則只會根據提供的百分比來分割定型集中的表達。
- 使用手動分割定型和測試資料：在專案的標記步驟期間，將每個表達指派給定型或測試集。
注意

只有在您將表達新增至標記資料分頁中的測試集時，才會啟用使用手動分割定型和測試資料選項。否則，會將其停用。
選取 [定型] 按鈕。

注意

只有成功完成的定型作業才會產生模型。
定型可能需要幾分鐘到幾小時的時間，以標記的資料大小而定。
您一次只能執行一個定型作業。除非執行中的作業完成，否則無法在同一個專案內啟動其他定型作業。

部署模型

定型模型後，您通常可檢閱其評估詳細資料。在本快速入門中，您只需部署模型，並讓其可供您在 Language Studio 中試用，或者您可以呼叫預測 API。

若要從 Language Studio 內部署您的模型：

從左側功能表中，選取 [部署模型]。
選取 [新增部署 ] 以啟動新的部署作業。
選取 [建立新的部署] 以建立新的部署，並從下方的下拉式清單中指派定型的模型。您也可以選取此選項來覆寫現有的部署，然後從下方的下拉式清單中，選取您想要為其指派的定型模型。

注意

覆寫現有的部署不需要變更預測 API 呼叫，但您取得的結果將會以新指派的模型為基礎。
若要連接一或多個 LUIS 應用程式或交談語言理解專案，則須指定部署名稱。
- 自訂問題回答或未連結的意圖不需要任何設定。
- LUIS 專案必須發佈至協調流程部署期間所設定的位置，而自訂問題回答 KB 也須發佈至其生產位置。
選取 [部署 ] 以提交部署作業
部署成功之後，在其旁邊會出現到期日。部署到期是已部署模型無法用於預測的時間，這通常會在定型設定到期的十二個月後發生。

測試模型

部署模型後便可開始使用，透過預測 API 進行預測。從本快速入門，您將可使用 Language Studio 提交語句、取得預測，並將結果視覺化。

從 Language Studio 測試模型

從左側功能表中，選取 [測試部署]。
選取您想要測試的模型。您只能測試指派給部署的模型。
從部署名稱下拉式清單中，選取您的部署名稱。
在文字方塊中，輸入要測試的語句。
從頂端功能表中，選取 [ 執行測試]。
執行測試後，應可在結果中看到模型的回應。您可在實體卡片檢視中檢視結果，或以 JSON 格式檢視結果。

清除資源

當您不再需要專案時，可以使用 Language Studio 來刪除您的專案。從左側導覽功能表中選取 [ 專案 ]，選取您要刪除的專案，然後從頂端功能表選取 [ 刪除 ]。

必要條件

Azure 訂用帳戶 - 建立免費帳戶。

從 Azure 入口網站建立語言資源

從 Azure 入口網站建立新的資源

移至Azure 入口網站以建立新的 Azure AI 語言資源。
選取 [繼續] 以建立您的資源
使用下列詳細資料建立語言資源。

執行個體詳細資料必要值

區域其中一個支援的區域。

名稱語言資源的名稱。

定價層其中一個支援的定價層。

執行個體詳細資料	必要值
區域	其中一個支援的區域。
名稱	語言資源的名稱。
定價層	其中一個支援的定價層。

取得您的資源金鑰和端點

前往您位於 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.com`
`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`myProject`
`{API-VERSION}`	您要呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`Ocp-Apim-Subscription-Key`	資源的索引鍵。用於驗證 API 要求。

主體

使用下列範例 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.com`
`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`myProject`
`{API-VERSION}`	您要呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`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.com`
`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`EmailApp`
`{API-VERSION}`	您要呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`Ocp-Apim-Subscription-Key`	資源的索引鍵。用於驗證 API 要求。

要求本文

在您的要求中使用下列物件。定型完成之後，系統會將模型命名為 MyModel。

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

Key	預留位置	值	範例
`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 且這兩個百分比的總和應該等於 100 時，才需要 trainingSplitPercentage 和 testingSplitPercentage。

傳送 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.com`
`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`EmailApp`
`{JOB-ID}`	用來尋找模型定型狀態的識別碼。這在您提交定型作業時收到的 `location` 標頭值中。	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	您要呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`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"
}

Key	值	範例
`modelLabel`	模型名稱	`Model1`
`trainingConfigVersion`	定型設定版本。預設使用最新版本。	`2022-05-01`
`startDateTime`	開始定型的時間	`2022-04-14T10:23:04.2598544Z`
`status`	定型作業的狀態	`running`
`estimatedEndDateTime`	定型作業完成的估計時間	`2022-04-14T10:29:38.2598544Z`
`jobId`	定型作業識別碼	`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.com`
`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`myProject`
`{DEPLOYMENT-NAME}`	部署的名稱。此值區分大小寫。	`staging`
`{API-VERSION}`	您要呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`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.com`
`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`myProject`
`{DEPLOYMENT-NAME}`	部署的名稱。此值區分大小寫。	`staging`
`{JOB-ID}`	用來尋找模型定型狀態的識別碼。這在您從 API 回應模型部署要求時所收到的 `location` 標頭值中。	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	您呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`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.com`
`{API-VERSION}`	您呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`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.com`
`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`myProject`
`{API-VERSION}`	您呼叫的 API 版本。	`2023-04-01`

標題

使用下列標頭來驗證您的要求。

Key	值
`Ocp-Apim-Subscription-Key`	資源的索引鍵。用於驗證 API 要求。

傳送 API 要求之後，您將會收到指出成功的 202 回應，這表示您的專案已刪除。

後續步驟

了解協調流程工作流程

共用方式為

快速入門：協調流程工作流程

必要條件

登入 Language Studio

建立協調流程工作流程專案

建置結構描述

定型模型

部署模型

測試模型

清除資源

必要條件

從 Azure 入口網站建立語言資源

從 Azure 入口網站建立新的資源

取得您的資源金鑰和端點

建立協調流程工作流程專案

要求 URL

標題

主體

建置結構描述

要求 URL

標題

主體

定型模型

要求 URL

標題

要求本文

取得定型訓練

要求 URL

標題

回應本文

部署模型

提交部署作業

要求 URL

標題

要求本文

取得部署工作狀態

要求 URL

標題

回應本文

查詢模型

要求 URL

標題

要求本文

回應本文

清除資源

要求 URL

標題

後續步驟

意見反應

意見反應

其他資源