快速入門:自訂文字分類 REST API

使用本文開始建立自訂文字分類專案,您可以在其中定型自訂模型以進行文字分類。 模型是經過訓練以執行特定任務的 AI 軟體。 在此系統中,模型會分類文字,並從標記的資料中學習以定型。

自訂文字分類支援兩種類型的專案:

  • 單一標籤分類:您只能為資料集中的每一個文件指派一個類別。 例如,電影劇本只能歸類為“浪漫”或“喜劇”。
  • 多重標籤分類:您可以為資料集中的每一個文件指派多個類別。 例如,電影劇本可以歸類為“喜劇”或“浪漫”和“喜劇”。

在這個快速入門中,你可以利用提供的範例資料集建立多標籤分類,將電影劇本分類為一個或多個類別。 或者,您也可以使用單一標籤分類資料集,將科學論文摘要分類到定義的領域之一。

先決條件

在 Foundry Tools 資源與 Azure 儲存帳戶中建立新的 Azure 語言

在使用自訂文字分類之前,你需要建立一個語言資源,這會提供你建立專案和開始訓練模型所需的憑證。 你還需要一個 Azure 儲存帳號,可以上傳用於建立模型的資料集。

重要事項

為了快速開始,我們建議依照本文提供的步驟建立一個新的語言資源,這樣你可以同時建立 Azure 語言資源,並建立和/或連接儲存帳號,這比之後做更容易。

如果你有想用的 既有資源 ,就需要把它連接到儲存帳號。

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

  1. 前往 Azure 入口網站以在 Foundry Tools 中建立一個新的 Azure Language 資源。

  2. 在出現的視窗中,從自訂功能選取 [自訂文字分類和自訂具名實體辨識]。 選取畫面底部的 [繼續建立您的資源]。

    螢幕擷取畫面顯示 Azure 入口網站中自訂文字分類和自訂具名實體辨識的選取項目。

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

    名稱 必要值
    訂用帳戶 您的 Azure 訂用帳戶。
    資源群組 將包含您資源的資源群組。 您可以使用現有群組或建立新的群組。
    區域 其中一個支援的區域。 例如「美國西部 2」。
    名稱 您的資源名稱。
    定價層 其中一個支援的定價層。 您可使用免費 (F0) 層來試用服務。

    如果您收到訊息指出「您的登入帳戶不是所選儲存體帳戶資源群組的擁有者」,您的帳戶必須先在資源群組上指派擁有者角色,才能建立語言資源。 請連絡您的 Azure 訂閱擁有者以取得協助。

    您可以搜尋您的資源群組,並遵循其相關聯訂用帳戶的連結來判斷您的 Azure 訂用帳戶擁有者。 然後:

    1. 選取 [存取控制 (IAM)] 索引標籤
    2. 選取 [角色指派]
    3. 依 [角色: 擁有者] 進行篩選。
  4. 在 [自訂文字分類和自訂具名實體辨識] 區段中,選取現有的儲存體帳戶,或選取 [新的儲存體帳戶]。 請注意,這些數值是幫助你入門的,不一定是你想在生產環境中使用的 儲存帳號數 值。 若要避免在建置專案期間的延遲,請連線至與語言資源位於相同區域中的儲存體帳戶。

    儲存體帳戶值 建議值
    儲存體帳戶名稱 任何名稱
    記憶體帳戶類型 標準 LRS
  5. 請確定已核取負責任 AI 通知。 選取頁面底部的 [檢閱 + 建立]。

將範例資料上傳至 Blob 容器

建立 Azure 儲存帳號並連接到你的語言資源後,你需要將範例資料集的文件上傳到容器的根目錄。 這些文件可用來訓練您的模型。

  1. 下載多個標籤分類專案的範例資料集。

  2. 開啟 .zip 檔案,然後擷取包含文件的資料夾。

