提供或自动检测架构

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

如果您提供了一个架构,之后又使用新架构对其进行了更新,那么新架构必须与原始架构向后兼容。否则,架构更新会失败。

如需了解有关该架构的参考信息,请参阅 dataStores.schemas

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

确定结构化数据的架构有多种方法。

  • 自动检测和修改。让 AI 应用自动检测并建议初始架构。然后,您可以通过控制台界面优化架构。Google 强烈建议您在系统自动检测到字段后,将关键属性映射到所有重要字段。

    如果您按照创建搜索数据存储区创建自定义推荐数据存储区中的 Google Cloud 控制台结构化数据说明操作,则会使用此方法。

  • 以 JSON 对象的形式提供架构。以 JSON 对象的形式向 AI 应用提供架构。您需要准备好正确的 JSON 对象。如需查看 JSON 对象示例,请参阅作为 JSON 对象的架构示例。创建架构后,您就可以根据该架构上传数据了。

    这是通过 API 使用 curl 命令(或程序)创建数据存储区时可以采用的方法。例如,请参阅从 BigQuery 导入一次。另请参阅以下说明:提供您自己的架构

  • 媒体:以 Google 定义的架构提供数据。如果您为媒体创建数据存储区,可以选择使用 Google 预定义的架构。选择此选项的前提是,您已按照媒体文档和数据存储区简介中所述的格式构建了 JSON 对象。默认情况下,自动检测会在数据注入期间将发现的所有新字段附加到架构中。

    如果您按照创建媒体应用和数据存储区中的说明操作,则会使用此方法。这也是教程媒体推荐使用入门媒体搜索使用入门中采用的方法,其中示例数据以 Google 预定义架构提供。

  • 媒体:自动检测和修改,确保包含所需的媒体属性。对于媒体数据,您可以使用自动检测功能来建议架构,然后进行修改以完善架构。在 JSON 对象中,您必须包含可映射到媒体密钥属性的字段:titleuricategorymedia_durationmedia_available_time

    如果媒体数据不符合 Google 定义的架构,您将使用此方法通过Google Cloud 控制台导入媒体数据。

  • 媒体:以 JSON 对象的形式提供您自己的架构。以 JSON 对象的形式向 AI 应用提供架构。您需要准备好正确的 JSON 对象。架构必须包含可映射到媒体密钥属性的字段:titleuricategorymedia_durationmedia_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",系统会忽略导入的数据中发现的新属性;这些属性不会添加到架构中,相应的值也不会导入。

    例如,某个架构具有两个属性:titledescription,而您上传的数据包含 titledescriptionrating 的属性。如果 dynamic"true",则会导入评分属性和数据。如果 dynamic"false",则不会导入 rating 属性,但会导入 titledescription

    默认值为 "true"

  • datetime_detection。如果 datetime_detection 设置为布尔值 true,则在导入日期时间格式的数据时,架构类型会设置为 datetime。支持的格式为 RFC 3339ISO 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。一种将预定义关键字映射到文档中的关键字段的字段,有助于明确这些字段的语义含义。值包括 titledescriptionuricategory。请注意,您的字段名称不必与 keyPropertyValues 值一致。例如,对于您命名为 my_title 的字段,您可以添加一个值为 titlekeyPropertyValues 字段。

    对于搜索数据存储区,标记为 keyPropertyMapping 的字段默认可编入索引和搜索,但不可检索、可补全或可动态构面。这意味着,您无需在包含 keyPropertyValues 字段的情况下添加 indexablesearchable 字段,即可获得预期的默认行为。

  • type。字段的类型。这是一个字符串值,可以是 datetimegeolocation 或某个基元类型(integerbooleanobjectarraynumberstring)。

以下属性字段仅适用于搜索应用:

  • retrievable。表示相应字段是否可以包含在搜索响应中。此属性可针对类型为 numberstringbooleanintegerdatetimegeolocation 的字段进行设置。最多可以将 50 个字段设置为可检索。默认情况下,用户定义的字段和 keyPropertyValues 字段无法检索。如需使字段可检索,请在字段中添加 "retrievable": true

  • indexable。表示此字段是否可在 servingConfigs.search 方法中进行过滤、分面、提升或排序。此属性可针对类型为 numberstringbooleanintegerdatetimegeolocation 的字段进行设置。 最多可以将 50 个字段设置为可编入索引。默认情况下,用户定义的字段不可编入索引,包含 keyPropertyMapping 字段的字段除外。如需使字段可编入索引,请在字段中添加 "indexable": true

  • dynamicFacetable。表示相应字段可用作动态分面。可以为 numberstringbooleaninteger 类型的字段设置此属性。如需使某个字段可进行动态构面,该字段还必须可编入索引:在字段中添加 "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_VERTICALGENERICMEDIA
  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"
          }
        }
      }
  4. 可选:按照查看架构定义中的步骤查看架构。

后续步骤