快速入門:自訂文字分類 (預覽)

使用本文開始建立自訂文字分類專案,以便定型自訂模型以進行文字分類。 模型是一種機器學習物件,可從我們提供的範例資料中學習,並經過定型之後將文字分類。

必要條件

建立新的 Azure 資源和 Azure Blob 儲存體帳戶

使用自訂文字分類之前,您必須先建立 Azure 語言資源,這會提供建立專案及開始定型模型所需的認證。 您也需要 Azure 儲存體帳戶,您可以在其中上傳將用來建置模型的資料集。

重要

若要快速開始使用,建議您使用以下提供的步驟來建立新的 Azure 語言資源,這可讓您建立資源,並同時設定儲存體帳戶,此做法將比稍後執行更容易。

如果您有想要使用的預先存在資源,將需要分別對此預先存在資源和儲存體帳戶進行設定。 如需詳細資訊,請參閱專案需求

  1. 前往 Azure 入口網站,建立新的 Azure 語言資源。 如果系統要求您選取其他功能,請選取 [自訂文字分類 & 自訂 NER]。 當您建立資源時,請確定其具有下列參數。

    Azure 資源需求 必要值
    位置 「美國西部 2」或「西歐」
    定價層 標準 (S) 定價層
  2. [自訂具名實體辨識 (NER) & 自訂文字分類 (Preview) ] 區段中,選取現有的儲存體帳戶,或選取 [ 建立新的儲存體帳戶]。 請注意,這些值適用於本快速入門,而不一定是您想要在生產環境中使用的儲存體帳戶值

    儲存體帳戶值 建議值
    Name 任何名稱
    效能 標準
    帳戶種類 儲存體 (一般用途 v1)
    複寫 本地備援儲存體 (LRS)
    位置 任何最接近您的位置,以達到最佳延遲。

將範例資料上傳至 Blob 容器

建立 Azure 儲存體帳戶並將其連結至您的語言資源之後,您需要為此快速入門上傳範例檔案到您容器的根資料夾。 這些檔案稍後將用來定型您的模型。

  1. 為本快速入門從 GitHub 下載範例電影摘要資料。 開啟.zip檔案,並擷取包含文字檔的資料夾。

  2. Azure 入口網站中,流覽至您所建立的儲存體帳戶,然後加以選取。

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

    A screenshot showing the main page for a storage account.

  4. 建立容器之後,按一下它。 然後選取[Upload] 按鈕,以選取您稍早下載的.txt和 .json 檔案。

    A screenshot showing the button for uploading files to the storage account.

    提示

    當您選取要上傳的檔案時,檔案總管會開啟至您的電腦。 若要選取資料夾中的所有檔案,請按 ctrl + a

提供的範例資料集包括大約 200 篇的電影摘要,其屬於下列一或多個類別:「推理」、「劇情」、「驚悚」、「喜劇」和「動作」。

建立自訂文字分類專案

設定您的資源和儲存體容器之後,請建立新的自訂文字分類專案。 專案是一個工作區域,可根據您的資料建置自訂 AI 模型。 您的專案只能由您和其他具有所使用 Azure 資源參與者存取權的人員存取。

  1. 登入 Language Studio。 隨即出現一個視窗,讓您選取訂閱和語言資源。 選取您在上一個步驟中建立的資源。

  2. 在 Language Studio 的 [分類文字 ] 區段下,從可用的服務中選取 [ 自訂文字分類 ],然後加以選取。

  3. 從 [專案] 頁面的頂端功能表中選取 [建立新專案]。 建立專案可讓您標記資料、定型、評估、改善及部署模型。

    A screenshot of the project creation page.

  4. 如果您已使用上述步驟建立資源,您將需要新增專案的資訊 (例如名稱),並選取您的儲存體容器。

    1. 選取您的專案類型。 在本快速入門中,我們將建立多標籤分類專案。 然後按一下 [下一步] 。

    2. 輸入專案資訊,包括名稱、描述以及您專案中檔案的語言。 您稍後將無法變更專案的名稱。

      提示

      您的資料集不需要完全採用相同的語言。 您可以有多個檔案,每個檔案都有不同的支援語言。 如果您的資料集包含不同語言的檔案,或者如果您預期在執行階段使用不同的語言,請在您輸入專案的基本資訊時,選取 [enable multi-lingual dataset] \(啟用多語言資料集\)。

    3. 選取您已上傳資料的容器。 在本快速入門中,我們將使用容器中可用的現有標記檔案。 然後按一下 [下一步] 。

    4. 檢閱您輸入的資料,然後選取 [建立專案]。

