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

向量数据库VikingDB

请输入
  • 文档首页
    • 向量数据库VikingDBVikingDB 向量库向量库历史版本（V1）API V1参考检索(Search)检索过滤能力后置处理算子
复制全文
下载 pdf
我的收藏
检索过滤能力
后置处理算子
复制全文
下载 pdf
我的收藏
后置处理算子

后置处理算子是 VikingDB 提供的一种检索后处理能力，用于在向量召回之后，对候选数据进行进一步的过滤和优化，确保最终返回的搜索结果更加精准、高效。
在 VikingDB 中，后置处理算子可用于：

  • 结果精准筛选：基于业务需求通过正则匹配设定筛选规则，如筛选包含某种特征文字信息的商品，确保用户获得有效的检索结果。
  • 数据质量提升：使用正则匹配对检索结果进行格式校验，过滤包含特殊字符、非法内容或广告信息的数据，确保返回内容符合标准，提高数据规范性。
  • 检索结果均衡：对特定字段设置出现频率限制，防止某些值占据过多搜索结果，如热门品牌、热门作者或特定分类过度曝光，保证检索结果的多样性和公平性。

后置处理算子是通用检索能力，您可以将其应用在向量近邻检索、稠密稀疏混合近邻检索中。

请求接口

请求向量数据库 VikingDB 的 OpenAPI 接口时，需要构造签名进行鉴权，详细的 OpenAPI 签名调用方法请参见 API签名调用指南。

URI

/api/index/search

统一资源标识符

请求方法

POST

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

请求参数

在向量检索请求的基础上，请在请求体顶层设置 post_process_ops、post_process_input_limit；这两个参数与 search 平级，不是 search 的子参数。

参数

子参数

类型

是否必选

默认值

参数说明

post_process_ops

list

否

后置处理算子列表。在向量或标量召回阶段后，对候选数据进行进一步过滤处理，如字符串匹配、频控等。每个算子为一个map，串行执行。默认为空。详见下文后置处理算子。

post_process_input_limit

int

否

1000

当设置了 post_process_ops 时，进入后置处理阶段的候选数量。最小值为 1，实际候选数不超过 min(10000, limit × 10)。

后置处理算子

算子

说明

示例

string_match

正则匹配算子。仅限string类型字段使用。
正则匹配规则请参考：Syntax

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

string_contain

关键词匹配算子。仅限string类型字段使用。
表示该字段内容包含pattern。

JSON <br> { <br> "op": "string_contain", <br> "field": "name", <br> "pattern": "bar" <br> } <br>

enum_freq_limiter

频控算子。仅限string类型字段使用。
用于保证一次召回的结果中, 一个特定取值出现的总数不超过 threshold 次。

JSON <br> { <br> "op": "enum_freq_limiter", <br> "field": "city", <br> "threshold": 5 <br> } <br>

响应消息

参数

参数说明

code

状态码

message

返回信息

request_id

标识每个请求的唯一标识符

data

检索结果，标量过滤检索会返回检索到的主键、score、fields。

状态码说明

状态码

http状态码

返回信息

状态码说明

0

200

search success

Index 检索成功。

1000008

400

index not exist

指定的 Index 不存在。

1000003

400

invalid request

非法参数：

  • 缺失必选参数。
  • 缺乏检索输入。
  • 不满足约束条件。

1000001

401

unauthorized

请求头中缺乏鉴权信息。

1000002

403

no permission

权限不足。

1000016

400

invalid vectors for index_recall

输入的向量格式不合法。

1000029

429

请求已达上限, 请调整CPU核数

需要调大 cpu_quota

完整示例

