GSP927

總覽

Document AI API 是文件解讀解決方案，可擷取文件和電子郵件等非結構化資料，方便您解讀、分析及使用。

在本實驗室中，您將建構文件處理管道，自動分析上傳至 Cloud Storage 的文件。這個管道會使用 Cloud Run 函式和 Document AI 表單處理器擷取資料，並儲存至 BigQuery。如果表單包含地址欄位，地址資料會傳送至 Pub/Sub 主題，進而觸發第二個 Cloud Run 函式。這個函式會使用 Geocoding API 新增座標，並將結果寫入 BigQuery。

這個簡單的管道使用一般表單處理器來偵測基本表單資料，例如含標籤的地址欄位。如為較複雜的文件，Document AI 會提供專用剖析器 (超出本實驗室範圍) 來處理。即使文件沒有明確標籤，這類剖析器也能從中擷取詳細資訊。舉例來說，應付憑據剖析器能解讀常見的應付憑據版面，因此可以從無標籤的應付憑據中找出地址和供應商詳細資料。

您將建立的整體解決方案架構如下所示：

1. 將包含地址資料的表單上傳至 Cloud Storage。
2. 上傳作業會觸發 Cloud Run 函式呼叫，來處理表單。
3. 透過 Cloud Run 函式呼叫 Document AI。
4. Document AI JSON 資料存回 Cloud Storage。
5. Cloud Run 函式將表單資料寫入 BigQuery。
6. Cloud Run 函式將地址傳送至 Pub/Sub 主題。
7. Pub/Sub 訊息觸發 Cloud Run 函式，執行地理編碼程序。
8. 透過 Cloud Run 函式呼叫 Geocoding API。
9. Cloud Run 函式將地理編碼資料寫入 BigQuery。

雖然這個範例架構使用 Cloud Run 函式導入簡易管道，但不建議在正式環境採取這種做法，因為 Document AI API 呼叫可能會超過 Cloud Run 函式支援的逾時時間。如需更穩健的無伺服器解決方案，建議使用 Cloud Tasks。

課程內容

本實驗室的內容包括：

• 啟用 Document AI API。
• 部署 Cloud Run 函式來使用 Document AI、BigQuery、Cloud Storage 和 Pub/Sub API。

您要將 Cloud Run 函式設為：

• 在文件上傳至 Cloud Storage 時觸發。
• 使用 Python Document AI 用戶端程式庫。
• 在建立 Pub/Sub 訊息時觸發。

設定和需求

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

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

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

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

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

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

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

注意事項：務必使用實驗室專用的學員帳戶。如果使用其他 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：啟用 API 及建立 API 金鑰

您必須為本實驗室啟用 Document AI API、Cloud Run functions API、Cloud Build API 和 Geocoding API，然後建立 Geocoding Cloud Run 函式所需的 API 金鑰。

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

2. 在 Cloud Shell 輸入下列指令，啟用實驗室所需的 API：

gcloud services enable documentai.googleapis.com gcloud services enable cloudfunctions.googleapis.com gcloud services enable cloudbuild.googleapis.com gcloud services enable geocoding-backend.googleapis.com

3. 前往控制台的「導覽選單」()，依序點選「API 和服務」>「憑證」。

4. 選取「建立憑證」，然後從下拉式選單中選取「API 金鑰」。

「已建立 API 金鑰」對話方塊中會顯示您新建立的金鑰。API 金鑰是一個長字串，其中包含大小寫英文字母、數字和連字號。例如：a4db08b757294ea94c08f2df493465a1。

5. 點選「動作」下方的三點圖示，然後在對話方塊中點選「編輯 API 金鑰」。

6. 在「API 限制」部分選取「限制金鑰」，為新 API 金鑰加上 API 限制。

7. 點按「請選取 API」下拉式選單，然後在篩選器方塊中輸入 Geocoding API。

8. 選取「Geocoding API」，然後點選「確定」。

9. 點選「儲存」按鈕。

注意： 如果在「限制金鑰」下拉式選單中找不到 Geocoding API，請重新整理頁面，更新可用 API 清單。 確認已啟用所有必要的 API。

工作 2：下載實驗室原始碼

在這項工作中，您要將原始碼檔案複製到 Cloud Shell。這些檔案包含 Cloud Run 函式的原始碼，以及您將在實驗室建立的 BigQuery 資料表結構定義。

1. 在 Cloud Shell 中輸入下列指令，下載本實驗室的原始碼：

