共用方式為

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

  • 發行項

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

在本文中，我們會使用 Language Studio 來示範自訂具名實體辨識 (NER) 的重要概念。 舉例來說，我們將建置自訂 NER 模型，以從貸款合約中擷取相關實體，例如：

  • 合約的日期
  • 借方的姓名、地址、城市和州
  • 貸方的姓名、地址、城市和州
  • 貸款和利息金額

必要條件

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

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

重要

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

如果您有想要使用的預先存在資源，必須將該資源連接到儲存體帳戶。 如需相關資訊，請參閱使用預先存在資源的操作指引。

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

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

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

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

  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 的 [擷取資訊] 區段下，選取 [自訂具名實體辨識]。

    顯示 Language Studio 登陸頁面中自訂 NER 位置的螢幕擷取畫面。

  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 AI 語言資源和 Azure 儲存體帳戶

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

重要

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

如果您有想要使用的預先存在資源，必須將該資源連接到儲存體帳戶。 請參閱建立專案以取得資訊。

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

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

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

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

  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 要求的端點和金鑰

    螢幕擷取畫面，其中顯示 Azure 入口網站中的金鑰和端點頁面

建立自訂 NER 專案

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

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

觸發匯入專案作業

使用下列 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}",
        "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-version {API-VERSION} 您正在呼叫的 API 版本。 此處所使用的版本必須是 URL 中的相同 API 版本。 深入了解其他可用的 API 版本 2022-03-01-preview
projectName {PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
projectKind CustomEntityRecognition 您的專案種類。 CustomEntityRecognition
language {LANGUAGE-CODE} 字串，指定專案中所用文件的語言代碼。 如果您的專案是多語系專案，請選擇大部分文件的語言代碼。 en-us
multilingual true 布林值，可讓您在資料集中具有多種語言的文件，而且當部署模型時，您可以使用任何支援的語言 (不一定包含在定型文件中) 查詢模型。 如需多語系支援的相關資訊，請參閱語言支援。 true
storageInputContainerName {CONTAINER-NAME} 您已上傳文件的 Azure 儲存體容器名稱。 myContainer
entities 陣列，其中包含您在專案中擁有的所有實體類型。 這些是從文件擷取到其中的實體類型。
documents 陣列，其中包含專案中的所有文件，以及每個文件內標記的實體清單。 []
location {DOCUMENT-NAME} 文件在儲存體容器中的位置。 因為所有文件都在容器的根目錄中，所以這應該是文件名稱。 doc1.txt
dataset {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"
}

部署模型

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

標頭

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

機碼 值
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 開始使用該模型來擷取實體。 在稍早下載的範例資料集中，您可以找到一些可在此步驟中使用的測試文件。

提交自訂 NER 工作

使用此 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": "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}"
      }
    }
  ]
}
機碼 預留位置 值 範例
displayName {JOB-NAME} 您的工作名稱。 MyJobName
documents [{},{}] 要對其執行工作的文件清單。 [{},{}]
id {DOC-ID} 文件名稱或識別碼。 doc1
language {LANGUAGE-CODE} 字串，指定文件的語言代碼。 如果未指定此金鑰，則服務將會採用專案建立期間所選取專案的預設語言。 如需支援的語言代碼清單，請參閱語言支援。 en-us
text {DOC-TEXT} 對其執行工作的文件工作。 Lorem ipsum dolor sit amet
tasks 我們需要執行的工作清單。 []
taskName CustomEntityRecognition 工作名稱 CustomEntityRecognition
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 版本。 此處參考的值適用於發行的最新版本。 若要深入了解其他可用的 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-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}
預留位置 值 範例
{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 標頭。

下一步

建立實體擷取模型之後，您可以：

當您開始建立自己的自訂 NER 專案時，請使用「操作說明」文章，以進一步了解標記、定型和取用模型的詳細資訊：