ByteHouse 混合检索 Skill
🚀 快速开始
环境准备
CODEBLOCK0
环境变量配置
优先从环境变量读取配置，
禁止硬编码明文敏感信息：
CODEBLOCK1
如果环境变量未配置，会自动提示用户输入。
📚 核心能力
1. 文本向量化
基于豆包文本向量化模型生成文本向量，支持任意长度中文文本。
2. 双索引构建
| 索引类型 | 说明 | 适用场景 |
|---|
| 全文倒排索引 | 基于BM25算法的全文检索，支持关键词匹配 | 精准关键词召回 |
| 向量索引 |
基于HNSW的向量相似度检索，支持语义匹配 | 语义相似召回 |
3. 核心功能
| 功能 | 方法 | 说明 |
|---|
| 全文检索 | INLINECODE0 | 基于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/ 目录：
快速使用
CODEBLOCK3
⚙️ 最佳实践
建表配置
CODEBLOCK4
RRF参数调整
- - 当全文检索结果更重要时，可降低
rrf_k值（推荐30-60） - 当向量检索结果更重要时，可提高
rrf_k值（推荐60-100）
🔗 参考文档
ByteHouse 混合检索 Skill
🚀 快速开始
环境准备
bash
pip install clickhouse-connect volcengine-python-sdk[ark] numpy scipy
环境变量配置
优先从环境变量读取配置，
禁止硬编码明文敏感信息：
bash
ByteHouse 配置
export BYTEHOUSE_HOST=<你的ByteHouse连接地址>
export BYTEHOUSE_PORT=
export BYTEHOUSE_USER=
export BYTEHOUSE_PASSWORD=
export BYTEHOUSE_DATABASE=<默认数据库，可选，默认default>
export BYTEHOUSE_SECURE=<是否启用加密，可选，默认true>
火山引擎方舟 API 配置
export ARKAPIKEY=<火山引擎方舟API密钥>
export ARKBASEURL=https://ark.cn-beijing.volces.com/api/v3
export EMBEDDING_MODEL=doubao-embedding-vision-251215 # 文本向量化模型
export EMBEDDING_DIMENSIONS=1536 # 向量维度，可选，默认1536
如果环境变量未配置，会自动提示用户输入。
📚 核心能力
1. 文本向量化
基于豆包文本向量化模型生成文本向量，支持任意长度中文文本。
2. 双索引构建
| 索引类型 | 说明 | 适用场景 |
|---|
| 全文倒排索引 | 基于BM25算法的全文检索，支持关键词匹配 | 精准关键词召回 |
| 向量索引 |
基于HNSW的向量相似度检索，支持语义匹配 | 语义相似召回 |
3. 核心功能
| 功能 | 方法 | 说明 |
|---|
| 全文检索 | fulltextsearch() | 基于BM25的全文检索，返回BM25分数 |
| 向量检索 |
vectorsearch() | 基于余弦相似度的向量检索，返回相似度分数 |
| 混合检索+RRF重排 | hybrid_search() | 双路召回后使用RRF算法重排，返回最终结果 |
| 自动生成向量 | insertdocument()/batchinsert_documents() | 插入文档时自动生成向量并存储，无需手动处理 |
| 单个文档向量更新 | updatedocumentembedding() | 为单个文档重新生成并更新向量 |
| 批量补全缺失向量 | batchupdatemissing_embeddings() | 自动扫描表中所有缺少向量的文档，批量生成并补全向量 |
4. RRF重排算法
Reciprocal Rank Fusion 算法，综合全文检索和向量检索的排名结果，公式：
score = Σ 1 / (k + rank)
默认k=60，可自定义调整。
📖 代码实现
完整示例代码实现位于 scripts/ 目录：
快速使用
python
from scripts import ByteHouseHybridSearch
初始化客户端
search = ByteHouseHybridSearch(connection_type=http)
创建混合检索表（自动构建全文索引和向量索引）
search.createhybridtable(myhybridindex)
插入文档（自动生成向量 + 存储原始文本）
search.insertdocument(myhybridindex, docid=1,
title=ByteHouse 混合检索,
content=ByteHouse 支持全文检索和向量检索，可实现混合检索能力)
混合检索（自动执行全文+向量检索，RRF重排返回结果）
results = search.hybridsearch(myhybridindex, query=ByteHouse检索能力, topk=10)
⚙️ 最佳实践
建表配置
sql
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 embeddingidx embedding TYPE HNSWSQ(DIM={vecdimensions}, metric=COSINE, M=32, EFCONSTRUCTION=256) GRANULARITY 1
)
ENGINE = MergeTree()
ORDER BY doc_id
SETTINGS
index_granularity = 1024,
enablevectorindex_preload = 1
RRF参数调整
- - 当全文检索结果更重要时，可降低rrfk值（推荐30-60）
- 当向量检索结果更重要时，可提高rrfk值（推荐60-100）
🔗 参考文档
