GSP924

總覽

Document AI API 是文件解讀解決方案，可擷取文件和電子郵件等非結構化資料，方便您解讀、分析和使用。本實驗室使用的一般表單處理器，可從簡單的文件中擷取鍵/值組合。

在本實驗室，您將瞭解如何使用 Document AI 建立文件剖析器、透過 Google Cloud 控制台和指令列提交文件進行處理，以及使用 Python 發出同步 API 呼叫。

課程內容

您將瞭解如何執行下列工作：

• 使用控制台建立及測試 Document AI 處理器。
• 使用指令列測試 Document AI 處理器。
• 使用 Python 測試 Document AI 同步 API 呼叫。

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，且中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您將在真正的雲端環境完成實作實驗室活動，而不是模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。

注意事項：請使用無痕模式 (建議選項) 或私密瀏覽視窗執行此實驗室，這可以防止個人帳戶和學員帳戶之間的衝突，避免個人帳戶產生額外費用。

• 是時候完成實驗室活動了！別忘了，活動一旦開始將無法暫停。

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 Google Cloud 帳戶，可能會產生額外費用。

如何開始實驗室及登入 Google Cloud 控制台

1. 按一下「Start Lab」按鈕。如果實驗室會產生費用，請在開啟的對話方塊中選取付款方式。右側的「Lab setup and access」面板會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 此實驗室所需的臨時憑證 (使用者名稱和密碼)
   • 完成此實驗室所需的其他資訊 (如有)

   請注意，實驗室計時器位於頁面頂端附近，會顯示剩餘時間。

2. 按一下「Open Google Cloud console」。如果使用 Chrome 瀏覽器，也可以按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗並排開啟分頁。

   注意：頁面顯示「選擇帳戶」對話方塊時，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab setup and access」面板找到「Username」。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab setup and access」面板找到「Password」。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 繼續點按後續頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請按一下「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

啟動 Cloud Shell

Cloud Shell 是搭載多項開發工具的虛擬機器，提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作。Cloud Shell 提供指令列存取權，方便您使用 Google Cloud 資源。

1. 點按 Google Cloud 控制台頂端的「啟用 Cloud Shell」圖示 。

2. 系統顯示視窗時，請按照下列步驟操作：

   • 繼續操作 Cloud Shell 視窗。
   • 授權 Cloud Shell 使用您的憑證發出 Google Cloud API 呼叫。

連線建立完成即代表已通過驗證，而且專案已設為您的 Project_ID：。輸出內容中有一行文字，宣告本工作階段的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的指令列工具，已預先安裝於 Cloud Shell，並支援 Tab 鍵自動完成功能。

3. (選用) 您可以執行下列指令來列出使用中的帳戶：

gcloud auth list

4. 點按「授權」。

輸出內容：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (選用) 您可以使用下列指令來列出專案 ID：

gcloud config list project

輸出內容：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需 gcloud 的完整說明，請前往 Google Cloud 參閱 gcloud CLI 總覽指南。

工作 1：啟用 Cloud Document AI API

在這項工作中，您將啟用 Document AI API，然後建立及測試一般表單處理器。一般表單處理器能處理任何類型的文件，並將文件中可辨識的所有文字內容擷取出來。這類處理器支援數種語言，不僅能處理印刷、手寫和以任意方向書寫的文字，還可解讀各項表單資料元素間的關係，方便您從含有文字標籤的表單欄位擷取鍵/值組合。

啟用 Cloud Document AI API

您必須先啟用 API，才能使用 Document AI。

1. 依序點選「導覽選單」圖示 >「API 和服務」>「程式庫」。

2. 搜尋「Cloud Document AI API」，然後點選「啟用」按鈕，即可在 Google Cloud 專案中使用這個 API。

如果先前已啟用 Cloud Document AI API，畫面上會顯示「管理」按鈕，表示您可繼續完成後續的實驗室活動。