mkdir ./documentai-pipeline-demo gcloud storage cp -r \ gs://spls/gsp927/documentai-pipeline-demo/* \ ~/documentai-pipeline-demo/

工作 3：建立表單處理器

使用 Document AI Form Parser 專用剖析器，建立要用於 Document AI 平台的一般表單處理器執行個體。一般表單處理器能處理任何類型的文件，並將文件中可辨識的所有文字內容擷取出來。這類處理器支援數種語言，不僅能處理印刷、手寫和以任意方向書寫的文字，還可解讀各項表單資料元素間的關係，協助您針對加上文字標籤的表單欄位擷取鍵/值組合。

1. 在 Google Cloud 控制台搜尋列中輸入 Document AI，然後點選產品頁面搜尋結果。

2. 依序點按「探索處理器」>「Form Parser」，建立新的處理器。

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

4. 點按「建立」即可建立處理器。

在本實驗室的後續步驟，您將使用這個處理器的處理器 ID 和位置設定 Cloud Run 函式，讓 Cloud Run 函式透過這個特定處理器處理範例應付憑據。

工作 4：建立 Cloud Storage bucket 和 BigQuery 資料集

在本節中，您將建立文件處理管道所需的 Google Cloud 資源，為環境做好準備。

建立輸入、輸出和封存 Cloud Storage bucket

為文件處理管道建立輸入、輸出和封存 Cloud Storage bucket。

1. 在 Cloud Shell 輸入下列指令，為實驗室建立 Cloud Storage bucket：

export PROJECT_ID=$(gcloud config get-value core/project) export BUCKET_LOCATION="{{{my_primary_project.default_region|REGION}}}" gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-input-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-output-invoices gsutil mb -c standard -l ${BUCKET_LOCATION} -b on \ gs://${PROJECT_ID}-archived-invoices

建立 BigQuery 資料集和資料表

建立資料處理管道所需的 BigQuery 資料集和三個輸出資料表。

1. 在 Cloud Shell 輸入下列指令，為實驗室建立 BigQuery 資料表：

bq --location="US" mk -d \ --description "Form Parser Results" \ ${PROJECT_ID}:invoice_parser_results cd ~/documentai-pipeline-demo/scripts/table-schema/ bq mk --table \ invoice_parser_results.doc_ai_extracted_entities \ doc_ai_extracted_entities.json bq mk --table \ invoice_parser_results.geocode_details \ geocode_details.json

您可以前往 Cloud 控制台的 BigQuery，並使用 BigQuery SQL 工作區檢查 invoice_parser_results 資料集的資料表結構定義。

建立 Pub/Sub 主題

初始化 Pub/Sub 主題，以便使用該主題觸發處理管道中的 Geocoding API 資料擴充作業。

1. 在 Cloud Shell 輸入下列指令，為實驗室建立 Pub/Sub 主題：

export GEO_CODE_REQUEST_PUBSUB_TOPIC=geocode_request gcloud pubsub topics \ create ${GEO_CODE_REQUEST_PUBSUB_TOPIC} 確認已建立 BigQuery 資料集、Cloud Storage bucket 和 Pub/Sub 主題。

工作 5：建立 Cloud Run 函式

建立兩個 Cloud Run 函式。資料處理管道將使用這些函式處理上傳至 Cloud Storage 的應付憑據。這些函式會透過 Document AI API，從原始文件中擷取地址資訊，然後使用 GeoCode API 擷取這些資訊的相關地理位置資料。

您可以使用程式碼編輯器或所選的任何其他編輯器，檢查這兩個 Cloud Run 函式的原始碼。Cloud Run 函式儲存在下列 Cloud Shell 資料夾：

• Process Invoices - scripts/cloud-functions/process-invoices
• Geocode Addresses - scripts/cloud-functions/geocode-addresses

檔案上傳至先前建立的輸入檔案 Storage bucket 時，會觸發主要 Cloud Run 函式 process-invoices。

函式資料夾 scripts/cloud-functions/process-invoices 包含兩個檔案，用於建立 Cloud Run 函式 process-invoices。

requirements.txt 檔案會指定函式所需的 Python 程式庫，包括 Document AI 用戶端程式庫，以及 Python 程式碼所需的其他 Google Cloud 程式庫。這樣即可從 Cloud Storage 讀取檔案、將資料儲存至 BigQuery，以及將訊息寫入 Pub/Sub，進而觸發解決方案管道中的其餘函式。

Python 檔案 main.py 則包含 Cloud Run 函式程式碼，可建立 Document AI、BigQuery 和 Pub/Sub API 用戶端，以及下列內部函式來處理文件：