提供的範例資料集包含大約 200 份文件,每份文件都是一部電影的摘要。 每份文件都屬於以下一或多個類別:

  • 「懸疑片」
  • 「劇情片」
  • 「恐怖片」
  • 「喜劇」
  • 「動作片」

Azure 入口網站

  1. 在 Azure 入口網站中,導覽到你建立的儲存帳號,選擇儲存 帳號 ,並在 「篩選」欄位中輸入儲存帳號名稱。

    如果您的資源群組未顯示,請確定 [訂用帳戶等於] 篩選已設定為 [全部]。

  2. 在儲存體帳戶中,從左側功能表選取位於 [資料儲存體] 下方的 [容器]。 在出現的畫面上,選取 [+ 容器]。 為容器指定名稱 example-data,並保留預設的公用存取層級。

    螢幕擷取畫面顯示儲存體帳戶的主要頁面。

  3. 容器建立完成後,選擇它。 然後選取 [上傳] 按鈕,以選取您稍早下載的 .txt 和 .json 檔案。

    螢幕擷取畫面顯示將檔案上傳至儲存體帳戶的按鈕。

取得您的資源金鑰和端點

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

  • 在左側功能表中,選取 [金鑰和端點]。 端點和金鑰用於 API 請求。

截圖顯示 Azure 入口網站的金鑰和端點頁面。

建立自訂分類專案

設定好資源和儲存體容器之後,請建立新的自訂文字分類專案。 專案是一個工作區域,用於根據您的資料建置自訂 ML 模型。 您的專案只能由您及其他擁有 Azure 語言資源存取權的人存取。

觸發匯入專案作業

使用下列 URL、標頭和 JSON 本文來提交 POST 要求,以匯入標籤檔案。 請確定您的標籤檔案遵循接受的格式。

如果具有相同名稱的專案已經存在,則會取代該專案的資料。

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}
預留位置 值 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 深入了解其他可用的 API 版本 2022-05-01

headers

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

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

body

在您的要求中使用下列 JSON。 以您自己的值取代預留位置值。

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customMultiLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customMultiLabelClassification",
    "classes": [
      {
        "category": "Class1"
      },
      {
        "category": "Class2"
      }
    ],
    "documents": [
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class1"
          },
          {
            "category": "Class2"
          }
        ]
      },
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class2"
          }
        ]
      }
    ]
  }
}

Key 預留位置 值 範例
API版本 {API-VERSION} 您所呼叫 API 的版本。 此處所使用的版本必須是 URL 中的相同 API 版本。 深入了解其他可用的 API 版本 2022-05-01
projectName {PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
專案類型 customMultiLabelClassification 您的專案種類。 customMultiLabelClassification
語言 {LANGUAGE-CODE} 字串,指定專案中所用文件的語言代碼。 如果您的專案是多語言專案,請選擇大部分文件的語言代碼。 若要深入了解多語系支援,請參閱語言支援。 en-us
多語系 true 布林值,可讓您在資料集中具有多種語言的文件,而且當部署模型時,您可以使用任何支援的語言 (不一定包含在定型文件中) 查詢模型。 若要深入了解多語系支援,請參閱語言支援。 true
storageInputContainerName {CONTAINER-NAME} 你上傳文件的 Azure 儲存容器名稱。 myContainer
類別 [] 陣列,其中包含您在專案中擁有的所有類別。 []
documents [] 陣列,其中包含專案中的所有文件,以及此文件標記的類別。 []
位置 {DOCUMENT-NAME} 文件在儲存體容器中的位置。 由於所有文件都在容器的根目錄中,應該是文件名稱。 doc1.txt
資料集 {DATASET} 在進行訓練前分割時,此文件會移至其中的測試集。 請參閱 如何訓練模型。 此欄位的可能值為 Train 和 Test。 Train

傳送 API 請求後,您會收到回應 202 ,指出任務已正確提交。 在回應標頭中,擷取 operation-location 的值,格式如下:

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

{JOB-ID} 用來識別您的要求,因為此為非同步作業。 您可以使用此 URL 來取得匯入工作狀態。

此要求的可能錯誤案例:

  • 選取的資源沒有儲存體帳戶的適當權限。
  • 指定的 storageInputContainerName 不存在。
  • 使用了無效的語言代碼,或語言代碼類型不是字串。
  • multilingual 值是字串,而不是布林值。

取得匯入作業狀態

使用下列 GET 要求來取得匯入專案的狀態。 以您自己的值取代預留位置值。

要求 URL

{ENDPOINT}/language/authoring/analyze-text/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} 用來尋找模型定型狀態的識別碼。 此值是在上一個步驟中收到的 location 標頭值。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 深入了解其他可用的 API 版本 2022-05-01

