ByteHouse 混合检索 Skill

🚀 快速开始

环境准备

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

环境变量配置

优先从环境变量读取配置，禁止硬编码明文敏感信息：

# ByteHouse 配置
export BYTEHOUSE_HOST="\x3C你的ByteHouse连接地址>"
export BYTEHOUSE_PORT="\x3CByteHouse端口>"
export BYTEHOUSE_USER="\x3CByteHouse用户名>"
export BYTEHOUSE_PASSWORD="\x3CByteHouse密码>"
export BYTEHOUSE_DATABASE="\x3C默认数据库，可选，默认default>"
export BYTEHOUSE_SECURE="\x3C是否启用加密，可选，默认true>"

# 火山引擎方舟 API 配置
export ARK_API_KEY="\x3C火山引擎方舟API密钥>"
export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export EMBEDDING_MODEL="doubao-embedding-vision-251215"  # 文本向量化模型
export EMBEDDING_DIMENSIONS="1536"  # 向量维度，可选，默认1536

如果环境变量未配置，会自动提示用户输入。

📚 核心能力

1. 文本向量化

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

2. 双索引构建

3. 核心功能

4. RRF重排算法

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

score = Σ 1 / (k + rank)

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

📖 代码实现

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

• scripts/embedding.py - 文本向量化模块
• scripts/hybrid_search_client.py - ByteHouse 混合检索客户端
• scripts/examples.py - 使用示例

快速使用

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":"v2"}') GRANULARITY 1,
    -- 向量索引（HNSW算法，余弦相似度）
    INDEX embedding_idx embedding TYPE HNSW_SQ('DIM={vec_dimensions}', 'metric=COSINE', 'M=32', 'EF_CONSTRUCTION=256') GRANULARITY 1
)
ENGINE = MergeTree()
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算法论文