• write_to_bq：將字典物件寫入 BigQuery 資料表。請注意，呼叫這個函式前，必須先確保結構定義有效。
• get_text：將表單名稱和值文字錨點對應至文件的掃描文字。這樣一來，函式就能識別特定表單元素 (例如供應商名稱和地址)，並擷取相關值。Document AI 專用處理器會直接在實體屬性中提供脈絡資訊。
• process_invoice：使用非同步 Document-AI 用戶端 API 讀取及處理 Cloud Storage 檔案，如下所示：
  • 建立非同步要求來處理觸發 Cloud Run 函式呼叫的檔案。
  • 處理表單資料，擷取應付憑據欄位且只將預先定義的特定結構定義欄位，儲存在字典中。
  • 發布 Pub/Sub 訊息，觸發 Geocoding Cloud Run 函式來使用擷取自文件的地址表單資料。
  • 將表單資料寫入 BigQuery 資料表。
  • 刪除非同步 Document AI API 呼叫的中繼 (輸出) 檔案。
  • 將輸入檔案複製到封存 bucket。
  • 刪除已處理的輸入檔案。

Cloud Run 函式 process_invoices 只偵測並處理含下列欄位名稱的表單資料：

• input_file_name
• address
• supplier
• invoice_number
• purchase_order
• date
• due_date
• subtotal
• tax
• total

當 Pub/Sub 主題收到新訊息，會觸發另一個 Cloud Run 函式 geocode-addresses，從 Pub/Sub 訊息中擷取參數資料。

建立 Cloud Run 函式，處理上傳至 Cloud Storage 的文件

建立 Cloud Run 函式，使用 Document AI 表單處理器剖析上傳至 Cloud Storage bucket 的表單文件。

1. 執行指令，取得專案的 Cloud Storage 服務代理電子郵件地址：

gcloud storage service-agent --project=$PROJECT_ID

2. 執行下列指令，向 Cloud Storage 服務帳戶授予必要權限：

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") gcloud iam service-accounts create "service-$PROJECT_NUMBER" \ --display-name "Cloud Storage Service Account" || true gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/pubsub.publisher" gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator" 注意：如果已有 Cloud Storage 服務帳戶，可忽略錯誤。

3. 建立 Invoice Processor Cloud Run 函式：

cd ~/documentai-pipeline-demo/scripts export CLOUD_FUNCTION_LOCATION="{{{my_primary_project.default_region|REGION}}}" gcloud functions deploy process-invoices \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_invoice \ --runtime=python39 \ --source=cloud-functions/process-invoices \ --timeout=400 \ --env-vars-file=cloud-functions/process-invoices/.env.yaml \ --trigger-resource=gs://${PROJECT_ID}-input-invoices \ --trigger-event=google.storage.object.finalize 注意：如果指令因權限錯誤而失敗，請稍後再試一次。

建立 Cloud Run 函式，根據地址查詢地理編碼資料

建立 Cloud Run 函式，接受來自 Pub/Sub 訊息的地址資料並使用 Geocoding API 找出精確地址。

1. 建立 Geocoding Cloud Run 函式：

cd ~/documentai-pipeline-demo/scripts gcloud functions deploy geocode-addresses \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_address \ --runtime=python39 \ --source=cloud-functions/geocode-addresses \ --timeout=60 \ --env-vars-file=cloud-functions/geocode-addresses/.env.yaml \ --trigger-topic=${GEO_CODE_REQUEST_PUBSUB_TOPIC}

工作 6：編輯 Cloud Run 函式的環境變數

在這項工作中，您將根據實驗室特定參數，透過 Cloud 控制台編輯各函式的環境變數，完成 Cloud Run 函式設定。

編輯 process-invoices Cloud Run 函式的環境變數

為 process-invoices 函式設定 Cloud Run 函式環境變數。

1. 在 Cloud 控制台搜尋列中輸入 Cloud Run functions，然後點選產品頁面搜尋結果。

系統會將您重新導向至 Cloud Run 控制台。點選「前往 Cloud Run functions (第 1 代)」，即可查看已部署的函式 process-invoices 和 geocode-addresses。

注意：如果沒看到「前往 Cloud Run functions (第 1 代)」連結，請重新整理 Cloud Run 控制台。

