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

提供或自動偵測結構定義

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

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

如需架構的參考資訊，請參閱 dataStores.schemas。

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

判斷結構化資料結構定義的方法有很多種。

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

按照 Google Cloud 控制台的結構化資料操作說明，在「建立搜尋資料儲存庫」和「建立自訂建議資料儲存庫」中，您會使用這種方法。
以 JSON 物件的形式提供結構定義。以 JSON 物件的形式將結構定義提供給 AI Applications。您必須準備正確的 JSON 物件。如需 JSON 物件範例，請參閱「JSON 物件形式的範例結構定義」。建立結構定義後，請按照該結構定義上傳資料。

透過 API 使用 curl 指令 (或程式) 建立資料儲存庫時，可以採用這種做法。例如，請參閱從 BigQuery 匯入一次。另請參閱下列操作說明：提供您自己的結構定義。
媒體：請以 Google 定義的結構定義提供資料。如果您為媒體建立資料儲存庫，可以選擇使用 Google 預先定義的架構。選擇這個選項的前提是，您已按照「關於媒體文件和資料存放區」一文中的格式，建構 JSON 物件。根據預設，自動偵測功能會在資料擷取期間，將找到的所有新欄位附加至結構定義。

按照「建立媒體應用程式和資料儲存庫」中的操作說明進行時，您會使用這種方法。此外，在「開始使用媒體推薦內容」和「開始使用媒體搜尋」教學課程中，我們也採用這種做法，並在 Google 預先定義的結構定義中提供範例資料。
媒體：自動偵測及編輯，確保包含必要的媒體屬性。如果是媒體資料，您可以使用自動偵測功能建議結構定義，並編輯以進行修正。在 JSON 物件中，您必須加入可對應至媒體鍵屬性的欄位：title、uri、category、media_duration 和 media_available_time。

如果媒體資料不符合 Google 定義的結構定義，透過Google Cloud 控制台匯入媒體資料時，請使用這個方法。
媒體：以 JSON 物件的形式提供您自己的結構定義。以 JSON 物件的形式將結構定義提供給 AI Applications。您必須準備正確的 JSON 物件。結構定義必須包含可對應至媒體金鑰屬性的欄位：title、uri、category、media_duration 和 media_available_time。

如需 JSON 物件範例，請參閱「JSON 物件形式的範例結構定義」。建立結構定義後，請按照該結構定義上傳媒體資料。

如要採用這種做法，請透過 curl 指令 (或程式) 使用 API。請參閱下列操作說明：提供您自己的結構定義。

關於自動偵測和編輯

開始匯入資料時，Vertex AI Search 會對匯入的前幾個文件進行取樣。並根據這些文件建議資料結構定義，供您查看或編輯。

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

如果 Vertex AI Search 在資料匯入期間發現其他欄位，仍會匯入這些欄位並新增至結構定義。如要在匯入所有資料後編輯結構定義，請參閱「更新結構定義」。

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
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

定義媒體結構定義時，必須加入可對應至媒體鍵屬性的欄位。這些重要屬性如本範例所示。

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

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。

此外，下列欄位僅適用於建議應用程式：

recommendationsFilterable：表示該欄位可用於建議篩選器運算式。如需篩選最佳化建議的一般資訊，請參閱「篩選最佳化建議」。
```
  ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": 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：您的 Google Cloud 專案 ID。
DATA_STORE_ID：您要建立的 Vertex AI Search 資料儲存庫 ID。這個 ID 只能包含小寫字母、數字、底線和連字號。
DATA_STORE_DISPLAY_NAME：要建立的 Vertex AI Search 資料儲存庫顯示名稱。
INDUSTRY_VERTICAL：GENERIC 或 MEDIA

使用 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：您的 Google Cloud 專案 ID。
DATA_STORE_ID：Vertex AI Search 資料儲存庫的 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"
}
}

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