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

本指南提供使用自訂命名實體識別（NER）搭配 Microsoft Foundry 或 REST API 的逐步指導說明。 NER 可讓您偵測非結構化文字中的實體並對其進行分類，例如人員、地點、組織和數字。透過自訂 NER，您可以訓練模型來識別特定於您業務的實體，並根據需求的變化進行調整。

若要開始使用，會提供範例貸款合約作為資料集，以建置自訂 NER 模型並擷取下列重要實體：

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

附註

如果你已經在 Foundry 工具中使用了 Azure 語言或多服務資源——無論是單獨使用還是透過 Language Studio 使用——你都可以繼續在 Microsoft Foundry 入口網站中使用這些現有的語言資源。欲了解更多資訊，請參閱 Foundry 入口網站中的「如何使用 Foundry 工具」。

先決條件

Azure 訂用帳戶。如果您沒有帳戶，您可以免費建立一個。
必要權限。請確定建立帳戶和項目的人員已獲指派為訂用帳戶層級的 Azure AI 帳戶擁有者角色。或者，在訂用帳戶範圍擁有 [參與者] 或 [認知服務參與者] 角色也符合這項需求。如需詳細資訊，請參閱角色型訪問控制（RBAC）。
一個帶有儲存帳號的語言資源。在 選擇附加功能 頁面，選擇 自訂文字分類、自訂命名實體識別、自訂情感分析及健康自訂文本分析 ，將所需儲存帳號連結至此資源：

附註

您需要在資源群組中指派擁有者角色，才能建立語言資源。
如果您將連線現有的儲存體帳戶，則應該已為其指派擁有者角色。
一旦連結到 Azure 語言資源，不要把儲存帳號移到其他資源群組或訂閱。

在 Foundry 中創建的鑄造廠專案。欲了解更多資訊， 請參閱「建立鑄造廠專案」。
上傳至儲存容器的自訂 NER 資料集。自訂具名實體辨識（NER）資料集是用來訓練自訂 NER 模型的標記文字文件集合。您可以下載本快速入門的範例資料集。來源語言為英文。

步驟 1：設定所需的角色、權限和設定

讓我們從配置您的資源開始。

啟用自訂具名實體辨識功能

請確定已在 Azure 入口網站中啟用自訂文字分類/自訂具名實體辨識功能。

在 Azure 入口網站中導覽你的語言資源。
從左側功能表的 [資源管理] 區段下，選取 [功能]。
請確定已啟用 自訂文字分類/自訂具名實體辨識 功能。
如果您未指派您的儲存體帳戶，請選取並連線您的儲存體帳戶。
選取 ，然後套用。

為您的語言資源新增必要角色

在 Azure 入口網站的語言資源頁面，選擇左側窗格的存取控制（IAM）。
選擇新增以 新增角色分配，並在你的語言資源中新增 認知服務語言擁有者 或認知 服務貢獻 者角色分配。
在 [存取權指派對象為] 內，選取 [使用者、群組或服務主體]。
選取 [選取成員]。
選取 您的使用者名稱。您可以在 [選取] 欄位中搜尋使用者名稱。對所有角色重複此步驟。
針對需要存取此資源的所有使用者帳戶重複這些步驟。

新增儲存體帳戶的必要角色

移至 Azure 入口網站中的儲存體帳戶頁面。
在左窗格中選取 [存取控制 (IAM)]。
選取 [新增] 以新增角色指派，然後選擇儲存體帳戶上的儲存體 Blob 資料參與者角色。
在 [指派存取權] 中，選取 [受控識別]。
選取 [選取成員]。
選取您的訂用帳戶，並 選取 [語言] 作為受控識別。您可以在選取欄位中搜尋您的語言資源。

新增必要的使用者角色

重要事項

如果您略過此步驟，當您嘗試連線到自訂專案時，您會收到 403 錯誤。即使您是儲存體帳戶的擁有者，您目前的使用者必須仍擁有此角色，才能存取儲存體帳戶 Blob 資料。

