提供或自动检测架构

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

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

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

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

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

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

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

• 以 JSON 对象的形式提供架构。以 JSON 对象的形式向 AI 应用提供架构。您需要准备好正确的 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 应用提供架构。您需要准备好正确的 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 的字段默认可编入索引和搜索，但不可检索、可补全或可动态构面。这意味着，您无需在包含 keyPropertyValues 字段的情况下添加 indexable 或 searchable 字段，即可获得预期的默认行为。

• 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. 可选：按照查看架构定义中的步骤查看架构。

后续步骤

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