本页介绍了如何使用 Google Cloud 控制台预览搜索结果,以及如何使用 API 获取搜索结果。
此外,您还可以进行 API 调用并将其集成到您的服务器或应用中,而不是创建要添加到网页中的搜索微件。本页包含代码示例,介绍如何使用 gRPC 客户端库搭配服务账号发出搜索查询。
搜索摘要因设备型号而异
如果您为查询生成搜索摘要,可能会发现控制台结果和 API 结果中的摘要有所不同。如果您看到此消息,可能是因为控制台使用的 LLM 模型与 API 使用的 LLM 模型不同。本页中的 curl 和代码示例使用的是稳定的 LLM 模型。
如需更改或查看界面预览页面中使用的 LLM 模型,请前往应用的配置页面 > 界面标签页。
对于方法调用,如需使用稳定模型以外的 LLM 模型,请参阅指定总结模型。
获取包含网站数据的应用的搜索结果
控制台
如需使用 Google Cloud 控制台预览包含网站数据的应用的搜索结果,请按以下步骤操作:
在 Google Cloud 控制台中,前往 Agent Builder 页面。
点击要修改的应用的名称。
点击预览。
在控制台中打开预览页面。
可选:如果您已将多个数据存储区连接到您的应用,但只希望从特定数据存储区获取结果,请选择要从中获取结果的数据存储区。
输入搜索查询。
- 如果您启用了自动补全功能,则在输入内容时,搜索栏下方会显示自动补全建议列表。
点击 Enter 键提交查询。
- 搜索栏下方会显示搜索结果列表。
- 每个结果均包含标题、摘要和网址。
- 点击相应结果即可打开该网址。
点击结果列表下方的箭头,即可加载下一页结果。
REST
如需使用此 API 获取包含网站数据的应用的搜索结果,请使用 engines.servingConfigs.search
方法:
找到您的应用 ID。如果您已经有应用 ID,请跳至下一步。
在 Google Cloud 控制台中,前往 Agent Builder 页面。
在应用页面上,找到应用的名称,然后从 ID 列中获取应用的 ID。
获取搜索结果。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search", "query": "QUERY", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "params": {"user_country_code": "USER_COUNTRY_CODE", "searchType": "SEARCH_TYPE"}, "filter": "FILTER", "boostSpec": "BOOST_SPEC", "contentSearchSpec": { "searchResultMode": "RESULT_MODE" }, "dataStoreSpecs": [{"DATA_STORE_SPEC"}] }'
替换以下内容:
PROJECT_ID
:您的 Google Cloud 项目的 ID。APP_ID
:您要查询的 Vertex AI Search 应用的 ID。QUERY
:要搜索的查询文本。PAGE_SIZE
:搜索返回的结果数。 允许的最大页面大小取决于数据类型。大于最大值的页面大小会被强制转换为最大值。- 采用基本索引的网站:默认
10
,上限25
- 启用了高级索引编制的网站:默认
25
,上限50
- 其他:默认
50
,最大100
- 采用基本索引的网站:默认
OFFSET
:结果的起始索引。默认值为 0。例如,如果偏移量为 2,页面大小为 10,并且要返回 15 个结果,则第一页会返回第 2 条到第 12 条结果。
ORDER_BY
:结果的排列顺序。用于排序的属性必须具有数值解释,例如date
。如需了解详情,请参阅对网页搜索结果进行排序。USER_COUNTRY_CODE
:用户的位置。此键值对是params
映射字段唯一支持的条目。默认值为空。如需了解可接受的值,请参阅可编程搜索引擎 JSON API 参考文档中的国家/地区代码。SEARCH_TYPE
:要执行的搜索类型。文档搜索的默认值为 0。图片搜索的另一个支持的值为 1。FILTER
:一个文本字段,用于使用过滤条件表达式过滤搜索结果。默认值为空字符串。如需详细了解如何使用filter
字段,请参阅过滤网站搜索。BOOST_SPEC
:可选。用于提升或隐藏文档的规范。值:RESULT_MODE
:确定搜索结果是作为完整文档还是分块返回。如需获取分块,数据存储区必须启用文档分块。可接受的值为documents
和chunks
。为数据存储区启用分块时,默认值为chunks
。否则,默认值为documents
。如需了解文档分块,请参阅解析和分块文档。此字段处于公开预览阶段;如需使用它,请在 curl 命令中将v1
更改为v1alpha
。DATA_STORE_SPEC
:用于搜索特定数据存储区的过滤条件。如果您的搜索应用连接到多个数据存储区,但您希望从特定数据存储区获取结果,请使用dataStoreSpecs
。
C#
如需了解详情,请参阅 Vertex AI Agent Builder C# API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需了解详情,请参阅 Vertex AI Agent Builder Java API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需了解详情,请参阅 Vertex AI Agent Builder Node.js API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需了解详情,请参阅 Vertex AI Agent Builder PHP API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需了解详情,请参阅 Vertex AI Agent Builder Python API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需了解详情,请参阅 Vertex AI Agent Builder Ruby API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
获取包含网站数据的应用的搜索结果(API 密钥)
如果您想使用 API 密钥(而不是通过服务账号或用户账号使用 OAuth 2.0)对搜索方法调用进行身份验证,请按照以下使用 searchLite
方法的步骤操作。searchLite
方法与 search
方法具有相同的功能,但只能用于搜索公开网站。
searchLite
方法在以下情况下特别适用:
您有一个静态网站,无法通过服务账号或用户账号设置 OAuth 2.0。
您已从可编程搜索引擎的 Custom Search Site Restricted JSON API 迁移到 Vertex AI Search。
您不想使用搜索微件。
准备工作
您需要先拥有 API 密钥,然后才能调用 servingConfigs.searchLite
方法。如果您没有 API 密钥,请完成部署搜索应用(API 密钥)中的第 1 步。
过程
REST
如需使用此 API 获取使用 API 密钥进行身份验证的公共网站数据的应用的搜索结果,请使用 engines.servingConfigs.searchLite
方法:
找到您的应用 ID。如果您已经有应用 ID,请跳至下一步。
在 Google Cloud 控制台中,前往 Agent Builder 页面。
在应用页面上,找到应用的名称,然后从 ID 列中获取应用的 ID。
运行以下 curl 命令可获取搜索结果:
curl -X POST -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:searchLite?key=API_KEY" \ -d '{ "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search", "query": "QUERY", }'
替换以下内容:
PROJECT_ID
:您的 Google Cloud 项目的 ID。API_KEY
:您的 API 密钥字符串。PROJECT_ID
:您的 Google Cloud 项目的 ID。APP_ID
:您要查询的 Vertex AI Search 应用的 ID。QUERY
:要搜索的查询文本。
Python
如需了解详情,请参阅 Vertex AI Agent Builder Python API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
获取包含结构化数据或非结构化数据的应用的搜索结果
您可以通过 Google Cloud 控制台预览搜索结果,也可以使用 API 获取搜索结果。
控制台
如需使用 Google Cloud 控制台预览包含结构化或非结构化数据的应用的搜索结果,请按以下步骤操作:
- 在控制台中打开预览页面。
- 输入搜索查询。
- 如果您在第 1 步中启用了自动补全功能,则在输入内容时,搜索栏下方会显示自动补全建议列表。
- (可选)如果您已将多个数据存储区连接到您的应用,但只希望从特定数据存储区获取结果,请选择要从中获取结果的数据存储区。
- 点击 Enter 键提交查询。
- 搜索栏下方会显示搜索结果列表。
- 如果未在配置页面中定义任何属性映射,则每个搜索结果都会显示为原始属性名称和值的列表。
- 如果您在配置页面中保存了任何属性映射,搜索结果中会显示与配置页面预览中相同的图片。
- 如果您在配置页面中指定了任何切面,它们也会以相同的方式显示。
- 点击结果列表下方的箭头,即可加载下一页结果。
REST
如需使用此 API 获取包含结构化或非结构化数据的应用的搜索结果,请使用 engines.servingConfigs.search
方法:
找到您的应用 ID。如果您已经有应用 ID,请跳至下一步。
在 Google Cloud 控制台中,前往 Agent Builder 页面。
在应用页面上,找到应用的名称,然后从 ID 列中获取应用的 ID。
获取搜索结果。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "query": "QUERY", "userPseudoId": "USER_PSEUDO_ID", "pageSize": "PAGE_SIZE", "offset": "OFFSET", "orderBy": "ORDER_BY", "filter": "FILTER", "boostSpec": "BOOST_SPEC", "facetSpec": "FACET_SPEC", "queryExpansionSpec": "QUERY_EXPANSION_SPEC", "spellCorrectionSpec": "SPELL_CORRECTION_SPEC", "contentSearchSpec": "CONTENT_SEARCH_SPEC", "dataStoreSpecs": [{"DATA_STORE_SPEC"}], }'
替换以下内容:
PROJECT_ID
:您的 Google Cloud 项目的 ID。PROJECT_ID
:您的 Google Cloud 项目的 ID。APP_ID
:您要查询的 Vertex AI Search 应用的 ID。QUERY
:要搜索的查询文本。USER_PSEUDO_ID
:可选。这是一个经过假名化处理的标识符,用于跟踪搜索访问者。Google 强烈建议使用此字段,因为这有助于提升模型效果和个性化质量。您可以为此字段使用 HTTP Cookie,该 Cookie 可唯一标识单个设备上的访问者。访问者登录或退出网站时,此标识符不会发生变化。请勿为多位用户将此字段设置为相同的标识符,否则系统会合并他们的事件历史记录,从而降低模型质量。请勿在此字段中包含个人身份信息 (PII)。PAGE_SIZE
:搜索返回的结果数。允许的最大页面大小取决于数据类型。大于最大值的页面大小会被强制转换为最大值。- 采用基本索引的网站:默认
10
,上限25
- 启用了高级索引编制的网站:默认
25
,上限50
- 其他:默认
50
,最大100
- 采用基本索引的网站:默认
OFFSET
:可选。结果的起始索引。 默认值为 0。例如,如果偏移量为 2,页面大小为 10,并且要返回 15 条结果,则第一页会返回第 2 条到第 11 条结果。
ORDER_BY
:可选。结果的排列顺序。FILTER
:可选。一个文本字段,用于使用过滤表达式过滤搜索结果。默认值为空字符串,表示不应用任何过滤条件。示例:
color: ANY("red", "blue") AND score: IN(*, 100.0e)
如需了解详情,请参阅过滤结构化或非结构化数据的搜索。
BOOST_SPEC
:可选。用于提升或隐藏文档的规范。值:BOOST
:[-1,1] 范围内的浮点数。当该值为负时,相应结果会被降级(在结果中显示在更低的位置)。当该值为正时,系统会提升结果的排名(即在结果中显示在更高的位置)。CONDITION
:一个文本过滤表达式,用于选择要应用该增强功能的文档。过滤条件的求值结果必须为布尔值。
如需了解如何为结构化搜索结果提升排名,请参阅提升搜索结果排名。
FACET_SPEC
:可选。用于执行分面搜索的 facet 规范。QUERY_EXPANSION_SPEC
:可选。用于确定应在何种情况下进行查询展开的规范。默认值为DISABLED
。SPELL_CORRECTION_SPEC
:可选。用于确定应在何种情况下进行拼写检查的规范。默认值为AUTO
。CONTENT_SEARCH_SPEC
:可选。用于获取摘要、提取式回答、提取式片段和搜索摘要。仅适用于非结构化数据。有关详情,请参阅:DATA_STORE_SPEC
:用于搜索特定数据存储区的过滤条件。如果您的搜索应用连接到多个数据存储区,则可以使用此方法。在搜索响应中查看引导式搜索结果:
系统会在结构化搜索和非结构化搜索的搜索响应中返回引导式搜索结果。引导式搜索结果包含根据搜索结果文档提取的属性键值对列表。这样,用户就可以使用某些属性键和值作为过滤条件来优化搜索结果。
在此示例响应中,系统使用了绿色,通过发出将过滤字段指定为
_gs.color: ANY("green")
的新搜索请求来优化搜索结果:{ "guidedSearchResult": { "refinementAttributes": [ { "attributeKey": "_gs.color", "attributeValue" : "green" }, { "attributeKey": "_gs.category", "attributeValue" : "shoe" } ] } }
C#
如需了解详情,请参阅 Vertex AI Agent Builder C# API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需了解详情,请参阅 Vertex AI Agent Builder Java API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需了解详情,请参阅 Vertex AI Agent Builder Node.js API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需了解详情,请参阅 Vertex AI Agent Builder PHP API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需了解详情,请参阅 Vertex AI Agent Builder Python API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需了解详情,请参阅 Vertex AI Agent Builder Ruby API 参考文档。
如需向 Vertex AI Agent Builder 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
获取媒体应用的即输即搜结果
对于媒体搜索,Vertex AI Agent Builder 提供两种搜索行为:
用户输入搜索查询,然后按 Enter 键。这是默认行为,与在微件中搜索和搜索非媒体(通用)应用的行为相同。请参阅获取包含结构化数据或非结构化数据的应用的搜索结果。
用户输入每个字母后,系统都会返回新的搜索结果。这称为“边输入边搜索”,对于通过电视遥控器等不太方便的界面输入搜索查询的用户来说,这一功能尤为有用。
如需为媒体应用获取“边输入边搜索”结果,请执行以下操作:
控制台
如需使用 Google Cloud 控制台为 widget 应用启用“边输入边搜索”功能,请执行以下操作:
在 Google Cloud 控制台中,前往 Agent Builder 页面。
点击您要为其启用“边输入边搜索”功能的媒体搜索应用的名称。
点击配置。
点击界面标签页。
点击启用即输即搜切换开关。
在预览窗格中,开始输入查询。
搜索结果会在每次按键后更新。
如要保留“边输入边搜索”设置,请点击保存并发布。
REST
使用 dataStores.servingConfigs.search
方法获取媒体应用的搜索结果:
找到您的应用 ID。如果您已经有应用 ID,请跳至下一步。
在 Google Cloud 控制台中,前往 Agent Builder 页面。
在应用页面上,找到应用的名称,然后从 ID 列中获取应用的 ID。
运行以下 curl 命令可获取“边输入边搜索”结果。
除
contentSearchSpec
之外的所有字段都可以与searchAsYouTypeSpec
字段结合使用。为清楚起见,我们已从 curl 命令中省略了可选字段。如需了解可选字段,请参阅获取包含结构化数据或非结构化数据的应用的搜索结果。curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \ -d '{ "query": "QUERY", "searchAsYouTypeSpec": {"condition": "ENABLED"} }'
替换以下内容:
PROJECT_ID
:您的 Google Cloud 项目的 ID。PROJECT_ID
:您的 Google Cloud 项目的 ID。APP_ID
:您要查询的 Vertex AI Search 应用的 ID。QUERY
:要搜索的查询文本。
点击此处查看 curl 命令示例。
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/12345/locations/global/collections/default_collection/engines/my-app_4321/servingConfigs/default_search:search" -d '{ "query": "midsummer night", "searchAsYouTypeSpec": {"condition": "ENABLED"} }'