Amazon Textract 極簡Python教學 - 快速上手Textract的同步與非同步處理
建議閱讀網站
- DetectDocumentText關於Line和Word的相關介紹,包含關係圖:https://docs.aws.amazon.com/zh_tw/textract/latest/dg/how-it-works-lines-words.html
- 文檔上的目標位置怎麼看?:https://docs.aws.amazon.com/zh_tw/textract/latest/dg/text-location.html
- 請求的格式說明:start_document_text_detection - Boto3 1.34.68 documentation (amazonaws.com)
安裝包
- ref: Textract/Quickstart
1 | # 習慣建立一個獨立的環境 |
本地權限設置
根據官方說法,要先設定以下:
- 先建立一個IAM使用者,該使用者必須擁有4個權限分別是:
AmazonTextractFullAccess
: 可以呼叫Textract的所有APIAmazonS3FullAccess
: 因為分析的檔案會放在S3上,所以要有存取的權限AmazonSQSFullAccess
+AmazonSNSFullAccess
: 如果要使用異步檢測,就需要這個權限,為了把分析成功的狀態由SNS通知給SQS
- 建立存取金鑰
- 在
~/.aws/credentials
設定該金鑰1
2
3[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY - 在
~/.aws/config
設定區域1
2[default]
region=us-east-1
這樣在執行 boto3.client(‘textract’) 時就會根據設定的金鑰和區域來進行操作。
Textract 非同步處理
從Detecting or Analyzing Text in a Multipage Document - Amazon Textract 整體整個操作流程,從上圖可以看到,我們Client Application在呼叫Textract的StartDocumentTextDetection方法時:
- Textract 會收到檔案分析的請求,根據請求內容找到S3上的檔案
- 開始分析,會回傳一個JobId讓使用者可以根據此JobId來檢索SQS中是否有Completion Status的JobId
- 如何給Textract發送SNS通知,需要設定相關權限,我們需要建立RoleArn (Textract) 的權限,讓SNS可以接收來自Textract的通知。
- 我們可以參考 Configuring Amazon Textract for Asynchronous Operations - Amazon Textract 需要先去建立一個Role,為了獲得
RoleArn
- SNS會通知SQS,SQS會將結果放到Queue中
- 需要先建立SNS Topic 和 SQS Queue, 並且 subscribe 建立的 queue 到 topic.
- 我們可以參考 Amazon SNS 入門 - Amazon Simple Notification Service 了解 SNS 的使用方式。
- 還可以參考 Subscribing an Amazon SQS queue to an Amazon SNS topic - Amazon Simple Notification Service 要讓SNS送訊息到SQS就需要先建立Topic和Queue,並且確保Queue有權限可以接受來自sqs:SendMessage的執行。(通常在SNS Subscribe後可以選擇要哪一個SQS,此時就會設定相關的Policy)。
- Client Application會不斷的檢查SQS中是否有Step2回傳的JobId,如果有表示該Job已經完成,可以透過GetDocumentTextDetection來取得結果。
- 相關的回傳和請求內容格式,可以參考 調用 Amazon Textract 異步操作 - Amazon Textract 裡面有說明發送請求的設定。
- 透過GetDocumentTextDetection取得結果後,就可以進行後續的處理。
Step2: 取得RoleArn
當異步操作完成時,Amazon Textract 需要獲得許可才能向您的 Amazon SNS 主題發送消息。您可以使用 IAM 服務角色,讓 Amazon Textract 存取 Amazon SNS 主題。創建 Amazon SNS 主題時,必須在主題名稱前加上AmazonTextract
— 例如,AmazonTextractMyTopicName
。
- 登入 IAM 主控台 (https://console.aws.amazon.com/iam)。
- 在導覽窗格中,選擇 Roles (角色)。
- 選擇 Create Role (建立角色)。
- 對於 Select type of trusted entity (選取信任的實體類型),選擇 AWS service (AWS 服務)。
- 適用於選擇將使用此角色的服務,選擇Textract。
- 選擇 Next: (下一步:) Permissions (許可)。
- 驗證AmazonTextractServiceRole策略已包含在附加策略列表中。若要在清單中顯示政策,請在篩選政策。
- 選擇 Next: (下一步:) Tags (標籤)。
- 您不需要新增標籤,所以請選擇下一頁: Review (檢閱)。
- 在 Review (檢閱) 區段中,針對 Role name (角色名稱),輸入角色的名稱 (例如,TextractRole)。In角色描述,請更新該角色的描述,然後選擇建立角色。
- 選擇新角色來開啟角色的詳細資訊頁面。
- 在 Summary (摘要) 中,複製 Role ARN (角色 ARN) 值,並將其儲存。
- 選擇 Trust relationships (信任關係)。
- 選擇編輯信任關係,並確保信任策略如下所示。為了防止混淆的代理問題,請確保信任策略包含限制權限範圍的條件。有關此潛在安全問題的更多詳細信息,請參閱跨服務混淆的代理預防措施。在下面的示例中,將
123456789012
文本替換為您的 AWS 帳戶 ID。 - 選擇Update Trust Policy更新信任政策。
1 | { |
結果如下:
Step 3: SQS and SNS
將許可提供給 Amazon SNS Topic,以將訊息傳送至 Amazon SQS 佇列。為了讓 Amazon SNS 主題能夠傳送訊息至Queue,您必須對Queue設定政策,允許 Amazon SNS 主題執行 sqs:SendMessage
動作。在您訂閱Queue到Topic之前,您需要建立Topic和Queue。如果您尚未建立Topic和Queue,請現在建立。如需詳細資訊,請參閱 建立Topic,並參閱 Amazon Queue Service 開發人員指南中的建立Queue。
使用 Amazon SQS 主控台設定佇列的 SendMessage 政策
- 登入 AWS Management Console,並在 https://console.aws.amazon.com/sqs/ 開啟 Amazon SQS 主控台。
- 選取您要設定其政策之佇列的方塊,選擇
Access policy (存取政策)
索引標籤,然後選擇Edit (編輯)
。 - 在存取政策區段中,定義誰可以存取您的佇列。
- 新增條件以允許用於主題的動作。
- 將 Principal 設定為 Amazon SNS 服務,如下列範例所示。
- 使用
aws:SourceArn
或者aws:SourceAccount
全域條件金鑰,以防止混淆代理人案例。如要使用這些條件金鑰,請將值設定為主題的 ARN。若您的佇列訂閱了多個主題,則可改用aws:SourceAccou
例如,下列政策允許 MyTopic 傳送訊息至 MyQueue。請取代123456789012為您的帳戶ID。
1 | { |
python code
可以參考 Detecting or Analyzing Text in a Multipage Document - Amazon Textract ,附上完整的Python程式碼,詳細的介紹如何透過Python實現上述講到的所有流程。
1 | import boto3 |
Textract 同步處理
- Ref: AWS Textract API 規格書:https://docs.aws.amazon.com/zh_tw/textract/latest/dg/API_DetectDocumentText.html
DetectDocumentText 是可以分析文件中的 line 或是 word 字段和位置。AWS Textract 可以選擇要透過S3 或是傳送 base64 編碼的bytes來進行分析。根據官方對偵測文字的說法,回應返回文檔中檢操到的:
- 文本的line和word
- 文本中line裡面和word之間的關係
- 檢測到的文本顯示在圖片上哪一個位置
在這裏,我們是使用同步檢測(一個做完才做下一個),如果要使用異步檢測可以參考StartDocumentTextDetection,並且透過GetDocumentTextDetection來取得結果。如需詳細資訊和範例,請參閱 使用異步操作處理文檔。
建立client
我們要先建立一個client,然後使用 detect_document_text
來進行分析。
1 |
|
處理回傳的資料
以下程式碼是官方提供的範例程式,主要可以看到如何處理回傳的資料,並且在圖片上畫出文字的位置。他的Bounding Box是一個比例,所以要乘上圖片的寬高才能得到正確的位置。
檢測到的文本將在Text欄位Block物件。所以此BlockType字段確定文本是一行文本 (LINE) 還是單詞 (WORD)。一個字是一或多個 ISO 基本拉丁腳本字符,不以空格分隔。一個線是製表符分隔和連續單詞的字符串。
最後bounding box的位置由以下組成:用來定義邊界框的四個點。[(x0, y0), (x1, y1)] 或 [x0, y0, x1, y1] 的數列
1 | def process_text_detection(): |
結果
詳細規格可以餐考文本檢測和文檔分析響應對象)
但是你會發現一個叫做confidence的欄位,從上圖跟下面的json可以看到,#Get x the * document IN from IN S3
這段x
跟*
還有IN
都不應該出現,而他們的confidence也很低,分別都是25。應該要進行filter掉信心不高的內容。根據不同的場景,可信度低的檢測可能需要人類的視覺確認。
1 | { |
補充內容
關於文字的位置
若要確定項目在文件頁面上的位置,請使用週框(Geometry)由 Amazon Textract 操作返回的信息Block物件。所以此Geometry物件包含兩類檢測到的項目的位置和幾何資訊:
- 軸對齊BoundingBox物件,該物件包含左上方座標以及項目的寬度和高度。
- 描述項目輪廓的多邊形對象,指定為Point對象包含X(水平軸) 和Y(垂直軸)每個點的文檔頁面座標。
1 | { |