共用方式為

如何建立自訂文字分類專案

使用本文來了解如何設定從自訂文字分類開始並建立專案的需求。

先決條件

在開始使用自訂文字分類之前，你需要：

建立語言資源

在開始使用自訂文字分類之前，你需要使用 Foundry Tools 中的 Azure 語言資源。 我們建議你建立語言資源，並在 Azure 入口網站中連結一個儲存帳號。 在 Azure 入口網站中建立資源可讓您同時建立 Azure 儲存體帳戶，並預先設定所有必要的許可權。 你也可以繼續閱讀本文，了解如何使用既有資源，並設定它以支援自訂文本分類。

你還需要一個 Azure 儲存帳號，才能上傳 .txt 用來訓練模型分類文字的文件。

附註

  • 您必須在資源群組上指派擁有者角色，才能建立語言資源。
  • 如果您連結了一個既有的儲存帳號，應指派一個 擁有者 角色給它。

建立語言資源並連線儲存體帳戶

附註

一旦與 Azure 語言資源連結，你不應該把儲存帳號移到其他資源群組或訂閱。

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

  1. 前往 Azure 入口網站以在 Foundry Tools 中建立一個新的 Azure Language 資源。

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

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

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

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

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

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

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

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

    儲存體帳戶值 建議值
    儲存體帳戶名稱 任何名稱
    記憶體帳戶類型 標準 LRS

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

附註

  • 將儲存帳號與語言資源連結的過程是不可逆的——之後無法斷開。
  • 您只能將語言資源連線至一個儲存體帳戶。

使用預先存在的語言資源

需求 描述
區域 請確定您已在下列其中一個支援的區域中佈建現有的資源。 如果你沒有資源，就需要在支援區域建立一個新的資源。
定價層 您資源的定價層。
受控識別 請確定已啟用資源的受控識別設定。 否則，請閱讀下一節。

若要使用自訂文字分類，您必須先建立 Azure 儲存體帳戶 (如果您還沒有一個帳戶)。

為資源啟用身分識別管理

您的語言資源必須具有身分識別管理，才能使用 Azure 入口網站加以啟用：

  1. 移至您的語言資源
  2. 從左側功能表的 [資源管理] 區段底下，選取 [身分識別]
  3. 從 [系統指派] 索引標籤中，請務必將 [狀態] 設定為 [開啟]

啟用自訂文字分類功能

請務必從 Azure 入口網站啟用自訂文字分類/自訂具名實體辨識功能。

  1. 移至您在 Azure 入口網站中的語言資源
  2. 從左側功能表的 [資源管理] 區段底下，選取 [功能]
  3. 啟用自訂文字分類/自訂具名實體辨識功能
  4. 連線您的儲存體帳戶
  5. 選取 [套用]

重要事項

  • 請確定您的語言資源在您連線的儲存體帳戶上獲指派儲存體 Blob 資料參與者角色。

設定 Azure Language 資源與儲存帳戶的角色

使用下列步驟來設定語言資源和儲存體帳戶的必要角色。

顯示如何在 Azure 入口網站中設定角色的動畫影像。

Foundry Tools 資源中的 Azure 語言角色

  1. 移至您在 Azure 入口網站中的儲存體帳戶或語言資源。

  2. 選取左窗格中的 [存取控制][IAM ]。

  3. 選取 [新增] 以新增角色指派，然後選擇您帳戶的適當角色。

    您應該在語言資源上指派擁有者或參與者角色。

  4. 在 [存取權指派對象為] 內，選取 [使用者、群組或服務主體]

  5. 選取 [+選取成員]

  6. 選取您的使用者名稱。 您可以在 [選取] 欄位中搜尋使用者名稱。 針對所有角色重複此操作。

  7. 針對需要存取此資源的所有使用者帳戶重複這些步驟。

儲存體帳戶的角色

  1. 移至您在 Azure 入口網站中的儲存體帳戶頁面。
  2. 選取左窗格中的 [存取控制][IAM ]。
  3. 選取 [新增] 以新增角色指派，然後選擇儲存體帳戶上的儲存體 Blob 資料參與者角色。
  4. 在 [存取權指派對象為]中，選取 [受控識別]。
  5. 選取 [+選取成員]
  6. 選取您的訂用帳戶，然後選取 [語言] 作為受控識別。 您可以在 [選取] 欄位中搜尋使用者名稱。

重要事項

如果您使用虛擬網路或私人端點，請務必在 Azure 入口網站中選取 [允許可信服務清單上的 Azure 服務加存取此儲存體帳戶]。

