使用非結構化資料的探索掃描功能

掃描非結構化資料的資料剖析檔時,系統會在 Cloud Storage 探索掃描期間使用 Vertex AI Gemini 2.5 Pro 模型,將 Cloud Storage 中的原始非結構化檔案 (例如 PDF) 轉換為 BigQuery 中可查詢的結構化資產。這項自動化工作流程專為從 Cloud Storage 原始檔案開始作業的使用者設計。如果您已有現成的 BigQuery 物件資料表,或想使用自訂提示引導擷取作業,請參閱「使用資料剖析功能處理非結構化資料」。

本文說明如何設定必要權限、準備非結構化檔案、使用 REST API 建立啟用語意推論的 Cloud Storage 探索掃描、查看產生的洞察資料、管理圖表設定檔,以及將資料擷取至 BigQuery。

事前準備

建立探索掃描前,請確認您具備必要的權限,並已啟用 API。

啟用 API

在專案中啟用下列 API:

  • dataplex.googleapis.com
  • bigquery.googleapis.com
  • aiplatform.googleapis.com (Vertex AI)

啟用 API 時所需的角色

如要啟用 API,您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin),其中包含 serviceusage.services.enable 權限。瞭解如何授予角色

啟用 API

必要角色和權限

如要設定及執行非結構化資料的資料剖析檔掃描,您必須符合探索掃描的基準權限,然後授予多個服務代理程式的語意推論額外角色。

基準探索掃描角色

請確認您和 Knowledge Catalog 使用的服務帳戶,都具備標準探索掃描作業所需的基準權限。如需完整清單,請參閱「探索及編目 Cloud Storage 資料」。

語意推論的其他角色

除了基本探索角色外,請確認您和服務帳戶具備下列額外的 Identity and Access Management (IAM) 角色。

其他身分和角色摘要

身分類型 主體格式範例 必要的 IAM 角色 核心用途
使用者 您的 Google Cloud 使用者帳戶
  • Dataplex DataScan 編輯者
  • Dataplex Catalog 編輯者
  • BigQuery 資料編輯者
  • BigQuery 工作使用者
您可以使用這些額外角色設定掃描、查看 AI 生成的結果、管理圖表剖析檔,以及觸發最終資料擷取作業。
Dataplex Universal Catalog 探索代理程式 service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com
  • Agent Platform 使用者
  • BigQuery 工作使用者
  • BigQuery 資料檢視者
這個由 Google 管理的服務代理會使用這些額外角色呼叫 Vertex AI,以生成推斷的結構定義和中繼資料。
BigQuery 連線服務帳戶 與連線相關聯的專屬 ID (例如 bqcx-<var>PROJECT_NUMBER</var>-<var>ID</var>@gcp-sa-bigquery-condel.iam.gserviceaccount.com)
  • Storage 物件檢視者 (來源 bucket)
  • Agent Platform 使用者 (專案)
這項功能可將 BigQuery 連線至外部儲存空間,讓 BigQuery 讀取原始檔案、建立物件資料表,以及執行 AI 推論,不必公開您的個人使用者憑證。
管道執行服務帳戶 (選用) 使用者自行管理的服務帳戶
  • BigQuery 資料編輯者
  • BigQuery 工作使用者
  • BigQuery 使用者
  • Agent Platform 使用者
如果您選擇使用自動化管道擷取資料,這個身分會執行背景作業,將 AI 生成的實體具體化至 BigQuery 資料表。
預設 Dataform 服務帳戶 (選用) service-<var>PROJECT_NUMBER</var>@gcp-sa-dataform.iam.gserviceaccount.com
  • 服務帳戶憑證建立者 (在管道執行服務帳戶上授予)
使用管道擷取方法時,Dataform 需要管道執行服務帳戶的模擬權限,才能協調工作流程。

一般使用者角色和權限

<0x0A

為確保您的使用者帳戶具備必要權限,能建立掃描、查看洞察資料、管理圖表設定檔及擷取資料,請要求管理員將專案的下列 IAM 角色授予您的使用者帳戶:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備建立掃描作業、查看洞察資料、管理圖表剖析檔,以及擷取資料所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