移至 Azure 入口網站中的儲存體帳戶頁面。
在左窗格中選取 [存取控制 (IAM)]。
選取 [新增] 以新增角色指派，然後選擇儲存體帳戶上的儲存體 Blob 資料參與者角色。
在 [存取權指派對象為] 內，選取 [使用者、群組或服務主體]。
選取 [選取成員]。
選取您的使用者。您可以在 [選取] 欄位中搜尋使用者名稱。

重要事項

如果您有防火牆、虛擬網路或私人端點，請務必在 Azure 入口網站的 [網路] 索引標籤下選取受信任服務清單上的 [允許 Azure 服務] 存取此儲存體帳戶。

允許 Foundry 啟用 Azure 服務的截圖。

步驟 2：將資料集上傳至儲存容器

接下來，讓我們新增一個容器，並將資料集檔案直接上傳到儲存容器的根目錄。這些文件可用來訓練您的模型。

將容器新增至與您的語言資源相關聯的儲存體帳戶。如需詳細資訊， 請參閱建立容器。
從 GitHub 下載樣本資料集。提供的範例資料集包含 20 個貸款合約：
- 每個合約皆包含兩方：貸方和借方。
- 您提取以下相關信息：雙方、協議日期、貸款金額和利率。
開啟 .zip 檔案，然後擷取包含文件的資料夾。
前往鑄造廠。
如果您尚未登入，入口網站會提示您使用您的 Azure 認證來執行此動作。
登入後，請進入您現有的 Foundry 專案，進行此快速入門。
從左側導覽功能表中選取 管理中心 。
從 管理中心功能表的 Hub 區段中選取已連線的資源。
接下來，選擇為您設定為連線資源的工作區 Blob 儲存體。
在工作空間的 Blob 儲存體中，選擇 View in Azure portal。
在 Blob 儲存體的 [AzurePortal] 頁面上，從頂端功能表中選取 [上傳]。接下來，選擇您之前下載的 .txt 和 .json 文件。最後，選取 [上傳] 按鈕，將檔案新增至您的容器。

現在所需的 Azure 資源已在 Azure 入口網站中配置並配置好，讓我們利用這些資源在 Foundry 中建立一個微調的自訂命名實體識別（NER）模型。

步驟 3：連結你的語言資源

接著我們建立與你的語言資源的連結，讓 Foundry 能安全存取。此連線提供安全的身分管理和身份驗證，以及對資料的受控和隔離存取。

返回鑄造廠。
存取您現有的 Foundry 專案，快速入門。
從左側導覽功能表中選取 管理中心 。
從 管理中心功能表的 Hub 區段中選取已連線的資源。
在主視窗中，選取 [+ 新增連線 ] 按鈕。
從「新增外部資產連線」視窗選擇語言。
選取 [ 新增連線]，然後選取 [關閉]。

步驟 4：微調您的自訂 NER 模型

現在，我們已準備好建立自訂 NER 微調模型。

從 管理中心 功能表的 [專案] 區段中，選取 [移至專案]。
從概觀功能表中，選取微調。
從主視窗中，選取 [AI 服務微調] 索引標籤，然後選取 [+ 微調] 按鈕。
從 [建立服務微調] 視窗中，選擇 [自訂具名實體辨識] 索引標籤，然後選取 [下一步]。
在 建立服務微調工作 視窗中，完成欄位，如下所示：
- 互聯服務。你的語言資源名稱預設已經出現在這個欄位裡。如果沒有，請從下拉式選單中新增它。
- 名稱. 為您的微調任務專案給予名稱。
- 語言。英文設定為預設值，且已顯示在欄位中。
- 描述。您可以選擇性地提供說明，或將此欄位留空。
- Blob 存放區容器。從步驟 2 中選取工作區 Blob 儲存體容器，然後選擇 [ 連線 ] 按鈕。
最後，選取 [建立] 按鈕。建立作業可能需要幾分鐘的時間才能完成。

步驟 5：訓練您的模型

Foundry 的微調工作流程截圖。