headers

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

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

定型模型

一般而言,建立專案之後,您就會開始為連線到專案的容器中具有的文件加入標記。 在本快速入門中,您已匯入範例標記資料集,並使用範例 JSON 標記檔案初始化專案。

開始定型您的模型

匯入專案之後,就可以開始定型模型。

使用下列 URL、標頭和 JSON 本文來提交 POST 要求,以提交定型作業。 以您自己的值取代預留位置值。

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
預留位置 值 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 深入了解其他可用的 API 版本 2022-05-01

headers

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

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

請求主體

在您的要求本文中使用下列 JSON。 定型完成之後,該模型將被賦予 {MODEL-NAME}。 只有成功的定型作業會產生模型。

{
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "evaluationOptions": {
        "kind": "percentage",
        "trainingSplitPercentage": 80,
        "testingSplitPercentage": 20
    }
}
Key 預留位置 值 範例
modelLabel {MODEL-NAME} 在成功訓練之後指派給模型的模型名稱。 myModel
訓練配置版本 (trainingConfigVersion) {CONFIG-VERSION} 這是用來訓練模型的 模型版本 。 2022-05-01
evaluationOptions 將您的資料分割到定型集和測試集的選項。 {}
種類 percentage 分割方法。 可能的值為 percentage 或 manual。 如需詳細資訊,請參閱如何定型模型。 percentage
trainingSplitPercentage 80 要包含在定型集中的標記資料百分比。 建議的值為 80。 80
testingSplitPercentage 20 要包含在測試集中的標記資料百分比。 建議的值為 20。 20

附註

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

傳送 API 請求後,您會收到回應 202 ,指出任務已正確提交。 在回應標頭中,擷取 location 的值,格式如下:

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

{JOB-ID} 用來識別您的要求,因為此為非同步作業。 您可以使用此 URL 來取得定型狀態。

取得定型作業狀態

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

使用下列 GET 要求來取得模型定型程序的狀態。 以您自己的值取代預留位置值。

要求 URL

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
預留位置 值 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{JOB-ID} 用來尋找模型定型狀態的識別碼。 此值是在上一個步驟中收到的 location 標頭值。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 欲了解更多資訊, 請參閱模型生命週期。 2022-05-01

headers

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

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

回應本文

一旦你發送請求,就會收到以下回覆。

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{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": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

部署模型

一般來說,在定型模型之後,您可以檢閱其評估詳細資料,並視需要加以改善。 在這個快速入門中,你只需部署模型,並讓它在 Microsoft Foundry 中試用,或者你可以呼叫預測 API。

提交部署作業

使用下列 URL、標頭和 JSON 本文來提交 PUT 要求,以提交部署作業。 以您自己的值取代預留位置值。

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}
預留位置 值 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{DEPLOYMENT-NAME} 您部署的名稱。 此值區分大小寫。 staging
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 深入了解其他可用的 API 版本 2022-05-01

headers

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

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

請求主體

在要求的主體中使用下列 JSON。 使用您要指派給部署的模型名稱。

