byted-bytehouse-ai-query

byted-bytehouse-ai-query

説明

ByteHouse AI Query スキルは、以下の主要な機能を提供します。

1. Text2SQL — 自然言語によるクエリ要件を ByteHouse SQL に変換します。
2. List Tables — 対象データベース／インスタンス内のすべてのデータベースとテーブルを一覧表示します。
3. Execute SQL — SQL クエリを実行して結果を返します。DQL 以外のクエリを保護する機能が組み込まれています。
4. マルチモーダルのベクトル化と検索 — テキスト、画像、動画のベクトル化と、ベクトル検索／ハイブリッド検索に対応します。

次のような場合にこのスキルを使用します：

1. ユーザーが自然言語で ByteHouse 内のデータをクエリしたい場合（「xxx テーブルのデータ件数を調べて」「どのデータベースやテーブルがあるか確認して」など）。
2. ユーザーが自然言語から SQL への変換（Text2SQL）を明示的に求めている場合、または ByteHouse で SQL を実行する必要がある場合。
3. ユーザーが ByteHouse でテキスト／画像／動画のベクトル化と保存、検索を行いたい場合。
4. ユーザーが ByteHouse、火山引擎クラウドデータウェアハウス、クラウドネイティブデータウェアハウス、データウェアハウスのクエリに関するキーワードに言及した場合。

🧭 エージェント向け使用ガイド（重要）

エージェントは上記のタスクを受ける際、以下の手順でこのスキル内のスクリプトを実行してください。

1. 設定を確認する：まず source scripts/export_config.sh を実行し、~/.bytehouse_config.json 内の設定を環境変数に読み込みます。
   • ~/.bytehouse_config.json が存在しない場合、または BYTEHOUSE_HOST／BYTEHOUSE_PASSWORD が不足している場合は、ユーザーに情報の提供を依頼してください。ユーザーから返された接続情報をその JSON ファイルに書き込んでから source を実行します。
2. データの全体像を把握する：ユーザーがデータベースやテーブルを明示していない場合は、まず scripts/list_tables.py を使ってデータベース／テーブルの一覧を取得し、ユーザー／エージェントがクエリ対象のテーブルを選べるようにします。
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 件の結果を返し、エラーが発生した場合はエラーの全文を表示します。どのような場合でも、キーやパスワードなどの機密情報は必ずマスクしてください。

エージェントは必ず上記のスクリプトを通じてクエリ／実行を行う必要があります。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"
}

• BYTEHOUSE_HOST（ホストアドレス）と BYTEHOUSE_PASSWORD（パスワード）は、必ずユーザーから提供してもらってください。
• BH_ARK_API_KEY はマルチモーダルのベクトル化時のみ使用します。それ以外の場合は無視できます。
• その他のフィールドはデフォルト値のままにすることをおすすめします。

使用上の制限

1. DQL 以外の保護：Text2SQL が生成した SQL が INSERT／UPDATE／DELETE／DROP などの DML／DDL 文に該当する場合、エージェントは必ず実行をブロックし、具体的な SQL をユーザーに提示して、実行してよいか明確に確認してください。
   • execute_sql.py は DQL 以外の SQL を検出すると、デフォルトでエラーを返し、確認を求めます。
   • ユーザーが明確に同意した場合に限り、--force パラメーターを追加して強制実行できます。例：

     python3 scripts/execute_sql.py "DROP TABLE xxx" --force
     

2. 結果の表示：デフォルトでは、クエリ条件に一致する結果の先頭 5 件を表示します。エラーが発生した場合は、エラー情報の全文を表示します。
3. 推測の禁止：データ／アセットに関する質問には、必ず SQL を実行してから回答してください。コンテキストに基づいて答えを推測してはいけません。
4. 機密情報の保護：パスワードやキーなどの機密情報をそのまま出力してはいけません。表示が必要な場合はマスクしてください。

前提条件

• Python 3.8+
• jq（export_config.sh による JSON の解析に必要です。未インストールの場合は brew install jq または sudo apt install jq でインストールできます）
• Python の依存関係：requirements.txt を参照してください。pip install -r requirements.txt でインストールできます。
• 有効な ByteHouse 接続情報（~/.bytehouse_config.json に保存）

🚀 クイックスタート

1. ByteHouse 接続情報を読み込む

# 从配置文件读取配置，导出到环境变量
source scripts/export_config.sh

2. データベースとテーブルを一覧表示する

# 列出所有数据库
python3 scripts/list_tables.py --databases

# 列出指定数据库的表
python3 scripts/list_tables.py --database tpcds

3. Text2SQL

# 执行 Text2SQL
python3 scripts/text2sql.py "get count of all call centers" "tpcds.call_center"

戻り値：

SELECT COUNT(*) AS call_center_count FROM tpcds.call_center;

4. SQL クエリを実行する

python3 scripts/execute_sql.py "SELECT * FROM tpcds.call_center LIMIT 5"
python3 scripts/execute_sql.py "SELECT count(*) FROM tpcds.store_sales" --format pretty

5. 一連の処理：Text2SQL + Execute

# 1. 生成 SQL
SQL=$(python3 scripts/text2sql.py "get count of call centers" "tpcds.call_center")

# 2. 执行 SQL
python3 scripts/execute_sql.py "$SQL"

6. マルチモーダルのベクトル化と検索

マルチモーダル関連のスクリプト：

• scripts/embedding.py — マルチモーダルのベクトル化モジュール
• scripts/search_client.py — ByteHouse ベクトル検索クライアント

# 从脚本目录调用，或将 scripts/ 加入 sys.path
from search_client import ByteHouseMultimodalSearch

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

# 创建表
search.create_multimodal_table("my_index")

# 插入文档
search.insert_document(
    "my_index",
    doc_id=1,
    content_type="text",
    content="ByteHouse 多模态检索",
    title="介绍",
)

# 向量检索（返回结果中已过滤掉 0 维向量）
query_embedding = search.embedding.encode_text("云原生数据仓库")
results = search.vector_search("my_index", query_embedding=query_embedding, top_k=10)

参考ドキュメント：

• ByteHouse ベクトル検索 SQL ドキュメント
• 火山引擎マルチモーダルベクトル化 API ドキュメント

💻 プログラムからの呼び出し

Text2SQL + Execute の一括実行

import subprocess
import json


def ai_query(natural_language: str, tables: list, config: dict = None) -> str:
    """调用 Text2SQL 并执行查询"""
    cmd = ["python3", "scripts/text2sql.py", natural_language] + tables
    if config:
        cmd.extend(["--config", json.dumps(config)])

    sql_result = subprocess.run(cmd, capture_output=True, text=True)
    sql = sql_result.stdout.strip()

    if not sql:
        return f"Text2SQL failed: {sql_result.stderr}"

    result = subprocess.run(
        ["python3", "scripts/execute_sql.py", sql],
        capture_output=True,
        text=True,
    )
    return result.stdout


if __name__ == "__main__":
    print(ai_query("get count of call centers", ["tpcds.call_center"]))

API リファレンス

Text2SQL リクエストパラメーター

パラメーター	型	必須	説明
systemHints	string	いいえ	システムプロンプトです。デフォルトは "TEXT2SQL" です
input	string	はい	自然言語によるクエリ
knowledgeBaseIDsString	string[]	いいえ	ナレッジベース ID の一覧です。デフォルトは ["*"] です
tables	string[]	はい	クエリ対象のテーブル名一覧です
config	object	いいえ	カスタム設定です
config.reasoningModel	string	いいえ	カスタムモデル ID です
config.reasoningAPIKey	string	いいえ	カスタム API Key です
config.url	string	いいえ	カスタム API URL です