如要建立掃描作業、查看洞察資料、管理圖表設定檔及擷取資料,必須具備下列權限:

  • DataScans:
    • dataplex.datascans.create
    • dataplex.datascans.get
    • dataplex.datascans.getData
    • dataplex.datascans.list
    • dataplex.datascans.update
  • 資料擷取:
    • bigquery.tables.create
    • bigquery.tables.update
    • bigquery.tables.getData
    • bigquery.jobs.create

管理員或許還可透過自訂角色或其他預先定義的角色,將這些權限授予您的使用者帳戶。

Dataplex Discovery 服務代理角色和權限

Dataplex 探索服務代理是服務代理,需要存取權才能執行掃描,並使用 Vertex AI 進行語意推論。

為確保 Dataplex 探索服務代理程式 (通常為 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) 具備必要權限,能使用 Vertex AI 執行掃描和語意推論,請要求管理員在專案中,將下列 IAM 角色授予 Dataplex 探索服務代理程式 (通常為 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com):

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備使用 Vertex AI 執行掃描和語意推論所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

如要使用 Vertex AI 執行掃描和語意推論,必須具備下列權限:

  • 全部:
    • aiplatform.endpoints.predict
    • bigquery.datasets.create
    • bigquery.datasets.get
    • bigquery.tables.get
    • bigquery.tables.getData
    • storage.buckets.get
    • storage.objects.get
    • storage.objects.list

管理員或許還可透過自訂角色或其他預先定義的角色,將這些權限授予 Dataplex 探索服務代理 (通常為 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)。

BigQuery 連線服務帳戶角色和權限

透過 BigQuery Cloud 資源連線,Knowledge Catalog 就能存取儲存在 Cloud Storage 中的非結構化資料。建立連線時,BigQuery 會自動為您建立專屬服務帳戶。這個服務帳戶是連線至外部資料來源時使用的身分。

根據預設,這個服務帳戶沒有任何權限。您必須明確授予這個服務帳戶,在含有資料的 Cloud Storage bucket 中所需的 IAM 角色。您可以使用現有的 BigQuery 連線,或在與來源 Cloud Storage bucket 相同的位置建立新連線。如要進一步瞭解如何共用連線,請參閱「與使用者共用連線」。

為確保 BigQuery 連線服務帳戶 (從連線詳細資料的「連線資訊」部分擷取 ID) 具備讀取物件資料表和執行推論的必要權限,請要求管理員將下列 IAM 角色授予 BigQuery 連線服務帳戶 (從連線詳細資料的「連線資訊」部分擷取 ID):

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備讀取物件表格及執行推論所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

如要讀取物件表格及執行推論,必須具備下列權限:

  • 全部:
    • storage.buckets.get 包含非結構化資料的 bucket
    • storage.objects.get 包含非結構化資料的 bucket
    • 專案的 aiplatform.endpoints.predict

管理員或許還可透過自訂角色或其他預先定義的角色,將這些權限授予 BigQuery 連線服務帳戶 (從連線詳細資料的「連線資訊」部分擷取 ID)。

管道執行服務帳戶角色和權限 (選用)

如果您選擇使用自動化管道擷取推論資料,就必須建立或提供專屬服務帳戶來執行管道。這個執行服務帳戶會做為身分,在 BigQuery 中驗證及執行背景資料擷取和分析工作。此外,您必須授予預設 Dataform 服務帳戶權限,才能模擬這個執行服務帳戶。

為確保 pipeline 執行服務帳戶具備必要權限,能使用 pipeline 擷取推斷的實體和關係,請要求管理員在專案中,將下列 IAM 角色授予 pipeline 執行服務帳戶:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備使用管道擷取推斷實體和關係所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

如要使用管道擷取推斷的實體和關係,必須具備下列權限:

  • 全部:
    • bigquery.tables.create
    • bigquery.tables.update
    • bigquery.tables.get
    • bigquery.tables.getData
    • bigquery.jobs.create
    • aiplatform.endpoints.predict

管理員或許還可透過自訂角色或其他預先定義的角色,授予 pipeline 執行服務帳戶這些權限。

