当您使用 Google Cloud 控制台导入结构化数据时,AI 应用会自动检测架构。您可以在引擎中使用此自动检测的架构,也可以使用 API 提供架构来指明数据的结构。
如果您提供一个架构,然后稍后使用新架构对其进行更新,则新架构必须与原始架构向后兼容。否则,架构更新将失败。
如需了解架构的参考信息,请参阅 dataStores.schemas
。
为数据存储区提供架构的方法
确定结构化数据架构的方法有很多种。
自动检测和修改。让 AI 应用自动检测并建议初始架构。然后,您可以通过控制台界面优化架构。Google 强烈建议您在系统自动检测字段后,将关键属性映射到所有重要字段。
在按照创建搜索数据存储区和创建自定义推荐数据存储区中的 Google Cloud 控制台结构化数据说明操作时,您将使用此方法。
将架构作为 JSON 对象提供。将架构作为 JSON 对象提供给 AI 应用。您需要准备正确的 JSON 对象。如需查看 JSON 对象示例,请参阅将架构作为 JSON 对象的示例。创建架构后,您可以根据该架构上传数据。
在使用 curl 命令(或程序)通过 API 创建数据存储区时,您可以使用此方法。例如,请参阅从 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 文档。例如,以下是有效的 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 对象提供。请按照以下步骤操作:
将架构准备为 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" } } }
可选:按照查看架构定义中的步骤查看架构。