快速入門：自訂文字分類

發行項
10/21/2024

使用本文開始建立自訂文字分類專案，您可以在其中定型自訂模型以進行文字分類。模型是定型以用來執行特定工作的人工智慧軟體。在此系統中，模型會分類文字，並從標記的資料中學習以定型。

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

單一標籤分類：您只能為資料集中的每一個文件指派一個類別。例如，電影腳本只能分類為「愛情片」或「喜劇」。
多重標籤分類：您可以為資料集中的每一個文件指派多個類別。例如，電影腳本可以分類為「喜劇」，或「愛情片」和「喜劇」。

在本快速入門中，您可以使用提供的範例資料集來建置多重標籤分類，您可以在其中將電影腳本分類成一或多個類別，也可以使用單一標籤分類資料集，在其中將科學論文的摘要歸類到其中一個定義的領域。

必要條件

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

建立新的 Azure AI 語言資源和 Azure 儲存體帳戶

使用自訂文字分類前，您必須建立 Azure AI 語言資源，因為此資源提供建立專案和開始訓練模型必要的認證。您也需要 Azure 儲存體帳戶，然後在此帳戶上傳用來組建模型的資料集。

重要

若要快速開始使用，建議您使用本文中提供的步驟來建立新的 Azure AI 語言資源。使用本文中的步驟將可讓您以更輕鬆的方式，同時建立語言資源與儲存體帳戶。

如果您有想要使用的預先存在資源，必須將該資源連接到儲存體帳戶。

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

移至 Azure 入口網站以建立新的 Azure AI 語言資源。
在出現的視窗中，從自訂功能選取 [自訂文字分類和自訂具名實體辨識]。選取畫面底部的 [繼續建立您的資源]。

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

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

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

您可以搜尋您的資源群組，並遵循其相關聯訂用帳戶的連結來判斷您的 Azure 訂用帳戶擁有者。接下來：

選取 [存取控制 (IAM)] 索引標籤
選取 [角色指派]
依 [角色: 擁有者] 進行篩選。

在 [自訂文字分類和自訂具名實體辨識] 區段中，選取現有的儲存體帳戶，或選取 [新的儲存體帳戶]。請注意，這些值可協助您開始使用，但不一定是您想要在生產環境中使用的儲存體帳戶值。若要避免在建置專案期間的延遲，請連線至與語言資源位於相同區域中的儲存體帳戶。

儲存體帳戶值建議值

儲存體帳戶名稱任何名稱

Storage account type 標準 LRS
請確定已核取負責任 AI 通知。選取頁面底部的 [檢閱 + 建立] 。

儲存體帳戶值	建議值
儲存體帳戶名稱	任何名稱
Storage account type	標準 LRS

將範例資料上傳至 Blob 容器

建立 Azure 儲存體帳戶並將其連結至您的語言資源之後，您需要將樣本資料集中的文件上傳到容器的根目錄。這些文件稍後將用於定型模型。

多重標籤分類
單一標籤分類

下載多個標籤分類專案的範例資料集。
開啟 .zip 檔案，然後擷取包含文件的資料夾。

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

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

在 Azure 入口網站中，瀏覽至您建立的儲存體帳戶，然後加以選取。您可以按一下 [儲存體帳戶]，然後在 [篩選任何欄位] 中輸入儲存體帳戶名稱來執行此動作。

如果您的資源群組未顯示，請確定 [訂用帳戶等於] 篩選條件已設定為 [全部]。
在您的儲存體帳戶中，從左側功能表中 [資料儲存體] 的下方選取 [容器]。在出現的畫面中，選取 [+ 容器]。為容器指定名稱 example-data，並保留預設的公用存取層級。
建立容器之後，請加以選取。然後選取 [上傳] 按鈕，以選取您稍早下載的 .txt 和 .json 檔案。

建立自訂文字分類專案

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

登入 Language Studio。隨即出現一個視窗，讓您選取訂用帳戶和語言資源。選取您的語言資源。
在 Language Studio 的 [分類文字] 區段下，選取 [自訂文字分類]。
從專案頁面頂端的功能表中選取 [建立新專案]。建立專案可讓您標示資料、定型、評估、改善以及部署模型。
您按一下 [建立新專案] 之後，隨即會出現一個視窗，讓您連線您的儲存體帳戶。如果您已連線儲存體帳戶，您會看到該儲存體帳戶已連線。如果沒有，請從出現的下拉式清單中選擇儲存體帳戶，然後選取 [連線儲存體帳戶]；這會為您的儲存體帳戶設定必要角色。如果您在該儲存體帳戶上未獲指派為擁有者身分，此步驟可能會傳回錯誤。
注意
- 您只需要針對您使用的每個新語言資源執行此步驟一次。
- 此程序無法復原，如果您將儲存體帳戶連線到語言資源，之後就無法中斷連線。
- 您只能將語言資源連線到一個儲存體帳戶。
選取專案類型。您可以建立多標籤分類專案，其中的每個文件可以屬於一或多個類別，或建立單一標籤分類專案，其中的每個文件只能屬於一個類別。稍後將無法變更該選取的類型。深入了解專案類型
輸入專案資訊，包括您專案中文件的名稱、描述和語言。如果您使用範例資料集，請選取 [英文]。您之後將無法變更專案的名稱。選取 [下一步]。

提示

您的資料集不需要完全採用相同的語言。您可以有多個文件，每個文件都有不同的支援語言。如果資料集包含不同語言的文件，或者如果您預期在執行階段使用不同語言的文字，請在您輸入專案的基本資訊時，選取 [啟用多語言資料集] 選項。您稍後可以從 [專案設定] 頁面啟用此選項。
選取您已上傳資料集的容器。

注意

如果您已標示資料，則請確定其遵循支援的格式，然後選取 [是，我的文件已加上標籤，而且我有已格式化的 JSON 標籤檔案]，然後從下方的下拉式功能表選取標籤檔案。

如果您使用其中一個範例資料集，請使用包含 webOfScience_labelsFile 或 movieLabels 的 JSON 檔案。然後選取下一步。
檢閱您輸入的資料，然後選取 [建立專案]。

定型您的模型

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

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

從左側功能表中，選取 [定型工作]。
從頂端功能表中選取 [開始定型作業]。
選取 [定型新模型]，然後在文字方塊中輸入模型名稱。您也可以藉由選取此選項來覆寫現有的模型，然後從下拉式功能表中選擇您想要覆寫的模型。覆寫定型的模型是無法復原的，但在您部署新模型之前，不會影響已部署的模型。
選取資料分割方法。您可以選擇 [從定型資料自動分割測試集]，其中系統會根據指定的百分比，在定型集與測試集之間分割標記的資料。或者，您可以使用手動分割定型和測試資料，只有在資料標記期間已將文件新增至測試集時，才會啟用此選項。如需資料分割的詳細資訊，請參閱如何定型模型。
選取 [定型] 按鈕。
如果您從清單中選取 [定型作業識別碼]，則會顯示側邊窗格，您可以在其中檢查此作業的 [定型進度]、[作業狀態] 和其他詳細資料。
注意
- 只有成功完成的定型作業才會產生模型。
- 根據標籤資料的大小，定型模型所需的時間可能需要幾分鐘到數小時的時間。
- 您一次只能執行一個定型作業。除非執行中的作業完成，否則無法在同一個專案內啟動其他定型作業。

部署模型

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

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

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

注意

覆寫現有的部署不需要變更預測 API 呼叫，但您取得的結果將會以新指派的模型為基礎。
選取 [部署] 以動部署作業。
部署成功之後，在其旁邊會出現到期日。部署到期表示部署的模型無法再用於預測，通常發生於訓練組態到期的十二個月後。

測試您的模型

部署模型之後，您可以透過預測 API 開始使用該模型來分類文字。在本快速入門中，您將使用 Language Studio 提交自訂文字分類工作，並將結果視覺化。在稍早下載的範例資料集中，您可以找到一些可在此步驟中使用的測試文件。

若要在 Language Studio 內測試已部署的模型：