定型模型

一般而言,建立專案之後,您會匯入資料並開始 標記其中的實體 ,以定型自訂文字分類模型。 在本快速入門中,您將使用稍早下載的範例標記資料檔案,並儲存在您的 Azure 儲存體帳戶中。

模型是將要定型以分類文字的機器學習物件。 您的模型將從範例資料中學習,之後便可將技術支援票證分類。

若要開始定型您的模型:

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

  2. 選取 [定型新模型],然後在下方的文字方塊中輸入模型名稱。

    A screenshot showing the model selection page for training

  3. 按一下頁面底部的 [定型] 按鈕。

    注意

    • 當您 標記資料 時,您可以判斷資料集如何分割成定型和測試集。 您也可以將資料隨機分割成定型和測試集。
    • 定型最多可能需要幾小時的時間。

部署模型

一般來說,在定型模型之後,您可以檢閱其評估詳細資料,並視需要進行改進。 在本快速入門中,您只需要部署您的模型,使其可供您試用。

在您的模型定型之後,您就可加以部署。 部署模型可讓您使用分析 API,開始使用模型分類文字。

  1. Language Studio中移至您的專案。

  2. 從左面板中,選取 [部署模型]。

  3. 按一下 [ 新增部署 ] 以提交新的部署作業。

    A screenshot showing the deployment button.

  4. 在出現的視窗中,您可以建立新的部署名稱,或覆寫現有的部署名稱。 然後,您可以將定型的模型新增至此部署名稱。

    A screenshot showing the screen for a new deployment

測試您的模型

部署模型之後,您就可以開始將其用於自訂文字分類。 使用下列步驟傳送您的第一個自訂文字分類要求。

  1. 從左側功能表中選取 [測試模型]。

  2. 選取您想要測試的模型。

  3. 使用您稍早下載的其中一個檔案,將檔案的文字新增至文字方塊。 您也可以上傳檔案 .txt

  4. 按一下 [執行測試]。

  5. [結果] 索引標籤中,您可以看到文字的預測類別。 您也可以在 [JSON] 索引標籤下檢視 JSON 回應。

    A screenshot showing model test results. The example is from CMU Movie Summary, CC BY-SA 3.0, modified by Microsoft

清除專案

當您不再需要專案時,可以從您的 Language Studio 專案頁面刪除您的專案。 選取您想要刪除的專案,並按一下 [刪除]。

必要條件

建立新的 Azure 資源和 Azure Blob 儲存體帳戶

使用自訂文字分類之前,您必須先建立語言資源,這可提供建立專案及開始定型模型所需訂閱和認證。 您也需要 Azure Blob 儲存體帳戶,這是保存文字以供分析所需的線上資料儲存體。

重要

若要快速開始使用,建議您使用以下提供的步驟來建立新的 Azure 語言資源,這可讓您建立資源,並同時設定儲存體帳戶,此做法將比稍後執行更容易。

