處理處理回應
處理要求的回應中會包含 Document
物件,其中包含已處理文件的所有資訊,包括 Document AI 能夠擷取的所有結構化資訊。
本頁提供文件範例,並將 OCR 結果的各個層面對應至 Document
物件 JSON 的特定元素,藉此說明 Document
物件的版面配置。另外,本頁也提供用戶端程式庫程式碼範例和 Document AI Toolbox SDK 程式碼範例。這些程式碼範例使用線上處理功能,但 Document
物件剖析功能在批次處理時的運作方式相同。
使用專門用於展開或摺疊元素的 JSON 檢視器或編輯公用程式。在純文字公用程式中查看原始 JSON 效率不彰。
文字、版面配置和品質分數
以下是文字文件範例:
以下是 Enterprise Document OCR 處理器傳回的完整文件物件:
由於 OCR 是由處理器執行,因此這項 OCR 輸出內容一律會納入 Document AI 處理器輸出內容。這項功能會使用現有的 OCR 資料,因此您可以使用內嵌文件選項,將這類 JSON 資料輸入 Document AI 處理器。
image=None, # all our samples pass this var
mime_type="application/json",
inline_document=document_response # pass OCR output to CDE input - undocumented
以下是一些重要欄位:
原始文字
text
欄位包含 Document AI 辨識的文字。除了空格、制表符和行饋給之外,這段文字不含任何版面配置結構。這是唯一儲存文件文字資訊的欄位,也是文件文字的可靠來源。其他欄位可以依位置參照文字欄位的部分 (startIndex
和 endIndex
)。
{
text: "Sample Document\nHeading 1\nLorem ipsum dolor sit amet, ..."
}
頁面大小和語言
文件物件中的每個 page
都會對應至範例文件中的實體頁面。範例 JSON 輸出內容包含一個頁面,因為這是單一 PNG 圖片。
{
"pages:" [
{
"pageNumber": 1,
"dimension": {
"width": 679.0,
"height": 460.0,
"unit": "pixels"
},
}
]
}
pages[].detectedLanguages[]
欄位包含特定網頁上找到的語言,以及可信度分數。
{
"pages": [
{
"detectedLanguages": [
{
"confidence": 0.98009938,
"languageCode": "en"
},
{
"confidence": 0.01990064,
"languageCode": "und"
}
]
}
]
}
OCR 資料
Document AI OCR 會偵測頁面中具有不同精細度或組織的文字,例如文字區塊、段落、符號和符號 (如果設定為輸出符號層級資料,則符號層級為選用)。這些都是頁面物件的成員。
每個元素都有對應的 layout
,可說明其位置和文字。非文字視覺元素 (例如核取方塊) 也位於網頁層級。
{
"pages": [
{
"paragraphs": [
{
"layout": {
"textAnchor": {
"textSegments": [
{
"endIndex": "16"
}
]
},
"confidence": 0.9939527,
"boundingPoly": {
"vertices": [ ... ],
"normalizedVertices": [ ... ]
},
"orientation": "PAGE_UP"
}
}
]
}
]
}
原始文字會在 textAnchor
物件中參照,該物件會使用 startIndex
和 endIndex
將索引編入主要文字字串。
對於
boundingPoly
,頁面左上角是起點(0,0)
。正 X 值往右,正 Y 值往下。vertices
物件使用與原始圖片相同的座標,而normalizedVertices
則位於[0,1]
範圍內。其中包含一個轉換矩陣,用來指出圖片歸一化過程中的偏斜度測量值和其他屬性。
- 如要繪製
boundingPoly
,請從一個頂點繪製至下一個頂點的線段。接著,從最後一個頂點繪製線段,將其連回第一個頂點,以便關閉多邊形。版面配置的 orientation 元素會指出文字是否已相對於網頁旋轉。
為了讓您更容易掌握文件的結構,以下圖片會為 page.paragraphs
、page.lines
、page.tokens
繪製邊界多邊形。
段落
線條
權杖
模塊
Enterprise Document OCR 處理器可根據文件的可讀性,對文件進行品質評估。
- 您必須將
processOptions.ocrConfig.enableImageQualityScores
欄位設為true
,才能在 API 回應中取得這項資料。
這個品質評估是 [0, 1]
中的品質分數,其中 1
代表完美品質。系統會在 Page.imageQualityScores
欄位中傳回品質分數。所有偵測到的瑕疵都會列為 quality/defect_*
,並依信心值遞減排序。
以下是太暗且模糊的 PDF,不易閱讀:
以下是 Enterprise Document OCR 處理器傳回的文件品質資訊:
{
"pages": [
{
"imageQualityScores": {
"qualityScore": 0.7811847,
"detectedDefects": [
{
"type": "quality/defect_document_cutoff",
"confidence": 1.0
},
{
"type": "quality/defect_glare",
"confidence": 0.97849524
},
{
"type": "quality/defect_text_cutoff",
"confidence": 0.5
}
]
}
}
]
}
程式碼範例
以下程式碼範例示範如何傳送處理要求,然後讀取及輸出欄位至終端機:
Java
詳情請參閱 Document AI Java API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
詳情請參閱 Document AI Node.js API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
詳情請參閱 Document AI Python API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
表單和表格
以下是範例表單:
以下是 表單剖析器傳回的完整文件物件:
以下是一些重要欄位:
表單剖析器可偵測網頁中的 FormFields
。每個表單欄位都有名稱和值。這也稱為鍵/值組合 (KVP)。請注意,K/V 與其他擷取器中的 (結構定義) 實體不同:
已設定實體名稱。KVP 中的鍵值就是文件中的鍵文字。
{
"pages:" [
{
"formFields": [
{
"fieldName": { ... },
"fieldValue": { ... }
}
]
}
]
}
- Document AI 也能偵測頁面中的
Tables
。
{
"pages:" [
{
"tables": [
{
"layout": { ... },
"headerRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
],
"bodyRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
]
}
]
}
]
}
表單剖析器中的表格擷取功能只會辨識簡單的表格,也就是沒有跨越資料列或資料欄的儲存格。因此 rowSpan
和 colSpan
一律為 1
。
從處理器版本
pretrained-form-parser-v2.0-2022-11-10
開始,表單剖析器也能辨識一般實體。詳情請參閱「表單剖析器」。為協助您以視覺化方式呈現文件結構,以下圖片繪製了
page.formFields
和page.tables
的邊界多邊形。表格中的核取方塊。表單剖析器可將圖片和 PDF 中的核取方塊以 KVP 的形式數位化。提供將核取方塊數位化做為鍵/值組合的範例。
在表格外,表單剖析器會將核取方塊視為視覺元素。在 UI 和 JSON 中的 Unicode ✓ 上,以醒目顯示帶有勾號的方塊。
"pages:" [
{
"tables": [
{
"layout": { ... },
"headerRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
],
"bodyRows": [
{
"cells": [
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
},
{
"layout": { ... },
"rowSpan": 1,
"colSpan": 1
}
]
}
]
}
]
}
]
}
在表格中,核取方塊會以 Unicode 字元顯示,例如 ✓ (已勾選) 或 ☐ (未勾選)。
已勾選的核取方塊值為 filled_checkbox:under pages > x > formFields > x > fieldValue > valueType.
。未勾選的核取方塊值為 unfilled_checkbox
。
內容欄位會在路徑 pages>formFields>x>fieldValue>textAnchor>content
中以醒目顯示的 ✓ 標示出核取方塊內容值。
為協助您視覺化文件結構,以下圖片會為 page.formFields
和 page.tables
繪製邊界多邊形。
表單欄位
資料表
程式碼範例
以下程式碼範例示範如何傳送處理要求,然後讀取及輸出欄位至終端機:
Java
詳情請參閱 Document AI Java API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
詳情請參閱 Document AI Node.js API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
詳情請參閱 Document AI Python API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
實體、巢狀實體和正規化值
許多專用處理器會擷取以明確定義的架構為基礎的結構化資料。舉例來說,月結單剖析器會偵測特定欄位,例如 invoice_date
和 supplier_name
。以下是月結單範例:
以下是 月結單剖析器傳回的完整文件物件:
以下是文件物件的一些重要部分:
偵測到的欄位:
Entities
包含處理器可偵測到的欄位,例如invoice_date
:{ "entities": [ { "textAnchor": { "textSegments": [ { "startIndex": "14", "endIndex": "24" } ], "content": "2020/01/01" }, "type": "invoice_date", "confidence": 0.9938466, "pageAnchor": { ... }, "id": "2", "normalizedValue": { "text": "2020-01-01", "dateValue": { "year": 2020, "month": 1, "day": 1 } } } ] }
對於某些欄位,處理器也會將值標準化。在這個範例中,日期已從
2020/01/01
正規化為2020-01-01
。正規化:對於許多支援的特定欄位,處理工具也會正規化值,並傳回
entity
。normalizedValue
欄位會新增至透過每個實體的textAnchor
取得的原始擷取欄位。因此,它會將文字字面值正規化,通常會將文字值分割成子欄位。舉例來說,2024 年 9 月 1 日的日期會以以下格式表示:
normalizedValue": {
"text": "2020-09-01",
"dateValue": {
"year": 2024,
"month": 9,
"day": 1
}
在本例中,日期已從 2020/01/01 標準化為 2020-01-01,這類標準格式可減少後續處理作業,並讓系統將資料轉換為所選格式。
地址也經常會經過標準化處理,將地址元素拆解為個別欄位。將整數或浮點數設為 normalizedValue
,即可將數字正規化。
- 豐富內容:某些處理器和欄位也支援豐富內容。舉例來說,文件
Google Singapore
中的原始supplier_name
已根據 Enterprise Knowledge Graph 規範化為Google Asia Pacific, Singapore
。請注意,由於 Enterprise Knowledge Graph 包含 Google 相關資訊,因此 Document AI 會推斷supplier_address
,即使該字詞並未出現在範例文件中。
{
"entities": [
{
"textAnchor": {
"textSegments": [ ... ],
"content": "Google Singapore"
},
"type": "supplier_name",
"confidence": 0.39170802,
"pageAnchor": { ... },
"id": "12",
"normalizedValue": {
"text": "Google Asia Pacific, Singapore"
}
},
{
"type": "supplier_address",
"id": "17",
"normalizedValue": {
"text": "70 Pasir Panjang Rd #03-71 Mapletree Business City II Singapore 117371",
"addressValue": {
"regionCode": "SG",
"languageCode": "en-US",
"postalCode": "117371",
"addressLines": [
"70 Pasir Panjang Rd",
"#03-71 Mapletree Business City II"
]
}
}
}
]
}
巢狀欄位:如要建立巢狀結構定義 (欄位),請先宣告實體為父項,然後在父項下方建立子項實體。父項的剖析回應會包含父項欄位的
properties
元素中的子欄位。在以下範例中,line_item
是父項欄位,其中包含兩個子項欄位:line_item/description
和line_item/quantity
。{ "entities": [ { "textAnchor": { ... }, "type": "line_item", "confidence": 1.0, "pageAnchor": { ... }, "id": "19", "properties": [ { "textAnchor": { "textSegments": [ ... ], "content": "Tool A" }, "type": "line_item/description", "confidence": 0.3461604, "pageAnchor": { ... }, "id": "20" }, { "textAnchor": { "textSegments": [ ... ], "content": "500" }, "type": "line_item/quantity", "confidence": 0.8077843, "pageAnchor": { ... }, "id": "21", "normalizedValue": { "text": "500" } } ] } ] }
以下剖析器會遵循此規則:
- 擷取 (自訂擷取器)
- 舊版
- 銀行對帳單剖析器
- 費用剖析器
- 應付憑據剖析器
- 薪資單剖析器
- W-2 表單剖析器
程式碼範例
下列程式碼範例示範如何傳送處理要求,然後從專用處理器讀取並列印欄位至終端機:
Java
詳情請參閱 Document AI Java API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
詳情請參閱 Document AI Node.js API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
詳情請參閱 Document AI Python API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
自訂文件擷取器
自訂文件擷取器處理器可從沒有可用預先訓練處理器的文件中擷取自訂實體。您可以透過訓練自訂模型,或使用生成式 AI 基礎模型來擷取命名實體,而無需進行任何訓練。詳情請參閱「在控制台中建立自訂文件擷取器」。
- 如果您訓練自訂模型,處理器的使用方式與預先訓練實體擷取處理器完全相同。
- 如果您使用基礎模型,可以建立處理器版本,為每項要求擷取特定實體,也可以根據個別要求進行設定。
如要瞭解輸出結構,請參閱「實體、巢狀實體和標準化值」。
程式碼範例
如果您使用的是自訂模型,或是使用基礎模型建立的處理器版本,請使用實體擷取程式碼範例。
以下程式碼範例示範如何針對每個要求,為基礎模型的自訂文件擷取器設定特定實體,並列印已擷取的實體:
Python
詳情請參閱 Document AI Python API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
摘要
摘要處理器會使用生成式 AI 基礎模型,總結從文件中擷取的文字。您可以透過下列方式自訂回應的長度和格式:
- 長度
BRIEF
:一或兩句簡短的摘要MODERATE
:段落長度的摘要COMPREHENSIVE
:可用的最長選項
- 格式
您可以為特定長度和格式建立處理器版本,也可以針對個別要求設定處理器版本。
摘要文字會顯示在 Document.entities.normalizedValue.text
中。您可以在「處理器輸出內容範例」中找到完整的輸出 JSON 檔案範例。
詳情請參閱「在控制台中建構文件摘要工具」。
程式碼範例
以下程式碼範例示範如何在處理要求中設定特定長度和格式,並列印摘要文字:
Python
詳情請參閱 Document AI Python API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
分割和分類
以下是包含不同類型文件和表單的 10 頁 PDF 檔案:
以下是 帳款文件分割器和分類器傳回的完整文件物件:
分割器偵測到的每份文件都會以 entity
表示。例如:
{
"entities": [
{
"textAnchor": {
"textSegments": [
{
"startIndex": "13936",
"endIndex": "21108"
}
]
},
"type": "1040se_2020",
"confidence": 0.76257163,
"pageAnchor": {
"pageRefs": [
{
"page": "6"
},
{
"page": "7"
}
]
}
}
]
}
Entity.pageAnchor
表示這份文件有 2 頁。請注意,pageRefs[].page
是以零為基數,也是document.pages[]
欄位的索引。Entity.type
指定此文件為 1040 附表 SE 表單。如需可辨識的完整文件類型清單,請參閱處理器說明文件中的「可辨識的文件類型」。
詳情請參閱「文件分割器行為」。
程式碼範例
分割器會辨識頁面邊界,但不會實際為您分割輸入文件。您可以使用 Document AI Toolbox 透過頁面邊界實際分割 PDF 檔案。下列程式碼範例會在不分割 PDF 的情況下列印頁面範圍:
Java
詳情請參閱 Document AI Java API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
詳情請參閱 Document AI Node.js API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
詳情請參閱 Document AI Python API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Document
頁面邊界,將 PDF 檔案分割。Python
詳情請參閱 Document AI Python API 參考說明文件。
如要向 Document AI 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Document AI Toolbox
Document AI Toolbox 是 Python 專用的 SDK,可提供公用函式,用於管理、操作及擷取文件回應中的資訊。它會根據 Cloud Storage 中 JSON 檔案的處理文件回應、本機 JSON 檔案,或直接從 process_document()
方法輸出內容,建立「包裝」文件物件。
可執行下列動作:
- 將批次處理作業產生的零散
Document
JSON 檔案合併為單一「包裝」文件。 - 將分片匯出為統一的
Document
。 -
取得
Document
輸出內容: - 從
Pages
、Lines
、Paragraphs
、FormFields
和Tables
存取文字,而無需處理Layout
資訊。 - 搜尋包含目標字串或符合規則運算式的
Pages
。 - 依名稱搜尋
FormFields
。 - 依類型搜尋
Entities
。 - 將
Tables
轉換為 Pandas Dataframe 或 CSV。 - 將
Entities
和FormFields
插入 BigQuery 資料表。 - 根據分割器/分類器處理器的輸出內容分割 PDF 檔案。
- 從
Document
定界框中擷取圖片Entities
。 -
將
Documents
轉換為常用的格式,或從常用的格式轉換為Documents
:- Cloud Vision API
AnnotateFileResponse
- hOCR
- 第三方文件處理格式
- Cloud Vision API
- 建立要從 Cloud Storage 資料夾中處理的文件批次。
程式碼範例
以下程式碼範例示範如何使用 Document AI Toolbox。