為確保預設 Dataform 服務帳戶 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) 具備模擬管道執行服務帳戶的必要權限,請要求管理員在管道執行服務帳戶中,將下列 IAM 角色授予預設 Dataform 服務帳戶 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com):

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備模擬 pipeline 執行服務帳戶所需的權限。如要查看確切的必要權限,請展開「Required permissions」(必要權限) 部分:

所需權限

如要模擬 pipeline 執行服務帳戶,必須具備下列權限:

  • 全部: iam.serviceAccounts.getAccessToken

管理員或許還可透過自訂角色或其他預先定義的角色,將這些權限授予預設 Dataform 服務帳戶 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)。


準備非結構化資料

執行探索掃描前,您必須將非結構化資料上傳至 Cloud Storage 值區。非結構化資料的資料剖析掃描功能經過最佳化,可分析 PDF 文件。

如要進一步瞭解如何在 Cloud Storage 中儲存及管理檔案,請參閱「上傳物件」一文。

建立 Cloud 資源連線

如要將探索掃描結果發布為 BigQuery 物件資料表,您必須建立 Cloud 資源連線,並授予其服務帳戶存取 Cloud Storage 中非結構化資料的權限。

  1. 建立 Cloud 資源連線
  2. 在包含非結構化資料的 Cloud Storage bucket 中,將「Storage 物件檢視者」(roles/storage.objectViewer) 角色授予與連線相關聯的服務帳戶。詳情請參閱「授予服務帳戶存取權」。

為非結構化資料建立探索掃描作業

如要從非結構化資料中擷取語意洞察,您必須先建立 Cloud Storage 探索掃描。這項掃描作業會自動找出 Cloud Storage 中的非結構化檔案,並將這些檔案編目至物件資料表。在此程序中啟用語意推論功能後,Knowledge Catalog 會使用 Vertex AI Gemini 2.5 Pro 模型分析檔案,並生成推論的中繼資料、結構定義和關係。

您可以使用 Google Cloud 控制台或 REST API,建立啟用語意推論功能的 Cloud Storage 探索掃描。

控制台

  1. 前往 Google Cloud 控制台的「Metadata curation」(中繼資料管理) 頁面。

    前往「中繼資料彙整」頁面

  2. 在「Cloud Storage discovery」(Cloud Storage 探索) 分頁中,按一下「Create」(建立)

  3. 輸入掃描名稱。

  4. 如要選取包含非結構化資料的 Cloud Storage bucket,請按一下「瀏覽」

  5. 在「非結構化資料選項」部分,選取「啟用語意推論」核取方塊。

  6. 在「連線 ID」欄位中,指定用於存取檔案的 BigQuery 連線。

    探索掃描作業會建立物件資料表,自動將非結構化資料編入 BigQuery 目錄。由於物件資料表會安全地將資料存取憑證與執行查詢的使用者分離,因此需要連線才能向 Cloud Storage 驗證身分並讀取檔案。

  7. 按一下「立即執行」 (執行隨選掃描) 或「建立」 (執行排程掃描)。

    如要瞭解所有可用的設定,請參閱「探索及編目 Cloud Storage 資料」。

Knowledge Catalog 會建立物件資料表,並使用 AI 生成的中繼資料擴充目錄項目。如果是標準資料集,這項程序通常只需要幾分鐘。

REST

如要使用 REST API 建立啟用語意推論功能的 Cloud Storage 探索掃描,請使用 dataScans.create 方法和 dataDiscoverySpec

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?dataScanId=DATASCAN
{
"description": "Cloud Storage discovery scan with semantic inference",
"data": {
"resource": "//storage.googleapis.com/BUCKET_NAME"
},
"executionSpec": {
"trigger": {
  "onDemand": {}
}
},
"dataDiscoverySpec": {
"bigqueryPublishingConfig": {
  "tableType": "OBJECT_TABLE",
  "connection": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID"
},
"unstructuredDataEventsConfig": {
  "enabled": true
}
}
}

