搜索数据对象

Search API 的用途是查找与给定查询类似的数据对象,并返回按相似度排序的结果列表。Search API 还支持过滤。

Search API 提供多种搜索数据对象的方式:向量搜索、全文搜索和语义搜索。此外,您还可以将任意类型的多次搜索组合在一起,以实现混合搜索。

借助 Vector Search,您可以提供自己的查询向量。这是搜索没有 embedding-config 的嵌入字段的必需方法。如果提供了多个 vector_search 字段,系统会使用相同的权重来合并结果。

以下示例演示了如何对 ID 为 COLLECTION_ID 的集合执行 Vector Search。

REST

在使用任何请求数据之前,请先进行以下替换:

  • COLLECTION_ID:集合的 ID。
  • LOCATION:您在其中使用 Agent Platform 的区域。
  • PROJECT_ID:您的 Google Cloud 项目 ID。

HTTP 方法和网址:

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search

请求 JSON 正文:

{
  "vector_search": {
    "search_field": "plot_embedding",
    "vector": {
      "values": [
        0.42426406871192845,
        0.565685424949238,
        0.7071067811865475
      ]
    },
    "filter": {
      "genre": {
        "$eq": "Thriller"
      }
    },
    "top_k": 5,
    "output_fields": {
      "data_fields": "*",
      "vector_fields": "*",
      "metadata_fields": "*"
    }
  }
}

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 JSON 响应:

{
  "results": [
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
        "createTime": "2026-01-31T20:05:06Z",
        "updateTime": "2026-02-02T13:59:24Z",
        "data": {
          "year": 1991,
          "title": "The Silence of the Lambs",
          "director": "Jonathan Demme",
          "genre": "Thriller"
        },
        "vectors": {
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.697
    },
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
        "createTime": "2026-02-04T14:35:29Z",
        "updateTime": "2026-02-04T14:37:29Z",
        "data": {
          "year": 1995,
          "title": "Se7en",
          "director": "David Fincher",
          "genre": "Thriller"
        },
        "vectors": {
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.75
    }
  ]
}

gcloud

在使用下面的命令数据之前,请先进行以下替换:

  • SEARCH_VECTOR_FILE:包含要搜索的密集向量或稀疏向量的 JSON 文件的本地路径。

    密集向量的文件内容示例:

    {
      "dense": {
        "values": [
          0.42426406871192845,
          0.565685424949238,
          0.7071067811865475
        ]
      }
    }

    稀疏向量的文件内容示例:

    {
      "sparse": {
        "indices": [1, 5, 10],
        "values": [0.1, 0.5, 0.21]
      }
    }
  • COLLECTION_ID:集合的 ID。
  • LOCATION:您在其中使用 Agent Platform 的区域。
  • PROJECT_ID:您的 Google Cloud 项目 ID。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud vector-search collections data-objects search \
  --vector-search-field="plot_embedding" \
  --vector-from-file=SEARCH_VECTOR_FILE \
  --json-filter='{"genre": {"$eq": "Thriller"}}' \
  --top-k=5 \
  --output-data-fields='*' \
  --output-vector-fields='*' \
  --output-metadata-fields='*' \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud vector-search collections data-objects search `
  --vector-search-field="plot_embedding" `
  --vector-from-file=SEARCH_VECTOR_FILE `
  --json-filter='{"genre": {"$eq": "Thriller"}}' `
  --top-k=5 `
  --output-data-fields='*' `
  --output-vector-fields='*' `
  --output-metadata-fields='*' `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud vector-search collections data-objects search ^
  --vector-search-field="plot_embedding" ^
  --vector-from-file=SEARCH_VECTOR_FILE ^
  --json-filter='{"genre": {"$eq": "Thriller"}}' ^
  --top-k=5 ^
  --output-data-fields='*' ^
  --output-vector-fields='*' ^
  --output-metadata-fields='*' ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

您应该会收到类似如下所示的响应:

---
dataObject:
  createTime: '2026-01-31T20:05:06Z'
  data:
    director: Jonathan Demme
    genre: Thriller
    title: The Silence of the Lambs
    year: 1991
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
  updateTime: '2026-02-02T13:59:24Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.697
---
dataObject:
  createTime: '2026-02-04T14:35:29Z'
  data:
    director: David Fincher
    genre: Thriller
    title: Se7en
    year: 1995
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
  updateTime: '2026-02-04T14:37:29Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.75

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
    search_field="plot_embedding",
    vector={"values": [0.1, 0.2, 0.3]},
    filter={"genre": {"$eq": "Thriller"}},
    top_k=5,
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    vector_search=vector_search,
)

