Method: projects.locations.dataStores.documents.search

搜索单个数据存储区的文档。

返回经过排序的子文档片段，每个片段都会引用其来源文档，并带有引用所需的出处信息。

HTTP 请求

POST https://vectorsearch.googleapis.com/v1beta/{parent}/documents:search

路径参数

参数
parent

string

必需。要搜索的数据存储区。格式：projects/{project}/locations/{location}/dataStores/{dataStore}

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "topK": integer,
  "documentIds": [
    string
  ],
  "rankingSpec": {
    object (RankingSpec)
  },
  "filter": {
    object
  },
  "outputFields": {
    object (OutputFields)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textQuery": {
    object (TextQuery)
  }
  // End of mutually exclusive fields.
}
字段
topK

integer

可选。要返回的结果数量。默认值为 10。大于 100 的值会强制转换为 100。
documentIds[]

string

可选。将搜索范围限制为这些文档 ID。最多 100 个。如果为空，则搜索整个数据存储区。
rankingSpec

object (RankingSpec)

可选。控制结果的排名方式。
filter

object (Struct format)

可选。将搜索范围限制为与此过滤条件（DocumentSearchResult 的字段路径上的 JSON 对象）匹配的片段：

  • metadata.<property>：在 DataStore 的 documentMetadataSchema 中声明的属性，例如 metadata.category。
  • unstructured_details.page_range.start_page 和 .end_page：适用于 UNSTRUCTURED 数据存储区。并非每个段都有页范围；请参阅 UnstructuredSegmentDetails.page_range。
  • video_details.start_offset 和 .end_offset：以秒为单位，适用于 VIDEO DataStore。

比较：$eq、$ne、$lt、$lte、$gt、$gte、$in、$nin、$all 和 $exists。将它们与 $and、$or 和 $not 组合使用，最多嵌套两层。例如：

{"$and": [{"metadata.year": {"$gte": 2025}}, {"unstructured_details.page_range.start_page": {"$lte": 20}}]}
outputFields

object (OutputFields)

可选。每个结果中要返回的字段。
必需。要搜索的查询。必须且只能设置一种查询类型。以下是互斥字段的列表。在响应中，最多只能设置其中一个字段：
textQuery

object (TextQuery)

文本查询。
互斥字段结束。

响应正文

DocumentSearchService.SearchDocuments 的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
字段
results[]

object (DocumentSearchResult)

仅限输出。与搜索条件匹配的文档片段，按相关性排序。
warnings[]

object (Status)

仅限输出。执行期间发生的警告或非严重错误。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/vectorsearch
  • https://www.googleapis.com/auth/vectorsearch.readonly

如需了解详情，请参阅 Authentication Overview。

TextQuery

文本查询。

JSON 表示法 
{
  "text": string
}
字段
text

string

必需。要搜索的文本。

RankingSpec

控制结果的排名方式。

JSON 表示法 
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
字段
rerankingSpec

object (RerankingSpec)

可选。控制重排序阶段。

RerankingSpec

在混合检索和倒数排序融合 (RRF) 之后，对候选结果应用语义重排序的配置。

JSON 表示法 
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
字段
enabled

boolean

可选。是否对融合结果进行重排序。默认值为 false：除非调用方选择启用，否则结果会按 RRF 融合顺序返回。

启用后，重排序功能会在 Vertex Ranking Service 上使用 semantic-ranker-fast@latest，并且需要在调用方的项目中启用 Discovery Engine API。

VIDEO DataStore 不支持：启用它的请求会失败，并显示 INVALID_ARGUMENT。
rankOversamplingFactor

integer

可选。在重排序之前对候选内容进行过采样的系数。检索到的用于重排序的候选集总数为 min(rankOversamplingFactor * topK, 200)。重排序后，结果会缩减为 SearchDocumentsRequest.top_k。

除非 enabled 为 true，否则会被忽略。启用后，默认值为 5（检索 min(5 * topK, 200) 个候选对象，最多 200 个）。

如需在不进行过采样的情况下重新排名，请将此字段设置为 1。

OutputFields

除了每个结果都包含的字段之外，每个 DocumentSearchResult 还要返回的字段。

JSON 表示法 
{
  "metadata": [
    string
  ]
}
字段
metadata[]

string

可选。要在 DocumentSearchResult.document.metadata 中返回的元数据属性，其名称与在 DataStore 的 documentMetadataSchema 中声明的名称相同。嵌套属性通过其点路径命名，例如 address.city，不带 filter 使用的 metadata. 前缀。"*" 会返回每个已声明的属性。未设置时，返回 none。如果文档没有某个属性的值，则该属性会被省略。

DocumentSearchResult

文档的单个匹配片段。

JSON 表示法 
{
  "document": {
    object (Document)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "videoDetails": {
    object (VideoSegmentDetails)
  },
  "unstructuredDetails": {
    object (UnstructuredSegmentDetails)
  }
  // End of mutually exclusive fields.
}
字段
document

object (Document)

仅限输出。此片段所属的文档，包括其资源名称和提取来源的 Cloud Storage 位置。

请注意，并非所有 Document 字段都会填充。如需获取完整文档，请对返回的文档名称调用 documents.get。
片段在其文档中的位置详情。设置哪个字段取决于父级数据存储区的 document_type。以下是互斥字段的列表。在响应中，最多只能设置其中一个字段：
videoDetails

object (VideoSegmentDetails)

当父级数据存储区的 documentType 为 VIDEO 时设置。
unstructuredDetails

object (UnstructuredSegmentDetails)

当父级数据存储区的 documentType 为 UNSTRUCTURED 时设置。
互斥字段结束。

VideoSegmentDetails

在视频文档中定位片段。

JSON 表示法 
{
  "startOffset": string,
  "endOffset": string
}
字段
startOffset

string (Duration format)

仅限输出。此片段相对于来源视频开头的起始位置。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
endOffset

string (Duration format)

仅限输出。此片段相对于源视频开头的结束位置。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

UnstructuredSegmentDetails

在非结构化文档中定位一个片段，并携带其文本。

JSON 表示法 
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
字段
contentSnippet

string

仅限输出。片段的文本内容。
pageRange

object (PageRange)

仅限输出。片段在源文档中的位置。针对 PDF、PowerPoint 和 Excel 文件设置，其中一页是指一个 PDF 页面、一张幻灯片或一个工作表。对于纯文本和 Word 文件，仅在文件拆分为页面时设置（pageSegmentationConfig，采用数字解析）；页面是文本的连续部分，按顺序编号。

PageRange

源文档中的页码范围。页码从 1 开始，范围包含起始页和结束页；单页表示为 startPage == endPage。

JSON 表示法 
{
  "startPage": string,
  "endPage": string
}
字段
startPage

string (int64 format)

仅限输出。范围的第一页。
endPage

string (int64 format)

仅限输出。范围的最后一页。