{
  "trainedModelLabel": "{MODEL-NAME}"
}
Key 預留位置 值 範例
trainedModelLabel {MODEL-NAME} 指派給部署的模型名稱。 您只能指派成功定型的模型。 此值區分大小寫。 myModel

傳送 API 請求後,您會收到回應 202 ,指出任務已正確提交。 在回應標頭中,擷取 operation-location 的值,格式如下:

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

{JOB-ID} 用來識別您的要求,因為此為非同步作業。 您可以使用此 URL 來取得部署狀態。

取得部署作業狀態

使用下列 GET 要求來查詢部署作業的狀態。 您可以使用您在上一個步驟中收到的 URL,或以您自己的值取代下列預留位置值。

{ENDPOINT}/language/authoring/analyze-text/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} 用來尋找模型定型狀態的識別碼。 它就在你在上一步收到的 location 標題值中。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 深入了解其他可用的 API 版本 2022-05-01

headers

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

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

回應本文

一旦你發送請求,就會收到以下回覆。 持續輪詢此端點,直到狀態參數變更為「成功」為止。 您應該會收到 200 代碼,指出要求是否成功。

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

分類文字

成功部署模型之後,您可以透過預測 API 開始使用該模型來分類文字。 在稍早下載的範例資料集中,您可以找到一些可在此步驟中使用的測試文件。

提交自訂文字分類工作

使用此 POST 要求來啟動文字分類工作。

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}
預留位置 值 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 欲了解更多資訊, 請參閱模型生命週期。 2022-05-01

headers

Key 值
Ocp-Apim-Subscription-Key 可讓您存取此 API 的金鑰。

body

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomMultiLabelClassification",
      "taskName": "Multi Label Classification",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}
Key 預留位置 值 範例
displayName {JOB-NAME} 您的工作名稱。 MyJobName
documents [{},{}] 要對其執行工作的文件清單。 [{},{}]
id {DOC-ID} 文件名稱或識別碼。 doc1
language {LANGUAGE-CODE} 字串,指定文件的語言代碼。 如果未指定此金鑰,則服務將會採用專案建立期間所選取專案的預設語言。 如需支援的語言代碼清單,請參閱語言支援。 en-us
text {DOC-TEXT} 對其執行工作的文件工作。 Lorem ipsum dolor sit amet
tasks 我們需要執行的工作清單。 []
taskName CustomMultiLabelClassification 工作名稱 CustomMultiLabelClassification
parameters 要傳遞至工作的參數清單。
project-name {PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
deployment-name {DEPLOYMENT-NAME} 您部署的名稱。 此值區分大小寫。 prod

回應

您會收到表示成功的 202 回應。 在回應標頭中,擷取 operation-location。 operation-location 的格式如下所示:

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

您可以使用此 URL 來查詢工作完成狀態,並在工作完成時取得結果。

取得工作結果

使用下列 GET 要求來查詢文字分類工作的狀態/結果。

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}
預留位置 值 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} 您所呼叫 API 的版本。 所參考的數值為最新版本的模型。 2022-05-01

headers

Key 值
Ocp-Apim-Subscription-Key 可讓您存取此 API 的金鑰。

回應主體

回應將會是具有下列參數的 JSON 文件。

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

清除資源

當您不再需要專案時,可以使用下列 DELETE 要求將其刪除。 以您自己的值取代預留位置值。

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
預留位置 值 範例
{ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{API-VERSION} 您所呼叫 API 的版本。 所引用的值為最新版本。 深入了解其他可用的 API 版本 2022-05-01

headers

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

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

一旦你發送 API 請求,就會收到 202 一個表示成功的回應,這表示你的專案會被刪除。 成功呼叫的結果是用於檢查作業狀態的 Operation-Location 標頭。

後續步驟

建立自訂文本分類模型後,你可以:

當您開始建立自己的自訂文字分類專案時,請使用「操作說明」文章,以深入了解如何開發模型的細節: