You need to enable JavaScript to run this app.
文档中心
向量数据库VikingDB

向量数据库VikingDB

请输入
  • 文档首页
    • 向量数据库VikingDBVikingDB 向量库向量库新版本（V2）API V2参考数据面API检索(Search)检索公共参数
复制全文
下载 pdf
我的收藏
检索(Search)
检索公共参数
复制全文
下载 pdf
我的收藏
检索公共参数

检索功能由多个接口组成，分别对应不同的检索模式和业务场景。

接口升级说明
  • 对应的V1接口说明为：https://www.volcengine.com/docs/84313/1580544，V1接口将各种检索模式放置在同一接口中，由不同参数组合来区分不同的检索模式。V2接口则将不同检索模式对应到不同的接口，更加清晰，便于您针对自己的业务场景，选择合适的检索方式。
  • 使用区别：
V2接口V1接口

向量检索

SearchByVector
dense_vector参数

https://www.volcengine.com/docs/84313/1419285
设置order_by_vector.vectors参数

稠密稀疏向量混合检索

SearchByVector，
设置sparse_vector参数

https://www.volcengine.com/docs/84313/1419286
设置order_by_vector.sparse_vectors参数

向量检索下支持张量重排

SearchByVector
设置 tensor_rerank 参数。

不支持

多模态检索

SearchByMultiModal
其中，若为支持instruction的模型，需要主动设置是否添加instruction，以增强感知度。请求结果中会返回拼接instruction后的query语句。

https://www.volcengine.com/docs/84313/1419288
设置order_by_raw参数

多模态检索下支持张量重排

SearchByMultiModal
设置 tensor_rerank 参数。

不支持

主键检索

SearchByID

https://www.volcengine.com/docs/84313/1419285
设置order_by_vector.primary_keys参数

标量排序检索

SearchByScalar

https://www.volcengine.com/docs/84313/1419287
设置order_by_scalar参数

随机检索

SearchByRandom

https://www.volcengine.com/docs/84313/1578505
不设置任何order_by_xxx参数

关键词检索SearchByKeywords不支持
主键过滤ids_in、ids_not_in参数primary_key_in、primary_key_not_in参数
子索引性能和易用性更强的分片研发中，敬请期待。partition参数指定
响应字段主键值会单独列出，便于定位数据所有字段均在同一级参数中

检索类接口通用请求体参数
参数名类型必选子参数类型备注
resource_idstring至少填写一个资源 ID；与 collection_name 至少传入一个，同时传入时优先使用 resource_id。资源 ID 可通过相应资源的创建接口返回结果获取，也可在资源详情中查看。
collection_namestring至少填写一个Collection 名称；未传 resource_id 时必填。
index_namestring是索引名称

output_fields

list

否

要返回的标量字段列表。

  1. 用户不传 output_fields 时, 返回所有标量字段
  2. 用户传一个空列表不返回标量字段
  3. output_fields格式错误或者过滤字段不是 collection 里的字段时, 接口返回错误
filtermap否过滤条件，格式见下文。默认为空，不做过滤
limitint否检索结果数量，默认为10, 上限是 100000
offsetint否偏移量。仅分页场景下使用，不建议设置过大值，否则有深分页影响。默认值为0。设置值至少为0，语义和 MySQL 的 offset 相同。
advance（一些高级参数，普通场景不需要设置）map否dense_weightfloat32如果collection带有sparse向量字段，这里可以指定检索时dense和sparse的权重。默认值0.5，可选范围[0.2, 1]
ids_inlist或list设定此参数，会限定仅在主键列表范围内进行检索。默认为空。
ids_not_inlist或list设定此参数，将把主键列表范围内的数据从检索结果中排除 。默认为空。
post_process_opslist后置处理算子列表。在向量或标量召回阶段后，对候选数据进行进一步过滤处理，如字符串匹配、频控等。每个算子为一个map，串行执行。默认为空。详见下文后置处理算子。

post_process_input_limit

int

当设置了post_process_ops时，进入后置处理阶段的候选数量。
默认值为上述limit参数值*3。若显式设置，则不应该小于limit值，但不超过100000。

scale_kfloat64检索 sef 是索引参数 sef 的 scale_k 倍。默认 1，取值范围 [0.1, 100]，值越大检索结果越精确，但相应地会降低性能。

filter结构

使用 filter 的前提是，相应的标量字段设置了标量索引（ScalarIndex）。

算子适用字段类型说明示例

must

string、int64、bool、list、带 FullText 配置的 text

针对指定字段名生效，语义为必须在 [...] 之中，即 "must in"。如果字段为 list 类型，过滤条件为过滤配置 list 中所有元素都没有出现在物品数据的标签中。

 
{
  "op": "must",
  "field": "region",
  "conds": ["cn", "sg"]
}

must_not

string、int64、bool、list、带 FullText 配置的 text

针对指定字段名生效，语义为必须不在 [...] 之中，即 "must not in"。如果字段为 list 类型，物品数据的标签集合中，任何一个标签都不能出现在过滤配置 list 中，否则将被过滤。

 
{
  "op": "must_not",
  "field": "data_type",
  "conds": [1, 2, 3]
}

and

/

逻辑算子，针对逻辑查询需求，对多个条件取交集。

 
{
  "op": "and",
  "conds": [
    {
      "op": "must",
      "field": "type",
      "conds": [1]
    },
    {
      "op": "must_not",
      "field": "status",
      "conds": ["offline"]
    }
  ]
}

