如何建立 CLU 專案

使用本文以了解如何設定這些需求和建立專案。

必要條件

開始使用 CLU 之前，您需要具備幾個項目：

• Azure 訂用帳戶 - 建立免費帳戶。
• Azure AI 語言資源

建立語言資源

開始使用 CLU 之前，您將需要 Azure AI 語言資源。

注意

• 您必須在資源群組上指派擁有者角色，才能建立語言資源。

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

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

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

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

4. 選取 [建立]

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

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

從 Language Studio 建立新的語言資源

如果這是您第一次登入，您將會在 Language Studio 中看到一個視窗，讓您選擇現有的語言資源或建立新的語言資源。 您也可以按一下右上角的設定圖示，選取 [資源]，然後按一下 [建立新的資源] 來建立資源。

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

執行個體詳細資料	必要值
Azure 訂用帳戶	您的 Azure 訂用帳戶
Azure 資源群組	您的 Azure 資源群組
Azure 資源名稱	您的語言資源名稱
Location	語言資源的支援區域。
定價層	語言資源的支援定價層。

重要

• 當建立語言資源時，請務必啟用 [受控識別]。
• 閱讀並確認負責任 AI 通知

登入 Language Studio

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

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

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

   

建立交談專案

一旦您建立了語言資源，請建立交談語言理解專案。

Language Studio

1. 在 Language Studio 中，尋找名為 [理解問題和交談語言]，並且選取 [交談語言理解]。
   

2. 這會帶您前往 [交談語言理解專案] 頁面。 選取 [建立新專案]。

   

若要建立新專案，您必須提供下列詳細資料：

值	描述
Name	您專案的名稱。 建立之後，就無法變更
描述	選擇性的專案描述。
語句主要語言	您專案的主要語言。 您的定型資料主要應該是採用這種語言。
啟用多語言	您是否想要讓您的專案一次支援多種語言。

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

REST API

使用下列 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

標頭

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

機碼	值
Ocp-Apim-Subscription-Key	資源的金鑰。 用於驗證 API 要求。
Content-Type	'application/merge-patch+json'

本文

使用下列範例 JSON 作為本文。

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "Conversation",
  "description": "Project description",
  "multilingual": true
}

機碼	預留位置	值	範例
projectName	{PROJECT-NAME}	您專案的名稱。 此值區分大小寫。	EmailApp
language	{LANGUAGE-CODE}	字串，指定專案中所用語句的語言代碼。 若您的專案是多語系專案，請選擇大部分語句的語言代碼。	en-us
multilingual	true	布林值，可讓您在資料集中具有多種語言的文件，而且當部署模型時，您可以使用任何支援的語言 (不一定包含在定型文件中) 查詢模型。 若要深入了解多語系支援，請參閱語言支援。	true

匯入專案

Language Studio

您可以前往 [交談專案] 頁面、選取專案，然後從功能表頂端按一下 [匯出]，隨時將交談語言理解專案匯出為 JSON 檔案。

可將該專案重新匯入為新的專案。 如果您匯入的專案具有完全相同的名稱，則會將專案的資料取代為新匯入的專案資料。

如果您有現有的 LUIS 應用程式，您可以直接將 LUIS 應用程式 JSON 匯入至交談語言理解，且其會使用目前可用的所有片段來建立交談專案：意圖、ML 實體和語句。 如需詳細資訊，請參閱 LUIS 移轉一文。

若要匯入專案，請選取 [建立新專案] 旁的箭號按鈕並選取 [匯入]，然後選取 LUIS 或交談語言理解 JSON 檔案。

REST API

您可以將 CLU JSON 匯入服務

使用下列 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}	如需在測試和定型集之間分割資料的相關資訊，請參閱如何定型模型。 此欄位的可能值為 Train 和 Test。	Train

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

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

匯出專案

Language Studio

您可以前往 [交談專案] 頁面、選取專案，然後按下 [匯出]，隨時將交談語言理解專案匯出為 JSON 檔案。

REST API

您可以隨時將交談語言理解專案匯出為 JSON 檔案。

使用下列 URL、標頭和 JSON 本文來建立 POST 要求，以匯出您的專案。

要求 URL

建立 API 要求時，請使用下列 URL。 請以您自己的值取代下列預留位置值。

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&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 要求。

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

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

JOB-ID 用來識別您的要求，因為此為非同步作業。 使用相同的驗證方法，使用此 URL 來取得匯出的專案 JSON。

取得 CLU 專案詳細資料

Language Studio

1. 移至您在 Language Studio 中的專案設定頁面。

2. 您可以查看專案詳細資料。

3. 在此頁面中，您可以更新專案描述，並在專案設定中啟用/停用多語言資料集。

4. 您也可以從此頁面擷取資源主要索引鍵。

   

REST API

若要取得您的專案詳細資料，請使用下列 URL 和標頭提交 GET 要求。 以您自己的值取代預留位置值。

{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 要求。

回應本文

傳送要求之後，您會收到下列回應。

{
  "createdDateTime": "2022-04-18T13:53:03Z",
  "lastModifiedDateTime": "2022-04-18T13:53:03Z",
  "lastTrainedDateTime": "2022-04-18T14:14:28Z",
  "lastDeployedDateTime": "2022-04-18T14:49:01Z",
  "projectKind": "Conversation",
  "projectName": "{PROJECT-NAME}",
  "multilingual": true,
  "description": "This is a sample conversation project.",
  "language": "{LANGUAGE-CODE}"
}

傳送 API 要求之後，您會收到 200 回應，指出成功和 JSON 回應本文與您的專案詳細資料。

刪除專案

Language Studio

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

REST API

當不再需要專案時，您可以使用 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 回應，這表示您的專案已刪除。

後續步驟

建置結構描述