本頁面由 Cloud Translation API 翻譯而成。

提供或自動偵測結構定義

使用 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 的欄位，您可以加入值為 title 的 keyPropertyValues 欄位。

標有 keyPropertyMapping 的欄位預設可供建立索引和搜尋，但無法擷取、完成或動態 Facetable。也就是說，您不需要在 keyPropertyValues 欄位中加入 indexable 或 searchable 欄位，即可取得預期的預設行為。

注意： 重要屬性可提升搜尋結果品質，並提高搜尋自動完成功能的準確度。如果您使用結構定義自動偵測功能，系統不會自動新增重要屬性。強烈建議使用 schemas.patch 方法將資料欄位標示為重要屬性，尤其是 title、uri 和 description。
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 物件的形式提供結構定義。步驟如下：

請使用「以 JSON 物件形式呈現的結構定義範例」做為指南，以 JSON 物件形式準備結構定義。

建立資料儲存庫。

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

使用 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"
    }
  }
}

指令與結果範例

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
"structSchema": {
"$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"
}
}
}
}'

{
"name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
"metadata": {
"@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
}
}

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