文档中心

向量数据库VikingDB

检索(Search)

searchByKeywords

概述

search_by_keywords 用于在指定数据集索引中按关键词检索数据，返回与关键词相关的数据及相关性分数。

bm25：全文检索模式（推荐）。数据集需要配置 FullText。该模式基于全文检索字段进行分词检索，并使用 BM25 计算相关性分数，适用于强关键词、弱语义、精确词项匹配等场景。
semantic_then_match：语义匹配模式。数据集需要配置 Vectorize，并对 text 字段做向量化。该模式基于向量化文本字段进行语义召回，再结合关键词命中情况排序，主要用于兼容历史关键词检索行为。

新接入关键词检索时，建议优先使用 bm25 模式。

如果请求中不指定 mode，系统会根据数据集配置自动选择模式：

数据集配置了 FullText 时，使用 bm25。
数据集未配置 FullText、但配置了 Vectorize 时，使用 semantic_then_match。
数据集同时配置 FullText 和 Vectorize 时，默认优先使用 bm25。

方法定义

response = index_client.search_by_keywords(request)

其中：

index_client 类型为 IndexClient。
request 类型为 SearchByKeywordsRequest。
返回类型为 SearchResponse。

请求参数

请求参数类型为 SearchByKeywordsRequest。resource_id、collection_name 和 index_name 通过 client.index(...) 设置，其余参数通过 SearchByKeywordsRequest 设置。

参数	必须	类型	备注
resource_id	二选一	`Optional[str]`	资源 ID。`resource_id` 和 `collection_name` 必须二选一。通过 `client.index(...)` 设置。
collection_name	二选一	`Optional[str]`	Collection 名称。`resource_id` 和 `collection_name` 必须二选一。通过 `client.index(...)` 设置。
index_name	是	`str`	Index 名称。通过 `client.index(...)` 设置。
mode	否	`Optional[str]`	检索模式。可选值为 `bm25`、`semantic_then_match`。不传时，系统根据数据集配置自动选择；同时配置 FullText 和 Vectorize 时默认使用 `bm25`。
keywords	二选一	`Optional[Sequence[str]]`	关键词列表。`keywords` 和 `query` 不能同时传，也不能都不传。推荐传入 1-5 个关键词，最多 20 个；元素不能为空字符串。
query	二选一	`Optional[str]`	检索语句，使用 analyzer分析。推荐长度不超过 100 字节，硬性限制为小于 2048 字节；系统最多使用 20 个有效关键词。
case_sensitive	否	`Optional[bool]`	是否大小写敏感。默认 `False`，仅对 `semantic_then_match` 模式生效。
fields	否	`Optional[Sequence[str]]`	仅对 `bm25` 模式生效，用于指定参与检索的 FullText 字段。不传时检索所有 FullText 字段。
fields_weights	否	`Optional[Mapping[str, float]]`	仅对 `bm25` 模式生效。key 必须与 `fields` 一一对应；value 为字段权重。不传时，各字段按默认权重 `1.0` 相加。
bm25_k1	否	`Optional[float]`	仅对 `bm25` 模式生效。默认值为 `1.25`，要求大于 0，通常取值在 1.2 到 2.0 之间。
bm25_b	否	`Optional[float]`	仅对 `bm25` 模式生效。默认值为 `0.75`，取值范围为 [0, 1]。
highlight	否	`Optional[Highlight]`	高亮信息配置。传入时 `highlight.enable` 必填。开启后，返回的 `SearchItemResult` 包含 `highlight`。
filter	否	`Optional[Mapping[str, Any]]`	标量过滤条件。默认为空，不做过滤。
output_fields	否	`Optional[Sequence[str]]`	要返回的标量字段列表。不传时返回所有标量字段；传空列表时不返回标量字段。
limit	否	`Optional[int]`	检索结果数量，默认值为 10，上限为 100000。
offset	否	`Optional[int]`	分页偏移量，默认值为 0，最小值为 0。不建议设置过大值。
advance	否	`Optional[SearchAdvance]`	高级参数，普通场景无需设置。详见检索公共参数。
partition	否	`Optional[str]`	仅检索指定分区；不传时默认检索全部分区。

Highlight

参数	必须	类型	备注
enable	是	`Optional[bool]`	是否返回关键词命中的高亮信息。设置为 `True` 时，返回结果包含 `highlight`。

返回参数

返回类型为 SearchResponse。

参数	必须	类型	备注
request_id	是	`Optional[str]`	请求链路 ID。排查问题时请记录该值。
code	是	`Optional[str]`	服务返回码。成功时为 `Success`。
message	是	`Optional[str]`	服务返回信息。
result	否	`Optional[SearchResult]`	检索结果。请求失败时可能为空。

SearchResult