從 Getting Started （開始使用 ）功能表中，選擇 Manage data （管理資料）。在 [ 新增定型和測試的資料 ] 視窗中，您會看到先前上傳至 Azure Blob 儲存體容器的範例資料。
接下來，從 [開始使用] 功能表中，選取 [訓練模型]。
選擇 [+ 訓練模型] 按鈕。當 [訓練新模型] 視窗出現時，請輸入新模型的名稱，並保留預設值。選取下一步按鈕。
在 [ 定型新模型 ] 視窗中，保留預設值 [ 自動從定型資料分割測試集 ] 啟用，並將建議的百分比設定為定型資料的 80%，測試資料的建議百分比設定為 20%。
檢閱您的模型設定，然後 選取建立按鈕 。
定型模型之後，您可以從 [入門] 功能表中選取 [評估模型]。 您可以從 「評估您的模型」 視窗中選取您的模型，並在必要時進行改進。

步驟 6：部署您的模型

訓練模型後，您通常可檢閱其評估詳細資料。在這個快速入門階段，你可以直接部署模型，並在 Azure 語言遊玩場中測試，或呼叫預測 API。不過，如果您願意，您可以花點時間從左側功能表中選取 [評估您的模型]，並探索模型的深入遙測。請完成以下步驟，在 Foundry 中部署您的模型。

從左側功能表中選取 [部署模型]。
接下來，從 [部署您的模型] 視窗中選取 [➕部署訓練模型]。
確定已選取 [建立新的部署] 按鈕。
完成 [部署已訓練模型] 視窗欄位：
- 部署名稱。為您的模型命名。
- 指派模型。從下拉式功能表中選取您的訓練模型。
- 區域。從下拉式功能表中選取區域。
最後，選取 [建立] 按鈕。部署模型可能需要幾分鐘的時間。
成功部署之後，您可以在 [部署您的模型] 頁面上檢視模型的部署狀態。顯示的到期日會指出已部署模型變得無法用於預測工作的日期。此日期通常是部署訓練設定後的 18 個月。

步驟七：嘗試 Azure 語言遊樂場

語言遊樂場提供沙箱，可在將微調模型部署至生產環境之前測試和設定，而不需要撰寫程式碼。

從頂端功能表列中，選取 [在 Playground 中試用]。
在 Azure 語言遊樂場視窗中，選擇 自訂命名實體識別 圖塊。
在 [組態 ] 區段中，從下拉式功能表中選取您的 專案名稱 和 部署名稱 。
輸入實體，然後選取執行。
您可以在 「詳細資料」 視窗中評估結果。

沒錯，恭喜！

在此快速入門中，您已建立微調的自訂 NER 模型、將其部署到 Foundry，並在 Azure Language 遊樂場測試您的模型。

清除資源

如果你不再需要你的專案，可以從 Foundry 刪除它。

前往 Foundry 首頁。除非您已經完成此步驟且目前的會話仍然有效，否則請登入以開始驗證過程。
從 「繼續用 Foundry 建構」中選擇你想刪除的專案。
選取 [管理中心]。
選取 [刪除專案]。

若要刪除中心及其所有專案：

導覽至「概觀」標籤中的「中樞」區段。
在右側，選取 [ 刪除中樞]。
鏈接會開啟 Azure 入口網站，讓您在那裡刪除集線器。

先決條件

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

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

在使用自訂命名實體識別（NER）之前，你需要建立一個語言資源，這會提供你建立專案並開始訓練模型所需的憑證。您也需要 Azure 儲存體帳戶，您可以在其中上傳用於建置模型的資料集。

重要事項

為了快速開始，我們建議建立一個新的語言資源。請依照本文提供的步驟，建立 Azure 語言資源，同時建立及/或連接儲存帳號。同時創建兩者比稍後再做更容易。

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

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

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

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

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

附註

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

