提供或自动检测架构

当您使用 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 定义的架构中，您在通过 Google Cloud 控制台导入媒体数据时，将使用此方法。

• 媒体：以 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 的字段，您可以添加一个值为 title 的 keyPropertyValues 字段。

  对于搜索数据存储区，标记为 keyPropertyMapping 的字段默认可编入索引和可搜索，但不可检索、补全或用于动态分面。这意味着，您无需将 indexable 或 searchable 字段与 keyPropertyValues 字段一起添加，即可获得预期的默认行为。

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

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

后续步骤

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