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 時觸發。
• 使用 Document AI 的 Python 用戶端程式庫。
• 在建立 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，然後建立地理編碼 Cloud Run 函式所需的 API 金鑰。

1. 在 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

2. 在控制台依序點按「導覽選單」圖示 >「API 和服務」>「憑證」。

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

4. 在「建立 API 金鑰」側邊面板的「可透過這個金鑰存取的 API」部分，點按「選取 API」下拉式選單。

5. 搜尋或捲動畫面並找到「Geocoding API」，然後勾選核取方塊。

注意： 如果在「選取 API 限制」下拉式選單中找不到「Geocoding API」，請重新整理頁面，更新可用 API 清單。

6. 點按「確定」。

7. 點按「建立」。

8. 複製系統產生的 API 金鑰，然後點按「關閉」。

確認所有必要的 API 皆已啟用。

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

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

• 在 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. 在「總覽」頁面，點按「探索處理器」。

3. 點按「Form Parser」(列於「一般」處理器部分)。

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

5. 點按「建立」以建立處理器。

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

6. 複製 form-processor 的 ID 和區域，供後續工作使用。

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

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

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

建立文件處理管道會用到的輸入、輸出和封存 Cloud Storage bucket。

• 在 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 資料集和三個輸出資料表。

• 在 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 data enrichment 作業。

• 在 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 資料夾：

• 處理應付憑據：scripts/cloud-functions/process-invoices
• 為地址進行地理編碼：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 則包含可建立 Document AI、BigQuery 和 Pub/Sub API 用戶端的 Cloud Run 函式程式碼，以及下列用於處理文件的內部函式：

• write_to_bq：將字典物件寫入 BigQuery 資料表。請注意，呼叫這個函式前，必須先確認結構定義有效。
• get_text：將表單名稱和值文字錨點對應至已掃描的文件文字。這樣一來，函式就能識別特定表單元素 (例如供應商名稱和地址)，並擷取相關值。專用的 Document AI 處理器會直接在實體屬性中提供脈絡資訊。
• process_invoice：使用非同步 Document-AI 用戶端 API 讀取及處理 Cloud Storage 中的檔案，流程如下：
  • 建立非同步要求來處理觸發 Cloud Run 函式呼叫的檔案。
  • 處理表單資料，擷取應付憑據欄位，且只將預先定義的特定結構定義欄位儲存在字典中。
  • 發布 Pub/Sub 訊息，觸發地理編碼 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. 建立應付憑據處理器 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=python312 \ --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 找出該地址的確切位置。

• 建立地理編碼 Cloud Run 函式：

cd ~/documentai-pipeline-demo/scripts gcloud functions deploy geocode-addresses \ --no-gen2 \ --region=${CLOUD_FUNCTION_LOCATION} \ --entry-point=process_address \ --runtime=python312 \ --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 函式設定。

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

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

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

2. 前往 Cloud Run 控制台的「服務」，然後點按「前往 Cloud Run functions (第 1 代)」，即可查看已部署的函式 process-invoices 和 geocode-addresses。

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

3. 點按 Cloud Run 函式「process-invoices」，開啟管理頁面。

4. 點按「編輯」。

5. 點按「執行階段、建構作業、連線和安全性設定」，展開該區塊。

6. 在「執行階段環境變數」底下，點按「新增變數」。

7. 在「名稱」中輸入 GCP_PROJECT，在「值」中輸入：

8. 在「執行階段環境變數」底下，將 PROCESSOR_ID 值更新為您在工作 3 建立的應付憑據處理器 ID。

9. 在「執行階段環境變數」底下，將 PARSER_LOCATION 值更新為您在工作 3 建立的應付憑據處理器區域值。

注意：這個位置參數值應是 us 或 eu，且必須使用小寫字母。

10. 點按「下一步」，然後選取 .env.yaml 。

11. 使用與步驟 7 相同的值新增 GCP_PROJECT，以及與步驟 8 至 9 相同的值更新應付憑據處理器的 PROCESSOR_ID 和 PARSER_LOCATION。

12. 點按「部署」。

部署應付憑據處理器 Cloud Run 函式

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

為 GeoCode data enrichment 函式設定 Cloud Run 函式環境變數。

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

部署為地址進行地理編碼的 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，然後點按 Cloud Run functions 的產品和頁面搜尋結果。

3. 前往「服務」並點按「前往 Cloud Run functions (第 1 代)」，然後點按名為「process-invoices」的 Cloud Run 函式，開啟管理頁面。

4. 點按「記錄」。

「記錄」部分會列出與函式建立和環境變數設定更新相關的事件，還有處理中的檔案和 Document AI 偵測到的資料等細節。

5. 點按「重新整理」以更新記錄檔，直到出現最終事件，指出函式已執行完畢，並以 LoadJob 結束。

如果記錄檔回報錯誤，請檢查上一節的 .env.yaml 檔案參數設定是否正確，

尤其記得檢查處理器 ID 和位置 (應一律為小寫 us 或 eu) 與您在工作 3 建立處理器時設定的值相同，且專案 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 時觸發，另一個則會使用 Document AI 的 Python 用戶端程式庫，並在 Pub/Sub 訊息建立時觸發。

後續步驟/瞭解詳情

• 請參閱這份指南，進一步瞭解這種驗證方式。

Google Cloud 教育訓練與認證

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

使用手冊上次更新日期：2026 年 6 月 16 日

實驗室上次測試日期：2026 年 6 月 16 日

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