本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 註釋
透過將自訂實體類型與訓練文件中發生的位置建立關聯，在內容中標記實體的註釋。
透過提交註釋與您的文件，您可以提高模型的準確性。使用註釋，您不僅提供您要尋找的實體位置，還為您要尋找的自訂實體提供更準確的內容。
例如，如果您使用實體類型 JUDGE 來搜尋名稱 John Johnson，提供註釋可能有助於模型了解您要尋找的人員是判斷者。如果它可以使用內容，則 Amazon Comprehend 找不到名為 John Johnson 且為律師或證人的人員。如果沒有提供註釋，Amazon Comprehend 將建立自己的註釋版本，但只有在包含判斷時才會有效。提供您自己的註釋可能有助於實現更好的結果，並在擷取自訂實體時產生能夠更好地利用內容的模型。
**Topics**
+ [註釋數量下限](#prep-training-data-ann)
+ [註釋最佳實務](#cer-annotation-best-practices)
+ [純文字註釋檔案](cer-annotation-csv.md)
+ [PDF 註釋檔案](cer-annotation-manifest.md)
+ [註釋 PDF 檔案](cer-annotation-pdf.md)
## 註釋數量下限
訓練模型所需的輸入文件和註釋數量下限取決於註釋的類型。
**PDF 註釋**
若要建立模型來分析影像檔案、PDFs或 Word 文件，請使用 PDF 註釋訓練您的辨識器。對於 PDF 註釋，提供每個實體至少 250 個輸入文件和至少 100 個註釋。
如果您提供測試資料集，則測試資料必須至少包含建立請求中指定之每個實體類型的一個註釋。
**純文字註釋**
若要建立模型來分析文字文件，您可以使用純文字註釋來訓練辨識器。
對於純文字註釋，提供每個實體至少三個註釋的輸入文件和至少 25 個註釋。如果您提供總計少於 50 個註釋，Amazon Comprehend 會保留超過 10% 的輸入文件來測試模型 （除非您在訓練請求中提供測試資料集）。別忘了，文件 corpus 大小下限為 5 KB。
如果您的輸入只包含一些訓練文件，您可能會遇到訓練輸入資料包含提及其中一個實體的文件太少的錯誤。使用提及實體的其他文件再次提交任務。
如果您提供測試資料集，則測試資料必須至少包含建立請求中指定之每個實體類型的一個註釋。
如需如何使用小型資料集對模型進行基準測試的範例，請參閱 AWS 部落格網站上的 [Amazon Comprehend 發佈自訂實體辨識的較低註釋限制](https://aws.amazon.com/blogs/machine-learning/amazon-comprehend-announces-lower-annotation-limits-for-custom-entity-recognition/)。
## 註釋最佳實務
使用註釋時，需要考慮一些事項才能獲得最佳結果，包括：
+ 請謹慎標註您的資料，並確認您已標註每個提到的實體。不精確的註釋可能會導致結果不佳。
+ 輸入資料不應包含重複項目，例如您要註釋的 PDF 複本。存在重複的樣本可能會導致測試集污染，並可能對訓練程序、模型指標和模型行為產生負面影響。
+ 請確保您的所有文件都已加上註釋，而且沒有註釋的文件是由於缺乏合法實體，而不是由於疏忽。例如，如果您的文件顯示「J Doe 已擔任工程師 14 年」，您也應該提供「J Doe」和「John Doe」的註釋。否則，模型會混淆，並可能導致模型無法將 "J Doe" 識別為 ENGINEER。這在相同文件和跨文件之間應該是一致的。
+ 一般而言，更多註釋可產生更好的結果。
+ 您可以使用[最少數量](guidelines-and-limits.md#limits-custom-entity-recognition)的文件和註釋來訓練模型，但新增資料通常會改善模型。我們建議將標註的資料量增加 10%，以提高模型的準確性。您可以在保持不變且可由不同模型版本測試的測試資料集上執行推論。然後，您可以比較連續模型版本的指標。
+ 盡可能提供類似實際使用案例的文件。應避免使用重複模式合成資料。輸入資料應盡可能多樣化，以避免過度擬合，並協助基礎模型更全面地概括真實的範例。
+ 文件在單字計數方面應該具有多樣性，這一點很重要。例如，如果訓練資料中的所有文件都很短，則產生的模型可能無法預測較長文件中的實體。
+ 嘗試並提供與實際偵測自訂實體時預期的訓練相同的資料分佈 （推論時間）。例如，在推論時間，如果您預期將沒有實體的文件傳送給我們，這也應該是訓練文件集的一部分。
如需其他建議，請參閱[改善自訂實體辨識器效能](https://docs.aws.amazon.com/comprehend/latest/dg/cer-metrics.html#cer-performance)。
# 純文字註釋檔案
對於純文字註釋，您可以建立包含註釋清單的逗號分隔值 (CSV) 檔案。如果您的訓練檔案輸入格式是**每行一個文件**，CSV 檔案必須包含下列資料欄。
| 檔案 | 折線圖 | 開始偏移 | 結束位移 | Type |
| --- | --- | --- | --- | --- |
| 包含文件的檔案名稱。例如，如果其中一個文件檔案位於 `s3://my-S3-bucket/test-files/documents.txt`，則`File`資料欄中的值將為 `documents.txt`。您必須包含副檔名 （在此案例中為 '`.txt`') 做為檔案名稱的一部分。 | 包含實體的行號。如果您的輸入格式是每個檔案一個文件，請省略此欄。 | 輸入文字中顯示實體開始位置的字元位移 （相對於行開頭）。第一個字元位於位置 0。 | 輸入文字中顯示實體結束位置的字元位移。 | 客戶定義的實體類型。實體類型必須是大寫、底線分隔的字串。建議使用描述性實體類型，例如 `MANAGER`、 `SENIOR_MANAGER`或 `PRODUCT_CODE`。每個模型最多可訓練 25 種實體類型。 |
如果您的訓練檔案輸入格式是**每個檔案一個文件**，則省略行號欄，而**開始位**移和**結束位移**值是實體從文件開頭的位移。
下列範例適用於每行一個文件。檔案`documents.txt`包含四行 （列 0、1、2 和 3)：
```
Diego Ramirez is an engineer in the high tech industry.
Emilio Johnson has been an engineer for 14 years.
J Doe is a judge on the Washington Supreme Court.
Our latest new employee, Mateo Jackson, has been a manager in the industry for 4 years.
```
具有註釋清單的 CSV 檔案如下所示：
```
File, Line, Begin Offset, End Offset, Type
documents.txt, 0, 0, 13, ENGINEER
documents.txt, 1, 0, 14, ENGINEER
documents.txt, 3, 25, 38, MANAGER
```
**注意**
在註釋檔案中，包含實體的行號開頭為行 0。在此範例中，CSV 檔案不包含第 2 行的項目，因為 的第 2 行中沒有實體`documents.txt`。
**建立資料檔案**
請務必將註釋放入正確設定的 CSV 檔案中，以降低發生錯誤的風險。若要手動設定 CSV 檔案，下列項目必須是 true：
+ 必須明確指定 UTF-8 編碼，即使它在大多數情況下用作預設值。
+ 第一行包含欄標頭：`File`、 `Line`（選用）`Begin Offset`、、`End Offset`、`Type`。
強烈建議您以程式設計方式產生 CSV 輸入檔案，以避免潛在問題。
下列範例使用 Python 為先前顯示的註釋產生 CSV：
```
import csv
with open("./annotations/annotations.csv", "w", encoding="utf-8") as csv_file:
csv_writer = csv.writer(csv_file)
csv_writer.writerow(["File", "Line", "Begin Offset", "End Offset", "Type"])
csv_writer.writerow(["documents.txt", 0, 0, 11, "ENGINEER"])
csv_writer.writerow(["documents.txt", 1, 0, 5, "ENGINEER"])
csv_writer.writerow(["documents.txt", 3, 25, 30, "MANAGER"])
```
# PDF 註釋檔案
對於 PDF 註釋，您可以使用 SageMaker AI Ground Truth 在擴增的資訊清單檔案中建立標記的資料集。Ground Truth 是一種資料標記服務，可協助您 （或您採用的人力） 建置機器學習模型的訓練資料集。Amazon Comprehend 接受擴增資訊清單檔案作為自訂模型的訓練資料。您可以使用 Amazon Comprehend 主控台或 [CreateEntityRecognizer](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_CreateEntityRecognizer.html) API 動作，在建立自訂實體辨識器時提供這些檔案。
您可以使用 Ground Truth 內建任務類型命名實體辨識，建立標籤任務，讓工作者識別文字中的實體。若要進一步了解，請參閱《*Amazon SageMaker AI 開發人員指南*》中的[具名實體辨識](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-named-entity-recg.html#sms-creating-ner-console)。若要進一步了解 Amazon SageMaker Ground Truth，請參閱[使用 Amazon SageMaker AI Ground Truth 來標記資料](https://docs.aws.amazon.com/sagemaker/latest/dg/sms.html)。
**注意**
使用 Ground Truth，您可以定義重疊的標籤 （與多個標籤相關聯的文字）。不過，Amazon Comprehend 實體辨識不支援重疊的標籤。
增強的資訊清單檔案採用 JSON 行格式。在這些檔案中，每一行都是完整的 JSON 物件，其中包含訓練文件及其相關聯的標籤。下列範例是擴增資訊清單檔案，可訓練實體辨識器偵測文字中提及之個人的專業：
```
{"source":"Diego Ramirez is an engineer in the high tech industry.","NamedEntityRecognitionDemo":{"annotations":{"entities":[{"endOffset":13,"startOffset":0,"label":"ENGINEER"}],"labels":[{"label":"ENGINEER"}]}},"NamedEntityRecognitionDemo-metadata":{"entities":[{"confidence":0.92}],"job-name":"labeling-job/namedentityrecognitiondemo","type":"groundtruth/text-span","creation-date":"2020-05-14T21:45:27.175903","human-annotated":"yes"}}
{"source":"J Doe is a judge on the Washington Supreme Court.","NamedEntityRecognitionDemo":{"annotations":{"entities":[{"endOffset":5,"startOffset":0,"label":"JUDGE"}],"labels":[{"label":"JUDGE"}]}},"NamedEntityRecognitionDemo-metadata":{"entities":[{"confidence":0.72}],"job-name":"labeling-job/namedentityrecognitiondemo","type":"groundtruth/text-span","creation-date":"2020-05-14T21:45:27.174910","human-annotated":"yes"}}
{"source":"Our latest new employee, Mateo Jackson, has been a manager in the industry for 4 years.","NamedEntityRecognitionDemo":{"annotations":{"entities":[{"endOffset":38,"startOffset":26,"label":"MANAGER"}],"labels":[{"label":"MANAGER"}]}},"NamedEntityRecognitionDemo-metadata":{"entities":[{"confidence":0.91}],"job-name":"labeling-job/namedentityrecognitiondemo","type":"groundtruth/text-span","creation-date":"2020-05-14T21:45:27.174035","human-annotated":"yes"}}
```
此 JSON 行檔案中的每一行都是完整的 JSON 物件，其中的屬性包括文件文字、註釋和其他來自 Ground Truth 的中繼資料。下列範例是擴增資訊清單檔案中的單一 JSON 物件，但其格式具有可讀性：
```
{
"source": "Diego Ramirez is an engineer in the high tech industry.",
"NamedEntityRecognitionDemo": {
"annotations": {
"entities": [
{
"endOffset": 13,
"startOffset": 0,
"label": "ENGINEER"
}
],
"labels": [
{
"label": "ENGINEER"
}
]
}
},
"NamedEntityRecognitionDemo-metadata": {
"entities": [
{
"confidence": 0.92
}
],
"job-name": "labeling-job/namedentityrecognitiondemo",
"type": "groundtruth/text-span",
"creation-date": "2020-05-14T21:45:27.175903",
"human-annotated": "yes"
}
}
```
在此範例中， `source` 屬性提供訓練文件的文字， `NamedEntityRecognitionDemo` 屬性則提供文字中實體的註釋。`NamedEntityRecognitionDemo` 屬性的名稱是任意的，您可以在 Ground Truth 中定義標籤工作時提供您選擇的名稱。
在此範例中， `NamedEntityRecognitionDemo` 屬性是*標籤屬性名稱*，這是提供 Ground Truth 工作者指派給訓練資料的標籤的屬性。當您將訓練資料提供給 Amazon Comprehend 時，您必須指定一或多個標籤屬性名稱。您指定的屬性名稱數量取決於擴增的資訊清單檔案是單一標記任務或鏈結標記任務的輸出。
如果您的檔案是單一標記任務的輸出，請指定在 Ground Truth 中建立任務時所使用的單一標籤屬性名稱。
如果您的檔案是鏈結標記任務的輸出，請指定鏈結中一或多個任務的標籤屬性名稱。每個標籤屬性名稱都會提供個別任務的註釋。您可以為鏈結標記任務產生的擴增資訊清單檔案指定最多 5 個這些屬性。
在擴增的資訊清單檔案中，標籤屬性名稱通常遵循 `source`金鑰。如果檔案是鏈結任務的輸出，則會有多個標籤屬性名稱。當您將訓練資料提供給 Amazon Comprehend 時，請僅提供包含與您模型相關註釋的屬性。請勿指定結尾為 "-metadata" 的屬性。
如需鏈結標記任務的詳細資訊，以及其產生的輸出範例，請參閱《Amazon SageMaker AI 開發人員指南》中的[鏈結標記任務](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-reusing-data.html)。
# 註釋 PDF 檔案
在 SageMaker AI Ground Truth 中註釋訓練 PDFs 之前，請先完成下列先決條件：
+ 安裝 python3.8.x
+ 安裝 [ jq](https://stedolan.github.io/jq/download/)
+ 安裝 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
如果您使用的是 us-east-1 區域，則可以略過安裝 AWS CLI，因為它已與您的 Python 環境一起安裝。在此情況下，您會建立虛擬環境以在 Cloud9 中使用 AWS Python 3.8。
+ 設定您的[AWS 登入](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)資料
+ 建立私有 [SageMaker AI Ground Truth 人力資源](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-workforce-private-use-cognito.html)以支援註釋
在安裝期間使用工作團隊時，請務必在新的私有人力資源中記錄您選擇的工作團隊名稱。
**Topics**
+ [設定您的環境](#cer-annotation-pdf-set-up)
+ [將 PDF 上傳至 S3 儲存貯體](#cer-annotation-pdf-upload)
+ [建立註釋任務](#cer-annotation-pdf-job)
+ [使用 SageMaker AI Ground Truth 註釋](#w2aac35c23c21c19c15)
## 設定您的環境
1. 如果使用 Windows，請安裝 [Cygwin](https://cygwin.com/install.html)；如果使用 Linux 或 Mac，請略過此步驟。
1. 從 GitHub 下載[註釋成品](http://github.com/aws-samples/amazon-comprehend-semi-structured-documents-annotation-tools)。解壓縮檔案。
1. 從終端機視窗中，導覽至解壓縮資料夾 (**amazon-comprehend-semi-structured-documents-annotation-tools-main**)。
1. 此資料夾包含您執行`Makefiles`以安裝相依性、設定 Python virtualenv 和部署所需資源的 選項。檢閱**讀我**檔案以做出您的選擇。
1. 建議選項使用單一命令將所有相依性安裝到 Virtualenv 中，從範本建置 CloudFormation 堆疊，並使用 AWS 帳戶 互動式指導將堆疊部署到 。執行以下命令：
`make ready-and-deploy-guided`
此命令提供一組組態選項。請確定您的 AWS 區域 正確無誤。對於所有其他欄位，您可以接受預設值或填入自訂值。如果您修改 CloudFormation 堆疊名稱，請在後續步驟中視需要將其寫下來。
![\[顯示 CloudFormation 組態選項的終端機工作階段。\]](http://docs.aws.amazon.com/zh_tw/comprehend/latest/dg/images/deploy_guided_anno.png)
CloudFormation 堆疊會建立和管理註釋工具所需的 [AWS lambda](https://aws.amazon.com/lambda/)、[AWS IAM](https://aws.amazon.com/iam/) 角色和 [AWS S3](https://aws.amazon.com/s3/) 儲存貯體。
您可以在 CloudFormation 主控台的堆疊詳細資訊頁面中檢閱這些資源。
1. 命令會提示您開始部署。CloudFormation 會在指定的區域中建立所有資源。
![\[顯示已部署 CloudFormation 組態的終端機工作階段。\]](http://docs.aws.amazon.com/zh_tw/comprehend/latest/dg/images/deploy_guided_anno_2.png)
當 CloudFormation 堆疊狀態轉換為 create-complete 時，資源即可使用。
## 將 PDF 上傳至 S3 儲存貯體
在[設定](#cer-annotation-pdf-set-up)區段中，您部署了 CloudFormation 堆疊，該堆疊會建立名為 **comprehend-semi-structured-documents-\$1\$1AWS：：Region\$1-\$1\$1AWS：：AccountId\$1** 的 S3 儲存貯體。您現在將來源 PDF 文件上傳至此儲存貯體。
**注意**
此儲存貯體包含標籤工作所需的資料。Lambda 執行角色政策會授予 Lambda 函數存取此儲存貯體的許可。
您可以使用 S3Bucket' 金鑰，在 **CloudFormation Stack 詳細資訊**中找到 S3 儲存貯體名稱。**SemiStructuredDocumentsS3Bucket**
1. 在 S3 儲存貯體中建立新的資料夾。將此新資料夾命名為 '**src**'。
1. 將 PDF 來源檔案新增至您的 '**src**' 資料夾。在後續步驟中，您會註釋這些檔案來訓練您的辨識器。
1. （選用） 以下 CLI AWS 範例可用來將來源文件從本機目錄上傳至 S3 儲存貯體：
`aws s3 cp --recursive local-path-to-your-source-docs s3://deploy-guided/src/`
或者，使用您的區域和帳戶 ID：
`aws s3 cp --recursive local-path-to-your-source-docs s3://deploy-guided-Region-AccountID/src/`
1. 您現在擁有私有 SageMaker AI Ground Truth 人力資源，並將來源檔案上傳至 S3 儲存貯體 **deploy-guided/src/**；您已準備好開始註釋。
## 建立註釋任務
`bin` 目錄中的 **comprehend-ssie-annotation-tool-cli.py** 指令碼是一種簡單的包裝函式命令，可簡化 SageMaker AI Ground Truth 標籤工作的建立。python 指令碼會從 S3 儲存貯體讀取來源文件，並建立對應的單一頁面資訊清單檔案，每行一個來源文件。然後指令碼會建立標記任務，需要資訊清單檔案做為輸入。
python 指令碼使用您在[設定](#cer-annotation-pdf-set-up)區段中設定的 S3 儲存貯體和 CloudFormation 堆疊。指令碼所需的輸入參數包括：
+ **input-s3-path**：S3 Uri 到您上傳到 S3 儲存貯體的來源文件。例如：`s3://deploy-guided/src/`。您也可以將您的區域和帳戶 ID 新增至此路徑。例如：`s3://deploy-guided-Region-AccountID/src/`。
+ **cfn-name**：CloudFormation 堆疊名稱。如果您使用堆疊名稱的預設值，您的 cfn-name 是 **sam-app**。
+ **work-team-name**：您在 SageMaker AI Ground Truth 中建置私有人力資源時建立的人力資源名稱。
+ **job-name-prefix**：SageMaker AI Ground Truth 標籤工作的字首。請注意，此欄位有 29 個字元的限制。時間戳記會附加至此值。例如：`my-job-name-20210902T232116`。
+ entity**-types**：您希望在標記任務期間使用的實體，以逗號分隔。此清單必須包含您要在訓練資料集中註釋的所有實體。Ground Truth 標記任務只會顯示這些實體，以供註釋器在 PDF 文件中標記內容。
若要檢視指令碼支援的其他引數，請使用 `-h`選項來顯示說明內容。
+ 使用輸入參數執行下列指令碼，如上一份清單所述。
```
python bin/comprehend-ssie-annotation-tool-cli.py \
--input-s3-path s3://deploy-guided-Region-AccountID/src/ \
--cfn-name sam-app \
--work-team-name my-work-team-name \
--region us-east-1 \
--job-name-prefix my-job-name-20210902T232116 \
--entity-types "EntityA, EntityB, EntityC" \
--annotator-metadata "key=info,value=sample,key=Due Date,value=12/12/2021"
```
指令碼會產生下列輸出：
```
Downloaded files to temp local directory /tmp/a1dc0c47-0f8c-42eb-9033-74a988ccc5aa
Deleted downloaded temp files from /tmp/a1dc0c47-0f8c-42eb-9033-74a988ccc5aa
Uploaded input manifest file to s3://comprehend-semi-structured-documents-us-west-2-123456789012/input-manifest/my-job-name-20220203-labeling-job-20220203T183118.manifest
Uploaded schema file to s3://comprehend-semi-structured-documents-us-west-2-123456789012/comprehend-semi-structured-docs-ui-template/my-job-name-20220203-labeling-job-20220203T183118/ui-template/schema.json
Uploaded template UI to s3://comprehend-semi-structured-documents-us-west-2-123456789012/comprehend-semi-structured-docs-ui-template/my-job-name-20220203-labeling-job-20220203T183118/ui-template/template-2021-04-15.liquid
Sagemaker GroundTruth Labeling Job submitted: arn:aws:sagemaker:us-west-2:123456789012:labeling-job/my-job-name-20220203-labeling-job-20220203t183118
(amazon-comprehend-semi-structured-documents-annotation-tools-main) user@3c063014d632 amazon-comprehend-semi-structured-documents-annotation-tools-main %
```
## 使用 SageMaker AI Ground Truth 註釋
現在您已設定必要的資源並建立標籤工作，您可以登入標籤入口網站並註釋 PDFs。
1. 使用 Chrome 或 Firefox Web 瀏覽器登入 [SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker)。
1. 選取**標記人力資源**，然後選擇**私有**。
1. 在**私有人力資源摘要**下，選取您使用私有人力資源建立的標記入口網站登入 URL。使用適當的登入資料登入。
如果您沒有看到任何列出的任務，請不要擔心，更新可能需要一些時間，具體取決於您上傳用於註釋的檔案數量。
1. 選取您的任務，然後在右上角選擇**開始工作**以開啟註釋畫面。
您會在註釋畫面中看到其中一個文件開啟，並在上面看到您在設定期間提供的實體類型。在實體類型右側有一個箭頭，您可以用來導覽文件。
![\[Amazon Comprehend 註釋畫面。\]](http://docs.aws.amazon.com/zh_tw/comprehend/latest/dg/images/annotation_demo1.png)
註釋開啟的文件。您也可以在每個文件上移除、復原或自動標記註釋；這些選項可在註釋工具的右側面板中使用。
![\[Amazon Comprehend 註釋右側面板中的可用選項。\]](http://docs.aws.amazon.com/zh_tw/comprehend/latest/dg/images/data_annotation.png)
若要使用自動標籤，請為其中一個實體的執行個體加上註釋；然後，該特定字詞的所有其他執行個體都會自動以該實體類型加上註釋。
完成後，請選取右下角的**提交**，然後使用導覽箭頭移至下一個文件。重複此操作，直到您已註釋所有 PDFs 為止。
註釋所有訓練文件後，您可以在此位置的 Amazon S3 儲存貯體中找到 JSON 格式的註釋：
```
/output/your labeling job name/annotations/
```
輸出資料夾也包含輸出資訊清單檔案，其中列出訓練文件中的所有註釋。您可以在下列位置找到輸出資訊清單檔案。
```
/output/your labeling job name/manifests/
```