参数	必须	类型	备注
data	是	`List[SearchItemResult]`	查询到的数据列表。
filter_matched_count	否	`Optional[int]`	满足过滤条件的文档总数。
total_return_count	是	`Optional[int]`	本次实际返回的结果数量。
real_text_query	否	`Optional[str]`	模型处理后实际参与检索的文本查询。
effective_keywords	否	`Optional[Mapping[str, List[str]]]`	各全文检索字段实际生效的关键词列表，主要在 `bm25` 模式下返回。
token_usage	否	`Dict[str, Any]`	Token 使用情况。

SearchItemResult

参数	必须	类型	备注
id	是	`Any`	数据的主键字段值。
fields	是	`Dict[str, Any]`	返回的标量字段。key 为字段名，value 为字段值。
score	是	`Optional[float]`	最终相关性得分。检索结果按 `score` 排序。
ann_score	否	`Optional[float]`	向量检索的原始 ANN 得分。
highlight	否	`Optional[Mapping[str, Mapping[str, List[int]]]]`	高亮信息。第一层 key 为字段名，第二层 key 为命中的关键词或词项，value 为基于字符的 0 起始命中位置列表。
origin_score	否	`Optional[float]`	原始得分，部分检索模式下返回。
addition_score	否	`Optional[float]`	附加得分，部分检索模式下返回。

示例

运行示例前，请完成以下准备：

按“安装与 client 初始化”文档在 Python 项目中引入 VikingDB 数据面 SDK。
配置 VIKINGDB_AK、VIKINGDB_SK、VIKINGDB_HOST、VIKINGDB_REGION 环境变量。
配置 VIKINGDB_COLLECTION 和 VIKINGDB_INDEX，分别指向目标 Collection 和 Index。

bm25 模式示例

以下示例适用于已配置 FullText 的数据集。

请求参数

import os
import traceback

from vikingdb import IAM
from vikingdb.vector import (
    SearchByKeywordsRequest,
    VikingDB,
    VikingVectorException,
)

client = VikingDB(
    host=os.environ["VIKINGDB_HOST"],
    region=os.environ["VIKINGDB_REGION"],
    auth=IAM(
        ak=os.environ["VIKINGDB_AK"],
        sk=os.environ["VIKINGDB_SK"],
    ),
    scheme="https",
)

index_client = client.index(
    collection_name=os.environ["VIKINGDB_COLLECTION"],
    index_name=os.environ["VIKINGDB_INDEX"],
)

request = SearchByKeywordsRequest(
    keywords=["机器学习", "检索", "排序"],
    mode="bm25",
    fields=["f_text"],
    output_fields=["f_text"],
    limit=5,
)

try:
    response = index_client.search_by_keywords(request)
    print("request success:")
    print(response)
except VikingVectorException as error:
    print("request VikingVectorException:")
    print("code:", error.code)
    print("http_status_code:", error.status_code)
    print("message:", error.message)
    print("request_id:", error.request_id)
except Exception as error:
    print("request exception:", error)
    traceback.print_exc()

bm25 模式开启 highlight 示例

以下示例在 bm25 模式下开启高亮信息返回。

请求参数

import os
import traceback

from vikingdb import IAM
from vikingdb.vector import (
    Highlight,
    SearchByKeywordsRequest,
    VikingDB,
    VikingVectorException,
)

client = VikingDB(
    host=os.environ["VIKINGDB_HOST"],
    region=os.environ["VIKINGDB_REGION"],
    auth=IAM(
        ak=os.environ["VIKINGDB_AK"],
        sk=os.environ["VIKINGDB_SK"],
    ),
    scheme="https",
)

index_client = client.index(
    collection_name=os.environ["VIKINGDB_COLLECTION"],
    index_name=os.environ["VIKINGDB_INDEX"],
)

request = SearchByKeywordsRequest(
    keywords=["机器学习", "检索", "排序"],
    mode="bm25",
    fields=["f_text"],
    output_fields=["f_text"],
    limit=5,
    highlight=Highlight(enable=True),
)

try:
    response = index_client.search_by_keywords(request)
    print("request success:")
    print(response)
except VikingVectorException as error:
    print("request VikingVectorException:")
    print("code:", error.code)
    print("http_status_code:", error.status_code)
    print("message:", error.message)
    print("request_id:", error.request_id)
except Exception as error:
    print("request exception:", error)
    traceback.print_exc()

最近更新时间：2026.11.05 16:37:13

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

Highlight #

SearchResult #

SearchItemResult #

bm25 模式示例 #

请求参数 #

bm25 模式开启 highlight 示例 #

请求参数 #

Highlight

SearchResult

SearchItemResult

bm25 模式示例

请求参数

bm25 模式开启 highlight 示例

请求参数