控管處理回應
處理要求的回應中會包含 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
都對應到範例文件中的實體頁面。由於是單一 PNG 圖片,因此 JSON 輸出範例只包含一頁。
{
"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
,請從一個頂點繪製線段到下一個頂點。 然後從最後一個頂點畫回第一個頂點,封閉多邊形。版面配置的方向元素會指出文字是否已相對於頁面旋轉。
為協助您瞭解文件結構,下列圖片會繪製 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)。請注意,KVP 與其他擷取器中的 (結構定義) 實體不同:
設定實體名稱。KVPs 中的鍵值就是文件上的鍵值文字。
{
"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 中的核取方塊數位化為鍵/值組合。提供核取方塊數位化的範例,做為鍵/值組合。
在表格以外,核取方塊會以表單剖析器中的視覺元素表示。 在 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
。
- 擴充:部分處理器和欄位也支援擴充。
舉例來說,文件中的原始
supplier_name
「Google Singapore
」已根據 Enterprise Knowledge Graph 正規化為「Google Asia Pacific, Singapore
」。此外,由於 Enterprise Knowledge Graph 包含 Google 的相關資訊,即使範例文件中沒有supplier_address
,Document AI 仍會推斷出這項資訊。
{
"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" } } ] } ] }
下列剖析器會遵循這項規則:
- 擷取 (Custom Extractor)
- 舊版
- 銀行對帳單剖析器
- 費用剖析器
- 應付憑據剖析器
- 薪資單剖析器
- 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 Schedule SE 表單。如需可辨識的文件類型完整清單,請參閱處理器說明文件中的「可辨識的文件類型」。
詳情請參閱「文件分割器行為」。
程式碼範例
分割器會識別頁面邊界,但不會實際分割輸入文件。您可以使用 Document AI 工具箱,依據頁面界線實際分割 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 工具箱
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
轉換為常用格式,或從常用格式轉換:- Cloud Vision API
AnnotateFileResponse
- hOCR
- 第三方文件處理格式
- Cloud Vision API
- 從 Cloud Storage 資料夾建立要處理的文件批次。
程式碼範例
下列程式碼範例說明如何使用 Document AI Toolbox。