byted-bytehouse-hybrid-search

name	byted-bytehouse-hybrid-search
description	ByteHouse 混合检索 Skill，支持全文检索 + 向量检索，结合 RRF 重排算法实现更精准的检索结果。当用户需要在ByteHouse数据库中进行全文检索 + 向量检索，结合 RRF 重排算法实现更精准的检索结果时，使用此Skill。
version	1.0.0

ByteHouse 混合检索 Skill

🚀 快速开始

环境准备

pip install clickhouse-connect volcengine-python-sdk[ark] numpy scipy

配置说明

配置保存在 ~/.bytehouse_config.json ，如果该文件存在且非空，则直接使用文件中的配置。如果不存在，则让用户提供ByteHouse连接信息（ 把这个文档也发给客户，文档里面介绍了如何获取主机地址和密码：https://www.volcengine.com/docs/6517/1121919?lang=zh ）。用户提供信息后，保存到json文件，避免重复向用户请求连接信息。当用户切换ByteHouse集群时，一并修改该文件。

{
   "BYTEHOUSE_HOST": "<ByteHouse-host>",
   "BYTEHOUSE_PORT": "8123",
   "BYTEHOUSE_USER": "bytehouse",
   "BYTEHOUSE_PASSWORD": "<ByteHouse-password>",
   "BYTEHOUSE_SECURE": true,
   "BYTEHOUSE_VERIFY": true, 
   "BH_ARK_API_KEY": "<火山引擎方舟API密钥>",
   "BH_ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
   "BH_EMBEDDING_MODEL": "doubao-embedding-vision-251215"
}

其中BYTEHOUSE_HOST（主机地址）和BYTEHOUSE_PASSWORD（密码）必须由用户提供。BH_ARK_API_KEY为可选配置，仅在embedding时使用，用户初次使用时可忽略。其余配置固定。

执行 scripts/export_config.sh 把配置信息导入环境变量中

source scripts/export_config.sh

---

📚 核心能力

1. 文本向量化

基于豆包文本向量化模型生成文本向量，支持任意长度中文文本。

2. 双索引构建

索引类型	说明	适用场景
全文倒排索引	基于BM25算法的全文检索，支持关键词匹配	精准关键词召回
向量索引	基于HNSW的向量相似度检索，支持语义匹配	语义相似召回

3. 核心功能

功能	方法	说明
全文检索	fulltext_search()	基于BM25的全文检索，返回BM25分数
向量检索	vector_search()	基于余弦相似度的向量检索，返回相似度分数
混合检索+RRF重排	hybrid_search()	双路召回后使用RRF算法重排，返回最终结果
自动生成向量	insert_document()/batch_insert_documents()	插入文档时自动生成向量并存储，无需手动处理
单个文档向量更新	update_document_embedding()	为单个文档重新生成并更新向量
批量补全缺失向量	batch_update_missing_embeddings()	自动扫描表中所有缺少向量的文档，批量生成并补全向量

4. RRF重排算法

Reciprocal Rank Fusion 算法，综合全文检索和向量检索的排名结果，公式：

score = Σ 1 / (k + rank)

默认k=60，可自定义调整。

---

📖 代码实现

完整示例代码实现位于 scripts/ 目录：

• scripts/embedding.py - 文本向量化模块
• scripts/hybrid_search_client.py - ByteHouse 混合检索客户端
• scripts/examples.py - 使用示例
• scripts/export_config.sh - 把配置文件中的信息导入环境变量

快速使用

from scripts import ByteHouseHybridSearch

# 初始化客户端
search = ByteHouseHybridSearch(connection_type="http")

# 创建混合检索表（自动构建全文索引和向量索引）
search.create_hybrid_table("my_hybrid_index")

# 插入文档（自动生成向量 + 存储原始文本）
search.insert_document("my_hybrid_index", doc_id=1, 
                      title="ByteHouse 混合检索", 
                      content="ByteHouse 支持全文检索和向量检索，可实现混合检索能力")

# 混合检索（自动执行全文+向量检索，RRF重排返回结果）
results = search.hybrid_search("my_hybrid_index", query="ByteHouse检索能力", top_k=10)

---

⚙️ 最佳实践

建表配置

CREATE TABLE {table_name} (
    `doc_id` UInt64,
    `title` String,
    `content` String,
    `embedding` Array(Float32),
    -- 全文倒排索引（version=2支持BM25分数）
    INDEX content_idx content TYPE inverted('standard', '{"version":"v4"}') GRANULARITY 1,
    -- 向量索引（HNSW算法，余弦相似度）
    INDEX embedding_idx embedding TYPE HNSW_SQ('DIM={vec_dimensions}', 'metric=COSINE', 'M=32', 'EF_CONSTRUCTION=256') GRANULARITY 1
)
ENGINE = CnchMergeTree()
ORDER BY doc_id
SETTINGS 
    index_granularity = 1024,
    enable_vector_index_preload = 1

RRF参数调整

• 当全文检索结果更重要时，可降低rrf_k值（推荐30-60）
• 当向量检索结果更重要时，可提高rrf_k值（推荐60-100）

🔗 参考文档

• ByteHouse 全文检索文档
• ByteHouse 向量检索文档
• RRF算法论文