了解如何建置文字分類專案

12 分鐘

自訂文字分類專案是用來建置、定型、改善和部署分類模型的工作區。您可以使用兩種方式來處理專案：透過 Language Studio 和經由 REST API。 Language Studio 是將在實驗室中使用的 GUI，但 REST API 具有相同的功能。無論您偏好使用哪種方法，開發模型的步驟都相同。

Azure AI 語言專案生命週期

定義標籤：了解您想分類的資料，識別您想分類的可能標籤。在電玩遊戲範例中，我們會使用「動作」、「冒險」、「策略」等標籤。
標記資料：標記現有的資料，並為每個檔案指定一或多個標籤。標記資料很重要，因為這是模型學習如何分類未來檔案的依據。最佳做法是讓標籤之間有清楚的差異，避免模棱兩可，並為每個標籤提供好範例讓模型學習。例如，我們會將 "Quest for the Mine Brush" 遊戲標記為「冒險」，並將 "Flight Trainer" 標記為「動作」。
訓練模型：使用加已標記資料來訓練模型。定型會教導模型應該將何種類型的電玩遊戲摘要標示為哪一種內容類型。
檢視模型：定型模型之後，檢視模型的結果。根據測試資料的精確度和召回率為模型評分 (分數範圍是 0 到 1)。記下哪些內容類型效能不佳。
改善模型：查看哪些分類無法評估為正確的標籤、查看標籤分佈，並找出要新增哪些資料以提高效能，藉此改善模型。例如，您可能會發現模型會將「冒險」和「策略」遊戲搞混。嘗試為每個標籤尋找更多範例，並新增至資料集以重新定型模型。
部署模型：模型如期望般執行後，可部署模型，使其可透過 API 使用。模型可命名為 "GameGenres"，部署完成後可用來分類遊戲摘要。
分類文字：使用模型來分類文字。實驗室會說明如何使用 API，您也可以檢視 API 參考

如何分割資料集以進行定型

標記資料時，您可以指定希望每個檔案所屬的資料集：

訓練 - 訓練資料集用於實際訓練模型；提供的資料和標籤會送入機器學習演算法，以教導模型應將哪些資料分類至哪個標籤。訓練資料集是這兩個資料集中較大的一方，建議大約是已標記資料的 80%。
測試 - 測試資料集是已標記的資料，用來在訓練模型之後加以驗證。 Azure 會取得測試資料集中的資料並將其提交至模型，且將輸出與您標記資料的方式進行比較，以判斷模型的效能。這項比較的結果是模型獲得的評分高低，並協助您了解如何改善預測效能。

進行定型模型步驟期間，有兩個選項可用來定型模型。

自動分割 - Azure 會採用所有資料、隨機分割成指定的百分比，然後套用至定型模型。當資料集較大、資料自然更一致，或資料分佈廣泛涵蓋您的類別時，這是最佳選項。
手動分割 - 手動指定每個資料集中應該有哪些檔案。提交定型作業時，Azure AI 語言服務會告訴您資料集的分割和分佈。此分割最適合與較小的資料集搭配使用，確保資料中的類別和變化分佈正確，以正確定型模型。

若要使用自動分割，請在標記資料時，將所有檔案放入「訓練」資料集 (這是預設選項)。若要使用手動分割，請在標記資料期間，分別指定應放入測試與訓練資料集的檔案。

部署選項

Azure AI 語言可讓每個專案同時建立多個模型和多個部署，且各自具有專屬的唯一名稱。優點包括能夠：

並排測試兩個模型
比較資料集分割如何影響效能
部署模型的多個版本

注意

每個專案的部署名稱上限為十個

在部署期間，您可以選擇已部署模型的名稱，然後在提交分類工作時選取：

<...>
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "MyTaskName",
      "parameters": {
        "projectName": "MyProject",
        "deploymentName": "MyDeployment"
      }
    }
  ]
<...>

使用 REST API

適用於 Azure AI 語言服務的 REST API 可用於 Azure AI 語言專案的 CLI 開發，方式與 Language Studio 提供用於建置專案的使用者介面相同。在本課程模組的實驗室中，將進一步探索 Language Studio。

使用 API 的模式

Azure AI 語言服務的 API 針對大部分呼叫都是以非同步方式運作。在每一個步驟中，我們會先提交要求給服務，然後透過後續呼叫回來檢查服務，以取得狀態或結果。

每個要求都需要標頭才能驗證要求：

機碼	值
`Ocp-Apim-Subscription-Key`	Azure AI 語言資源的索引鍵

提交初始要求

提交要求的 URL 會因您所處的步驟而有所不同，但所有 URL 前都會加上 Azure AI 語言資源所提供的端點。

