文档中心

向量数据库VikingDB

检索

searchByKeywords

概述

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

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

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

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

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

方法定义

response, err := indexClient.SearchByKeywords(ctx, request)

方法签名：

SearchByKeywords(
    ctx context.Context,
    request model.SearchByKeywordsRequest,
    opts ...vector.RequestOption,
) (*model.SearchResponse, error)

请求参数

ResourceID、CollectionName 和 IndexName 通过 model.IndexLocator 设置，其余参数通过 model.SearchByKeywordsRequest 设置。

参数	必须	类型	备注
ResourceID	二选一	`string`	资源 ID。`ResourceID` 和 `CollectionName` 必须二选一。
CollectionName	二选一	`string`	Collection 名称。`ResourceID` 和 `CollectionName` 必须二选一。
IndexName	是	`string`	Index 名称。
Mode	否	`string`	检索模式。可选值为 `bm25`、`semantic_then_match`。不传时，系统根据数据集配置自动选择；同时配置 FullText 和 Vectorize 时默认使用 `bm25`。
Keywords	二选一	`[]string`	关键词列表。`Keywords` 和 `Query` 不能同时传，也不能都不传。推荐传入 1-5 个关键词，最多 20 个；元素不能为空字符串。
Query	二选一	`string`	检索语句，使用 analyzer分析。推荐长度不超过 100 字节，硬性限制为小于 2048 字节；系统最多使用 20 个有效关键词。
CaseSensitive	否	`bool`	是否大小写敏感。默认 `false`，仅对 `semantic_then_match` 模式生效。
Fields	否	`[]string`	仅对 `bm25` 模式生效，用于指定参与检索的 FullText 字段。不传时检索所有 FullText 字段。
FieldsWeights	否	`map[string]float32`	仅对 `bm25` 模式生效。key 必须与 `Fields` 一一对应；value 为字段权重。不传时，各字段按默认权重 `1.0` 相加。
BM25K1	否	`*float64`	仅对 `bm25` 模式生效。默认值为 `1.25`，要求大于 0，通常取值在 1.2 到 2.0 之间。
BM25B	否	`*float64`	仅对 `bm25` 模式生效。默认值为 `0.75`，取值范围为 [0, 1]。
Highlight	否	`*model.Highlight`	高亮信息配置。传入时 `Highlight.Enable` 必填。开启后，返回的 `SearchItemResult` 包含 `Highlight`。
Filter	否	`model.MapStr`	标量过滤条件。默认为空，不做过滤。
OutputFields	否	`[]string`	要返回的标量字段列表。不传时返回所有标量字段；传空切片时不返回标量字段。
Limit	否	`*int`	检索结果数量，默认值为 10，上限为 100000。
Offset	否	`*int`	分页偏移量，默认值为 0，最小值为 0。不建议设置过大值。
Advance	否	`*model.SearchAdvance`	高级参数，普通场景无需设置。详见检索公共参数。
Partition	否	`string`	仅检索指定分区；不传时默认检索全部分区。

Highlight

参数	必须	类型	备注
Enable	是	`*bool`	是否返回关键词命中的高亮信息。设置为 `true` 时，返回结果包含 `Highlight`。

返回参数

返回类型为 *model.SearchResponse。

参数	必须	类型	备注
RequestID	是	`string`	请求链路 ID。排查问题时请记录该值。
Code	是	`string`	服务返回码。成功时为 `Success`。
Message	是	`string`	服务返回信息。
Result	否	`*model.SearchResult`	检索结果。请求失败时可能为空。

SearchResult

参数	必须	类型	备注
Data	是	`[]model.SearchItemResult`	查询到的数据列表。
FilterMatchedCount	否	`int`	满足过滤条件的文档总数。
TotalReturnCount	是	`int`	本次实际返回的结果数量。
RealTextQuery	否	`string`	模型处理后实际参与检索的文本查询。
EffectiveKeywords	否	`map[string][]string`	各全文检索字段实际生效的关键词列表，主要在 `bm25` 模式下返回。
TokenUsage	否	`model.MapStr`	Token 使用情况。

SearchItemResult

参数	必须	类型	备注
ID	是	`interface{}`	数据的主键字段值。
Fields	是	`model.MapStr`	返回的标量字段。key 为字段名，value 为字段值。
Score	是	`float32`	最终相关性得分。检索结果按 `Score` 排序。
ANNScore	否	`float32`	向量检索的原始 ANN 得分。
Highlight	否	`map[string]map[string][]int`	高亮信息。第一层 key 为字段名，第二层 key 为命中的关键词或词项，value 为基于字符的 0 起始命中位置列表。
OriginScore	否	`*float32`	原始得分，部分检索模式下返回。
AdditionScore	否	`*float32`	附加得分，部分检索模式下返回。