# Make the request
response = data_object_search_service_client.search_data_objects(request=request)

# Handle the response
print(response)

调整搜索准确性和性能

对于嵌入数量超过 100,000 个的密集 ANN 索引上的 Vector Search,Agent Retrieval 默认会尝试在召回率和延迟时间之间实现最佳平衡。您可以通过指定目标召回率,针对您的用例调整此平衡。

值必须大于或等于 0.00 且小于或等于 1.00。

如需了解如何创建 ANN 索引,请参阅创建 ANN 索引。

以下示例演示了如何对目标召回率为 0.95 的密集 ANN 索引执行 Vector Search。

REST

HTTP 方法和网址:

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search

请求 JSON 正文:

{
  "vectorSearch": {
    "searchField": "plot_embedding",
    "vector": {
      "values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
    },
    "topK": 10,
    "searchHint": {
      "indexHint": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
        "denseScannParams": {
          "targetRecall": 0.95
        }
      }
    },
    "outputFields": {
      "dataFields": "*",
      "vectorFields": "*",
      "metadataFields": "*"
    }
  }
}

gcloud

将查询向量保存到 JSON 文件(例如 vector.json)中:

{
  "dense": {
    "values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
  }
}

然后,运行 gcloud vector-search collections data-objects search 命令:

gcloud vector-search collections data-objects search \
    --project=PROJECT_ID \
    --location=LOCATION \
    --collection=COLLECTION_ID \
    --vector-search-field=plot_embedding \
    --vector-from-file=vector.json \
    --use-index=INDEX_ID \
    --dense-scann-target-recall=0.95 \
    --top-k=10

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

collection = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Set the target recall rate on the index hint
search_hint = vectorsearch_v1.SearchHint(
    index_hint=vectorsearch_v1.SearchHint.IndexHint(
        name=f"{collection}/indexes/INDEX_ID",
        dense_scann_params=vectorsearch_v1.SearchHint.IndexHint.DenseScannParams(
            target_recall=0.95,
        ),
    ),
)

# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
    search_field="plot_embedding",
    vector={"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]},
    top_k=10,
    search_hint=search_hint,
    output_fields=vectorsearch_v1.OutputFields(
        data_fields=["*"],
        vector_fields=["*"],
        metadata_fields=["*"],
    ),
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent=collection,
    vector_search=vector_search,
)

# Make the request
response = data_object_search_service_client.search_data_objects(request=request)

# Handle the response
print(response)

此函数可执行不含稀疏向量的全文搜索。默认的“字词”查询方言会将整个输入视为具有隐式 AND 运算符的各个搜索字词。您可以将 enhanced_query 设置为 true,以扩展搜索字词、处理词干提取、移除停用词,并允许使用其他搜索运算符:

  • OR:一种区分大小写的析取运算符,用于匹配包含至少一个指定字词的文档。它仅适用于两个相邻的字词。

  • ":(双引号)用于搜索词组。

  • -:否定运算符。它会排除包含其前面任何字词的文档。

借助 Agent Retrieval 文本搜索 API,您可以通过包含一个或多个子查询的结构化查询来表达文本搜索,从而实现以下目的:

  • 与特定数据对象字段匹配。

  • 指定要执行的匹配类型:

    • 每个字词,不区分大小写

    • 完全匹配,区分大小写

  • 包含针对每种语言的增强功能,以匹配词干、同义词、拼写错误和停用词(例如“a”“an”和“the”)。

  • 使用 AND、OR 和 NOT 布尔运算符组合子查询。

  • 通过将子查询分组在一起来控制评估顺序。

  • 提升得分贡献度,以影响排名。

子查询有三种类型:

  • Text:提供搜索文本以及一个或多个要匹配的字段。

  • 一元:对单个子查询应用 NOT 操作。

  • 组合:应用 AND 或 OR 运算符来组合子查询,并可用于对其他组合子查询进行分组,以控制求值顺序。

本页面中的示例使用下表所示的集合。它包含六个数据对象,并在其数据架构中定义了以下字段:字符串 ID、Title、Description 和字符串数组 Keywords。