為您的儲存體帳戶啟用 CORS

啟用跨原始來源資源共用 (CORS) 時，請務必允許 (GET、PUT、DELETE) 方法。 將允許的來源欄位設定為 https://language.cognitive.azure.com。 透過將 * 新增至允許的標頭值以允許所有標頭，並將最長存留期設定為 500。

螢幕擷取畫面：顯示如何在儲存體帳戶中使用 CORS。

建立自訂的文字分類專案（REST API）

設定好資源和儲存體容器之後，請建立新的自訂文字分類專案。 專案是一個工作區域，可根據您的資料建置自訂 AI 模型。 您的專案只能由您和其他有權存取正在使用的 Azure 資源的人存取。 如果你標註了資料，可以將資料 匯入 以開始。

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

附註

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

使用下列 URL、標頭和 JSON 本文來建立 PATCH 要求，以建立您的專案。

要求 URL

使用下列 URL 來建立專案。 以您自己的值取代預留位置值。

{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

headers

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

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

body

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

{
  "projectName": "{PROJECT-NAME}",
  "language": "{LANGUAGE-CODE}",
  "projectKind": "customMultiLabelClassification",
  "description": "Project description",
  "multilingual": "True",
  "storageInputContainerName": "{CONTAINER-NAME}"
}
Key 預留位置 值 範例
projectName {PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
語言 {LANGUAGE-CODE} 字串，指定專案中所用文件的語言代碼。 如果你的專案是多語言專案，請選擇大多數文件的語言代碼。 若要深入了解支援的語言代碼，請參閱語言支援。 en-us
projectKind customMultiLabelClassification 您的專案種類。 customMultiLabelClassification
多語系 true 布林值，可讓您在資料集中具有多種語言的文件，而且當部署模型時，您可以使用任何支援的語言 (不一定包含在定型文件中) 查詢模型。 若要深入了解多語系支援，請參閱語言支援。 true
storageInputContainerName {CONTAINER-NAME} 你上傳文件的 Azure 儲存容器名稱。 myContainer

此要求會傳回 201 回應，這表示專案已建立。

如果下列狀況，此要求會傳回錯誤：

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

匯入自訂的文字分類專案（REST 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

headers

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

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

body

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

取得專案細節（REST API）

若要取得自訂文字分類專案詳細資料，請使用下列 URL 和標頭提交 GET 要求。 以您自己的值取代預留位置值。

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}?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 要求。

回應本文

一旦你發送請求，就會收到以下回覆。

{
  "createdDateTime": "2022-04-23T13:39:09.384Z",
  "lastModifiedDateTime": "2022-04-23T13:39:09.384Z",
  "lastTrainedDateTime": "2022-04-23T13:39:09.384Z",
  "lastDeployedDateTime": "2022-04-23T13:39:09.384Z",
  "projectKind": "customSingleLabelClassification",
  "storageInputContainerName": "{CONTAINER-NAME}",
  "projectName": "{PROJECT-NAME}",
  "multilingual": true,
  "description": "Project description",
  "language": "{LANGUAGE-CODE}"
}
值 暫存區 描述 範例
projectKind customSingleLabelClassification 您的專案種類。 此值可以是 customSingleLabelClassification 或 customMultiLabelClassification。
storageInputContainerName {CONTAINER-NAME} 你上傳文件的 Azure 儲存容器名稱。 myContainer
projectName {PROJECT-NAME} 您專案的名稱。 此值區分大小寫。 myProject
multilingual 布林值，可讓您在資料集中具有多種語言的文件。 部署模型時，您可以以任何支援的語言 (不一定要包含在定型文件中) 查詢模型。 如需多語系支援的詳細資訊，請參閱語言支援。 true
language {LANGUAGE-CODE} 字串，指定專案中所用文件的語言代碼。 如果您的專案是多語言專案，請選擇大部分文件的語言代碼。 若要深入了解支援的語言代碼，請參閱語言支援。 en-us

一旦你發送 API 請求，就會收到 200 一個表示成功的回應，以及包含專案細節的 JSON 回應內容。

刪除專案（REST API）

當您不再需要專案時，可以使用下列 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

headers

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

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

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

後續步驟

  • 你應該規劃用來標註資料的 專案架構 。

  • 建立專案後，您可以開始 標記資料。 標籤有助於指導你的文本分類模型如何解讀文本，並用於訓練與評估。

  • Last updated on