從螢幕左側的功能表中選取 [測試部署]。
選取您要測試的部署。您只能測試指派給部署的模型。
針對多語系專案，從語言下拉式清單中選取您要測試的文字語言。
從下拉式清單中，選取您要查詢/測試的部署。
輸入您要在要求中提交的文字，或上傳要使用的 .txt 文件。如果您使用其中一個範例資料集，則您可以使用其中一個包含的 .txt 檔案。
選取頂端功能表中的 [執行測試]。
在 [結果] 索引標籤中，您可以看到文字的預測類別。您也可以在 [JSON] 索引標籤下檢視 JSON 回應。下列範例適用於單一標籤分類專案。多重標籤分類專案會在結果中傳回多個類別。

清除專案

當您不再需要專案時，可以使用 Language Studio 來刪除您的專案。選取頂端的 [自訂文字分類]，然後選取您想要刪除的專案。選取頂端功能表中的 [刪除] 以刪除專案。

必要條件

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

建立新的 Azure AI 語言資源和 Azure 儲存體帳戶

使用自訂文字分類前，您必須建立 Azure AI 語言資源，因為此資源提供建立專案和開始訓練模型必要的認證。您也需要 Azure 儲存體帳戶，然後在此帳戶上傳用於組建模型的資料集。

重要

若要快速開始使用，建議您使用本文提供的步驟來建立新的 Azure AI 語言資源，這可讓您建立語言資源，同時建立及/或連接儲存體帳戶，此做法會比稍後執行更容易。

如果您有想要使用的預先存在資源，必須將該資源連接到儲存體帳戶。

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

移至 Azure 入口網站以建立新的 Azure AI 語言資源。
在出現的視窗中，從自訂功能選取 [自訂文字分類和自訂具名實體辨識]。選取畫面底部的 [繼續建立您的資源]。

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

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

您可以搜尋您的資源群組，並遵循其相關聯訂用帳戶的連結來判斷您的 Azure 訂用帳戶擁有者。接下來：

選取 [存取控制 (IAM)] 索引標籤
選取 [角色指派]
依 [角色: 擁有者] 進行篩選。

在 [自訂文字分類和自訂具名實體辨識] 區段中，選取現有的儲存體帳戶，或選取 [新的儲存體帳戶]。請注意，這些值可協助您開始使用，但不一定是您想要在生產環境中使用的儲存體帳戶值。若要避免在建置專案期間的延遲，請連線至與語言資源位於相同區域中的儲存體帳戶。

儲存體帳戶值建議值

儲存體帳戶名稱任何名稱

Storage account type 標準 LRS
請確定已核取負責任 AI 通知。選取頁面底部的 [檢閱 + 建立] 。

儲存體帳戶值	建議值
儲存體帳戶名稱	任何名稱
Storage account type	標準 LRS

將範例資料上傳至 Blob 容器

建立 Azure 儲存體帳戶並將其連結至您的語言資源之後，您需要將樣本資料集中的文件上傳到容器的根目錄。這些文件稍後將用於定型模型。

多重標籤分類
單一標籤分類

下載多個標籤分類專案的範例資料集。
開啟 .zip 檔案，然後擷取包含文件的資料夾。

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

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

在 Azure 入口網站中，瀏覽至您建立的儲存體帳戶，然後加以選取。您可以按一下 [儲存體帳戶]，然後在 [篩選任何欄位] 中輸入儲存體帳戶名稱來執行此動作。

如果您的資源群組未顯示，請確定 [訂用帳戶等於] 篩選條件已設定為 [全部]。
在您的儲存體帳戶中，從左側功能表中 [資料儲存體] 的下方選取 [容器]。在出現的畫面中，選取 [+ 容器]。為容器指定名稱 example-data，並保留預設的公用存取層級。
建立容器之後，請加以選取。然後選取 [上傳] 按鈕，以選取您稍早下載的 .txt 和 .json 檔案。

取得您的資源金鑰和端點

前往您位於 Azure 入口網站的資源概觀頁面
在左側功能表中，選取 [金鑰和端點]。您將使用 API 要求的端點和金鑰

建立自訂文字分類專案

觸發匯入專案作業

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

標頭

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

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

本文

在您的要求中使用下列 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"
          }
        ]
      }
    ]
  }
}

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

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