如果您有想要使用的預先存在資源,將需要分別對此預先存在資源和儲存體帳戶進行設定。 如需詳細資訊,請參閱專案需求

  1. 前往 Azure 入口網站,建立新的 Azure 語言資源。 如果系統要求您選取其他功能,請選取 [略過此步驟]。 當您建立資源時,請確定其具有下列參數。

    Azure 資源需求 必要值
    位置 「美國西部 2」或「西歐」
    定價層 標準 (S) 定價層
  2. [自訂具名實體辨識 (NER) & 自訂文字分類 (Preview) ] 區段中,選取 [建立新的儲存體帳戶]。 這些值適用於本快速入門,而不一定是您想要在生產環境中使用的儲存體帳戶值

    儲存體帳戶值 建議值
    Name 任何名稱
    效能 標準
    帳戶種類 儲存體 (一般用途 v1)
    複寫 本地備援儲存體 (LRS)
    位置 任何最接近您的位置,以達到最佳延遲。

將範例資料上傳至 Blob 容器

建立 Azure 儲存體帳戶並將其連結至您的語言資源之後,您需要為此快速入門上傳範例檔案到您容器的根資料夾。 這些檔案稍後將用來定型您的模型。

  1. 為本快速入門從 GitHub 下載範例電影摘要資料。 開啟.zip檔案,然後擷取包含其中文字檔的資料夾。

  2. Azure 入口網站中,流覽至您建立的儲存體帳戶,然後加以選取。

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

    A screenshot showing the main page for a storage account.

  4. 建立容器之後,請按一下它。 然後選取[Upload] 按鈕,以選取您稍早下載.txt和 .json 檔案。

    A screenshot showing the button for uploading files to the storage account.

    提示

    當您選取要上傳的檔案時,檔案總管會開啟至您的電腦。 若要選取資料夾中的所有檔案,請按 ctrl + a

提供的範例資料集包括大約 200 篇的電影摘要,其屬於下列一或多個類別:「推理」、「劇情」、「驚悚」、「喜劇」和「動作」。

取得您的資源金鑰和端點

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

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

A screenshot showing the key and endpoint page in the Azure portal

建立專案

若要開始建立自訂文字分類模型,您需要建立專案。 建立專案可讓您標記資料、定型、評估、改善及部署模型。

注意

所有作業的專案名稱皆區分大小寫。

使用下列 URL、標頭和 JSON 本文來建立 POST 要求,以建立您的專案並匯入標記檔案。

要求 URL

使用下列 URL 來建立專案,並匯入您的標記檔案。 請以您自己的值取代下列預留位置值。