更改下列內容:

  • PROJECT_ID:專案的 ID。 Google Cloud
  • LOCATION:區域 (必須支援 Gemini 2.5 Pro)。 Google Cloud
  • DATASCAN:探索掃描的名稱。
  • BUCKET_NAME:包含非結構化資料的 Cloud Storage bucket。
  • CONNECTION_ID:BigQuery 連線 ID。

執行探索掃描

如果將探索掃描設定為隨選執行,您必須手動觸發掃描,才能找出非結構化資料並產生洞察資訊。

您可以使用 Google Cloud 控制台或 REST API 觸發探索掃描。

控制台

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」頁面

  2. 在導覽選單中,依序點選「治理」>「中繼資料管理」。

  3. 在「Cloud Storage discovery」窗格中,按一下要執行的探索掃描。

  4. 按一下「立即執行」

REST

如要使用 REST API 執行隨選探索掃描,請使用 dataScans.run 方法:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN:run"

請替換下列變數:

  • PROJECT_ID:專案的 ID。 Google Cloud
  • LOCATION:探索掃描所在的 Google Cloud 區域。
  • DATASCAN:探索掃描的名稱。

Knowledge Catalog 會執行探索掃描、建立物件資料表,並使用 AI 生成的中繼資料擴充目錄項目。如果是標準資料集,這項程序通常只需要幾分鐘。

找出物件資料表

探索掃描作業完成後,Knowledge Catalog 會建立一或多個物件資料表,並在 Knowledge Catalog 中填入相應的項目,其中包含 AI 生成的中繼資料。如果探索掃描作業建立多個項目,每個項目都會有專屬的「洞察」分頁。您可以查看自動產生的資料表說明、推論的結構定義和關係圖。

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」頁面

  2. 在導覽選單中,依序點選「治理」>「中繼資料管理」。

  3. 在「Cloud Storage 探索」窗格中,按一下您為非結構化資料執行的探索掃描。

    • 「掃描詳細資料」部分會顯示探索掃描的詳細資料。
    • 「掃描狀態」部分會顯示最近一次掃描工作的探索結果。
  4. 按一下「已發布的資料集」連結。

  5. 在 BigQuery 資料集顯示的資料表清單中,選取為探索資料掃描產生的物件資料表。

  6. 複製資料表 ID。下一節會用到這項資訊。

查看探索掃描結果

您可以在 Knowledge Catalog 中查看物件表格及其推斷的語意圖。

  1. 前往 Google Cloud 控制台的 Knowledge Catalog「Search」(搜尋) 頁面。

    前往「搜尋」

  2. 貼上並搜尋您在上一節中選取的物件資料表 ID。

  3. 在搜尋結果中按一下表格,開啟表格的項目頁面。

  4. 在「詳細資料」分頁的「層面」下方,確認「圖形設定檔」層面 (dataplex-types.global.graph-profile) 是否存在。這個層面包含實體和關係的推斷結構定義。

  5. 點按「深入分析結果」分頁標籤,在「洞察」分頁中,你可以查看下列資訊:

    • 語意擷取。橫幅會指出系統偵測到可擷取的實體和關係。其中包含「擷取」按鈕,可使用 SQL 或管道部署作業實現資料。

    • 說明。AI 生成的摘要可供使用者瞭解非結構化資料內容。並說明探索到的主要節點 (實體),以及這些節點如何透過邊緣 (關係) 相互對應。

    • 管道。與這項資源相關聯的先前部署資料擷取管道清單。您可以查看顯示名稱、區域、建立時間,以及建立管道的使用者。

    • 推論實體和關係。互動式圖表會以視覺化方式顯示非結構化資料的語意結構。圖表包含代表不同實體的節點 (例如 RecipeIngredient),以及代表節點之間連結的邊緣 (例如 HasAllergenStatus)。你可以使用圖例篩選及探索特定節點和邊緣。

    • 實體。系統探索到的主要實體詳細清單。您可以展開每個實體,查看 AI 生成的說明和推斷的結構定義,包括欄位名稱、資料類型和欄位說明。

    • 關係。實體之間發現的連結詳細清單。您可以展開每項關係,查看說明和定義實體對應方式的結構定義。

更新推論洞察資料

推論洞察資料會儲存在 Knowledge Catalog 目錄中,並附加至物件資料表。您可以使用 REST API 手動更新這些洞察資料。