點選「Check my progress」，確認目標已達成。

已啟用 Cloud Document AI API

工作 2：建立及測試一般表單處理器

接著，您將使用 Document AI 表單剖析器建立 Document AI 處理器。

建立處理器

1. 前往控制台，依序點選「導覽選單」圖示 >「Document AI」>「總覽」。

2. 點選「探索處理器」。

3. 點選「Form Parser」 (一般處理器的一種)。

4. 將處理器名稱設為 form-parser，然後從清單中選取「US (美國)」。

5. 點選「建立」，即可建立 form-parser 處理器。

系統會建立處理器，並返回處理器詳細資料頁面，當中會顯示處理器 ID、狀態和預測端點。

6. 記下處理器 ID，以便在後續工作搭配使用 curl 對 API 發出 POST 呼叫。

下載範例表單

在這項工作中，您將從 Cloud Storage 下載範例表單。下一個工作需要上傳這份表單，因此請先將表單下載到本機電腦。

1. 將 form.pdf 檔案下載至本機電腦。

檔案應該會直接下載到本機；如果在瀏覽器中開啟，請使用瀏覽器的檔案控制項下載檔案。form.pdf 檔案是一份健康資料登記表，內含手寫範例資料。

上傳表單以供 Document AI 處理

接著，您要將下載的範例表單上傳至 form-parser 處理器。系統會分析檔案，並在控制台顯示結果。

1. 在「form-parser」頁面，點選「上傳測試文件」按鈕，然後在彈出的對話方塊中，選取在上一項工作下載的檔案並上傳。

進度列會顯示分析程序的完成程度，完成後就會顯示結果。您會看到一般處理器已擷取表單中的資料，並轉換為一組鍵/值組合。

控制台會顯示從來源文件剖析出的鍵/值組合。左側窗格會列出資料，右側窗格則會以藍色矩形標示資料在已剖析文件中的原始位置。檢查輸出內容，並比對結果與來源資料。

在這項工作中，您將從指令列發出 API 呼叫，測試 Document AI 一般表單處理器。

點選「Check my progress」，確認目標已達成。

建立及測試一般表單處理器

工作 3：設定實驗室執行個體

在本節中，您將設定實驗室執行個體，以使用 Document AI API。

透過 SSH 連線到實驗室 VM 執行個體

您將在名為 document-ai-dev 的實驗室 VM 中完成其餘實驗室工作。

1. 依序點選「導覽選單」圖示 >「Compute Engine」>「VM 執行個體」。

2. 點選 VM 執行個體「document-ai-dev」的「SSH」連結。

這個步驟需使用您在工作 1 建立的 Document AI 處理器 ID。如果剛才未記下，請在 Cloud 控制台分頁執行下列操作：

• 開啟導覽選單 ()。
• 依序點選「Document AI」>「處理器」。
• 點選處理器名稱，開啟詳細資料頁面。
• 在顯示的頁面中複製處理器 ID。

3. 在 SSH 工作階段中，建立環境變數來儲存 Document AI 處理器 ID。您必須將 [your processor id] 預留位置文字改成自己的處理器 ID：

export PROCESSOR_ID=[your processor id]

4. 在 SSH 工作階段中，確認環境變數包含 Document AI 處理器 ID：

echo Your processor ID is:$PROCESSOR_ID

5. 系統應該會輸出類似以下內容的處理器 ID：

Your processor ID is:4897d834d2f4415d

本實驗室的後續步驟都會用到這個 SSH 工作階段。

驗證 API 要求

您必須提供有效的憑證，才能向 Document AI API 發出要求。在這項工作中，您將建立服務帳戶，並將授予該服務帳戶的權限限制為實驗室所需的權限，然後為該帳戶產生憑證，用於驗證 Document AI API 要求。

1. 使用專案 ID 設定環境變數；本實驗室全程都會用到這個環境變數：

