共用方式為

快速入門：自訂類別 (標準模式) (預覽)

  • 發行項

請遵循本指南，使用 Azure AI 內容安全自訂類別 (標準) RESTAPI 建立您自己的內容類別，以供使用案例使用，並訓練 Azure AI 內容安全，以在新的文字內容中偵測它們。

如需自訂類別的詳細資訊，請參閱自訂類別概念頁面。 有關 API 輸入限制，請參閱「概觀」的輸入要求一節。

重要

僅某些 Azure 區域提供此功能。 請參閱區域可用性 (英文)。

重要

允許足夠的時間進行模型定型

自訂類別訓練的端對端執行可能需要大約 5 小時到 10 小時的時間。 據此規劃審核管道。

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 擁有 Azure 訂用帳戶之後，在 Azure 入口網站中建立 Content Safety 資源，以取得您的金鑰和端點。 輸入您資源的唯一名稱，選取您的訂用帳戶，然後選取資源群組、支援的區域，以及支援的定價層。 然後選取建立。
    • 部署資源需要幾分鐘的時間。 完成後，選取 [移至資源]。 在左側窗格中，於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 將端點和任一索引鍵值複製到暫存位置，以供稍後使用。
  • 此外，建立 AzureBlob 記憶體容器，您將在其中保留定型註解檔案。
  • 已安裝下列其中一項：

備妥您的訓練資料

若要定型自訂類別，您需要代表您想要偵測的類別所出現的範例文字資料。 在本指南中，您可以使用範例資料。 提供的註解檔案包含關於野營/荒野情況生存建議的文字提示。 定型的模型將瞭解如何在新的文字資料中偵測這種類型的內容。

提示

如需建立您自己的資料集的秘訣，請參閱操作指南。

  1. 從 Github 存放庫下載範例文字資料檔案。
  2. 將 .jsonl 檔案上傳到您的 Azure 儲存體帳戶 Blob 容器。 然後將 Blob URL 複製到暫存位置以供稍後使用。

重要

使用者的記憶體帳戶會設定為階層命名空間帳戶，自定義類別不支援此帳戶。 請嘗試改用一般記憶體帳戶。 例如，您的 Blob URL 無法分割成兩個層次，例如 example/example1/，而且應該只有一層。 如需詳細資訊，請參閱檔：Azure Data Lake Storage 階層命名空間 - Azure 儲存體。

授與記憶體存取權

接下來，您必須提供 Content Safety 資源存取權，以從 Azure 儲存體資源讀取。 為 Azure AI Content Safety 實例啟用系統指派的受控識別，並將記憶體 Blob 數據參與者/擁有者的角色指派給身分識別：

重要

只有記憶體 Blob 數據參與者或記憶體 Blob 數據擁有者是有效的角色，才能繼續。

  1. 為 Azure AI 內容安全執行個體啟用受控識別。

    Azure 入口網站啟用受控識別的螢幕擷取畫面。

  2. 將儲存體 Blob 資料參與者/擁有者的角色指派給受控識別。 以下醒目提示的任何角色應該都能正常運作。

    Azure 入口網站中 [新增角色指派] 畫面的螢幕擷取畫面。

    Azure 入口網站中指派角色的螢幕擷取畫面。

    受控識別角色的螢幕擷取畫面。

建立和定型自訂類別

在下列命令中，以您自己的值取代 <your_api_key>、<your_endpoint> 和其他必要參數。 然後在終端機視窗中輸入每個命令並加以執行。

建立新類別版本

curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
            \"categoryName\": \"survival-advice\",
            \"definition\": \"text prompts about survival advice in camping/wilderness situations\",
            \"sampleBlobUrl\": \"https://<your-azure-storage-url>/example-container/survival-advice.jsonl\"
        }"

提示

每次您變更類別名稱、定義或範例時，都會建立新版本。 您可以使用版本號碼回溯至舊版。 請記住此版本號碼，因為下一個步驟訓練自定義類別的URL中將會需要此號碼。

API 要求

欄位 描述 範例值
categoryName 要求所關聯之類別或主題的名稱。 生存建議
definition 類別內容類型的簡短描述。 關於露營/荒野情況生存建議的文字提示
sampleBlobUrl 用來存取範例 JSONL 檔案的 URL，其中包含類別的數據範例。 連結

API 回應

欄位 描述 範例值
categoryName 回應所關聯之類別或主題的名稱。 生存建議
definition 類別內容類型的簡短描述。 關於露營/荒野情況生存建議的文字提示
sampleBlobUrl 用來存取範例 JSONL 檔案的 URL，其中包含類別的數據範例。 連結
sampleBlobSnapshotUrl 範例 JSONL 檔案的快照 URL，可提供特定數據版本的存取權。 快照集 URL
version 類別數據的版本號碼。 1
createdTime 建立類別數據時的時間戳。 2024-10-28T22：06：59.4626988Z
status 類別數據處理的目前狀態。 成功

啟動類別建置流程：

將your_api_key和your_endpoint>取代為您自己的值，並在您從最後一個步驟取得的 URL 中附加版本號碼。 <><允許足夠的時間進行模型定型：自定義類別訓練的端對端執行可能需要大約5小時到10小時的時間。 據此規劃審核管道。 收到回應之後，請將作業識別碼 (稱為 id) 儲存在暫存位置。 在下一節中使用取得狀態 API 擷取組建狀態時，需要此識別碼。

curl -X POST "<your_endpoint>/contentsafety/text/categories/survival-advice:build?api-version=2024-09-15-preview&version={version}" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

API 回應

欄位 描述 範例值
operation id 擷取組建狀態的唯一標識碼 b6c69dc1-2338-484e-85a5b-xxxxxxxxx
status 要求的目前狀態 成功

取得類別組建狀態：

若要擷取狀態，請使用從先前 API 回應取得的 id，並將它放在下列 API 的路徑中。

curl -X GET "<your_endpoint>/contentsafety/text/categories/operations/<id>?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

API 回應

欄位 描述 範例值
operation id 擷取組建狀態的唯一標識碼 b6c69dc1-2338-484e-855b-xxxxxxxxx
status 要求的目前狀態 成功

使用自訂類別分析文字

執行下列命令來分析具有您自訂類別的文字。 將<your_api_key> 和 <your_endpoint> 取代為您自己的值。

curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
            \"text\": \"<Example text to analyze>\",
            \"categoryName\": \"survival-advice\", 
            \"version\": 1
        }"

API 要求

欄位 描述
text 用於類別偵測的文字內容或訊息
categoryName 文字要偵測到的類別名稱
version 類別的版本號碼

API 回應

欄位 描述 範例值
customCategoryAnalysis 包含類別分析結果的物件。 —
detected 指出是否偵測到指定的類別。 false

其他自訂類別作業

請記得將下列佔位元取代為 API 金鑰、端點和特定內容的實際值 (類別名稱、定義等等)。 這些範例可協助您管理帳戶中的自訂類別。

取得自訂類別或特定版本的類別

在終端機視窗中，以您自己的值取代預留位置，並執行下列命令：

curl -X GET "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

列出其最新版本的類別

在終端機視窗中，以您自己的值取代預留位置，並執行下列命令：

curl -X GET "<endpoint>/contentsafety/text/categories?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

刪除自訂類別或特定版本的類別

在終端機視窗中，以您自己的值取代預留位置，並執行下列命令：

curl -X DELETE "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

相關內容