REST

如要使用 REST API 更新推論洞察資料,請按照下列步驟操作:

  1. 建立名為 payload.json 的檔案,然後新增要更新的層面 JSON 內容。例如:

    {
      "aspects": {
        "dataplex-types.global.graph-profile": {
          "data": {
            "nodeTypes": [],
            "edgeTypes": []
          }
        }
      }
    }
    
  2. 在終端機中執行下列指令:

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d @payload.json \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID?updateMask=aspects"
    

    更改下列內容:

    • PROJECT_ID:專案 ID,例如 example-project
    • LOCATION:項目的位置,例如 us-central1
    • ENTRY_GROUP_ID:項目群組的 ID,例如 example-entry-group (如果是 BigQuery 物件資料表,請使用 @bigquery)
    • ENTRY_ID:項目的 ID,例如 example-entry (在 Google Cloud 控制台的項目詳細資料頁面中,從「總覽」分頁擷取此 ID)

如需其他語言的詳細資訊和程式碼範例,請參閱「更新項目面向」。

將資料擷取至 BigQuery

您可以使用 SQL 或自動化管道,將推斷的實體和關係具體化為 BigQuery 中的結構化表格或檢視區塊。

  1. 在 Google Cloud 控制台,前往 Knowledge Catalog 的「Search」(搜尋) 頁面。

    前往「搜尋」

  2. 搜尋掃描作業產生的物件資料表。

  3. 在搜尋結果中按一下表格,開啟表格的項目頁面。

  4. 按一下「洞察」分頁標籤。

  5. 在「洞察」分頁標籤中,按一下「擷取」

  6. 根據分析需求和非結構化資料規模,選擇下列其中一種方法:

    • 透過 SQL 擷取:選擇這個選項可進行快速的臨時分析、處理中小型資料集,或使用 BigQuery 遠端模型,以零基礎架構的方式進行分析。

      如要使用 SQL 擷取資料,請按照下列步驟操作:

      1. 選取「透過 SQL 擷取」
      2. 在「Extract with SQL」(使用 SQL 擷取) 窗格中,選取目的地資料集。資料集必須與來源位於相同位置。
      3. 按一下「擷取」
      4. BigQuery 編輯器會開啟預先填入的查詢,其中使用 ML.PROCESS_DOCUMENT 函式。執行查詢,建立標準資料表和檢視表。

      如要進一步瞭解如何使用 SQL 擷取文件洞察資料,請參閱「使用 ML.PROCESS_DOCUMENT 函式處理文件」。

    • 依管道擷取:如要大規模處理資料,或需要強大的重試邏輯、錯誤處理和自動化調度管理機制來處理大量文件,請選擇這個選項。

      如要使用管道擷取資料,請按照下列步驟操作:

      1. 選取「透過管道擷取」
      2. 在「Extract with pipeline」(使用管道擷取) 窗格中,輸入管道的顯示名稱。
      3. 請選取區域。
      4. 選取目的地資料集。資料集必須與來源位於相同位置。
      5. 按一下「擷取」。這會建立 BigQuery 管道,使用 Dataform 協調資料具體化作業。
      6. 執行管道中的所有工作,產生結構化節點和邊緣檢視畫面。

      如要進一步瞭解如何執行資料工作流程,請參閱 Dataform 簡介

將語意洞察資料擷取並具體化到 BigQuery 後,您可以執行下列工作:

  • 查詢結構化資料。針對新建立的資料表執行標準 SQL 查詢,分析擷取的實體和關係。

  • 與現有資料彙整在一起。將從非結構化檔案擷取的質性洞察資料,與現有的結構化 BigQuery 資料集合併 (例如將剖析的月結單資料與會計資料表合併)。

  • 探索資料洞察。使用 BigQuery Studio 的「資料洞察」功能,為新的結構化資產自動生成自然語言問題和 SQL 查詢。

  • 使用 Gemini 分析。在 BigQuery 中使用 Gemini 執行對話式分析、彙整趨勢,或根據擷取的資料在 Google 數據分析中建立資訊主頁。

後續步驟