快速入門：自訂具名實體辨識

必要條件

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

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

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

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

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

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

   

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

   名稱	描述
   訂用帳戶	您的 Azure 訂閱。
   資源群組	將包含您資源的資源群組。 您可以使用現有群組或建立新的群組。
   區域	語言資源的區域。 例如，「美國西部 2」。
   名稱	您的資源名稱。
   定價層	語言資源的定價層。 您可使用免費 (F0) 層來試用服務。

   注意

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

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

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

5. 請確定已核取負責任 AI 通知。 選取頁面底部的 [檢閱 + 建立] 按鈕，然後選取 [建立]。

將範例資料上傳至 Blob 容器

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

1. 從 GitHub 下載樣本資料集。

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

3. 在 Azure 入口網站中，瀏覽至您建立的儲存體帳戶，然後加以選取。

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

   

5. 建立容器之後，請加以選取。 然後選取 [上傳] 按鈕，以選取您稍早下載的 .txt 和 .json 檔案。

   

提供的範例資料集包含 20 個貸款合約。 每個合約皆包含兩方：貸方和借方。 您可以使用所提供的範例檔案來擷取雙方相關資訊、合約日期、貸款金額及利率。

建立自訂具名實體辨識專案

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

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

2. 在 Language Studio 的 [擷取資訊] 區段下，選取 [自訂具名實體辨識]。

   

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

   

4. 您按一下 [建立新專案] 之後，隨即會出現一個視窗，讓您連線您的儲存體帳戶。 如果您已連線儲存體帳戶，您會看到該儲存體帳戶已連線。 如果沒有，請從出現的下拉式清單中選擇儲存體帳戶，然後選取 [連線儲存體帳戶]；這會為您的儲存體帳戶設定必要角色。 如果您在該儲存體帳戶上未獲指派為擁有者身分，此步驟可能會傳回錯誤。

   注意

   • 您只需要針對您使用的每個新資源執行此步驟一次。
   • 此程序無法復原，如果您將儲存體帳戶連線到語言資源，之後就無法中斷連線。
   • 您只能將語言資源連線到一個儲存體帳戶。

   

5. 輸入專案資訊，包括名稱、描述以及您專案中檔案的語言。 如果您使用範例資料集，請選取 [英文]。 您之後將無法變更專案的名稱。 選取下一個

   提示

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

6. 選取您已上傳資料集的容器。 如果您已經標示資料，請確定其遵循支援的格式，然後選取 [是，我的檔案已加上標籤，而且我已設定 JSON 標籤檔案的格式]，然後從下拉式功能表中選取標籤檔案。 選取 [下一步]。

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

定型您的模型

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

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

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

2. 從頂端功能表中選取 [開始定型作業]。

3. 選取 [定型新模型]，然後在文字方塊中輸入模型名稱。 您也可以藉由選取此選項來覆寫現有的模型，然後從下拉式功能表中選擇您想要覆寫的模型。 覆寫定型的模型是無法復原的，但在您部署新模型之前，不會影響已部署的模型。

   

4. 選取資料分割方法。 您可以選擇 [從定型資料自動分割測試集]，其中系統會根據指定的百分比，在定型集與測試集之間分割標記的資料。 或者，您可以使用手動分割定型和測試資料，只有在資料標記期間已將文件新增至測試集時，才會啟用此選項。 如需資料分割的相關資訊，請參閱如何定型模型。

5. 選取 [定型] 按鈕。

6. 如果您從清單中選取 [定型作業識別碼]，則會顯示側邊窗格，您可以在其中檢查此作業的 [定型進度]、[作業狀態] 和其他詳細資料。

   注意

   • 只有成功完成的定型作業才會產生模型。
   • 定型可能需要幾分鐘到數小時的時間，以標記的資料大小而定。
   • 您一次只能執行一個定型作業。 除非執行中的作業完成，否則無法在同一個專案內啟動其他定型作業。

部署模型

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

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

1. 從左側功能表中，選取 [部署模型]。

2. 選取 [新增部署] 以啟動新的部署作業。

   

3. 選取 [建立新的部署] 以建立新的部署，並從下方的下拉式清單中指派定型的模型。 您也可以選取此選項來覆寫現有的部署，然後從下方的下拉式清單中，選取您想要為其指派的定型模型。

   注意

   覆寫現有的部署不需要變更預測 API 呼叫，但您取得的結果將會以新指派的模型為基礎。

   

4. 選取 [部署] 以啟動部署作業。

5. 部署成功之後，在其旁邊會出現到期日。 部署到期表示部署的模型無法再用於預測，通常發生於訓練組態到期的十二個月後。

測試您的模型

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

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

1. 從左側功能表中，選取 [測試部署]。

2. 選取您要測試的部署。 您只能測試指派給部署的模型。