{YOUR-ENDPOINT}/language/analyze-text/projects/{projectName}/:import?api-version=2021-11-01-preview
預留位置 範例
{YOUR-ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com

標題

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

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

主體

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

{
    "api-version": "2021-11-01-preview",
    "metadata": {
        "name": "MyProject",
        "multiLingual": true,
        "description": "Trying out custom text classification",
        "modelType": "multiClassification",
        "language": "string",
        "storageInputContainerName": "YOUR-CONTAINER-NAME",
        "settings": {}
    },
    "assets": {
        "classifiers": [
            {
                "name": "Class1"
            }
        ],
        "documents": [
            {
                "location": "doc1.txt",
                "language": "en-us",
                "dataset": "Train",
                "classifiers": [
                    {
                        "classifierName": "Class1"
                    }
                ]
            }
        ]
    }
}

針對中繼資料索引鍵:

Key 範例
modelType 您的模型類型,用於單一標籤分類,請使用 singleClassification multiClassification
storageInputContainerName 您的 Azure Blob 儲存體容器名稱。 myContainer

針對檔金鑰:

Key 範例
location Blob 存放區上的檔案名稱。 doc2.txt
language 檔的語言。 en-us
dataset 選擇性欄位,指定此檔所屬的資料集。 TrainTest

如果有下列情況,此要求將會傳回錯誤:

  • 選取的資源沒有儲存體帳戶的適當權限。

開始定型您的模型

建立專案之後,您就可以開始定型自訂文字分類模型。 使用下列 URL、標頭和 JSON 本文建立 POST 要求,以開始定型自訂文字分類模型。

要求 URL

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

{YOUR-ENDPOINT}/language/analyze-text/projects/{PROJECT-NAME}/:train?api-version=2021-11-01-preview
預留位置 範例
{YOUR-ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject

標題

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

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

要求本文

在您的要求中使用下列 JSON。 定型完成之後,就會將模型命名為 MyModel

{
  "modelLabel": "MyModel",
  "runValidation": true,
  "evaluationOptions":
    {
        "type":"percentage",
        "testingSplitPercentage":"30",
        "trainingSplitPercentage":"70"
    }
}
Key 範例
modelLabel 您的模型名稱。 MyModel
runValidation 要在測試集上執行驗證的布林值。 TrueFalse
evaluationOptions 指定評估選項。
type 指定 datasplit 類型。 set 或 percentage
testingSplitPercentage 如果 type百分比,則為必要的整數位段。 指定測試分割。 30
trainingSplitPercentage 如果 type百分比,則為必要的整數位段。 指定定型分割。 70

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

{YOUR-ENDPOINT}/language/analyze-text/projects/{YOUR-PROJECT-NAME}/train/jobs/{JOB-ID}?api-version=2021-11-01-preview

JOB-ID 是用來識別您的要求,因為此為非同步作業。 您將在下一個步驟中使用此 URL 來取得定型狀態。

取得定型訓練

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

{YOUR-ENDPOINT}/language/analyze-text/projects/{YOUR-PROJECT-NAME}/train/jobs/{JOB-ID}?api-version=2021-11-01-preview
預留位置 範例
{YOUR-ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{JOB-ID} 用來尋找模型定型狀態的識別碼。 這是在上一個步驟中收到的 location 標頭值。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx

標題

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

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

回應本文

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

{
  "jobs": [
    {
      "result": {
        "trainedModelLabel": "MyModel",
        "trainStatus": {
          "percentComplete": 0,
          "elapsedTime": "string"
        },
        "evaluationStatus": {
          "percentComplete": 0,
          "elapsedTime": "string"
        }
      },
      "jobId": "string",
      "createdDateTime": "2021-10-19T23:24:41.572Z",
      "lastUpdatedDateTime": "2021-10-19T23:24:41.572Z",
      "expirationDateTime": "2021-10-19T23:24:41.572Z",
      "status": "unknown",
      "errors": [
        {
          "code": "unknown",
          "message": "string"
        }
      ]
    }
  ],
  "nextLink": "string"
}

部署模型

使用下列 URL、標頭和 JSON 主體建立 PUT 要求,以開始部署自訂文字分類模型。

{YOUR-ENDPOINT}/language/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version=2021-11-01-preview
預留位置 範例
{YOUR-ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{DEPLOYMENT-NAME} 您部署的名稱。 此值區分大小寫。 prod

標題

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

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

要求本文

在您的要求中使用下列 JSON。 定型完成之後,就會將模型命名為 MyModel

{
  "trainedModelLabel": "MyModel",
  "deploymentName": "prod"
}

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

{YOUR-ENDPOINT}/language/analyze-text/projects/{YOUR-PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version=2021-11-01-preview

JOB-ID 是用來識別您的要求,因為此為非同步作業。 您將在下一個步驟中使用此 URL 來取得發佈狀態。

取得部署狀態

使用下列 GET 要求來查詢模型發佈程序的狀態。 您可以使用您在上一個步驟中收到的 URL,或以您自己的值取代下列預留位置值。

{YOUR-ENDPOINT}/language/analyze-text/projects/{YOUR-PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version=2021-11-01-preview
預留位置 範例
{YOUR-ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
{DEPLOYMENT-NAME} 您部署的名稱。 此值區分大小寫。 prod
{JOB-ID} 用來尋找模型定型狀態的識別碼。 這是在上一個步驟中收到的 location 標頭值。 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx

標題

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

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

提交自訂文字分類工作

注意

Project名稱區分大小寫。

使用此 POST 要求來啟動實體擷取工作。 將 {projectName} 取代為您有需要使用模型的專案名稱。

{YOUR-ENDPOINT}/text/analytics/v3.2-preview.2/analyze

標題

Key
Ocp-Apim-Subscription-Key 可讓您存取此 API 的訂用帳戶金鑰。

主體

{
    "displayName": "MyJobName",
    "analysisInput": {
        "documents": [
            {
                "id": "doc1", 
                "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc tempus, felis sed vehicula lobortis, lectus ligula facilisis quam, quis aliquet lectus diam id erat. Vivamus eu semper tellus. Integer placerat sem vel eros iaculis dictum. Sed vel congue urna."
            },
            {
                "id": "doc2",
                "text": "Mauris dui dui, ultricies vel ligula ultricies, elementum viverra odio. Donec tempor odio nunc, quis fermentum lorem egestas commodo. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos."
            }
        ]
    },
    "tasks": {
        "customMultiClassificationTasks": [      
            {
                "parameters": {
                      "project-name": "MyProject",
                      "deployment-name": "MyDeploymentName"
                      "stringIndexType": "TextElements_v8"
                }
            }
        ]
    }
}
答案 範例值 Description
displayName "MyJobName" 您的作業名稱
文件 [{},{}] 要在其中執行工作的文件清單
識別碼 "doc1" 字串文件識別碼
text "Lorem ipsum dolor sit amet" 使用字串格式的文件
"tasks" [] 我們需要執行的工作清單。
-- customMultiClassificationTasks 所要執行工作的工作識別碼。 用於 customClassificationTasks 單一標籤分類工作和 customMultiClassificationTasks 多重標籤分類工作。
參數 [] 所要傳遞至工作的參數清單
project-name "MyProject" 您的專案名稱。 專案名稱須區分大小寫。
deployment-name "MyDeploymentName" 您的部署名稱

將文件的文字取代為電影摘要以進行分類。

回應

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

{YOUR-ENDPOINT}/text/analytics/v3.2-preview.2/analyze/jobs/<jobId>

您將使用此端點來取得自訂文字分類工作結果。

取得自訂文字分類工作狀態和結果

使用下列 GET 要求來查詢自訂分類工作的狀態/結果。 您可以使用您在上一個步驟中收到的端點。

{YOUR-ENDPOINT}/text/analytics/v3.2-preview.2/analyze/jobs/<jobId>.

標題

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

回應本文

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

{
    "createdDateTime": "2021-05-19T14:32:25.578Z",
    "displayName": "MyJobName",
    "expirationDateTime": "2021-05-19T14:32:25.578Z",
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
    "status": "completed",
    "errors": [],
    "tasks": {
        "details": {
            "name": "MyJobName",
            "lastUpdateDateTime": "2021-03-29T19:50:23Z",
            "status": "completed"
        },
        "completed": 1,
        "failed": 0,
        "inProgress": 0,
        "total": 1,
        "tasks": {
    "customMultiClassificationTasks": [
        {
            "lastUpdateDateTime": "2021-05-19T14:32:25.579Z",
            "name": "MyJobName",
            "status": "completed",
            "results": {
                "documents": [
                    {
                        "id": "doc1",
                        "classes": [
                            {
                                "category": "Class_1",
                                "confidenceScore": 0.0551877357
                            }
                        ],
                        "warnings": []
                    },
                    {
                        "id": "doc2",
                        "classes": [
                            {
                                "category": "Class_1",
                                "confidenceScore": 0.0551877357
                            },
                                                        {
                                "category": "Class_2",
                                "confidenceScore": 0.0551877357
                            }
                        ],
                        "warnings": []
                    }
                ],
                "errors": [],
                "statistics": {
                    "documentsCount":0,
                    "erroneousDocumentsCount":0,
                    "transactionsCount":0
                }
                    }
                }
            ]
        }
    }

清除資源

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

{YOUR-ENDPOINT}/language/analyze-text/projects/{PROJECT-NAME}
預留位置 範例
{YOUR-ENDPOINT} 用於驗證 API 要求的端點。 https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject

標題

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

Key
Ocp-Apim-Subscription-Key 資源的索引鍵。 用於驗證 API 要求。

後續步驟

建立自訂文字分類模型之後,您可以:

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