示例

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

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

bm25 模式示例

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

请求参数

package main

import (
	"context"
	"errors"
	"fmt"
	"os"

	"github.com/volcengine/vikingdb-go-sdk/vector"
	"github.com/volcengine/vikingdb-go-sdk/vector/model"
)

func main() {
	client, err := vector.New(
		vector.AuthIAM(
			os.Getenv("VIKINGDB_AK"),
			os.Getenv("VIKINGDB_SK"),
		),
		vector.WithEndpoint("https://"+os.Getenv("VIKINGDB_HOST")),
		vector.WithRegion(os.Getenv("VIKINGDB_REGION")),
	)
	if err != nil {
		fmt.Println("client initialization failed:", err)
		return
	}

	indexClient := client.Index(model.IndexLocator{
		CollectionLocator: model.CollectionLocator{
			CollectionName: os.Getenv("VIKINGDB_COLLECTION"),
		},
		IndexName: os.Getenv("VIKINGDB_INDEX"),
	})

	limit := 5
	request := model.SearchByKeywordsRequest{
		Mode:     "bm25",
		Keywords: []string{"机器学习", "检索", "排序"},
		Fields:   []string{"f_text"},
		SearchBase: model.SearchBase{
			OutputFields: []string{"f_text"},
			Limit:        &limit,
		},
	}

	response, err := indexClient.SearchByKeywords(
		context.Background(),
		request,
	)
	if err != nil {
		printSearchError(err)
		return
	}

	fmt.Println("request success:")
	fmt.Printf("%+v\n", response)
}

func printSearchError(err error) {
	fmt.Println("request error:", err)

	var sdkError *model.Error
	if errors.As(err, &sdkError) {
		fmt.Println("code:", sdkError.Code)
		fmt.Println("http status code:", sdkError.StatusCode)
		fmt.Println("message:", sdkError.Message)
		fmt.Println("request ID:", sdkError.RequestID)
		if sdkError.Err != nil {
			fmt.Println("original error:", sdkError.Err)
		}
	}
}

bm25 模式开启 highlight 示例

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

请求参数

package main

import (
	"context"
	"errors"
	"fmt"
	"os"

	"github.com/volcengine/vikingdb-go-sdk/vector"
	"github.com/volcengine/vikingdb-go-sdk/vector/model"
)

func main() {
	client, err := vector.New(
		vector.AuthIAM(
			os.Getenv("VIKINGDB_AK"),
			os.Getenv("VIKINGDB_SK"),
		),
		vector.WithEndpoint("https://"+os.Getenv("VIKINGDB_HOST")),
		vector.WithRegion(os.Getenv("VIKINGDB_REGION")),
	)
	if err != nil {
		fmt.Println("client initialization failed:", err)
		return
	}

	indexClient := client.Index(model.IndexLocator{
		CollectionLocator: model.CollectionLocator{
			CollectionName: os.Getenv("VIKINGDB_COLLECTION"),
		},
		IndexName: os.Getenv("VIKINGDB_INDEX"),
	})

	limit := 5
	enableHighlight := true
	request := model.SearchByKeywordsRequest{
		Mode:      "bm25",
		Keywords:  []string{"机器学习", "检索", "排序"},
		Fields:    []string{"f_text"},
		Highlight: &model.Highlight{Enable: &enableHighlight},
		SearchBase: model.SearchBase{
			OutputFields: []string{"f_text"},
			Limit:        &limit,
		},
	}

	response, err := indexClient.SearchByKeywords(
		context.Background(),
		request,
	)
	if err != nil {
		printSearchError(err)
		return
	}

	fmt.Println("request success:")
	fmt.Printf("%+v\n", response)
}

func printSearchError(err error) {
	fmt.Println("request error:", err)

	var sdkError *model.Error
	if errors.As(err, &sdkError) {
		fmt.Println("code:", sdkError.Code)
		fmt.Println("http status code:", sdkError.StatusCode)
		fmt.Println("message:", sdkError.Message)
		fmt.Println("request ID:", sdkError.RequestID)
		if sdkError.Err != nil {
			fmt.Println("original error:", sdkError.Err)
		}
	}
}

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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

Highlight #

SearchResult #

SearchItemResult #

bm25 模式示例 #

请求参数 #

bm25 模式开启 highlight 示例 #

请求参数 #

Highlight

SearchResult

SearchItemResult

bm25 模式示例

请求参数

bm25 模式开启 highlight 示例

请求参数