使用本文開始建立自訂文字分類專案，您可以在其中定型自訂模型以進行文字分類。 模型是經過訓練以執行特定任務的 AI 軟體。 在此系統中，模型會分類文字，並從標記的資料中學習以定型。
自訂文字分類支援兩種類型的專案：
- 單一標籤分類：您只能為資料集中的每一個文件指派一個類別。 例如，電影劇本只能歸類為“浪漫”或“喜劇”。
- 多重標籤分類：您可以為資料集中的每一個文件指派多個類別。 例如，電影劇本可以歸類為“喜劇”或“浪漫”和“喜劇”。
在這個快速入門中，你可以利用提供的範例資料集建立多標籤分類，將電影劇本分類為一個或多個類別。 或者，您也可以使用單一標籤分類資料集，將科學論文摘要分類到定義的領域之一。
先決條件
- Azure 訂用帳戶 - 建立免費帳戶。
在 Foundry Tools 資源與 Azure 儲存帳戶中建立新的 Azure 語言
在使用自訂文字分類之前，你需要建立一個語言資源，這會提供你建立專案和開始訓練模型所需的憑證。 你還需要一個 Azure 儲存帳號，可以上傳用於建立模型的資料集。
重要事項
為了快速開始，我們建議依照本文提供的步驟建立一個新的語言資源，這樣你可以同時建立 Azure 語言資源，並建立和/或連接儲存帳號，這比之後做更容易。
如果你有想用的 既有資源 ，就需要把它連接到儲存帳號。
從 Azure 入口網站建立新的資源
前往 Azure 入口網站以在 Foundry Tools 中建立一個新的 Azure Language 資源。
在出現的視窗中，從自訂功能選取 [自訂文字分類和自訂具名實體辨識]。 選取畫面底部的 [繼續建立您的資源]。
使用下列詳細資料建立語言資源。
名稱 必要值 訂用帳戶 您的 Azure 訂用帳戶。 資源群組 將包含您資源的資源群組。 您可以使用現有群組或建立新的群組。 區域 其中一個支援的區域。 例如「美國西部 2」。 名稱 您的資源名稱。 定價層 其中一個支援的定價層。 您可使用免費 (F0) 層來試用服務。 如果您收到訊息指出「您的登入帳戶不是所選儲存體帳戶資源群組的擁有者」，您的帳戶必須先在資源群組上指派擁有者角色，才能建立語言資源。 請連絡您的 Azure 訂閱擁有者以取得協助。
您可以搜尋您的資源群組，並遵循其相關聯訂用帳戶的連結來判斷您的 Azure 訂用帳戶擁有者。 然後：
- 選取 [存取控制 (IAM)] 索引標籤
- 選取 [角色指派]
- 依 [角色: 擁有者] 進行篩選。
在 [自訂文字分類和自訂具名實體辨識] 區段中，選取現有的儲存體帳戶，或選取 [新的儲存體帳戶]。 請注意，這些值可協助您開始使用，但不一定是您想要在生產環境中使用的儲存體帳戶值。 若要避免在建置專案期間的延遲，請連線至與語言資源位於相同區域中的儲存體帳戶。
儲存體帳戶值 建議值 儲存體帳戶名稱 任何名稱 記憶體帳戶類型 標準 LRS 請確定已核取負責任 AI 通知。 選取頁面底部的 [檢閱 + 建立]。
將範例資料上傳至 Blob 容器
建立 Azure 儲存帳號並連接到你的語言資源後，你需要將範例資料集的文件上傳到容器的根目錄。 這些文件可用來訓練您的模型。
開啟 .zip 檔案，然後擷取包含文件的資料夾。
提供的範例資料集包含大約 200 份文件，每份文件都是一部電影的摘要。 每份文件都屬於以下一或多個類別：
- 「懸疑片」
- 「劇情片」
- 「恐怖片」
- 「喜劇」
- 「動作片」
Azure 入口網站
在 Azure 入口網站中，導覽到你建立的儲存帳號，選擇儲存 帳號 ，並在 「篩選」欄位中輸入儲存帳號名稱。
如果您的資源群組未顯示，請確定 [訂用帳戶等於] 篩選已設定為 [全部]。
在儲存體帳戶中，從左側功能表選取位於 [資料儲存體] 下方的 [容器]。 在出現的畫面上，選取 [+ 容器]。 為容器指定名稱 example-data，並保留預設的公用存取層級。
容器建立完成後，選擇它。 然後選取 [上傳] 按鈕，以選取您稍早下載的
.txt和.json檔案。
取得您的資源金鑰和端點
前往您位於 Azure 入口網站的資源概觀頁面
在左側功能表中，選取 [金鑰和端點]。 端點和金鑰用於 API 請求。
建立自訂分類專案
設定好資源和儲存體容器之後，請建立新的自訂文字分類專案。 專案是一個工作區域，用於根據您的資料建置自訂 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 的版本。 所引用的值為最新版本。 深入了解其他可用的 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版本 | {API-VERSION} |
您所呼叫 API 的版本。 此處所使用的版本必須是 URL 中的相同 API 版本。 深入了解其他可用的 API 版本 | 2022-05-01 |
| projectName | {PROJECT-NAME} |
您專案的名稱。 此值區分大小寫。 | myProject |
| 專案類型 | 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值是字串，而不是布林值。
取得匯入作業狀態
使用下列 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 |
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 的版本。 所引用的值為最新版本。 深入了解其他可用的 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 的版本。 所引用的值為最新版本。 深入了解其他可用的 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 的版本。 所引用的值為最新版本。 深入了解其他可用的 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 開始使用該模型來分類文字。 在稍早下載的範例資料集中，您可以找到一些可在此步驟中使用的測試文件。
提交自訂文字分類工作
使用此 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": "Classifying documents",
"analysisInput": {
"documents": [
{
"id": "1",
"language": "{LANGUAGE-CODE}",
"text": "Text1"
},
{
"id": "2",
"language": "{LANGUAGE-CODE}",
"text": "Text2"
}
]
},
"tasks": [
{
"kind": "CustomMultiLabelClassification",
"taskName": "Multi Label Classification",
"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 |
CustomMultiLabelClassification | 工作名稱 | CustomMultiLabelClassification |
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-xxxxxx-xxxxx-xxxx",
"lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
"status": "succeeded",
"tasks": {
"completed": 1,
"failed": 0,
"inProgress": 0,
"total": 1,
"items": [
{
"kind": "customMultiClassificationTasks",
"taskName": "Classify documents",
"lastUpdateDateTime": "2020-10-01T15:01:03Z",
"status": "succeeded",
"results": {
"documents": [
{
"id": "{DOC-ID}",
"classes": [
{
"category": "Class_1",
"confidenceScore": 0.0551877357
}
],
"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 |
headers
使用下列標頭來驗證您的要求。
| Key | 值 |
|---|---|
| Ocp-Apim-Subscription-Key | 資源的金鑰。 用於驗證 API 要求。 |
一旦你發送 API 請求，就會收到 202 一個表示成功的回應，這表示你的專案會被刪除。 成功呼叫的結果是用於檢查作業狀態的 Operation-Location 標頭。
後續步驟
建立自訂文本分類模型後，你可以：
當您開始建立自己的自訂文字分類專案時，請使用「操作說明」文章，以深入了解如何開發模型的細節：