2. 點選 Cloud Run 函式「process-invoices」，開啟管理頁面。
3. 點選「編輯」。
4. 點選「執行階段、建構作業、連線和安全性設定」，展開該部分。
5. 在「執行階段環境變數」下方，新增 GCP_PROJECT 變數，並將值設為您的專案 ID。
6. 在「執行階段環境變數」下方，將 PROCESSOR_ID 值更新為先前建立的應付憑據處理器 ID。
7. 在「執行階段環境變數」下方，將 PARSER_LOCATION 值更新為先前建立的應付憑據處理器區域值。這個參數值應是 us 或 eu，且必須為小寫。
8. 點選「下一步」，選取「.env.yaml」，然後將 PROCESSOR_ID、PARSER_LOCATION 和 GCP_PROJECT 值更新為您的應付憑據處理器設定值，與先前一樣。

9. 點選「部署」。

部署 Process Invoices Cloud Run 函式

編輯 geocode-addresses Cloud Run 函式的環境變數

為 GeoCode 資料擴充函式設定 Cloud Run 函式環境變數。

1. 點選 Cloud Run 函式「geocode-addresses」，開啟管理頁面。
2. 點選「編輯」。
3. 點選「執行階段、建構作業、連線和安全性設定」，展開該部分。
4. 在「執行階段環境變數」下方，將 API_key 值更新為您在工作 1 建立的 API 金鑰值。
5. 點選「下一步」，選取「.env.yaml」，然後將 API_key 值更新為您在上一步設定的 API 金鑰值。
6. 點選「部署」。

部署 Geocode Addresses Cloud Run 函式

工作 7：測試並驗證端對端解決方案

將測試資料上傳至 Cloud Storage，並監控管道處理文件及強化擷取資料的進度。

1. 在 Cloud Shell 輸入下列指令，將範例表單上傳至 Cloud Storage bucket，觸發 Cloud Run 函式 process-invoices：

export PROJECT_ID=$(gcloud config get-value core/project) gsutil cp gs://spls/gsp927/documentai-pipeline-demo/sample-files/* gs://${PROJECT_ID}-input-invoices/

2. 在 Cloud 控制台搜尋列中輸入 Cloud Run functions，然後點選產品頁面搜尋結果。
3. 點選 Cloud Run 函式「process-invoices」，開啟管理頁面。
4. 點選「記錄」。

「記錄」部分列出的事件會先說明建立函式建立和環境變數設定更新作業，接著詳細說明處理中的檔案，以及 Document AI 偵測到的資料。

查看事件，直到最終事件指出函式已執行完畢且狀態為 LoadJob。如果系統回報錯誤，請再次檢查上一節的 .env.yaml 檔案參數設定是否正確。請特別確認處理器 ID、位置和專案 ID 是否有效。另外，事件清單不會自動重新整理。

處理完畢後，如果 Document AI 處理器在上傳的文件中偵測到地址資料，BigQuery 資料表就會填入 Document AI 擷取的實體，以及 Geocoding API 提供的增補資料。

開啟 BigQuery 控制台

1. 在 Google Cloud 控制台中，依序選取「導覽選單」>「BigQuery」。

接著，畫面中會顯示「歡迎使用 Cloud 控制台中的 BigQuery」訊息方塊，當中會列出快速入門導覽課程指南的連結和版本資訊。

2. 點選「完成」。

BigQuery 控制台會隨即開啟。

3. 在「Explorer」展開專案 ID。

4. 展開「invoice_parser_results」。

5. 選取「doc_ai_extracted_entities」，然後點按「預覽」。

您會看到應付憑據處理器從應付憑據中擷取的表單資訊，以及偵測到的地址資訊和供應商名稱。

6. 選取「geocode_details」，然後點按「預覽」。

您會看到處理過的應付憑據內含 Document AI 可擷取的地址資料，且每張應付憑據的地址和經緯度皆套用格式。

確認端對端管道已處理表單和地址資料。

恭喜！

您已成功使用 Document AI API 和其他 Google Cloud 服務，建構端對端應付憑據處理管道。在本實驗室中，您學會啟用 Document AI API，以及部署 Cloud Run 函式來使用 Document AI、BigQuery、Cloud Storage 和 Pub/Sub API。此外，您也學會設定兩個 Cloud Run 函式：其中一個函式會在文件上傳至 Cloud Storage 時觸發，另一個函式則會在建立 Pub/Sub 訊息時觸發，並使用 Python Document AI 用戶端程式庫。

後續步驟/瞭解詳情

• 如要進一步瞭解這個表單驗證方法，請參閱指南。

Google Cloud 教育訓練與認證

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

使用手冊上次更新日期：2025 年 8 月 26 日

實驗室上次測試日期：2025 年 7 月 29 日

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