feat: 支持可配置的混合检索融合权重

[zpf2000]

变更说明

• 在插件检索链路中透传 vector_weight 参数
• 在 Chroma hybrid 检索中支持按 vector_weight / 1 - vector_weight 做加权融合
• 在 SeekDB hybrid 检索中支持将 vector_weight 映射为 knn_boost/query_boost
• 为 SeekDB 增加 collection 名规范化，兼容 LangBot 的知识库 UUID
• 为 SeekDB 返回结果增加 JSON-safe 转换，避免 Decimal 序列化失败
• 补充最小日志，便于验证 hybrid 融合配置

验证

• 已在 Chroma 后端验证 vector_weight 透传和加权融合日志
• 已在 SeekDB server 模式验证 vector_weight 映射为 knn_boost/query_boost
• 已验证关闭 rerank 后，纯 hybrid 检索可以成功返回结果

说明

• 本 PR 不包含本地开发用的 editable SDK 配置改动
• 本 PR 不包含 web/ 目录的测试性改动

[RockChinQ]

@huanghuoguoguo review

[huanghuoguoguo]

看一下seekdb的官方文档，是这样调用的吗

[huanghuoguoguo]

来自opus

RRF 权重调节（pyseekdb hybrid_search）

pyseekdb 的 hybrid_search 通过 rank（RRF 全局配置） 和 boost（单路召回权重） 两个维度控制权重，最终生成 JSON 传给 OceanBase 的 DBMS_HYBRID_SEARCH.GET_SQL，核心规则如下：

1. rank 参数 — RRF 全局配置

用于定义 RRF 融合的基础规则，格式：

rank={"rrf": {"rank_window_size": 60, "rank_constant": 60}}

• rank_constant（RRF 公式中的 k）：RRF 得分 = 1 / (k + rank)。k 越大，排名靠后的结果衰减越慢，各路召回结果差异越“拉平”，默认 60。
• rank_window_size：参与 RRF 融合的每路结果窗口大小。
• 传空 rank={"rrf": {}} 表示使用 OceanBase 默认 RRF 参数。

2. boost 参数 — 单路召回权重

调节全文检索（BM25）和向量检索的相对重要性，核心示例：

results = collection.hybrid_search(
    query={
        "where_document": {"$contains": "机器学习"},
        "boost": 0.3,          # 全文检索路的权重
    },
    knn={
        "query_texts": ["AI研究"],
        "boost": 0.7,          # 向量检索路的权重
        "n_results": 20,
    },
    rank={"rrf": {"rank_constant": 60, "rank_window_size": 100}},
    n_results=10,
)

• query.boost：全文检索（BM25）路的权重（最终加到 query_string.boost）；
• knn.boost：向量检索路的权重（直接设到 knn 表达式的 boost 字段）。

3. 核心逻辑说明

• rank 参数：pyseekdb 直接透传，OceanBase 引擎执行 RRF 融合计算；
• boost 参数：控制单路召回得分的缩放权重，是调节全文/向量检索优先级的核心。

参数汇总表

参数	作用域	核心作用
rank.rrf.rank_constant	全局	RRF 公式的 k 值，越大越平滑
rank.rrf.rank_window_size	全局	每路参与融合的结果窗口大小
query.boost	全文检索路	全文检索得分的缩放权重
knn.boost	向量检索路	向量检索得分的缩放权重

权重调节建议

• 想侧重语义相似度：调高 knn.boost；
• 想侧重关键词匹配：调高 query.boost。

总结

1. RRF 融合的全局规则由 rank 参数控制，核心是 rank_constant（平滑度）和 rank_window_size（融合窗口）；
2. 全文/向量检索的相对权重由 boost 控制，是业务侧调节召回优先级的核心；
3. pyseekdb 仅透传参数，最终 RRF 计算由 OceanBase 引擎完成。