構造化データと非構造化データを更新する

このページでは、構造化データと非構造化データの更新について説明します。

ウェブサイト アプリを更新するには、ウェブページを更新するをご覧ください。

構造化データを更新する

データストア内のスキーマと同じスキーマまたは下位互換性のあるスキーマを使用する限り、構造化データストア内のデータを更新できます。たとえば、既存のスキーマに新しいフィールドのみを追加すると、下位互換性が維持されます。

構造化データを更新するには、Google Cloud コンソールまたは API を使用します。

Console

Google Cloud コンソールを使用してデータストアのブランチから構造化データを更新する手順は次のとおりです。

  1. Google Cloud コンソールで、[Agent Builder] ページに移動します。

    Agent Builder

  2. ナビゲーション メニューで [データストア] をクリックします。

  3. [名前] 列で、編集するデータストアをクリックします。

  4. [ドキュメント] タブで、[データをインポート] をクリックします。

  5. Cloud Storage から更新するには:

    1. [データソースを選択] ペインで、[Cloud Storage] を選択します。
    2. [Cloud Storage からデータをインポート] ペインで、[参照] をクリックし、更新されたデータを含むバケットを選択して、[選択] をクリックします。または、[gs://] フィールドにバケットの場所を直接入力します。
    3. [データ インポートのオプション] で、インポート オプションを選択します。
    4. [インポート] をクリックします。

  6. BigQuery から更新するには:

    1. [データソースを選択] ペインで、[BigQuery] を選択します。
    2. [BigQuery からデータをインポート] ペインで、[参照] をクリックし、更新されたデータを含むテーブルを選択して、[選択] をクリックします。または、[BigQuery パス] フィールドにテーブルの場所を直接入力します。
    3. [データ インポートのオプション] で、インポート オプションを選択します。
    4. [インポート] をクリックします。

REST

適切な reconciliationMode 値を指定して、documents.import メソッドを使用してデータを更新します。

コマンドラインを使用して BigQuery または Cloud Storage から構造化データを更新する手順は次のとおりです。

  1. データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。

    1. Google Cloud コンソールで [Agent Builder] ページに移動し、ナビゲーション メニューで [データストア] をクリックします。

      [データストア] ページに移動

    2. データストアの名前をクリックします。

    3. データストアの [データ] ページで、データストア ID を取得します。

  2. BigQuery から構造化データをインポートするには、次のメソッドを呼び出します。BigQuery または Cloud Storage からインポートできます。Cloud Storage からインポートするには、次のステップに進みます。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents:import" \
-d '{
  "bigquerySource": {
    "projectId": "PROJECT_ID",
    "datasetId":"DATASET_ID",
    "tableId": "TABLE_ID",
    "dataSchema": "DATA_SCHEMA_BQ",
  },
  "reconciliationMode": "RECONCILIATION_MODE",
  "autoGenerateIds": AUTO_GENERATE_IDS,
  "idField": "ID_FIELD",
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'
    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: Vertex AI Search データストアの ID。
    • DATASET_ID: BigQuery データセットの名前。
    • TABLE_ID: BigQuery テーブルの名前。
    • DATA_SCHEMA_BQ: BigQuery ソースからのデータの解析時に使用するスキーマを指定するオプション フィールド。次のいずれかの値を取ります。
      • document: デフォルト値。使用する BigQuery テーブルは、次のデフォルトの BigQuery スキーマに準拠している必要があります。各ドキュメントの ID を自分で定義し、データ全体を json_data 文字列でラップできます。
      • custom: 任意の BigQuery テーブル スキーマが受け入れられ、Vertex AI Agent Builder がインポートされる各ドキュメントの ID を自動的に生成します。
    • ERROR_DIRECTORY: インポートに関するエラー情報用の Cloud Storage ディレクトリを指定する省略可能なフィールド（例: gs://<your-gcs-bucket>/directory/import_errors）。Vertex AI Agent Builder が一時ディレクトリを自動的に作成できるように、このフィールドを空のままにすることをおすすめします。
    • RECONCILIATION_MODE: インポートされたドキュメントを宛先データストアの既存のドキュメントと調整する方法を指定するオプション フィールド。次のいずれかの値を取ります。
      • INCREMENTAL: デフォルト値。BigQuery からデータストアへのデータの増分更新が発生します。これにより、アップサート オペレーションが実行され、新しいドキュメントを追加し、既存のドキュメントを更新された同じ ID のドキュメントで置き換えます。
      • FULL: データストア内のドキュメントの完全な再ベース化が行われます。したがって、新しいドキュメントと更新されたドキュメントがデータストアに追加され、BigQuery にないドキュメントがデータストアから削除されます。FULL モードは、不要になったドキュメントを自動的に削除する場合に便利です。

    • AUTO_GENERATE_IDS: ドキュメント ID を自動生成するかどうかを指定するオプション フィールド。true に設定すると、ドキュメント ID はペイロードのハッシュに基づいて生成されます。生成されたドキュメント ID は、複数のインポートで整合性が維持されない場合があります。複数のインポートで ID を自動生成する場合は、ドキュメント ID の整合性を維持するために、reconciliationMode を FULL に設定することを強くおすすめします。

      autoGenerateIds は、bigquerySource.dataSchema が custom に設定されている場合にのみ指定します。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。autoGenerateIds を指定しない場合、または false に設定しない場合は、idField を指定する必要があります。そうしないと、ドキュメントのインポートに失敗します。

    • ID_FIELD: ドキュメント ID であるフィールドを指定するオプション フィールド。BigQuery ソースファイルの場合、idField は、ドキュメント ID を含む BigQuery テーブルの列の名前を示します。

      idField は、次の両方の条件が満たされている場合にのみ指定します。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

      • bigquerySource.dataSchema は custom に設定されています
      • auto_generate_ids が false に設定されているか、未指定である。

      また、BigQuery 列名の値は文字列型で、1 から 63 文字の範囲で、RFC-1034 に準拠している必要があります。そうしないと、ドキュメントのインポートに失敗します。

    デフォルトの BigQuery スキーマは次のとおりです。dataSchema を document に設定する場合、BigQuery テーブルはこのスキーマに準拠している必要があります。

    [
 {
   "name": "id",
   "mode": "REQUIRED",
   "type": "STRING",
   "fields": []
 },
 {
   "name": "jsonData",
   "mode": "NULLABLE",
   "type": "STRING",
   "fields": []
 }
]

  3. Cloud Storage から構造化データをインポートするには、次のメソッドを呼び出します。 BigQuery または Cloud Storage からインポートできます。BigQuery からインポートするには、前の手順に移動します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents:import" \
-d '{
  "gcsSource": {
    "inputUris": ["GCS_PATHS"],
    "dataSchema": "DATA_SCHEMA_GCS",
  },
  "reconciliationMode": "RECONCILIATION_MODE",
  "idField": "ID_FIELD",
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'
    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: Vertex AI Search データストアの ID。
    • GCS_PATHS: インポート元の Cloud Storage ロケーションへの URI のカンマ区切りのリスト。各 URI の長さは 2,000 文字までです。URI は、ストレージ オブジェクトのフルパスと一致することも、1 つ以上のオブジェクトのパターンと一致することもできます。たとえば、gs://bucket/directory/*.json は有効なパスです。
    • DATA_SCHEMA_GCS: BigQuery ソースからのデータの解析時に使用するスキーマを指定するオプション フィールド。次のいずれかの値を取ります。
      • document: デフォルト値。使用する BigQuery テーブルは、次のデフォルトの BigQuery スキーマに準拠している必要があります。各ドキュメントの ID を自分で定義し、データ全体を json_data 文字列でラップできます。
      • custom: 任意の BigQuery テーブル スキーマが受け入れられ、Vertex AI Agent Builder がインポートされる各ドキュメントの ID を自動的に生成します。
    • ERROR_DIRECTORY: インポートに関するエラー情報用の Cloud Storage ディレクトリを指定する省略可能なフィールド（例: gs://<your-gcs-bucket>/directory/import_errors）。Vertex AI Agent Builder が一時ディレクトリを自動的に作成できるように、このフィールドを空のままにすることをおすすめします。
    • RECONCILIATION_MODE: インポートされたドキュメントを宛先データストアの既存のドキュメントと調整する方法を指定するオプション フィールド。次のいずれかの値を取ります。
      • INCREMENTAL: デフォルト値。BigQuery からデータストアへのデータの増分更新が発生します。これにより、アップサート オペレーションが実行され、新しいドキュメントを追加し、既存のドキュメントを更新された同じ ID のドキュメントで置き換えます。
      • FULL: データストア内のドキュメントの完全な再ベース化が行われます。したがって、新しいドキュメントと更新されたドキュメントがデータストアに追加され、BigQuery にないドキュメントがデータストアから削除されます。FULL モードは、不要になったドキュメントを自動的に削除する場合に便利です。

Python

詳細については、Vertex AI Agent Builder Python API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。


from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION" # Values: "global"
# data_store_id = "YOUR_DATA_STORE_ID"
# bigquery_dataset = "YOUR_BIGQUERY_DATASET"
# bigquery_table = "YOUR_BIGQUERY_TABLE"

#  For more information, refer to:
# https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)

# Create a client
client = discoveryengine.DocumentServiceClient(client_options=client_options)

# The full resource name of the search engine branch.
# e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
parent = client.branch_path(
    project=project_id,
    location=location,
    data_store=data_store_id,
    branch="default_branch",
)

request = discoveryengine.ImportDocumentsRequest(
    parent=parent,
    bigquery_source=discoveryengine.BigQuerySource(
        project_id=project_id,
        dataset_id=bigquery_dataset,
        table_id=bigquery_table,
        data_schema="custom",
    ),
    # Options: `FULL`, `INCREMENTAL`
    reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
)

# Make the request
operation = client.import_documents(request=request)

print(f"Waiting for operation to complete: {operation.operation.name}")
response = operation.result()

# After the operation is complete,
# get information from operation metadata
metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

# Handle the response
print(response)
print(metadata)

非構造化データを更新する

非構造化データを更新するには、Google Cloud コンソールまたは API を使用します。

Console

Google Cloud コンソールを使用してデータストアのブランチから非構造化データを更新する手順は次のとおりです。

  1. Google Cloud コンソールで、[Agent Builder] ページに移動します。

    Agent Builder

  2. ナビゲーション メニューで [データストア] をクリックします。

  3. [名前] 列で、編集するデータストアをクリックします。

  4. [ドキュメント] タブで、[データをインポート] をクリックします。

  5. Cloud Storage バケットから取り込む（メタデータありまたはメタデータなし）には:

    1. [データソースを選択] ペインで、[Cloud Storage] を選択します。
    2. [Cloud Storage からデータをインポート] ペインで、[参照] をクリックし、更新されたデータを含むバケットを選択して、[選択] をクリックします。または、[gs://gs://] フィールドにバケットの場所を直接入力します。
    3. [データ インポートのオプション] で、インポート オプションを選択します。
    4. [インポート] をクリックします。

  6. BigQuery から取り込むには:

    1. [データソースを選択] ペインで、[BigQuery] を選択します。
    2. [BigQuery からデータをインポート] ペインで、[参照] をクリックし、更新されたデータを含むテーブルを選択して、[選択] をクリックします。または、[BigQuery パス] フィールドにテーブルのロケーションを直接入力します。
    3. [データ インポートのオプション] で、インポート オプションを選択します。
    4. [インポート] をクリックします。

REST

API を使用して非構造化データを更新するには、適切な reconciliationMode 値を指定して documents.import メソッドを使用してデータを再インポートします。非構造化データのインポートの詳細については、非構造化データをご覧ください。

Python

詳細については、Vertex AI Agent Builder Python API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_LOCATION" # Values: "global"
# data_store_id = "YOUR_DATA_STORE_ID"

# Examples:
# - Unstructured documents
#   - `gs://bucket/directory/file.pdf`
#   - `gs://bucket/directory/*.pdf`
# - Unstructured documents with JSONL Metadata
#   - `gs://bucket/directory/file.json`
# - Unstructured documents with CSV Metadata
#   - `gs://bucket/directory/file.csv`
# gcs_uri = "YOUR_GCS_PATH"

#  For more information, refer to:
# https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)

# Create a client
client = discoveryengine.DocumentServiceClient(client_options=client_options)

# The full resource name of the search engine branch.
# e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
parent = client.branch_path(
    project=project_id,
    location=location,
    data_store=data_store_id,
    branch="default_branch",
)

request = discoveryengine.ImportDocumentsRequest(
    parent=parent,
    gcs_source=discoveryengine.GcsSource(
        # Multiple URIs are supported
        input_uris=[gcs_uri],
        # Options:
        # - `content` - Unstructured documents (PDF, HTML, DOC, TXT, PPTX)
        # - `custom` - Unstructured documents with custom JSONL metadata
        # - `document` - Structured documents in the discoveryengine.Document format.
        # - `csv` - Unstructured documents with CSV metadata
        data_schema="content",
    ),
    # Options: `FULL`, `INCREMENTAL`
    reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
)

# Make the request
operation = client.import_documents(request=request)

print(f"Waiting for operation to complete: {operation.operation.name}")
response = operation.result()

# After the operation is complete,
# get information from operation metadata
metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

# Handle the response
print(response)
print(metadata)