byted-bytehouse-hybrid-search

Q: How do I install byted-bytehouse-hybrid-search?

Run npx skills add https://github.com/bytedance/agentkit-samples --skill byted-bytehouse-hybrid-search in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/byted-bytehouse-hybrid-search/ (personal) or .claude/skills/byted-bytehouse-hybrid-search/ (project).

by bytedance

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

Installs: 45
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/bytedance/agentkit-samples --skill byted-bytehouse-hybrid-search

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads byted-bytehouse-hybrid-search automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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）

🔗 参考文档

FAQ

What does the byted-bytehouse-hybrid-search skill do?

How do I install byted-bytehouse-hybrid-search?

Run npx skills add https://github.com/bytedance/agentkit-samples --skill byted-bytehouse-hybrid-search in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/byted-bytehouse-hybrid-search/ (personal) or .claude/skills/byted-bytehouse-hybrid-search/ (project).

Which AI agents can use byted-bytehouse-hybrid-search?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is byted-bytehouse-hybrid-search safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains byted-bytehouse-hybrid-search?

It is published by bytedance in bytedance/agentkit-samples. It has 45 recorded installs.

More from bytedance/agentkit-samples

View all →

byted-web-search

bytedance/agentkit-samples

火山引擎联网搜索 API，返回网页/图片结果。联网搜索场景优先使用本 skill。触发词包括：查/搜/找、真的吗/靠谱吗/确认/核实、最近/今天/最新/近期、出处/来源/链接、有什么/有哪些/推荐、价格/政策/汇率/行情、对比/区别/哪个好、听说/据说/不太确定、热搜/热门/火、帮我看/了解一下、求证/辟谣、值不值得/该不该。任务依赖在线事实或时效性时优先使用。若回答可能依赖外部事实，优先调用本 skill 再作答。支持 API Key / AK/SK。

Productivity & Automation618 installs

byted-seedream-image-generate

bytedance/agentkit-samples

Generate high-quality images from text prompts using Volcano Engine Seedream models. Supports multiple artistic styles and aspect ratios. Use this skill when users want to create images from text descriptions, generate artwork in various styles, create visual content for creative projects, or need AI-powered image generation capabilities.

Media & Creative298 installs

byted-las-video-edit

bytedance/agentkit-samples

智能视频剪辑：用自然语言描述要保留的片段/人物/事件，自动从长视频抽取剪辑（可用参考图做人物/物体匹配）。当用户要按描述找片段、提取高光或做智能剪辑时触发。

Media & Creative209 installs

byted-text-to-speech

bytedance/agentkit-samples

将文本合成为语音（TTS）。使用火山引擎豆包语音合成 API，支持流式合成、多种音色、语速/音调/音量调节、Markdown 过滤和 LaTeX 公式播报。当用户需要把文字转成语音、生成朗读音频、配音、旁白、播报，或提到「文字转语音」「TTS」「语音合成」「朗读」「配音」时使用本技能。

Media & Creative184 installs

byted-seedance-video-generate

bytedance/agentkit-samples

Generate videos using Seedance models. Invoke when user wants to create videos from text prompts, images, or reference materials.

Media & Creative181 installs

byted-las-pdf-parse-doubao

bytedance/agentkit-samples

Open the skill to read its SKILL.md instructions.

Docs & Writing162 installs

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs

byted-bytehouse-hybrid-search

Install

Install

Describe the task

Review the result

SKILL.md

ByteHouse 混合检索 Skill

🚀 快速开始

环境准备

配置说明

📚 核心能力

1. 文本向量化

2. 双索引构建

3. 核心功能

4. RRF重排算法

📖 代码实现

快速使用

⚙️ 最佳实践

建表配置

RRF参数调整

🔗 参考文档

FAQ

More from bytedance/agentkit-samples

Popular other skills