機碼	預留位置	值	範例
api-version	`{API-VERSION}`	您正在呼叫的 API 版本。此處所使用的版本必須是 URL 中的相同 API 版本。	`2022-05-01`
projectName	`{PROJECT-NAME}`	您專案的名稱。此值區分大小寫。	`myProject`
projectKind	`customSingleLabelClassification`	您的專案種類。	`customSingleLabelClassification`
language	`{LANGUAGE-CODE}`	字串，指定專案中所用文件的語言代碼。如果您的專案是多語系專案，請選擇大部分文件的語言代碼。若要深入了解支援的語言代碼，請參閱語言支援。	`en-us`
多語系	`true`	布林值，可讓您在資料集中具有多種語言的文件，而且當部署模型時，您可以使用任何支援的語言 (不一定包含在定型文件中) 查詢模型。若要深入了解多語系支援，請參閱語言支援。	`true`
storageInputContainerName	`{CONTAINER-NAME}`	您已上傳文件的 Azure 儲存體容器名稱。	`myContainer`
類別	[]	陣列，其中包含您在專案中擁有的所有類別。這些是您要用來分類文件的類別。	[]
文件	[]	陣列，其中包含專案中的所有文件，以及此文件所屬的類別。	[]
location	`{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`

標頭

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

機碼	值
`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`

標頭

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

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

要求本文

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

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

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

注意

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

傳送 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 版本。此處參考的值適用於發行的最新版本。若要深入了解其他可用的 API 版本，請參閱模型生命週期。	`2022-05-01`

標頭

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

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

部署模型

提交部署作業

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

標頭

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

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

要求本文

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

{
  "trainedModelLabel": "{MODEL-NAME}"
}

機碼	預留位置	值	範例
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`

標頭

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

機碼	值
`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 版本。此處參考的值適用於發行的最新版本。若要深入了解其他可用的 API 版本，請參閱模型生命週期。	`2022-05-01`

標頭

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

{
  "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}"
      }
    }
  ]
}

機碼	預留位置	值	範例
`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`

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "Single Classification Label",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

機碼	預留位置	值	範例
displayName	`{JOB-NAME}`	您的工作名稱。	`MyJobName`
文件		要對其執行工作的文件清單。
`id`	`{DOC-ID}`	文件名稱或識別碼。	`doc1`
`language`	`{LANGUAGE-CODE}`	字串，指定文件的語言代碼。如果未指定此金鑰，則服務將會採用專案建立期間所選取專案的預設語言。如需支援的語言代碼清單，請參閱語言支援。	`en-us`
`text`	`{DOC-TEXT}`	對其執行工作的文件工作。	`Lorem ipsum dolor sit amet`
`taskName`	CustomSingleLabelClassification	工作名稱	CustomSingleLabelClassification
`tasks`	[]	我們要執行的工作陣列。	[]
`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`

標頭

機碼	數值
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"
        }
      }
    ]
  }
}

{
  "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": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "class": [
                  {
                      "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`

標頭

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

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

傳送 API 要求之後，您將會收到指出成功的 202 回應，這表示您的專案已刪除。成功呼叫的結果是用於檢查作業狀態的 Operation-Location 標頭。

下一步

建立自訂文字分類模型之後，您可以：

使用執行時間 API 將文字分類

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

共用方式為

快速入門：自訂文字分類

必要條件

建立新的 Azure AI 語言資源和 Azure 儲存體帳戶

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

將範例資料上傳至 Blob 容器

建立自訂文字分類專案

定型您的模型

部署模型

測試您的模型

清除專案

必要條件

建立新的 Azure AI 語言資源和 Azure 儲存體帳戶

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

將範例資料上傳至 Blob 容器

取得您的資源金鑰和端點

建立自訂文字分類專案

觸發匯入專案作業

標頭

本文

取得匯入作業狀態

要求 URL

標頭

定型您的模型

開始定型您的模型

標頭

要求本文

取得定型作業狀態

要求 URL

標頭

回應本文

部署模型

提交部署作業

標頭

要求本文

取得部署作業狀態

標頭

回應本文

分類文字

提交自訂文字分類工作

標頭

本文

回應

取得工作結果

標頭

回應本文

清除資源

標頭

下一步

意見反應

其他資源