请求消息 

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",
    "index_name": "index_test",
    "search": {
        "order_by_vector": {
            "vectors": [
                [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9], 
                [0.01, 0.02, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09]
            ],
            "sparse_vectors": [
                {"什么": 0.34, "是": 0.03, "B": 0.11, "M": 0.32, "25": 0.03}, 
                {"一": 0.08, "种": 0.14, "信息": 0.19, "检索": 0.63, "算法": 0.97} 
            ]            
        }, 
        "limit": 2,
        "dense_weight": 0.5,
        "partition": "default"
    },
    "post_process_ops": [           // 后置处理算子列表，处理初步召回后的结果
        {
            "op": "string_match",   // 字符串匹配算子，适用于 string 类型字段
            "field": "name",        // 针对 `name` 字段进行正则过滤
            "pattern": "^[0-9A-Za-z_]+$" // 仅保留匹配正则表达式的字段值
            // 示例：过滤掉非字母、数字、下划线以外的 `name` 候选
        },
        {
            "op": "enum_freq_limiter", // 枚举频控算子，限制结果中某个字段值的频次
            "field": "city",        // 针对 `city` 字段进行频控
            "threshold": 5          // 单个 `city` 字段值最多出现 5 次
            // 示例：如果某个城市的候选数量超过 5，自动裁剪至 5 个
        }
    ],
    "post_process_input_limit": 1000 // 后置处理阶段的最大输入数量，默认值为 1000，确保后置处理只对初步筛选的前 1000 个候选应用，提高效率
}'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "message":"search success",
    "request_id":"021695029757920fd001de6666600000000000000000002569b8f",
    "data": [
        [
            {
                "id": 1,
                "score": 0.99,
                "fields": {
                    "time": 1690529704,
                    "author": "zhangsan"
                } 
            },
            {
                "id": 2,
                "score": 0.98,
                "fields": {
                    "time": 1690529701,
                    "author": "lisi"
                } 
            }
        ],
        [
            {
                "id": 9,
                "score": 0.95,
                "fields": {
                    "time": 1690529708,
                    "author": "wangwu"
                } 
            },
            {
                "id": 8,
                "score": 0.84,
                "fields": {
                    "time": 1690529710,
                    "author": "zhaoliu"
                } 
            }            
        ]
    ]
}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000008, "message":"index not exist", "request_id":"021695029757920fd001de6666600000000000000000002569b8f"}

参数说明补充

post_process_ops 与 post_process_input_limit 位于请求体顶层，与 search 平级，不是 search 的子字段。完整请求结构为 { "search": {...}, "post_process_ops": [...], "post_process_input_limit": 1000 }。

参数说明补充

post_process_input_limit 必须为正整数，最小值为 1，默认值为 1000；实际候选数不超过 min(10000, limit × 10)。只有设置 post_process_ops 时生效。

参数说明补充

算子字段

字段类型必填含义
opstring是算子名称。
fieldstring是参与后处理的字段名。
patternstring字符串匹配算子必填匹配模式或待匹配文本。
thresholdnumber阈值类算子必填过滤或截断阈值。

示例修正

已将 enum_freq_limiter 示例修正为合法 JSON："field": "city", 后再书写下一字段。

返回说明补充

检索结果结构

返回字段 data 的类型为 array<array<object>>：外层数组与请求中的查询项一一对应；每个内层数组是该查询项的 TopN 结果列表。

字段类型含义
data[][].idstring 或 int64命中数据的主键，类型与 Collection 主键类型一致。
data[][].scorefloat32命中结果的相关性分数。
data[][].fieldsmap<string, any>命中数据的字段集合；键为字段名，值类型与 Collection 字段定义一致。

返回说明补充

检索结果结构

返回字段 data 的类型为 array<array<object>>：外层数组与请求中的查询项一一对应；每个内层数组是该查询项的 TopN 结果列表。

字段类型含义
data[][].idstring 或 int64命中数据的主键，类型与 Collection 主键类型一致。
data[][].scorefloat32命中结果的相关性分数。
data[][].fieldsmap<string, any>命中数据的字段集合；键为字段名，值类型与 Collection 字段定义一致。

错误处理补充

常见错误处理建议

错误码处理建议
1000001检查 AK/SK、签名时间和 Authorization 请求头，并按 API 签名调用指南重新生成签名。
1000002检查 IAM 用户是否具有目标项目和 VikingDB 资源权限，缺少权限时由管理员授权。
1000003根据错误消息检查必填参数、类型、枚举值和数值范围。
1000005检查 collection_name 是否拼写正确、是否位于当前项目且尚未删除。
1000008检查 index_name 是否正确、索引是否已创建并处于可用状态。
1000011检查数据主键是否存在于目标 Collection；不存在时先写入数据。

完整触发条件参见向量库 V1 错误码。

最近更新时间：2026.09.08 15:30:03
这个页面对您有帮助吗？
有用
有用
无用
无用