ID 标题 说明 关键字
1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者
2 慵懒夏日 棕色的狗在睡觉。 家养, 宠物, 房子, 犬科动物, 平静, 懒惰, 听话
3 狐狸与狗 聪明的狐狸智胜了狗。 野生, 家养, 冲突, 犬形亚目, 哺乳动物, 互动
4 棕熊 在森林中快速移动。 野生、森林、熊科、顶级掠食者、冬眠、庞大
5 狐狸的故事 小狗跳得很高。 狡猾、跳跃
6 我的慵懒夏日 一个关于在暑假期间放松身心的短篇故事。 夏天, 放松, 假期, 太阳

文本子查询

文本查询会与数据对象中的一个或多个字段进行匹配。所有结构化查询都必须至少包含一个文本查询。

以下示例定义了一个基本文本查询:

"text_search": {
  "structured_query": {
    "text": {
      "text": "fox vs dog"
    }
  }
}

默认情况下,文本会被拆分为单个字词,并且系统会在指定的字段中搜索每个字词。在前面的示例中,系统会在 Title 字段中搜索字词“fox”“vs”和“dog”。

文本查询具有以下可选参数:

  • fields:要匹配的字段数组。如果未指定,则默认与所有字段进行匹配。字段与隐式 OR 运算符匹配。

  • match_type:要执行的匹配类型。匹配类型可以是 EXACT,用于指定字段必须与搜索文本完全匹配。如果该字段是字符串数组,则会针对数组中的任何元素进行匹配。

  • enhancement:指定 enabled 和 languageCode,以便针对 languageCode 指定的语言(例如 en-US)中的同义词、词干、拼写错误和停用词执行匹配。默认不进行增强。

  • boost:可选。要应用于查询分数的系数。 默认值为 1.0。

匹配类型

match_type 参数指定搜索文本与字段值的匹配方式。

该参数的值可以是:

  • EXACT:字段必须与查询字词完全匹配。如果该字段是字符串数组,则会针对数组中的任何元素执行匹配。

以下示例指定了 EXACT 匹配类型:

"text_search": {
  "structured_query": {
    "text": {
      "text": "Fox vs Dog",
      "fields": [ "Title" ],
      "match_type": "EXACT"
    }
  }
}

字符串数组的匹配类型

查询结果如下表所示:

得分 ID 标题 说明 关键字
1.0000 3 狐狸与狗 聪明的狐狸智胜了狗。 野生, 家养, 冲突, 犬形亚目, 哺乳动物, 互动

如果字段是字符串数组,则搜索文本会与任何数组元素匹配。

以下示例展示了如何在 Keywords 字符串数组中搜索确切文本 wild:

"text_search": {
  "structured_query": {
    "text": {
      "text": "wild",
      "fields": [ "Keywords" ],
      "match_type": "EXACT"
    }
  }
}

查询结果如下表所示:

得分 ID 标题 说明 关键字
1.0000 3 狐狸与狗 聪明的狐狸智胜了狗。 野生, 家养, 冲突, 犬形亚目, 哺乳动物, 互动
1.0000 4 棕熊 在森林中快速移动。 野生、森林、熊科、顶级掠食者、冬眠、庞大
1.0000 1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者

查询增强功能

搜索查询可以包含可选的 queryEnhancement 参数,以指定特定于语言的增强功能。这包括与同义词、词干(例如,“jump”词干“jumping”)、拼写错误和停用词(例如“a”“an”和“the”)进行匹配。

该参数是一个具有以下属性的对象:

  • enabled:一个布尔值,用于指定是否启用增强功能。

  • languageCode:一个字符串,用于指定增强功能的语言(例如 en-US)。

以下示例为 en-US 语言启用了增强功能:

"text_search": {
  "structured_query": {
    "text": {
      "text": {
        "text": "jump",
        "fields": [ "Description" ],
        "queryEnhancement": {
          "enabled": true,
          "languageCode": "en-US"
        }
      }
    }
  }
}

查询结果如下表所示:

得分 ID 标题 说明 关键字
0.3419 1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者
0.3419 5 狐狸的故事 小狗跳得很高。 狡猾、跳跃

如果未指定 queryEnhancement 或 enabled 为 false,则不会进行匹配。

组合子查询

组合查询会对两个或更多子查询应用布尔运算。支持的操作为 AND 和 OR。

组合查询具有以下属性:

  • op:要应用于子查询的布尔运算符。值可以是 AND 或 OR。

  • subQueries:一个由要组合的子查询构成的数组。这些子查询可以是任何受支持的子查询类型,包括其他组合查询。嵌套深度上限为 2。

    • boost:可选。要应用于查询分数的系数。 默认值为 1.0。

