提供或自動偵測結構定義

使用 Google Cloud 控制台匯入結構化資料時，Gemini Enterprise 會自動偵測結構定義。您可以在引擎中使用這項自動偵測到的結構定義，也可以使用 API 提供結構定義，指出資料結構。

如果您提供結構定義，之後又更新為新的結構定義，則新的結構定義必須與原始結構定義回溯相容。否則結構定義更新會失敗。

如需結構定義的參考資訊，請參閱 dataStores.schemas。

提供資料儲存庫結構定義的方法

決定結構化資料的結構定義時，可以採取多種方法。

  • 自動偵測及編輯。讓 Gemini Enterprise 自動偵測並建議初始結構定義。接著，您會在控制台介面中調整結構定義。Google 強烈建議您在系統自動偵測欄位後，將重要屬性對應至所有重要欄位。

    按照 Google Cloud 控制台的結構化資料操作說明，在「建立第一方資料商店」中建立第一方資料商店時，您會使用這種方法。

  • 以 JSON 物件形式提供結構定義。以 JSON 物件的形式向 Gemini Enterprise 提供結構定義。您必須準備正確的 JSON 物件。如需 JSON 物件範例，請參閱「JSON 物件形式的結構定義範例」。建立結構定義後，請根據該結構定義上傳資料。

    透過 API 使用 curl 指令 (或程式) 建立資料儲存庫時，可以採用這種做法。例如，請參閱「從 BigQuery 匯入一次」。另請參閱「提供自己的結構定義」的操作說明。

關於自動偵測和編輯

開始匯入資料時，Gemini Enterprise 會對最先匯入的幾份文件進行取樣。並根據這些文件建議資料結構定義，供您查看或編輯。

如果取樣文件中沒有要對應至重要屬性的欄位，您可以在檢查結構定義時手動新增這些欄位。

如果 Gemini Enterprise 在匯入資料時遇到其他欄位，仍會匯入這些欄位並新增至結構定義。如要在匯入所有資料後編輯結構定義，請參閱「更新結構定義」。

以 JSON 物件表示的結構定義範例

您可以使用 JSON 結構定義格式定義自己的結構定義，這是一種開放原始碼的宣告式語言，用於定義、註解及驗證 JSON 文件。舉例來說，以下是有效的 JSON 結構定義註解：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    }
  }
}

以下是這個結構定義範例中的部分欄位：

  • dynamic。如果 dynamic 設為字串值 "true"，則匯入資料中發現的任何新屬性都會新增至結構定義。如果 dynamic 設為 "false"，系統會忽略匯入資料中找到的新屬性，不會將屬性新增至結構定義，也不會匯入值。

    舉例來說，假設結構定義有兩個屬性：title 和 description，而您上傳的資料包含 title、description 和 rating 的屬性。如果 dynamic 為 "true"，系統就會匯入評分屬性和資料。如果 dynamic 為 "false"，則不會匯入 rating 屬性，但會匯入 title 和 description。

    預設為 "true"。

  • datetime_detection。如果 datetime_detection 設為布林值 true，則匯入日期時間格式的資料時，結構定義類型會設為 datetime。支援的格式為 RFC 3339 和 ISO 8601。

    例如：

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    如果 datatime_detection 設為布林值 false，匯入日期時間格式的資料時，結構定義類型會設為 string。

    預設為 true。

  • geolocation_detection。如果 geolocation_detection 設為布林值 true，則匯入地理位置格式的資料時，結構定義類型會設為 geolocation。如果資料是包含經緯度數字的物件，或包含地址字串的物件，系統會將其偵測為地理位置。

    例如：

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    如果 geolocation_detection 設為布林值 false，則匯入地理位置格式的資料時，結構定義類型會設為 object。

    預設為 true。

  • keyPropertyMapping：這個欄位會將預先定義的關鍵字對應至文件中的重要欄位，有助於釐清語意。值包括 title、description、uri 和 category。請注意，欄位名稱不一定要與 keyPropertyValues 值相符。舉例來說，如果欄位名稱為 my_title，您可以加入 keyPropertyValues 欄位，並將值設為 title。

    標示 keyPropertyMapping 的欄位預設可建立索引及搜尋，但無法擷取、完成或做為動態商情項目。這表示您不需要在 keyPropertyValues 欄位中加入 indexable 或 searchable 欄位，即可取得預期的預設行為。

  • type：欄位類型。這是字串值，可以是 datetime、geolocation 或其中一種原始型別 (integer、boolean、object、array、number 或 string)。

  • retrievable：指出是否可在搜尋回應中傳回這個欄位。這項設定適用於 number、string、boolean、integer、datetime 和 geolocation 類型的欄位。最多可將 50 個欄位設為可擷取。系統預設不會擷取使用者定義的欄位和 keyPropertyValues 欄位。如要讓欄位可供擷取，請在欄位中加入 "retrievable": true。

  • indexable。指出這個欄位是否可在 servingConfigs.search 方法中篩選、分面、提升或排序。這項設定適用於 number、string、boolean、integer、datetime 和 geolocation 類型的欄位。最多可將 50 個欄位設為可建立索引。根據預設，使用者定義的欄位無法建立索引，但包含 keyPropertyMapping 欄位的欄位除外。如要讓欄位可建立索引，請在欄位中加入 "indexable": true。

  • dynamicFacetable：表示欄位可做為動態 facet。這項設定適用於 number、string、boolean 和 integer 類型的欄位。如要讓欄位可動態篩選，該欄位也必須可建立索引：請在欄位中加入 "dynamicFacetable": true 和 "indexable": true。

  • searchable。指出這個欄位是否可反向建立索引，以比對非結構化文字查詢。這個值只能針對 string 類型的欄位設定。最多可將 50 個欄位設為可搜尋。根據預設，使用者定義的欄位無法搜尋，但包含 keyPropertyMapping 欄位的欄位除外。如要讓欄位可供搜尋，請在欄位中加入 "searchable": true。

  • completable：指出這個欄位是否可做為自動完成建議傳回。這項設定僅適用於 string 類型的欄位。如要讓欄位可填寫，請在欄位中加入 "completable": true。

以 JSON 物件形式提供您自己的結構定義

如要提供自己的結構定義，請建立包含空白結構定義的資料儲存庫，然後更新結構定義，並以 JSON 物件的形式提供結構定義。步驟如下：

  1. 請使用範例結構定義 (JSON 物件)做為指南，以 JSON 物件形式準備結構定義。

  2. 建立資料儲存庫。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "INDUSTRY_VERTICAL"
}'

    更改下列內容：

    • PROJECT_ID：專案的 ID。
    • DATA_STORE_ID：要建立的資料儲存庫 ID。這個 ID 只能包含小寫英文字母、數字、底線和連字號。
    • DATA_STORE_DISPLAY_NAME：要建立的資料儲存庫顯示名稱。
    • INDUSTRY_VERTICAL：GENERIC

  3. 使用 schemas.patch API 方法，以 JSON 物件形式提供新的 JSON 結構定義。

    curl -X PATCH \
-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/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

    更改下列內容：

    • PROJECT_ID：專案的 ID。
    • DATA_STORE_ID：資料儲存庫的 ID。

    • JSON_SCHEMA_OBJECT：新的 JSON 結構定義，以 JSON 物件表示。例如：

      {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

  4. 選用：按照「查看結構定義」一節的程序檢查結構定義。

後續步驟