文档中心

向量数据库VikingDB

检索(Search)

关键词检索-SearchByKeywords

概述

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

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

新接入关键词检索时，建议优先使用 bm25 模式。
如果请求中不指定 mode，系统会根据数据集配置自动选择模式：

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

请求接口

请求向量数据库 VikingDB 的 OpenAPI 接口时，可以使用API Key（推荐）或者 AK、SK 构造签名进行鉴权。请参见数据面API调用流程，复制调用示例并填入必要信息。

URI	/api/vikingdb/data/search/keywords	统一资源标识符
方法	POST	客户端对向量数据库服务器请求的操作类型
请求头	Content-Type: application/json	请求消息类型
	Authorization: ***	鉴权

请求体参数

仅列出本接口特有的参数。更多信息请参见检索公共参数。

参数名	必选	类型	备注
mode	否	string	检索模式。可选值： `bm25`：全文检索模式。推荐使用，要求数据集已配置 FullText。 `semantic_then_match`：语义匹配模式，要求数据集已配置 Vectorize，并对 text 字段做向量化。不填时，系统会根据数据集配置自动选择。若数据集同时配置 FullText 和 Vectorize，默认使用 bm25。推荐传入 1-5 个关键词，最多可传 20 个；元素不能为空字符串。
keywords	是（二选一）	list	关键词列表。`keywords`和 `query`必须二选一，不能同时传，也不能都不传。建议只传入对检索有实际区分度的词，避免传入助词、介词、语气词、标点等无意义词。推荐传入 1-5 个关键词，最多可传 20 个；元素不能为空字符串。示例：推荐 `["机器学习", "检索", "排序"]`；不推荐 `["帮我", "找一下", "关于", "的"]`。
query	是（二选一）	string	检索语句，使用analyzer分析。`keywords`和 `query`必须二选一，不能同时传，也不能都不传。建议使用尽可能短的查询内容，并以关键词拼接为主，避免输入完整的语义化描述或长句。系统会从 query 中提取有效关键词，最多使用 20 个；有效关键词指经过大小写转换、停用词过滤等处理后，仍可参与检索匹配的关键词。推荐长度不超过 100 字节；硬性限制为小于 2048 字节。示例：推荐 `"机器学习检索排序"`、`"向量数据库 bm25"`；不推荐 `"请帮我查找所有关于机器学习检索排序机制的详细介绍"`。
case_sensitive	否	bool	是否大小写敏感。默认 false。仅对 semantic_then_match 模式生效。
fields	否	list	只对 bm25 模式生效，用于指定检索哪些全文检索字段。不传时，默认检索数据集中所有 FullText 字段。传入时，每个字段都必须是已配置 FullText 的 text 字段。
fields_weights	否	float	只针对bm25搜索时生效。设置各全文检索字段的 BM25 得分权重。key为字段名，必须与fields参数列表一一对应，value为权重系数（float）。不传时，各字段权重按默认1.0相加。
bm25_k1	否	map	只针对bm25搜索时生效。 bm25的k1参数。默认1.25。用于调节词频对相关性分数的影响。要求大于0，通常取值在 1.2 到 2.0 之间。k1越大，高频词越能显著提升分数；k1越小，词频越容易饱和，即高频词的得分增长有限。一般无需设置。
bm25_b	否	float	只针对bm25搜索时生效。 bm25的b参数。默认0.75。用于调节文档长度对相关性分数的影响。要求在[0,1]之间。b越大，长文档的分数被压缩的越明显；b越小，文档长度的影响越有限，接近0则长文档和短文档平等对待。一般无需设置。
highlight	否	map	高亮信息配置，适用于需要在检索结果页标出关键词命中位置的场景。第一层 key 为字段名，第二层 key 为命中的关键词或词项，value 为命中位置列表。位置为基于字符的 0 起始下标。当前支持子参数 `enable`。传入 highlight 时，`highlight.enable`必填。设置 `highlight.enable=true` 后，返回结果中包含 highlight 字段。开启 highlight 会增加额外处理开销，默认不推荐使用；仅在需要展示命中位置时开启。

响应体参数

见检索公共参数。

请求响应示例

bm25模式示例

以下示例适用于已配置 FullText 的数据集。新接入关键词检索时，建议使用该模式。

请求参数