连词 (AND)

AND 运算符会匹配包含所有子查询字词的数据对象。

以下示例演示了如何使用 AND 运算符组合三个文本查询:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

在示例中,只有在所有三个子查询都匹配时,才会进行匹配。

查询结果如下表所示:

得分 ID 标题 说明 关键字
5.0587 4 棕熊 在森林中快速移动。 野生、森林、熊科、顶级掠食者、冬眠、庞大
5.0587 1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者

当文本子查询有多个要匹配的字段时,系统会应用隐式 OR,如以下示例所示:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title", "Description" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

在前面的示例中:

  • 第一个子查询在 Title 或 Description 字段中匹配不区分大小写的字词 Brown。

  • 第二个子查询匹配 Description 字段中不区分大小写的字词 quick。

  • 第三个子查询与 Keywords 字符串数组字段中的任何值中的不区分大小写的字词 forest 和 predator 匹配。

  • 如果这三个子查询都匹配,则组合查询也会匹配。

查询结果如下表所示:

得分 ID 标题 说明 关键字
6.3176 1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者
5.0587 4 棕熊 在森林中快速移动。 野生、森林、熊科、顶级掠食者、冬眠、庞大

析取 (OR)

OR 运算符会匹配包含至少一个子查询字词的数据对象。

以下示例演示了如何使用 OR 运算符组合三个文本查询:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "OR",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title", "Description" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

在示例中,如果三个子查询中的任何一个匹配,则会进行匹配。

查询结果如下表所示:

得分 ID 标题 说明 关键字
6.3176 1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者
5.0587 4 棕熊 在森林中快速移动。 野生、森林、熊科、顶级掠食者、冬眠、庞大

分组

组合子查询可以嵌套在其他组合子查询中,以控制求值顺序。

以下示例演示了如何对子查询进行分组:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "combine": {
            "op": "OR",
            "subQueries": [
              {
                "text": {
                  "text": "Fox",
                  "fields": [ "Title" ]
                }
              },
              {
                "text": {
                  "text": "jumps",
                  "fields": [ "Description" ]
                }
              }
            ]
          }
        },
        {
          "unary": {
            "op": "NOT",
            "subQuery": {
              "text": {
                "text": "domestic",
                "fields": [ "Keywords" ]
              }
            }
          }
        }
      ]
    }
  }
}

上述示例等同于: (Title 中不区分大小写的 Fox 或 Description 中不区分大小写的 jumps)且不是任何 Keywords 元素中不区分大小写的 domestic。

下表显示了查询结果:

得分 ID 标题 说明 关键字
3.5178 1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者
2.2589 5 狐狸的故事 小狗跳得很高。 狡猾、跳跃

一元子查询

一元子查询将布尔运算应用于结构化查询中的单个子查询。NOT 运算符是唯一受支持的一元运算。

一元查询具有以下属性:

  • op:要应用于子查询的布尔运算符。值可以是 NOT。

  • subQuery:要应用一元运算的子查询。

    • boost:可选。要应用于查询分数的系数。 默认值为 1.0。

取反 (NOT)

NOT 运算符匹配不包含子查询字词的数据对象。

以下示例演示了如何使用 NOT 运算符:

"text_search": {
  "structured_query": {
    "unary": {
      "op": "NOT",
      "subQuery": {
        "text": {
          "text": "dog",
          "fields": [ "Description" ]
        }
      }
    }
  }
}

查询结果如下表所示:

得分 ID 标题 说明 关键字
1.000 4 棕熊 在森林中快速移动。 野生、森林、熊科、顶级掠食者、冬眠、庞大
1.000 6 我的慵懒夏日 一个关于在暑假期间放松身心的短篇故事。 夏天, 放松, 假期, 太阳

如果应用于字符串数组,则当该字词不包含在数组的任何元素中时,NOT 运算符会匹配数据对象。

在此示例中,如果 Keywords 字符串数组的任何元素中都不包含不区分大小写的字词 orange,则会进行匹配。

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        },
        {
          "unary": {
            "op": "NOT",
            "subQuery": {
              "text": {
                "text": "orange",
                "fields": [ "Keywords" ]
              }
            }
          }
        }
      ]
    }
  }
}

查询结果如下表所示:

得分 ID 标题 说明 关键字
6.0587 4 棕熊 在森林中快速移动。 野生、森林、熊科、顶级掠食者、冬眠、庞大

