byted-bytehouse-multimodal-search

ByteHouse マルチモーダル検索 Skill

説明

この Skill は、ByteHouse のベクトル検索機能と火山エンジン Ark のマルチモーダルベクトル化モデル（デフォルトは doubao-embedding-vision）を基に、ベクトル化 → テーブル作成 → 書き込み → 検索までの一連のマルチモーダル検索のリファレンス実装を提供します。主な機能は次のとおりです。

1. マルチモーダルベクトル化：テキスト／画像／動画 → 統一された次元のベクトル。
2. ベクトルテーブルの作成：HNSW、IVF_FLAT、IVF_PQ などのインデックスをサポートし、全文転置インデックスを任意で有効にできます。
3. ドキュメントの書き込み：単一／一括挿入に対応し、content_type、title、metadata を付加します。
4. 検索機能：ベクトル検索、ハイブリッド検索（ベクトル + キーワード）、テキストから画像を検索、画像から画像／動画を検索。

次の場合にこの Skill を使用してください：

1. ユーザーが ByteHouse でマルチモーダルベクトル検索サービスを構築したい場合。
2. ユーザーが既存のマルチモーダルデータ（テキスト、画像、動画）をベクトル化して ByteHouse に書き込む必要がある場合。
3. ユーザーが「ベクトル検索」、「マルチモーダル検索」、「ハイブリッド検索」、「テキストから画像を検索」、「画像から動画を検索」などのキーワードに言及した場合。

前提条件

• Python 3.8+
• Python 依存関係：clickhouse-connect、clickhouse-driver（TCP の場合）、volcengine-python-sdk[ark]、numpy

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

• jq（export_config.sh の依存関係。JSON 設定の解析に使用します。インストール方法：brew install jq または sudo apt install jq）
• 有効な ByteHouse 接続情報と Ark API Key（~/.bytehouse_config.json に保存）

📁 ファイルの説明

• SKILL.md — 本ファイル。Skill のメインドキュメントです。
• scripts/embedding.py — マルチモーダルベクトル化モジュール（MultimodalEmbedding）。
• scripts/search_client.py — ByteHouse マルチモーダル検索クライアント（ByteHouseMultimodalSearch）。
• scripts/examples.py — 一般的な呼び出し例（初期化、テーブル作成、書き込み、検索）。
• scripts/init.py — Python パッケージのエントリーポイント。MultimodalEmbedding と ByteHouseMultimodalSearch を公開します。
• scripts/export_config.sh — ~/.bytehouse_config.json から環境変数に設定を読み込みます（jq が必要です）。

🧭 エージェント向け使用ガイド

1. 設定の確認：source scripts/export_config.sh を実行して、BYTEHOUSE_*、BH_ARK_* などの環境変数を使用できる状態にします。
2. 用途の確認：ユーザーに「テーブル作成 + 書き込み」か「検索のみ」か、またデータのモダリティ（テキストのみ／テキスト + 画像／動画など）を確認します。
3. インデックス戦略の選択：
   • データ量が 100 万件未満：HNSW + COSINE（デフォルト）。
   • データ量が多い場合、またはメモリ使用量を抑えたい場合：HNSW_SQ／IVF_FLAT／IVF_PQ。
4. テーブル作成 + 書き込み：ByteHouseMultimodalSearch.create_multimodal_table(...)、insert_document(...)、または batch_insert(...) を呼び出します。
5. 検索：まず vector_search(...) または hybrid_search(...) を使用します。返される結果からはゼロベクトルや異常データが自動的に除外されます。
6. セキュリティに関する注意：BH_ARK_API_KEY、BYTEHOUSE_PASSWORD などの認証情報は ~/.bytehouse_config.json にのみ保存し、ログやメッセージに出力しないでください。

設定の説明