req_path = "/api/vikingdb/data/search/keywords"
req_body = {
    "collection_name": "test_coll_with_fulltext",
    "index_name": "idx_1",
    "keywords": ["机器学习", "检索", "排序"],
    "mode": "bm25",
    "fields": ["f_text"],
    "output_fields": ["f_text"],
    "limit": 5
}

响应参数

{
    "code": "Success",
    "message": "The API call was executed successfully.",
    "request_id": "02175438839168500000000000000000000ffff0a003ee4fc3499",
    "result": {
        "data": [
            {
                "id": "uid_001",
                "fields": {
                    "f_text": "机器学习检索"
                },
                "score": 3.605649671017216
            }
        ],
        "total_return_count": 1
    }
}

bm25 模式开启 highlight 示例

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

请求参数

req_path = "/api/vikingdb/data/search/keywords"
req_body = {
    "collection_name": "test_coll_with_fulltext",
    "index_name": "idx_1",
    "keywords": ["机器学习", "检索", "排序"],
    "mode": "bm25",
    "fields": ["f_text"],
    "output_fields": ["f_text"],
    "limit": 5,
    "highlight": {
        "enable": True
    }
}

响应参数

{
    "code": "Success",
    "message": "The API call was executed successfully.",
    "request_id": "02175438839168500000000000000000000ffff0a003ee4fc3499",
    "result": {
        "data": [
            {
                "id": "uid_001",
                "fields": {
                    "f_text": "机器学习检索"
                },
                "highlight": {
                    "f_text": {
                        "机器": [0],
                        "学习": [2],
                        "检索": [4]
                    }
                },
                "score": 3.605649671017216
            }
        ],
        "total_return_count": 1
    }
}

请求模板

"""
pip3 install volcengine
"""

from volcengine.base.Request import Request
import requests, json


class ClientForDataApi:
    def __init__(self, api_key=None, host=None):
        """
        初始化ClientForDataApi类
        :param api_key: VikingDB的API Key
        :param host: VikingDB的API Host
        """
        if not api_key or not host:
            raise ValueError("api_key and host are required")
        self.api_key = api_key
        self.host = host

    def prepare_request(self, method, path, params=None, data=None):
        r = Request()
        r.set_shema("https")
        r.set_method(method)
        r.set_connection_timeout(10)
        r.set_socket_timeout(10)
        mheaders = {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "Host": self.host,
            "Authorization": f"Bearer {self.api_key}",
        }
        r.set_headers(mheaders)
        if params:
            r.set_query(params)
        r.set_host(self.host)
        r.set_path(path)
        if data is not None:
            r.set_body(json.dumps(data))
        return r

    def do_req(self, req_method, req_path, req_params, req_body):
        req = self.prepare_request(
            method=req_method, path=req_path, params=req_params, data=req_body
        )
        return requests.request(
            method=req.method,
            url="https://{}{}".format(self.host, req.path),
            headers=req.headers,
            data=req.body,
            timeout=10000,
        )


if __name__ == "__main__":
    import os
    client = ClientForDataApi(
        api_key=os.environ.get("VIKINGDB_API_KEY", "***"), # 从环境变量中获取API Key，若未设置则使用默认值
        host="api-vikingdb.vikingdb.cn-beijing.volces.com",  # 替换为您所在的域名
    )
    req_method = "POST"
    req_params = None
    req_path = "/api/vikingdb/data/search/keywords"
    req_body = {
        "collection_name": "test_coll_with_vectorize",
        "index_name": "idx_1",
        "keywords": ["火山", "向量", "检索", "亿"],
        "output_fields": [
            "f_text"
        ],
        "limit": 5,
    }
    result = client.do_req(
        req_method=req_method, req_path=req_path, req_params=req_params, req_body=req_body
    )
    print("req http status code: ", result.status_code)
    print("req result: \n", result.text)

错误处理补充

错误码

本接口的业务错误码、触发条件和处理建议统一参见向量库 V2 错误码。排查时请同时记录响应中的 request_id，以便定位具体请求。

最近更新时间：2026.09.28 14:22:30

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

bm25模式示例 #

bm25 模式开启 highlight 示例 #

错误处理补充 #

错误码 #

bm25模式示例

bm25 模式开启 highlight 示例

错误处理补充

错误码