or

/

逻辑算子，针对逻辑查询需求，对多个条件取并集。

 
{
  "op": "or",
  "conds": [
    {
      "op": "must",
      "field": "type",
      "conds": [1]
    },
    {
      "op": "must",
      "field": "type",
      "conds": [2]
    }
  ]
}

range

int64、float32

针对指定字段名生效，语义为必须在指定范围内。配置使用 gte（大于等于）、gt（大于）、lte（小于等于）、lt（小于），用以圈定一维范围。

 
{
  "op": "range",
  "field": "price",
  "gte": 100.0,
  "lt": 500.0
}

{
  "op": "range",
  "field": "price",
  "gte": 100.0
}

time_range

date_time

时间点筛选，配置使用 gte（大于等于）、gt（大于）、lte（小于等于）、lt（小于），用以圈定一维范围。

 
{
  "collection_name": "test",
  "index_name": "test",
  "filter": {
    "op": "and",
    "conds": [
      {
        "op": "time_range",
        "field": "f_date_time",
        "gt": "2025-08-12T00:00:00+08:00",
        "lt": "2025-08-13T00:00:00+08:00"
      }
    ]
  }
}

geo_range

geo_point

地理距离筛选，使用 center 为中心点，radius 为距离半径。

 
{
  "collection_name": "test",
  "index_name": "test",
  "filter": {
    "op": "and",
    "conds": [
      {
        "op": "geo_range",
        "field": "f_geo_point",
        "center": "116.412138,39.914912",
        "radius": "10000m"
      }
    ]
  }
}

后置处理结构

算子适用字段类型说明
score_fusionstring分数融合算子，用于融合指定的时空标量的分数。
string_containstring关键词匹配过滤算子。表示该字段内容包含 pattern。
string_matchstring正则匹配过滤算子。
enum_freq_limiterstring频控算子。用于保证一次召回的结果中，一个特定取值出现的总数不超过 threshold 次。

算子示例

score_fusion

{
  "op": "score_fusion",
  "fusion_by": "add",
  "addition_score_weight": 0.6, // 附加 score 的权重为 0.6，ann score 的权重为 1 - 0.6 = 0.4
  "addition_score": [
    {
      "factor": 1.0,
      "base_value_from": "scalar_field",
      "field": "f_sales"
    },
    {
      "factor": -10.0, // 投诉多的商品，score 应该降低
      "base_value_from": "scalar_field",
      "field": "f_complain"
    }
  ]
}

string_contain

{
  "op": "string_contain",
  "field": "name",
  "pattern": "bar"
}

string_match

{
  "op": "string_match",
  "field": "name",
  "pattern": "^[0-9A-Za-z_]+$"
}

enum_freq_limiter

{
  "op": "enum_freq_limiter",
  "field": "city",
  "threshold": 5
}

Tensor Rerank 结构

注：此参数仅在 searchByVector 和 searchByMultiModal 接口中支持

参数名类型必选说明

tensor

list

  • 在 searchByVector 中必选；
  • 在 searchByMultiModal 中不允许设置；

张量检索数据：用于和数据库中已有的张量做相似度计算的输入

  • 仅在 searchByVector 中必填
  • 在 searchByMultiModal 中会自动由模型生成
input_limitint是进入张量重排的候选数量，范围：[1, 1000]

检索类接口通用响应体参数
参数名类型子参数说明
resultmapdatalist查询到的数据列表，SearchItem结构见下。
total_return_countint返回实际检索结果的数据条数
token_usagemap包括prompt_tokens、completion_tokens、image_tokens、total_tokens信息

SearchItem

参数名类型备注
idstring/int64数据的主键字段值。
fieldsmap<string,any>key为字段名，value为字段值
scorefloat必返回。最终得分 score 值。search 接口返回的结果按 score 排序。
ann_scorefloat非必返回。如果是全文检索、score值计算处理等算子加工过，会返回向量检索（ANN）的原始score值。

参数说明补充

advance 为可选高级检索配置对象；其子参数 dense_weight、sparse_weight、need_instruction、instruction、rerank、post_process_ops 和 post_process_input_limit 均为可选项，仅在对应混合检索、Instruction、重排或后处理能力开启时生效。未填写的子参数使用接口默认行为。

返回说明补充

token_usage 结构

token_usage 仅在接口实际调用向量化模型并返回用量信息时出现。

字段类型含义
prompt_tokensint64输入文本消耗的 Token 数。
completion_tokensint64模型输出消耗的 Token 数；无生成阶段时可能不返回或为 0。
image_tokensint64图片或视频帧折算的 Token 数。
total_tokensint64本次向量化总 Token 数。

请求接口补充

适用接口

能力方法与路径
向量检索POST /api/vikingdb/data/search/vector
随机检索POST /api/vikingdb/data/search/random
关键词检索POST /api/vikingdb/data/search/keywords
ID 检索POST /api/vikingdb/data/search/id
标量排序检索POST /api/vikingdb/data/search/scalar
多模态检索POST /api/vikingdb/data/search/multi_modal

错误处理补充

错误码

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

最近更新时间：2026.09.16 14:34:03
这个页面对您有帮助吗？
有用
有用
无用
无用