提高

任何子查询都可以具有 boost 参数,用于对子查询的分数应用乘数。默认情况下,所有子查询的 boost 均为 1.0。

以下示例演示了如何提升子查询:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "OR",
      "subQueries": [
        {
          "text": {
            "text": "fox",
            "fields": [ "Title" ]
          },
          "boost": 1.0
        },
        {
          "text": {
            "text": "jumps",
            "fields": [ "Description" ]
          },
          "boost": 1.0
        },
        {
          "text": {
            "text": "interaction",
            "fields": [ "Keywords" ]
          },
          "boost": 5.0
        }
      ]
    }
  }
}

查询结果如下表所示:

得分 ID 标题 说明 关键字
7.5534 3 狐狸与狗 聪明的狐狸智胜了狗。 野生, 家养, 冲突, 犬形亚目, 哺乳动物, 互动
2.5178 1 The Quick Brown Fox 一只敏捷的棕色狐狸轻松跃过那只懒狗。 野生, 森林, 哺乳动物, 橙色, 敏捷, 捕食者
1.2589 5 狐狸的故事 小狗跳得很高。 狡猾、跳跃

此搜索功能会将您的文本查询转换为嵌入,以便根据语义含义查找结果。它使用架构中定义的 embedding-config 生成查询嵌入。如果提供了多个 vector_search 字段,系统会使用相同的权重来合并结果。

使用 batch_search_data_objects 并行执行多项搜索(Vector Search、文本搜索和语义搜索)。您可以选择使用 ReciprocalRankFusion 排序器合并结果并对其进行排名,该排序器使用倒数排序融合 (RRF) 算法合并结果集。

正在对合并结果进行排序

使用 combine.sorts,根据集合数据架构中的字段对 batch_search_data_objects 请求的合并结果进行重新排序,例如价格升序、年份降序或状态标志。combine.sorts 在 v1beta batchSearch 方法中可用。

排序会在 RRF 之后、VertexRanker(如果已配置)之后以及 combine.top_k 截断之前应用于合并后的结果。系统只会对搜索检索到的候选对象进行排序,而不会对集合中的每个数据对象进行排序。例如,您可以在单个请求中请求语义匹配度最高的三篇最新文章,如果发布时间相同,则按观看次数排序。

本部分中的示例使用以下数据对象。发布时间会同时存储为 ISO 8601 字符串和 Unix 纪元数字。这两种格式均按时间顺序排序。

ID title published_at published_unix views
a1 美联储维持利率不变 2026-09-29T14:00:00Z 1790690400 5200
a2 市场因财报而上涨 2026-09-29T14:00:00Z 1790690400 8100
a3 油价下跌 2026-09-28T09:30:00Z 1790587800 12000
a4 科技股反弹 2026-09-30T08:15:00Z 1790756100 3000
a5 债券收益率攀升 2026-09-27T16:45:00Z 1790527500 9000

以下示例演示了对 v1beta dataObjects:batchSearch 方法的请求正文,该方法会返回三篇最新文章,并按最高观看次数打破平局:

{
  "searches": [
    {
      "vector_search": {
        "search_field": "embedding",
        "vector": { "values": [0.7, 0.3, 0.1] },
        "top_k": 5,
        "output_fields": { "data_fields": ["title", "published_at", "views"] }
      }
    }
  ],
  "combine": {
    "ranker": { "rrf": { "weights": [1.0] } },
    "top_k": 3,
    "sorts": [
      { "field": "published_at", "direction": "DESC" },
      { "field": "views", "direction": "DESC" }
    ]
  }
}

请求的结果如下表所示。按 published_unix 而不是 published_at 排序会返回相同的顺序。

ID title published_at views
a4 科技股反弹 2026-09-30T08:15:00Z 3000
a2 市场因财报而上涨 2026-09-29T14:00:00Z 8100
a1 美联储维持利率不变 2026-09-29T14:00:00Z 5200

数据对象 a2 和 a1 具有相同的 published_at 值,因此 views 决定了它们的顺序。数据对象 a3 的浏览次数最多,但时间较早,因此 combine.top_k 将其排除。

在 output_fields 中添加排序字段,以缩短延迟时间

为了对合并后的结果进行排序,服务需要每个候选数据对象的每个排序字段的值。它会从每次搜索返回的数据中读取这些值,而这些值由该搜索的 output_fields 控制。如果任何候选文档缺少任何排序字段,该服务会在排序之前通过额外的查找从存储空间中提取缺少的字段。