export PROJECT_ID=$(gcloud config get-value core/project)

2. 使用下列指令建立新的服務帳戶，以存取 Document AI API：

export SA_NAME="document-ai-service-account" gcloud iam service-accounts create $SA_NAME --display-name $SA_NAME

3. 將服務帳戶繫結至 Document AI API 使用者角色：

gcloud projects add-iam-policy-binding ${PROJECT_ID} \ --member="serviceAccount:$SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com" \ --role="roles/documentai.apiUser"

4. 建立供新服務帳戶登入的憑證，並將憑證儲存至工作目錄中名為 key.json 的 JSON 檔案：

gcloud iam service-accounts keys create key.json \ --iam-account $SA_NAME@${PROJECT_ID}.iam.gserviceaccount.com

5. 設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數並指向憑證檔案，程式庫會使用這個變數尋找您的憑證：

export GOOGLE_APPLICATION_CREDENTIALS="$PWD/key.json"

6. 確認 GOOGLE_APPLICATION_CREDENTIALS 環境變數已設為先前建立的 JSON 憑證檔案完整路徑：

echo $GOOGLE_APPLICATION_CREDENTIALS

gcloud 指令列工具會使用這個環境變數，指定執行指令時要使用的憑證。如要進一步瞭解這種驗證方式，請參閱應用程式預設憑證指南。

將範例表單下載至 VM 執行個體

現在您可以下載範例表單，然後以 Base64 編碼再提交至 Document AI API。

1. 在 SSH 視窗中輸入下列指令，將範例表單下載至工作目錄：

gsutil cp gs://spls/gsp924/health-intake-form.pdf .

2. 建立 JSON 要求檔案，提交 Base64 編碼的表單以供處理：

echo '{"inlineDocument": {"mimeType": "application/pdf","content": "' > temp.json base64 health-intake-form.pdf >> temp.json echo '"}}' >> temp.json cat temp.json | tr -d \\n > request.json

點選「Check my progress」，確認目標已達成。

驗證 API 要求並下載範例表單

工作 4：使用 curl 發出同步處理文件要求

在這項工作中，您將使用 curl 呼叫同步 Document AI API 端點，處理範例文件。

1. 透過 curl 提交表單以供處理。結果會儲存在 output.json 檔案：

export LOCATION="us" export PROJECT_ID=$(gcloud config get-value core/project) curl -X POST \ -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ https://${LOCATION}-documentai.googleapis.com/v1beta3/projects/${PROJECT_ID}/locations/${LOCATION}/processors/${PROCESSOR_ID}:process > output.json

2. 確認 output.json 檔案包含 API 呼叫結果：

cat output.json 如果收到驗證錯誤，請確認已將 GOOGLE_APPLICATION_CREDENTIALS 環境變數設為指向先前建立的憑證 JSON 檔案。IAM 政策可能需要幾分鐘才會生效，如果收到錯誤訊息，請稍後再試。

Cloud IAM 服務帳戶的存取權杖會即時產生，並透過 Authorization: HTTP 標頭傳遞至 API。回應包含 JSON 格式的資料，該資料會儲存至 output.json 檔案。

擷取表單實體

接著來看看從範例表單擷取的資訊。

1. 使用下列指令，擷取在文件中偵測到的原始文字：

sudo apt-get update sudo apt-get install jq cat output.json | jq -r ".document.text"

輸出內容會列出在上傳文件中偵測到的所有文字。

2. 擷取表單處理器偵測到的表單欄位清單：

cat output.json | jq -r ".document.pages[].formFields"

輸出內容會列出文件中偵測到的所有表單欄位的物件資料。您可以使用每個表單的 textAnchor.startIndex 和 textAnchor.endIndex 值，在 document.text 欄位中找出偵測到的表單名稱。下一項工作會用到的 Python 指令碼，可為您完成這項對應作業。