在 [自訂文字分類和自訂具名實體辨識] 區段中，選取現有的儲存體帳戶，或選取 [新的儲存體帳戶]。這些數值是幫助你入門的，不一定是你想在生產環境中使用的儲存帳號數值。為了避免建置專案延遲，請連接與語言資源相同區域的儲存帳號。

儲存體帳戶值建議值

儲存體帳戶名稱任何名稱

記憶體帳戶類型標準本地冗餘儲存（LRS）
請確定已核取負責任 AI 通知。選取頁面底部的 [檢閱 + 建立] 按鈕，然後選取 [建立]。

儲存體帳戶值	建議值
儲存體帳戶名稱	任何名稱
記憶體帳戶類型	標準本地冗餘儲存（LRS）

將範例資料上傳至 Blob 容器

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

從 GitHub 下載樣本資料集。
開啟 .zip 檔案，然後擷取包含文件的資料夾。
在 Azure 入口網站中，瀏覽至您建立的儲存體帳戶，然後加以選取。
在儲存體帳戶中，從左側功能表選取位於 [資料儲存體] 下方的 [容器]。在出現的畫面上，選取 [+ 容器]。為容器指定名稱 example-data，並保留預設的公用存取層級。
容器建立完成後，選擇它。然後選取 [上傳] 按鈕，以選取您稍早下載的 .txt 和 .json 檔案。

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

取得您的資源金鑰和端點

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

建立自訂 NER 專案

設定好資源和儲存體帳戶之後，請建立新的自訂 NER 專案。專案是一個工作區域，用於根據您的資料建置自訂 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 版本。此處參考的值適用於發行的最新版本。欲了解更多資訊，請參閱模型生命週期。	`2022-05-01`

headers

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

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

body

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

Key	預留位置	值	範例
`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 版本。所引用的值為最新版本。欲了解更多資訊，請參閱模型生命週期。	`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 版本。所引用的值為最新版本。欲了解更多資訊，請參閱模型生命週期。	`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"
}

部署模型

一般來說，在定型模型之後，您可以檢閱其評估詳細資料，並視需要加以改善。在本快速入門中，您只需部署模型，並使其可供您在 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 版本。所引用的值為最新版本。欲了解更多資訊，請參閱模型生命週期。	`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 版本。所引用的值為最新版本。欲了解更多資訊，請參閱模型生命週期。	`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 開始使用該模型來擷取實體。在先前下載的範例資料集中，您可以找到一些可在此步驟中使用的測試文件。

提交自訂 NER 工作

使用此 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": "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}"
      }
    }
  ]
}

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`	`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 版本。所引用的值為最新版本。欲了解更多資訊，請參閱模型生命週期。	`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-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 版本。所引用的值為最新版本。欲了解更多資訊，請參閱模型生命週期。	`2022-05-01`

headers

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

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

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

建立實體擷取模型之後，您可以使用執行時期 API 來擷取實體。

當您建立自己的自訂 NER 專案時，請使用我們的操作說明文章，更詳細地了解標記、訓練和使用模型的詳細過程。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-18

共用方式為

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

先決條件

步驟 1：設定所需的角色、權限和設定

啟用自訂具名實體辨識功能

為您的語言資源新增必要角色

新增儲存體帳戶的必要角色

新增必要的使用者角色

步驟 2：將資料集上傳至儲存容器

步驟 3：連結你的語言資源

步驟 4：微調您的自訂 NER 模型

步驟 5：訓練您的模型

步驟 6：部署您的模型

步驟七：嘗試 Azure 語言遊樂場

清除資源

先決條件

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

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

將範例資料上傳至 Blob 容器

取得您的資源金鑰和端點

建立自訂 NER 專案

觸發匯入專案作業

headers

body

取得匯入作業狀態

要求 URL

headers

定型模型

開始定型作業

headers

請求主體

取得定型作業狀態

要求 URL

headers

回應本文

部署模型

開始部署作業

headers

請求主體

取得部署作業狀態

headers

回應本文

擷取自訂實體

提交自訂 NER 工作

headers

body

回應

取得工作結果

headers

回應本文

清除資源

headers

相關內容

意見反應

其他資源