提供或自动检测架构

使用 Google Cloud 控制台导入结构化数据时，Vertex AI Agent Builder 自动检测架构。您可以在引擎中使用此自动检测的架构，也可以使用 API 提供架构来指明数据的结构。

如果您提供了架构，之后又使用新架构对其进行了更新，则新架构 必须与原始版本向后兼容。否则，架构更新 失败。

重要提示：如果您未提供架构，则在您导入新数据时，自动检测功能可通过纳入任何新检测到的字段来更新架构。如果导入的数据中的任何文档包含与原始架构不向后兼容的新字段，则这些文档将无法导入。

如需了解架构的参考信息，请参阅 dataStores.schemas。

关键术语：在架构的上下文中，术语“字段”和“字段” “属性”可以互换使用。

为数据存储区提供架构的方法

您可以通过多种方法确定结构化数据的架构。

• 自动检测和修改。让 Vertex AI Agent Builder 自动检测并提供建议 初始架构然后，通过 控制台界面。Google 强烈建议 将关键属性映射到 重要字段

  在按照创建搜索数据存储区和创建通用推荐数据存储区中的 Google Cloud 控制台说明操作时，您将使用此方法。

• 将架构作为 JSON 对象提供。提供 将架构以 JSON 对象的形式添加到 Vertex AI Agent Builder。您需要准备正确的 JSON 对象。如需查看 JSON 对象示例，请参阅示例架构 指定为 JSON 对象。创建架构后 根据该架构上传数据

  这是通过 通过 curl 命令（或程序）访问 API。有关示例，请参见导入一次 BigQuery。另请参阅以下内容 说明提供您自己的架构。

• 媒体：在 Google 定义的架构中提供数据。如果您为媒体创建数据存储区，可以选择使用 Google 预定义的架构。正在选择 此选项假定您已按照以下格式构建了 JSON 对象： 关于媒体文档和数据存储区。修改者 默认情况下，自动检测功能会将找到的任何新字段附加到架构中 在数据注入期间运行

  在按照 创建媒体应用和数据存储区。这也是媒体推荐使用入门和媒体搜索使用入门教程中采用的方法，其中的示例数据是在 Google 预定义架构中提供的。

• 媒体：自动检测和修改，确保添加所需的媒体 属性。对于媒体数据，您可以使用自动检测功能提供架构建议 然后进行修改以进行优化在 JSON 对象中，您必须添加可映射到媒体键属性的字段：title、uri、category、media_duration 和 media_available_time。

  这是通过 Google Cloud 控制台（如果媒体数据不在 Google 定义的架构中）。

• 媒体：以 JSON 对象形式提供您自己的架构。提供 将架构以 JSON 对象的形式添加到 Vertex AI Agent Builder。你需要准备好 正确的 JSON 对象。架构必须包含可 映射到以下媒体键属性：title、uri、category media_duration 和 media_available_time。

  如需查看 JSON 对象示例，请参阅将架构作为 JSON 对象的示例。创建架构后 然后根据该架构上传媒体数据

  对于此方法，您可以通过 curl 命令（或程序）使用 API。 请参阅以下说明，提供您自己的架构。

自动检测和修改简介

当您开始导入数据时，Vertex AI Search 会对第一个 已导入几个文档。它会根据这些文档为数据建议架构，然后您可以查看或修改该架构。

如果要映射到关键属性的字段未在选段文档中，您可以在查看架构时手动添加这些字段。

提示： 请确保数据集开头的文档正确无误 确保所有关键字段都得到表示这样，您就无需向 或稍后修改字段。

如果 Vertex AI Search 后面的 它仍会导入这些字段并将其添加到架构中。如果您想在导入所有数据后修改架构，请参阅更新架构。

示例架构（作为 JSON 对象）

您可以使用 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字段，则可以添加keyPropertyValues字段 值为 title。

  对于搜索数据存储区，标记为 包含 keyPropertyMapping 字段在默认情况下可编入索引且可搜索，但无法 可检索、可完成或 dynamicFacetable。也就是说 需要包含 indexable 或 searchable 字段以及 keyPropertyValues 字段，以获取预期的默认行为。

  注意 ：关键属性可以提高搜索质量和 推荐结果和搜索自动补全的准确性。如果您使用 自动检测架构，因此不会自动添加关键属性。我们强烈建议使用 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。表示该字段可用作动态 商品详情。您可以为类型为 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 对象提供。请按照以下步骤操作：

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：您的 Google Cloud 项目的 ID。
   • DATA_STORE_ID：您要创建的 Vertex AI Search 数据存储区的 ID。此 ID 只能包含小写字母、数字、下划线和连字符。
   • DATA_STORE_DISPLAY_NAME：您要创建的 Vertex AI Search 数据存储区的显示名称。
   • INDUSTRY_VERTICAL：GENERIC 或 MEDIA

3. 使用 schemas.patch 以 JSON 对象形式提供新 JSON 架构的 API 方法。

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

4. 可选：按照查看架构定义中的步骤查看架构。

后续步骤

• 创建搜索应用
• 创建推荐应用
• 创建媒体应用
• 获取结构化数据的架构定义
• 更新结构化数据的架构