JSON 檔案相當大，因為其中包含以 Base64 編碼的來源文件，以及所有偵測到的文字和文件屬性。如要查看 JSON 檔案，可以用文字編輯器開啟，或使用 jq 等 JSON 查詢工具。

確認 Document AI API 已處理文件。

工作 5：使用 Python 用戶端程式庫測試 Document AI 表單處理器

使用 Python Document AI 用戶端程式庫，對 Document AI API 發出同步呼叫。

現在，您要使用同步端點處理文件。使用非同步 API，即可一次處理大量文件。如要進一步瞭解如何使用 Document AI API，請參閱這份指南。

如要直接執行 Python 指令碼，必須提供適當憑證，才能使用已設定正確權限的服務帳戶，對 API 發出呼叫。如要進一步瞭解如何設定這種驗證方式，請參閱「以服務帳戶進行驗證」說明文件。

設定 VM 執行個體以使用 Document AI Python 用戶端

現在要將 Python Google Cloud 用戶端程式庫安裝至 VM 執行個體。

1. 在 SSH 終端機殼層輸入下列指令，將實驗室檔案匯入 VM 執行個體：

gsutil cp gs://spls/gsp924/synchronous_doc_ai.py .

2. 輸入下列指令，安裝 Document AI 需要用到的 Python 用戶端程式庫，以及本實驗室所需的其他程式庫：

sudo apt install python3-pip python3 -m pip install --upgrade google-cloud-documentai google-cloud-storage prettytable

如果出現「Do you want to continue? (Y/n)」這個提示訊息，請輸入 Y。

輸出內容應該會指出程式庫已安裝成功。

查看 Document AI API Python 程式碼

請花點時間檢查範例檔案中的 Python 程式碼。您可以使用 vi 或 nano 等編輯器，在 SSH 工作階段中查看程式碼，也可以使用前一節的指令，將範例程式碼複製到 Cloud Shell，然後使用程式碼編輯器查看原始碼。

1. 前兩個程式碼區塊會匯入必要的程式庫，並剖析參數來初始化變數，用於識別 Document AI 處理器和輸入資料。

import argparse from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage from prettytable import PrettyTable parser = argparse.ArgumentParser() parser.add_argument("-P", "--project_id", help="Google Cloud Project ID") parser.add_argument("-D", "--processor_id", help="Document AI Processor ID") parser.add_argument("-F", "--file_name", help="Input file name", default="form.pdf") parser.add_argument("-L", "--location", help="Processor Location", default="us") args = parser.parse_args()

2. process_document 函式可對 Document AI 處理器發出同步呼叫。這個函式會建立 Document AI API 用戶端物件。

API 呼叫所需的處理器名稱會透過 project_id、location 和 processor_id 這些參數建立，接著會讀取要處理的文件，並以 mime_type 結構儲存該文件。

隨後會將處理器名稱和文件傳遞至 Document AI API 用戶端物件，並發出同步 API 呼叫。如果要求順利完成，處理器將傳回文件物件，當中的屬性包含 Document AI 處理器偵測到的資料。

def process_document(project_id, location, processor_id, file_path ): # 建立用戶端執行個體 client = documentai.DocumentProcessorServiceClient() # 處理器的完整資源名稱，例如： # projects/project-id/locations/location/processor/processor-id # 您必須先在 Cloud 控制台建立新的處理器 name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" # 將檔案載入記憶體 with open(file_path, "rb") as image: image_content = image.read() # 建立文件物件 document = {"content": image_content, "mime_type": "application/pdf"} # 設定處理要求 request = {"name": name, "document": document} # 使用 Document AI 用戶端同步端點處理要求 result = client.process_document(request=request) return result.document

3. 接著，指令碼會使用必要參數呼叫 process_document 函式，並將回應儲存在 document 變數中。

document = process_document(args.project_id,args.location,args.processor_id,args.file_name )

