本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 執行自訂實體辨識的分析任務
您可以執行非同步分析任務，以偵測一組或多份文件中的自訂實體。
**開始之前**
您需要自訂實體辨識模型 （也稱為辨識器），才能偵測自訂實體。如需這些模型的詳細資訊，請參閱 [訓練自訂實體辨識器模型](training-recognizers.md)。
使用純文字註釋訓練的辨識器僅支援純文字文件的實體偵測。使用 PDF 文件註釋訓練的辨識器支援純文字文件、影像、PDF 檔案和 Word 文件的實體偵測。對於文字檔案以外的檔案，Amazon Comprehend 會在執行分析之前執行文字擷取。如需輸入檔案的資訊，請參閱 [非同步自訂分析的輸入](idp-inputs-async.md)。
如果您打算分析影像檔案或掃描的 PDF 文件，IAM 政策必須授予使用兩種 Amazon Textract API 方法 (DetectDocumentText 和 AnalyzeDocument) 的許可。Amazon Comprehend 會在文字擷取期間叫用這些方法。如需政策範例，請參閱 [執行文件分析動作所需的許可](security_iam_id-based-policy-examples.md#security-iam-based-policy-perform-cmp-actions)。
若要執行非同步分析任務，請執行下列整體步驟：
1. 將文件存放在 Amazon S3 儲存貯體中。
1. 使用 API 或主控台啟動分析任務。
1. 監控分析任務的進度。
1. 任務執行到完成之後，請從您在啟動任務時指定的 S3 儲存貯體擷取分析結果。
**Topics**
+ [啟動自訂實體偵測任務 （主控台）](detecting-cer-async-console.md)
+ [啟動自訂實體偵測任務 (API)](detecting-cer-async-api.md)
+ [非同步分析任務的輸出](outputs-cer-async.md)
# 啟動自訂實體偵測任務 （主控台）
您可以使用 主控台啟動和監控自訂實體辨識的非同步分析任務。
**啟動非同步分析任務**
1. 登入 AWS 管理主控台 並前往 https：//[https://console.aws.amazon.com/comprehend/](https://console.aws.amazon.com/comprehend/) 開啟 Amazon Comprehend 主控台
1. 從左側選單中，選擇**分析任務**，然後選擇**建立任務**。
1. 為分類任務命名。名稱必須是您的帳戶和目前區域的唯一名稱。
1. 在**分析類型**下，選擇**自訂實體辨識**。
1. 從**辨識器模型**中，選擇要使用的自訂實體辨識器。
1. 從**版本**中，選擇要使用的辨識器版本。
1. （選用） 如果您選擇在處理任務時加密 Amazon Comprehend 使用的資料，請選擇**任務加密**。然後選擇要使用與目前帳戶相關聯的 KMS 金鑰，還是使用另一個帳戶的 KMS 金鑰。
+ 如果您使用的是與目前帳戶相關聯的金鑰，請選擇 **KMS 金鑰 ID 的金鑰 ID**。
+ 如果您使用的是與不同帳戶相關聯的金鑰，請在 **KMS 金鑰 ARN 下輸入金鑰 ID 的 ARN**。
**注意**
如需建立和使用 KMS 金鑰和相關聯加密的詳細資訊，請參閱[金鑰管理服務 (KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)。
1. 在**輸入資料**下，輸入包含輸入文件的 Amazon S3 儲存貯體位置，或選擇**瀏覽 S3** 導覽至該儲存貯體。此儲存貯體必須與您呼叫的 API 位於相同的區域。您用於分析任務存取許可的 IAM 角色必須具有 S3 儲存貯體的讀取許可。
1. （選用） 針對**輸入格式**，您可以選擇輸入文件的格式。格式可以是每個檔案一個文件，或單一檔案中每行一個文件。每行一個文件僅適用於文字文件。
1. （選用） 對於**文件讀取模式**，您可以覆寫預設的文字擷取動作。如需詳細資訊，請參閱[設定文字擷取選項](idp-set-textract-options.md)。
1. 在**輸出資料**下，輸入 Amazon S3 Amazon Comprehend ** S3** 儲存貯體位置。此儲存貯體必須與您呼叫的 API 位於相同的區域。您用於分類任務存取許可的 IAM 角色必須具有 S3 儲存貯體的寫入許可。
1. （選用） 如果您選擇加密任務的輸出結果，請選擇**加密**。然後選擇要使用與目前帳戶相關聯的 KMS 金鑰，還是使用另一個帳戶的 KMS 金鑰。
+ 如果您使用的是與目前帳戶相關聯的金鑰，請選擇 **KMS 金鑰 ID 的金鑰別名或 ID**。
+ 如果您使用的是與不同帳戶相關聯的金鑰，請在 **KMS 金鑰** ID 下輸入金鑰別名或 ID 的 ARN。
1. （選用） 若要從 VPC 啟動您的資源到 Amazon Comprehend，請在 VPC 下輸入 **VPC** ID，或從下拉式清單中選擇 ID。
1. 選擇**子網路 （子網路） 下的子網路**。選取第一個子網路之後，您可以選擇其他子網路。
1. 在**安全群組 (Security Group)** 下，如果您指定安全群組，請選擇要使用的安全群組。選取第一個安全群組之後，您可以選擇其他安全群組。
**注意**
當您搭配分析任務使用 VPC 時，`DataAccessRole`用於建立和啟動操作的 必須具有存取輸出儲存貯體之 VPC 的許可。
1. 選擇**建立任務**以建立實體辨識任務。
# 啟動自訂實體偵測任務 (API)
您可以使用 API 啟動和監控自訂實體辨識的非同步分析任務。
若要使用 [StartEntitiesDetectionJob](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_StartEntitiesDetectionJob.html) 操作啟動自訂實體偵測任務，您需要提供 EntityRecognizerArn，這是訓練模型的 Amazon Resource Name (ARN)。您可以在 [CreateEntityRecognizer](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_CreateEntityRecognizer.html) 操作的回應中找到此 ARN。
**Topics**
+ [使用 偵測自訂實體 AWS Command Line Interface](#detecting-cer-async-api-cli)
+ [使用 偵測自訂實體 適用於 Java 的 AWS SDK](#detecting-cer-async-api-java)
+ [使用 偵測自訂實體 適用於 Python (Boto3) 的 AWS SDK](#detecting-cer-async-api-python)
+ [覆寫 PDF 檔案的 API 動作](#detecting-cer-api-pdf)
## 使用 偵測自訂實體 AWS Command Line Interface
針對 Unix、Linux 和 macOS 環境使用以下範例。用於 Windows 時，請以插入號 (^) 取代每一行結尾處的 Unix 接續字元斜線 (\$1)。若要偵測文件集中的自訂實體，請使用下列請求語法：
```
aws comprehend start-entities-detection-job \
--entity-recognizer-arn "arn:aws:comprehend:region:account number:entity-recognizer/test-6" \
--job-name infer-1 \
--data-access-role-arn "arn:aws:iam::account number:role/service-role/AmazonComprehendServiceRole-role" \
--language-code en \
--input-data-config "S3Uri=s3://Bucket Name/Bucket Path" \
--output-data-config "S3Uri=s3://Bucket Name/Bucket Path/" \
--region region
```
Amazon Comprehend 會回應 `JobID`和 ，`JobStatus`並傳回您在請求中指定的 S3 儲存貯體中任務的輸出。
## 使用 偵測自訂實體 適用於 Java 的 AWS SDK
如需使用 Java 的 Amazon Comprehend 範例，請參閱 [Amazon Comprehend Java 範例](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/comprehend)。
## 使用 偵測自訂實體 適用於 Python (Boto3) 的 AWS SDK
此範例會建立自訂實體辨識器、訓練模型，然後使用 在實體辨識器任務中執行 適用於 Python (Boto3) 的 AWS SDK。
執行個體化適用於 Python 的 SDK。
```
import boto3
import uuid
comprehend = boto3.client("comprehend", region_name="region")
```
建立實體辨識器：
```
response = comprehend.create_entity_recognizer(
RecognizerName="Recognizer-Name-Goes-Here-{}".format(str(uuid.uuid4())),
LanguageCode="en",
DataAccessRoleArn="Role ARN",
InputDataConfig={
"EntityTypes": [
{
"Type": "ENTITY_TYPE"
}
],
"Documents": {
"S3Uri": "s3://Bucket Name/Bucket Path/documents"
},
"Annotations": {
"S3Uri": "s3://Bucket Name/Bucket Path/annotations"
}
}
)
recognizer_arn = response["EntityRecognizerArn"]
```
列出所有辨識器：
```
response = comprehend.list_entity_recognizers()
```
等待實體辨識器達到 TRAINED 狀態：
```
while True:
response = comprehend.describe_entity_recognizer(
EntityRecognizerArn=recognizer_arn
)
status = response["EntityRecognizerProperties"]["Status"]
if "IN_ERROR" == status:
sys.exit(1)
if "TRAINED" == status:
break
time.sleep(10)
```
啟動自訂實體偵測任務：
```
response = comprehend.start_entities_detection_job(
EntityRecognizerArn=recognizer_arn,
JobName="Detection-Job-Name-{}".format(str(uuid.uuid4())),
LanguageCode="en",
DataAccessRoleArn="Role ARN",
InputDataConfig={
"InputFormat": "ONE_DOC_PER_LINE",
"S3Uri": "s3://Bucket Name/Bucket Path/documents"
},
OutputDataConfig={
"S3Uri": "s3://Bucket Name/Bucket Path/output"
}
)
```
## 覆寫 PDF 檔案的 API 動作
對於映像檔案和 PDF 檔案，您可以使用 中的 `DocumentReaderConfig` 參數覆寫預設擷取動作`InputDataConfig`。
下列範例定義名為 myInputDataConfig.json 的 JSON 檔案來設定`InputDataConfig`值。它`DocumentReadConfig`將 設定為對所有 PDF 檔案使用 Amazon Textract `DetectDocumentText` API。
**Example**
```
"InputDataConfig": {
"S3Uri": s3://Bucket Name/Bucket Path",
"InputFormat": "ONE_DOC_PER_FILE",
"DocumentReaderConfig": {
"DocumentReadAction": "TEXTRACT_DETECT_DOCUMENT_TEXT",
"DocumentReadMode": "FORCE_DOCUMENT_READ_ACTION"
}
}
```
在 `StartEntitiesDetectionJob`操作中，指定 myInputDataConfig.json 檔案做為 `InputDataConfig` 參數：
```
--input-data-config file://myInputDataConfig.json
```
如需`DocumentReaderConfig`參數的詳細資訊，請參閱 [設定文字擷取選項](idp-set-textract-options.md)。
# 非同步分析任務的輸出
分析任務完成後，會將結果存放在您在請求中指定的 S3 儲存貯體中。
## 文字輸入的輸出
對於文字輸入檔案，輸出包含每個輸入文件的實體清單。
下列範例顯示來自名為 之輸入檔案的兩個文件的輸出**50\$1docs**，每個行格式使用一個文件。
```
{
"File": "50_docs",
"Line": 0,
"Entities":
[
{
"BeginOffset": 0,
"EndOffset": 22,
"Score": 0.9763959646224976,
"Text": "John Johnson",
"Type": "JUDGE"
}
]
}
{
"File": "50_docs",
"Line": 1,
"Entities":
[
{
"BeginOffset": 11,
"EndOffset": 15,
"Score": 0.9615424871444702,
"Text": "Thomas Kincaid",
"Type": "JUDGE"
}
]
}
```
## 半結構化輸入的輸出
對於半結構化輸入文件，輸出可以包含下列其他欄位：
+ DocumentMetadata – 文件的擷取資訊。中繼資料包含文件中的頁面清單，其中包含從每個頁面擷取的字元數。如果請求包含 `Byte` 參數，則此欄位會出現在回應中。
+ DocumentType – 輸入文件中每個頁面的文件類型。此欄位會出現在包含 `Byte` 參數之請求的回應中。
+ 區塊 – 輸入文件中每個文字區塊的相關資訊。區塊可以在區塊內巢狀化。頁面區塊包含每行文字的區塊，其中包含每個單字的區塊。此欄位會出現在包含 `Byte` 參數之請求的回應中。
+ BlockReferences – 此實體每個區塊的參考。此欄位會出現在包含 `Byte` 參數之請求的回應中。欄位不存在於文字檔案。
+ 錯誤 – 系統在處理輸入文件時偵測到的頁面層級錯誤。如果系統沒有發生錯誤，則此欄位為空白。
如需這些輸出欄位的詳細資訊，請參閱《*Amazon Comprehend API 參考*》中的 [DetectEntities](https://docs.aws.amazon.com/comprehend/latest/APIReference/API_DetectEntities.html)
下列範例顯示單頁原生 PDF 輸入文件的輸出。
**Example PDF 文件自訂實體辨識分析的範例輸出**
```
{
"Blocks":
[
{
"BlockType": "LINE",
"Geometry":
{
"BoundingBox":
{
"Height": 0.012575757575757575,
"Left": 0.0,
"Top": 0.0015063131313131314,
"Width": 0.02262091503267974
},
"Polygon":
[
{
"X": 0.0,
"Y": 0.0015063131313131314
},
{
"X": 0.02262091503267974,
"Y": 0.0015063131313131314
},
{
"X": 0.02262091503267974,
"Y": 0.014082070707070706
},
{
"X": 0.0,
"Y": 0.014082070707070706
}
]
},
"Id": "4330efed-6334-4fc4-ba48-e050afa95c8d",
"Page": 1,
"Relationships":
[
{
"ids":
[
"f343ce48-583d-4abe-b84b-a232e266450f"
],
"type": "CHILD"
}
],
"Text": "S-3"
},
{
"BlockType": "WORD",
"Geometry":
{
"BoundingBox":
{
"Height": 0.012575757575757575,
"Left": 0.0,
"Top": 0.0015063131313131314,
"Width": 0.02262091503267974
},
"Polygon":
[
{
"X": 0.0,
"Y": 0.0015063131313131314
},
{
"X": 0.02262091503267974,
"Y": 0.0015063131313131314
},
{
"X": 0.02262091503267974,
"Y": 0.014082070707070706
},
{
"X": 0.0,
"Y": 0.014082070707070706
}
]
},
"Id": "f343ce48-583d-4abe-b84b-a232e266450f",
"Page": 1,
"Relationships":
[],
"Text": "S-3"
}
],
"DocumentMetadata":
{
"PageNumber": 1,
"Pages": 1
},
"DocumentType": "NativePDF",
"Entities":
[
{
"BlockReferences":
[
{
"BeginOffset": 25,
"BlockId": "4330efed-6334-4fc4-ba48-e050afa95c8d",
"ChildBlocks":
[
{
"BeginOffset": 1,
"ChildBlockId": "cbba5534-ac69-4bc4-beef-306c659f70a6",
"EndOffset": 6
}
],
"EndOffset": 30
}
],
"Score": 0.9998825926329088,
"Text": "0.001",
"Type": "OFFERING_PRICE"
},
{
"BlockReferences":
[
{
"BeginOffset": 41,
"BlockId": "f343ce48-583d-4abe-b84b-a232e266450f",
"ChildBlocks":
[
{
"BeginOffset": 0,
"ChildBlockId": "292a2e26-21f0-401b-a2bf-03aa4c47f787",
"EndOffset": 9
}
],
"EndOffset": 50
}
],
"Score": 0.9809727537330395,
"Text": "6,097,560",
"Type": "OFFERED_SHARES"
}
],
"File": "example.pdf",
"Version": "2021-04-30"
}
```