使用 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 对象的形式提供您的架构。请按照以下步骤操作:
使用示例架构(以 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" } } }
可选:按照查看架构定义中的步骤查看架构。