例如，若要定型模型，您需為 URL 建立 POST，如下所示：

<YOUR-ENDPOINT>/language/analyze-text/projects/<PROJECT-NAME>/:train?api-version=<API-VERSION>

預留位置	值	範例
`<YOUR-ENDPOINT>`	API 要求的端點	`https://<your-custom-resource>.cognitiveservices.azure.com`
`<PROJECT-NAME>`	專案名稱 (值會區分大小寫)	`myProject`

下列本文會附加至要求：

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

機碼	值
`<YOUR-MODEL>`	您的模型名稱。
`trainingConfigVersion`	用於定型模型的模型版本。
`runValidation`	在測試集上執行驗證的布林值。
`evaluationOptions`	指定評估選項。
`kind`	指定資料分割類型。如果使用的是自動分割，可以是 `percentage`，或者若手動分割資料集，則為 `set`
`testingSplitPercentage`	只有當 `type` 是百分比時，才需要整數欄位。指定測試分割。
`trainingSplitPercentage`	只有當 `type` 是百分比時，才需要整數欄位。指定定型分割。

上述要求的回應會是 202，這表示要求成功。在回應標頭中抓取 location 值，其看起來會類似下列 URL：

<ENDPOINT>/language/analyze-text/projects/<PROJECT-NAME>/train/jobs/<JOB-ID>?api-version=<API-VERSION>

機碼	值
`<JOB-ID>`	要求的識別碼

下一個步驟中會使用此 URL 來取得定型狀態。

取得定型狀態

若要取得定型狀態，請使用要求回應標頭中的 URL 來提交 GET 要求，並使用提供 Azure AI 語言服務金鑰的相同標頭進行驗證。回應本文應該會類似以下 JSON：

{
  "result": {
    "modelLabel": "<MODEL-NAME>",
    "trainingConfigVersion": "<CONFIG-VERSION>",
    "estimatedEndDateTime": "2023-05-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2023-05-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "<JOB-ID>",
  "createdDateTime": "2023-05-18T15:44:44Z",
  "lastUpdatedDateTime": "2023-05-18T15:45:48Z",
  "expirationDateTime": "2023-05-25T15:44:44Z",
  "status": "running"
}

定型模型可能需要一些時間，因此請定期回來確認此狀態 URL，直到回應 status 傳回 succeeded 為止。定型成功之後，您就能檢視、驗證及部署模型。

取用已部署的模型

使用模型來遵循上述相同模式分類文字，並使用 POST 要求來提交作業，以及透過 GET 要求擷取結果。

提交文字進行分類

若要使用您的模型，請在下列 URL 將 POST 提交至「分析」端點：

<ENDPOINT>/language/analyze-text/jobs?api-version=<API-VERSION>

預留位置	值	範例
`<YOUR-ENDPOINT>`	API 要求的端點	`https://<your-custom-resource>.cognitiveservices.azure.com`

重要

請記得在 Ocp-Apim-Subscription-Key 的標頭中包含資源索引鍵

下列 JSON 結構會附加至要求：

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "<LANGUAGE-CODE>",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "<LANGUAGE-CODE>",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "<TASK-REQUIRED>",
      "taskName": "<TASK-NAME>",
      "parameters": {
        "projectName": "<PROJECT-NAME>",
        "deploymentName": "<DEPLOYMENT-NAME>"
      }
    }
  ]
}

機碼	值
`<TASK-REQUIRED>`	您要求的工作。若為多標籤專案，則工作會是 `CustomMultiLabelClassification`；單一標籤專案則為 `CustomSingleLabelClassification`
`<LANGUAGE-CODE>`	語言程式碼，例如 `en-us`。
`<TASK-NAME>`	您的工作名稱。
`<PROJECT-NAME>`	您的專案名稱。
`<DEPLOYMENT-NAME>`	您的部署名稱。

上述要求的回應會是 202，這表示要求成功。在回應標頭中尋找 operation-location 值，其會尋找類似下列 URL：

<ENDPOINT>/language/analyze-text/jobs/<JOB-ID>?api-version=<API-VERSION>

機碼	值
`<YOUR-ENDPOINT>`	API 要求的端點
`<JOB-ID>`	要求的識別碼

此 URL 可用來取得工作結果。

取得分類結果

將 GET 要求提交至先前要求的端點，並使用相同的標頭進行驗證。回應本文應該會類似以下 JSON：

{
  "createdDateTime": "2023-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2023-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2023-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2022-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "<DOC-ID>",
              "class": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2022-04-01"
        }
      }
    ]
  }
}

針對每個提交的文件，分類結果位於項目陣列的 results 物件內。