4. 最後一個程式碼區塊會輸出 .text 屬性，其中包含在文件中偵測到的所有文字，並使用表單剖析器偵測到的每個表單欄位的文字錨點資料，來顯示表單資訊。

print("Document processing complete.") # 輸出原始文字 print("Text: \n{}\n".format(document.text)) # 定義函式來擷取具名元素的物件字典 def get_text(doc_element: dict, document: dict): """ Document AI 會根據文件文字中的偏移位置來識別表單欄位。這個函式會將偏移位置轉換為文字片段。 """ response = "" # 如果某個文字區段跨越多行， # 其內容就會儲存於不同的文字區段中。 for segment in doc_element.text_anchor.text_segments: start_index = ( int(segment.start_index) if segment in doc_element.text_anchor.text_segments else 0 ) end_index = int(segment.end_index) response += document.text[start_index:end_index] return response # 擷取每個鍵/值組合及其對應的可信度分數。 document_pages = document.pages print("Form data detected:\n") # 擷取每一頁的每個表單欄位，並顯示欄位名稱、值和可信度分數 for page in document_pages: print("Page Number:{}".format(page.page_number)) for form_field in page.form_fields: fieldName=get_text(form_field.field_name,document) nameConfidence = round(form_field.field_name.confidence,4) fieldValue = get_text(form_field.field_value,document) valueConfidence = round(form_field.field_value.confidence,4) print(fieldName+fieldValue +" (Confidence Scores: (Name) "+str(nameConfidence)+", (Value) "+str(valueConfidence)+")\n")

點選「Check my progress」，確認目標已達成。

測試 Document AI 表單處理器

工作 6：執行 Document AI Python 程式碼

執行程式碼範例，並處理與先前相同的檔案。

1. 為專案 ID 和 IAM 服務帳戶憑證檔案建立環境變數：

export PROJECT_ID=$(gcloud config get-value core/project) export GOOGLE_APPLICATION_CREDENTIALS="$PWD/key.json"

2. 使用所需參數呼叫 synchronous_doc_ai.py Python 程式：

python3 synchronous_doc_ai.py \ --project_id=$PROJECT_ID \ --processor_id=$PROCESSOR_ID \ --location=us \ --file_name=health-intake-form.pdf | tee results.txt

您會看到以下這段文字輸出內容： FakeDoc M.D. HEALTH INTAKE FORM Please fill out the questionnaire carefully. The information you provide will be used to complete your health profile and will be kept confidential. Date: Sally Walker Name: 9/14/19 ...

第一段文字是單一文字元素，包含文件中的所有文字。這段文字無法辨識表單型資料，因此 Date 和 Name 等項目會混雜在原始文字值中。

接著，程式碼會使用 form-parser 從文件結構推論出的表單資料，輸出結構更完整的資料檢視畫面。這項結構化輸出內容也包含表單欄位名稱和值的可信度分數。這個部分輸出的內容，會更清楚呈現表單欄位名稱與值的對應關係，例如 Date 和 Name 表單欄位與正確值的連結。

Form data detected: Page Number:1 Phone #: (906) 917-3486 (Confidence Scores: (Name) 1.0, (Value) 1.0) ... Date: 9/14/19 (Confidence Scores: (Name) 0.9999, (Value) 0.9999) ... Name: Sally Walker (Confidence Scores: (Name) 0.9973, (Value) 0.9973) ...

點選「Check my progress」，確認目標已達成。

執行 Document AI Python 程式碼

恭喜！

您已成功透過 Document AI API，使用一般表單處理器從文件中擷取資料。在本實驗室中，您使用控制台和指令列建立並測試了 Document AI 處理器，並透過 Python 發出 Document AI 同步 API 呼叫。

後續步驟/瞭解詳情

• 詳情請參閱 Cloud Document AI API 說明文件。

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2026 年 3 月 10 日

實驗室上次測試日期：2026 年 3 月 10 日

Copyright 2026 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。