共用方式為


快速入門:交談語言理解

使用此文章來開始使用 Language Studio 和 REST API 進行交談語言理解。 請遵循下列步驟來試用範例。

必要條件

登入 Language Studio

  1. 請前往 Language Studio,並以您的 Azure 帳戶登入。

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

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

    顯示 Language Studio 中資源選擇畫面的螢幕擷取畫面。

建立交談語言理解專案

一旦您選取了語言資源,請建立交談語言理解專案。 專案是一個工作區域,用於根據您的資料建置自訂 ML 模型。 您的專案只能由您和具有要使用的語言資源存取權的其他人員存取。

針對本快速入門,您可以下載此範例專案檔並將其匯入。 此專案可以從使用者輸入預測預定的命令,例如:讀取電子郵件、刪除電子郵件,以及將檔附加至電子郵件。

  1. 在 Language Studio 的 [理解問題和交談語言] 區段下,選取 [交談語言理解]

    螢幕擷取畫面:顯示 Language Studio 登陸頁面中的 Language Understanding 位置。

  2. 這會帶您前往 [交談語言理解專案] 頁面。 在 [建立新專案] 按鈕旁,選取 [匯入]。

    螢幕擷取畫面:顯示 Language Studio 中交談專案頁面。

  3. 在出現的視窗中,上傳您想要匯入的 JSON 檔案。 確定您的檔案遵循支援的 JSON 格式

一旦上傳完成,您就會登陸 [結構描述定義] 頁面。 針對本快速入門,已建置結構描述,且語句已加上意圖和實體的標籤。

定型您的模型

一般而言,在建立專案之後,您應該建置結構描述標記語句。 針對本快速入門,我們已匯入備妥專案,其中具有已建置的結構描述和已標記的語句。

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

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

  1. 從左側功能表中選取 [定型模型]

  2. 從頂端功能表中選取 [開始定型作業]

  3. 選取 [定型新模型],然後在文字輸入框中輸入模型名稱。 否則,若要以在新資料上定型的模型取代現有的模型,請選取 [覆寫現有的模型],然後選取現有的模型。 覆寫定型的模型是無法復原的,但在您部署新模型之前,不會影響已部署的模型。

  4. 選取定型模式。 您可以選擇 [標準定型] 來加快定型速度,但僅適用於英文。 或者,您可以選擇支援其他語言和多語系專案的 [進階定型],但需要較長的定型時間。 深入瞭解模型定型

  5. 選取資料分割方法。 您可以選擇 [從定型資料自動分割測試集],使用此方法時,系統會根據指定的百分比,將您的表達分割為定型集與測試集。 或者,您可以選擇 [使用手動分割定型和測試資料],但只有在表達已新增至測試集,且您標記表達時,才會啟用此選項。

  6. 選取 [定型] 按鈕。

    顯示 Language Studio 中 [訓練] 頁面的螢幕擷取畫面。

  7. 選取清單中的定型作業識別碼。 隨即顯示窗格,您可以在其中檢查此作業的定型進度、作業狀態及其他詳細資料。

    注意

    • 只有成功完成的定型作業才會產生模型。
    • 根據表達的計數,定型可能需要幾分鐘到幾小時的時間。
    • 您一次只能執行一個定型作業。 除非執行中的作業完成,否則無法在同一個專案內啟動其他定型作業。
    • 用來定型模型的機器學習會定期更新。 若要在先前的設定版本上定型,請從 [開始定型作業] 頁面選取 [選取這裡以變更],然後選擇舊版。

部署模型

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

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

  1. 從左側功能表中,選取 [部署模型]

  2. 選取 [新增部署] 以啟動 [新增部署] 精靈。

    螢幕擷取畫面:顯示 Language Studio 中的模型部署按鈕。

  3. 選取 [建立新的部署] 以建立新的部署,並從下方的下拉式清單中指派定型的模型。 否則,您可以選取 [覆寫現有的部署名稱],以有效地取代現有部署所使用的模型。

    注意

    覆寫現有的部署不需要變更預測 API 呼叫,但您取得的結果將會以新指派的模型為基礎。

    螢幕擷取畫面:顯示 Language Studio 中的新增部署畫面。

  4. [模型] 下拉式清單中選取定型的模型。

  5. 選取 [部署] 以啟動部署作業。

  6. 部署成功之後,在其旁邊會出現到期日。 部署到期表示部署的模型無法再用於預測,通常發生於訓練組態到期的十二個月後。

