byted-bytehouse-ai-query

byted-bytehouse-ai-query

描述

ByteHouse AI Query Skill，提供以下核心能力：

1. Text2SQL — 将自然语言查询需求转换为 ByteHouse SQL。
2. List Tables — 列出目标数据库/实例下的所有库与表。
3. Execute SQL — 执行 SQL 查询并返回结果，内置非 DQL 保护。
4. 多模态向量化与检索 — 支持文本、图片、视频的向量化，以及向量/混合检索。

当以下情况时使用此 Skill：

1. 用户希望通过自然语言查询 ByteHouse 中的数据（"帮我查一下 xxx 表数据量"、"看看有哪些库和表" 等）。
2. 用户明确要求把自然语言转成 SQL（Text2SQL），或需要在 ByteHouse 上执行 SQL。
3. 用户希望在 ByteHouse 上进行文本/图片/视频的向量化存储与检索。
4. 用户提到 ByteHouse、火山引擎云数仓、云原生数仓、数据仓库查询相关关键词。

🧭 智能体使用指引（重要）

Agent 在承接上述任务时，按以下流程调度本 Skill 内的脚本：

1. 确保配置就绪：先执行 source scripts/export_config.sh，把 ~/.bytehouse_config.json 中的配置注入环境变量。
   • 若 ~/.bytehouse_config.json 不存在或缺失 BYTEHOUSE_HOST / BYTEHOUSE_PASSWORD，主动引导用户提供，并把用户返回的连接信息写入该 JSON 文件后再 source。
2. 摸清数据全貌：若用户没有明确指定库表，先使用 scripts/list_tables.py 查询数据库/表列表，帮助用户/Agent 选定要查的表。
3. 生成 SQL：需要把自然语言转成 SQL 时，使用 scripts/text2sql.py，将目标表以位置参数传入。
4. 执行 SQL：拿到 SQL 后使用 scripts/execute_sql.py。默认只允许执行 DQL，非 DQL（INSERT/UPDATE/DROP 等）需要先向用户确认再附加 --force。
5. 多模态检索场景：使用 scripts/embedding.py + scripts/search_client.py 完成向量化与向量/混合检索。
6. 展示结果：默认返回前 5 条结果，异常时展示完整报错。任何时候都要对密钥、密码等敏感字段做 Mask。

Agent 必须通过上述脚本发起查询/执行，不允许自行拼装 SQL 或直接连接 ByteHouse。

📁 文件说明

• SKILL.md — 本文件，技能主文档。
• requirements.txt — Python 依赖列表。
• scripts/text2sql.py — Text2SQL 转换脚本。
• scripts/list_tables.py — 列出数据库或指定库下的表。
• scripts/execute_sql.py — 执行 SQL 查询脚本，内置 DQL 保护。
• scripts/client.py — ByteHouse 连接客户端通用模块。
• scripts/embedding.py — 多模态向量化脚本。
• scripts/search_client.py — ByteHouse 向量检索客户端。
• scripts/export_config.sh — 从 ~/.bytehouse_config.json 加载配置到环境变量（依赖 jq）。

配置说明

配置文件位于 ~/.bytehouse_config.json。如果文件存在且非空，直接使用文件中的配置；否则，向用户询问必填连接信息（可以把这份文档发给用户以便查阅 ByteHouse 连接信息获取指引），拿到后写入 JSON 文件，避免重复询问。当用户切换 ByteHouse 集群时，一并更新该文件。

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