設定は ~/.bytehouse_config.json に保存します。ファイルが存在し、空でない場合はそのまま使用します。それ以外の場合は、ユーザーに ByteHouse 接続情報と Ark API Key を提供してもらい（ByteHouse 接続情報の取得ガイドもあわせてユーザーに送信できます）、受け取った情報を JSON ファイルに書き込み、同じ内容を再度尋ねないようにします。ユーザーが ByteHouse クラスターまたは Ark アカウントを切り替えた場合は、このファイルもあわせて更新します。

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

• BYTEHOUSE_HOST（ホストアドレス）と BYTEHOUSE_PASSWORD（パスワード）は、必ずユーザーから提供してもらう必要があります。
• その他のフィールドはデフォルト値のままにすることを推奨します。
• 実行前に必ず source scripts/export_config.sh を実行して、設定を環境変数にエクスポートしてください。search_client.py と embedding.py は環境変数からのみ設定を読み取ります。

source scripts/export_config.sh

🚀 クイックスタート

1. クライアントの初期化

import sys, os
# 把 scripts/ 目录加入 sys.path
SKILL_SCRIPTS_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "scripts")
sys.path.insert(0, SKILL_SCRIPTS_DIR)

from search_client import ByteHouseMultimodalSearch

search = ByteHouseMultimodalSearch(connection_type="http")

2. マルチモーダル検索テーブルの作成

search.create_multimodal_table(
    table_name="multimodal_index",
    enable_text_search=True,
    index_type="HNSW",
    metric="COSINE",
)

3. データの書き込み

# 文本
search.insert_document(
    "multimodal_index",
    doc_id=1,
    content_type="text",
    content="ByteHouse 是火山引擎推出的云原生数据仓库",
    title="ByteHouse 介绍",
    metadata={"category": "文档"},
)

# 图片（自动生成向量）
search.insert_document(
    "multimodal_index",
    doc_id=2,
    content_type="image",
    content="https://example.com/image.jpg",
    title="示例图片",
)

4. ベクトル検索

# 文本查询 → 向量检索
query_embedding = search.embedding.encode_text("云原生数据仓库")
results = search.vector_search(
    "multimodal_index",
    query_embedding=query_embedding,
    top_k=10,
)

# 混合检索（关键词 + 向量）
results = search.hybrid_search(
    "multimodal_index",
    query_text="云原生数据仓库",
    top_k=10,
)

その他の例は scripts/examples.py を参照してください。

対応するインデックスの種類

インデックスの種類	説明	パラメーター
HNSW	高性能な汎用インデックス	M, EF_CONSTRUCTION
HNSW_SQ	HNSW スカラー量子化。メモリを節約します	M, EF_CONSTRUCTION
IVF_FLAT	転置ファイルインデックス	dim, metric
IVF_PQ	直積量子化	dim, metric
IVF_PQ_FS	PQ 高速検索	dim, metric

対応するベクトル化入力

• テキスト：任意の文字列。
• 画像：URL または Base64 エンコード。
• 動画：URL または Base64 エンコード（フレームサンプリング + ベクトル化）。

失敗時のフォールバック案

現象	対処方法
ModuleNotFoundError: volcenginesdkarkruntime	ユーザーに pip install "volcengine-python-sdk[ark]" のインストールを案内します。
BH_ARK_API_KEY が設定されていない	Ark コンソールで API Key を取得し、~/.bytehouse_config.json に書き込むようユーザーに案内します。
BYTEHOUSE_HOST／BYTEHOUSE_PASSWORD が設定されていない	ユーザーに接続情報を提供してもらい、~/.bytehouse_config.json に書き込んだ後、source scripts/export_config.sh を実行するよう案内します。
返された結果が空のベクトル／すべて 0 のベクトル	クライアントはゼロベクトルをすでに除外しています。それでも頻繁に発生する場合は、ベクトル化の入力形式（URL にアクセスできるか、画像が破損していないか）を確認します。
テーブル作成時に "index type xxx not supported" エラーが発生する	ユーザーにクラスターのバージョンを確認してもらうか、フォールバックとして HNSW を使用します。

参考ドキュメント

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