測試已部署的模型

若要從 Language Studio 內測試已部署的模型:

  1. 從左側功能表中,選取 [測試部署]

  2. 針對多語系專案,從 [選取文字語言] 下拉式清單中,選取您要測試哪種語言的語句。

  3. 從 [部署名稱] 下拉式清單中,選取對應至您要測試之模型的部署名稱。 您只能測試指派給部署的模型。

  4. 在文字方塊中,輸入要測試的語句。 例如,如果您為與電子郵件相關的表達建立了應用程式,則可輸入刪除此電子郵件

  5. 在頁面頂端,選取 [執行測試]

  6. 執行測試後,應可在結果中看到模型的回應。 您可在實體卡片檢視中檢視結果,或以 JSON 格式檢視結果。

清除資源

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

必要條件

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

  1. 登入 Azure 入口網站以建立新的 Azure AI 語言資源。

  2. 選取 [建立新的資源]

  3. 在出現的視窗中,搜尋語言服務

  4. 選取 [建立]

  5. 使用下列詳細資料建立語言資源。

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

取得您的資源金鑰和端點

  1. 前往您位於 Azure 入口網站的資源概觀頁面。

  2. 在左側功能表中,選取 [金鑰和端點]。 您將使用 API 要求的端點和金鑰

    螢幕擷取畫面,其中顯示 Azure 入口網站中的金鑰和端點頁面

匯入新的 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.com
{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} 如需在測試和定型集之間分割資料的相關資訊,請參閱如何定型模型。 此欄位的可能值為 TrainTest Train

成功要求時,API 回應會包含 operation-location 標頭,其中包含可用來檢查匯入工作狀態的 URL。 其格式如下所示:

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

取得匯入工作狀態

當您傳送成功的專案匯入要求時,檢查匯入作業狀態的完整要求 URL (包括端點、專案名稱和作業識別碼) 會包含在回應的 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.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 myProject
{JOB-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.com
{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 分割方法。 可能的值為 percentagemanual。 如需詳細資訊,請參閱如何定型模型 percentage
trainingSplitPercentage 80 要包含在定型集中的標記資料百分比。 建議的值為 80 80
testingSplitPercentage 20 要包含在測試集中的標記資料百分比。 建議的值為 20 20

注意

只有在 Kind 設定為 percentage 且這兩個百分比的總和應該等於 100 時,才需要 trainingSplitPercentagetestingSplitPercentage

傳送 API 要求之後,您會收到表示成功的 202 回應。 在回應標頭中,擷取 operation-location 值。 其格式如下:

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

您可以使用此 URL 來取得定型作業狀態。

取得定型作業狀態

完成定型可能需要時間,有時需要 10 到 30 分鐘。 您可以使用下列要求來持續輪詢定型作業的狀態,直到成功完成為止。

當您傳送成功的訓練要求時,檢查作業狀態的完整要求 URL (包括端點、專案名稱和作業識別碼) 包含在回應的 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.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 EmailApp
{JOB-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 定型作業識別碼 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

標頭

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

機碼
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 (包括端點、專案名稱和作業識別碼) 會包含在回應的 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.com
{PROJECT-NAME} 專案名稱。 此值區分大小寫。 myProject
{DEPLOYMENT-NAME} 部署的名稱。 此值區分大小寫。 staging
{JOB-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.com
{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 「讀出 Matt 的電子郵件」 為了查詢而提交的文字。
topIntent 「讀出」 具備最高信賴分數的預測意圖。
意圖 [] 針對查詢文字預測的所有意圖清單,其中每個意圖都有信賴分數。
實體 [] 陣列,其中包含從查詢文字中擷取的實體清單。

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

標頭

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

機碼
Ocp-Apim-Subscription-Key 資源的金鑰。 用於驗證 API 要求。

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

下一步