3. 針對多語系專案，從語言下拉式清單中，選取您要測試的文字語言。

4. 從下拉式清單選取您要查詢/測試的部署。

5. 您可以輸入想在要求中提交的文字，或上傳要使用的 .txt 檔案。

6. 選取頂端功能表中的 [執行測試]。

7. 在 [結果] 索引標籤中，您可以看到來自您文字的已擷取實體及實體的類型。 您也可以在 [JSON] 索引標籤下檢視 JSON 回應。

清除資源

當您不再需要專案時，可以使用 Language Studio 來刪除您的專案。 從頂端選取 [自訂具名實體辨識 (NER)]、選取您想要刪除的專案，然後從頂端功能表中選取 [刪除]。

必要條件

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

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

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

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

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

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

   

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

   名稱	描述
   訂用帳戶	您的 Azure 訂閱。
   資源群組	將包含您資源的資源群組。 您可以使用現有群組或建立新的群組。
   區域	語言資源的區域。 例如，「美國西部 2」。
   名稱	您的資源名稱。
   定價層	語言資源的定價層。 您可使用免費 (F0) 層來試用服務。

   注意

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

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

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

5. 請確定已核取負責任 AI 通知。 選取頁面底部的 [檢閱 + 建立] 按鈕，然後選取 [建立]。

將範例資料上傳至 Blob 容器

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

1. 從 GitHub 下載樣本資料集。

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

3. 在 Azure 入口網站中，瀏覽至您建立的儲存體帳戶，然後加以選取。

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

   

5. 建立容器之後，請加以選取。 然後選取 [上傳] 按鈕，以選取您稍早下載的 .txt 和 .json 檔案。

   

提供的範例資料集包含 20 個貸款合約。 每個合約皆包含兩方：貸方和借方。 您可以使用所提供的範例檔案來擷取雙方相關資訊、合約日期、貸款金額及利率。

取得您的資源金鑰和端點

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

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

   

建立自訂 NER 專案

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

使用您在上一個步驟中從樣本資料下載的標記檔案，並將其新增至下列要求的本文。

觸發匯入專案作業

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

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

標頭

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

本文

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

{
    "projectFileVersion": "{API-VERSION}",
    "stringIndexType": "Utf16CodeUnit",
    "metadata": {
        "projectName": "{PROJECT-NAME}",
        "projectKind": "CustomEntityRecognition",
        "description": "Trying out custom NER",
        "language": "{LANGUAGE-CODE}",
        "multilingual": true,
        "storageInputContainerName": "{CONTAINER-NAME}",
        "settings": {}
    },
    "assets": {
    "projectKind": "CustomEntityRecognition",
        "entities": [
            {
                "category": "Entity1"
            },
            {
                "category": "Entity2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 500,
                        "labels": [
                            {
                                "category": "Entity1",
                                "offset": 25,
                                "length": 10
                            },
                            {
                                "category": "Entity2",
                                "offset": 120,
                                "length": 8
                            }
                        ]
                    }
                ]
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 100,
                        "labels": [
                            {
                                "category": "Entity2",
                                "offset": 20,
                                "length": 5
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

傳送 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}

標頭

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

定型您的模型

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

開始定型作業

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

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

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

標頭

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

要求本文

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

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

傳送 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}

標頭

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

回應本文

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

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

部署模型

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

開始部署作業

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

標頭

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

要求本文

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

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

傳送 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}

標頭

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

回應本文

傳送要求之後，您會收到下列回應。 持續輪詢此端點，直到狀態參數變更為「成功」為止。 您應該會收到 200 代碼，指出要求是否成功。

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

擷取自訂實體

部署模型之後，您可以透過預測 API 開始使用該模型來擷取實體。 在稍早下載的範例資料集中，您可以找到一些可在此步驟中使用的測試文件。

提交自訂 NER 工作

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

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

標頭

本文

{
  "displayName": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomEntityRecognition",
      "taskName": "Entity Recognition",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

回應

您會收到 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}

標頭

回應本文

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

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxx-xxxxx-xxxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "EntityRecognitionLROResults",
        "taskName": "Recognize Entities",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "entities": [
                {
                  "category": "Event",
                  "confidenceScore": 0.61,
                  "length": 4,
                  "offset": 18,
                  "text": "trip"
                },
                {
                  "category": "Location",
                  "confidenceScore": 0.82,
                  "length": 7,
                  "offset": 26,
                  "subcategory": "GPE",
                  "text": "Seattle"
                },
                {
                  "category": "DateTime",
                  "confidenceScore": 0.8,
                  "length": 9,
                  "offset": 34,
                  "subcategory": "DateRange",
                  "text": "last week"
                }
              ],
              "id": "1",
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

清除資源

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

標頭

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

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