只有当每次搜索都返回每个排序字段时,服务才会跳过查找。 这包括重新排序器不保留其结果的搜索,因为排序会对所有搜索中的候选结果运行。如果请求中的某项搜索省略了排序字段,则请求会执行查找。

例如,以下请求按 published_at 和 views 排序。Vector Search 会返回这两个字段,但文本搜索仅返回 title,因此服务会执行额外的查找:

{
  "searches": [
    {
      "vector_search": {
        "search_field": "embedding",
        "vector": { "values": [0.7, 0.3, 0.1] },
        "top_k": 5,
        "output_fields": { "data_fields": ["title", "published_at", "views"] }
      }
    },
    {
      "text_search": {
        "search_text": "rates",
        "data_field_names": ["title"],
        "top_k": 5,
        "output_fields": { "data_fields": ["title"] }
      }
    }
  ],
  "combine": {
    "ranker": { "rrf": { "weights": [1.0, 1.0] } },
    "top_k": 3,
    "sorts": [
      { "field": "published_at", "direction": "DESC" },
      { "field": "views", "direction": "DESC" }
    ]
  }
}

为避免执行查找,请将 published_at 和 views 也添加到文本搜索的 output_fields 中:

"output_fields": { "data_fields": ["title", "published_at", "views"] }

使用 "data_fields": ["*"] 请求所有字段也可以避免查找。

如果您不希望在响应中包含排序字段,仍然可以将其从 output_fields 中排除。该请求会以相同的顺序返回相同的结果,只是速度较慢。对字段进行排序,以便从响应中移除 output_fields 中没有搜索请求的字段。

排序规范

combine.sorts 中的每个条目都包含以下字段:

字段 必需 说明
field 是 要排序依据的数据字段。对嵌套字段使用点路径,例如 product.price。该字段必须存在于集合架构中。
direction 可选 排序方向:ASC 或 DESC。默认值为 ASC。

条目会按顺序应用。第一个条目是主要排序键,后面的每个条目仅用于解决前面条目留下的平局。如需在值经常冲突时使顺序可预测,请添加更多条目,例如 year 升序,然后 title 升序。

如果数据对象在每个排序条目上都相同,则排名得分较高的数据对象排在前面。Ranker 得分是 RRF 得分,如果配置了重排序器,则为 VertexRanker 得分。如果分数也相同,则数据对象会按数据对象 ID 升序排序,因此同一请求始终会按相同顺序返回结果。

可排序的字段类型

您可以按以下架构类型的字段进行排序:

  • 数字(number 或 integer):值作为双精度浮点数进行比较,因此大于 253 的整数可能会被视为相等。

  • 布尔值:按升序排序时,false 排在 true 之前。

  • 字符串:值按 UTF-8 字节顺序进行比较,区分大小写。例如,"Apple" 排在 "Zebra" 之前,后者排在 "apple" 之前。 如需进行不区分大小写的排序,请存储字段的标准化副本(例如小写副本),并按该字段进行排序。

  • 日期和时间戳:没有专用的日期类型。以一致的格式将这些值存储为 ISO 8601 UTC 字符串,或存储为 Unix 纪元数字。

您无法按数组或对象字段进行排序。

对于 ASC 和 DESC,排序字段没有值的数据对象会放在所有排序字段有值的数据对象之后。

与排名器的互动

  • RRF:RRF 会合并搜索结果,combine.sorts 对合并后的列表重新排序,然后 combine.top_k 截断该列表。

  • VertexRanker:combine.sorts 会在 combine.top_k 截断之前重新排列重排序器的 top_n 输出。最终顺序遵循排序条目,而不是重排序器得分。响应在 search_response_metadata.warnings 字段中包含一条警告,其中包含代码 FAILED_PRECONDITION 和消息 "Both sort and a Vertex reranker were configured. The final order reflects the sort, not the reranker score."。请求仍然成功。

如果 VertexRanker 调用失败,系统会改为对 RRF 融合结果应用 combine.sorts。如需了解详情,请参阅故障处理和警告。

错误

错误代码 原因
INVALID_ARGUMENT combine.sorts[i].field 为空,或者该字段未在集合架构中定义。
INVALID_ARGUMENT “combine.sorts[i].direction”不是有效值。
FAILED_PRECONDITION combine.sorts[i].field 是指无法排序的字段,例如数组或对象字段。