Skip to content

README_ja.md

Latest commit

 

History

History
201 lines (134 loc) · 9.97 KB

README_ja.md

File metadata and controls

201 lines (134 loc) · 9.97 KB

画像検索アプリケーション

English Edition | 中国語版

紹介

OceanBase のベクトル保存および検索機能を活用することで、画像検索アプリケーションを構築できます。このアプリケーションは画像をベクトルとして埋め込み、データベースに保存します。ユーザーが画像をアップロードすると、アプリケーションはデータベース内から最も類似した画像を検索して返します。

注意：画像データはご自身で用意し、UI上の Image Base 設定を更新する必要があります。ローカルに画像がない場合は、Kaggle の Animals-10 データセットなどのオンラインデータセットをダウンロードして利用できます。

システムアーキテクチャと原理

本プロジェクトは以下の4つのコアコンポーネントで構成されています。

  • フロントエンド（Streamlit UI）：画像のアップロード、パラメータ設定（top_k、検索モード、distance_thresholdなど）、および結果の表示を担当します。
  • アプリケーション層（OBImageStore）：データセットの読み込み、多次元検索、および結果の融合に関するコアロジックをカプセル化し、検索タスクを完了するために各モジュールを調整します。
  • 特徴量とセマンティック情報の抽出・生成：
    • 画像ベクトル（Embedding）：DashScope Multimodal-Embedding API を介して画像ベクトルを生成し、類似度検索に使用します。
    • 画像説明（Caption）：全文検索およびハイブリッド検索用に、OpenAI互換インターフェースを介して画像の内容を説明する短いテキストを生成します。
  • ストレージ層（OceanBase / seekdb）：デフォルトで seekdb コンテナをベクトルデータベースとして使用します。ベクトルインデックスとキャプション全文インデックスの両方を同時に維持します。

以下に、「データセットの読み込み / 画像検索」の各ステップを説明します（単体のテキスト検索UIは現在非表示です）。

1) データセットの読み込み

使用方法：サイドバーで画像の圧縮ファイルを選択し、画像を読み込む をクリックします。

データセット読み込みのプロセス：

  1. 解凍とスキャン：アップロードされた圧縮ファイルを解凍し、画像ファイル（jpg、jpeg、png形式をサポート）をスキャンします。
  2. ステップバイステップ処理：
    • 画像の読み込みと基本情報の抽出。
    • ベクトルの生成：後続の類似度検索で使用される画像の埋め込み（Embedding）を生成します。
    • 説明の生成：後続のテキスト検索またはハイブリッド検索で使用される画像の短いテキスト説明（Caption）を生成します。
  3. インフラストラクチャの準備：データベーステーブルと、それに関連付けられたベクトルインデックス（HNSW）および全文インデックスが準備されていることを確認します。これは効率的な検索のための前提条件です。
  4. 一括インポート：画像のファイル名、パス、説明、およびベクトル特徴量を OceanBase / seekdb に一括で書き込みます。

補足事項：

  • make init によるテーブル/インデックスの作成：初期化スクリプトは、テーブルとベクトル＋キャプション全文インデックスを作成します。テーブルが既に存在する場合はスキップされます。
  • 読み込みプロセス中のテーブル作成フォールバック：作成コマンドを事前に実行しなかった場合でも、アプリケーション層は最初のインポート時にテーブルの存在を確認し、存在しない場合は作成します。

2) 画像検索

使用方法：画像をアップロードして検索をクリックします。

検索プロセス：

  1. 画像のアップロード：フロントエンドが検索入力として画像をアップロードします。
  2. クエリ特徴量の生成：
    • ベクトル特徴量：データベース内の画像に対してベクトル類似度検索を行うために、画像のベクトルを抽出します。
    • テキスト特徴量：データベースでの全文検索用に、画像の内容を説明するテキスト（Caption）を生成します。
  3. 検索モードに応じたリコールとランキング：
    • 全文検索モード：caption 全文インデックスのみで結果をリコールします。
    • ハイブリッドモード：ベクトルと全文の両方を使い、pyseekdb のネイティブ hybrid_search（RRF）で融合・ランキングします。
    • ベクトルモード：ベクトル類似検索のみを行い、distance_threshold によるフィルタリングをサポートします。
  4. Top K を返却：最終的な Top K 結果を出力します。

クイックスタート（推奨）

Docker Compose を使用してアプリケーションとデータベースを一括起動します。

1. 環境変数の設定

cd docker
cp .env.example .env

docker/.env ファイルを編集し、以下の必須項目を設定します：

# 画像埋め込み API Key（必須）
EMBEDDING_API_KEY=sk-your-dashscope-key

# 画像キャプション VLM API Key（ハイブリッド/全文検索モードで必須、ベクトルモードでは不要）
# OpenAI 互換の VLM プロバイダで利用可能
VLM_API_KEY=sk-your-vlm-key
VLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# データベース選択（seekdb または oceanbase）
DB_STORE=seekdb

2. サービスの起動

# seekdb を使用（デフォルト、メモリ使用量が少ない）
docker compose --profile seekdb up -d

# または oceanbase を使用
docker compose --profile oceanbase up -d

3. アプリケーションへのアクセス

ブラウザで http://localhost:8501 にアクセスし、サイドバーで画像の圧縮ファイルをアップロードしてデータセットを読み込み、検索を開始できます。

4. サービスの停止

docker compose down

ローカル開発デプロイ

Docker を使用せずにローカル環境で直接実行する場合は、以下の手順に従ってください。

準備

  1. 依存関係管理ツールとして uv をインストールします。
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. システムで make コマンドが利用可能であることを確認してください。

1. 環境変数の設定

.env.example ファイルを .env にコピーし、必要に応じて設定を修正します。

cp .env.example .env

重要な設定項目：

  • EMBEDDING_API_KEY（必須）：画像埋め込み生成用の API キー
  • VLM_API_KEY（ハイブリッド/全文検索モードで必須）：画像キャプション生成用の API キー
    • ベクトルモードのみを使用する場合は設定不要です
    • OpenAI、Qwen（通義千問）など、OpenAI API 互換のサービスをサポートしています

その他の設定項目（通常はデフォルト値を使用）：

  • EMBEDDING_TYPE：埋め込みバックエンドタイプ（デフォルト dashscope）
  • EMBEDDING_MODEL：埋め込みモデル名（デフォルト tongyi-embedding-vision-plus）
  • EMBEDDING_DIMENSION：ベクトル次元（デフォルト 1024）
  • VLM_BASE_URL：画像キャプション API サービスエンドポイント（デフォルトは Qwen のサービス）
  • MODEL：画像キャプションモデル名（デフォルト qwen-vl-max）

設定例（.env）：

# 必須設定
EMBEDDING_API_KEY=sk-your-dashscope-key
VLM_API_KEY=sk-your-vlm-key

# オプション設定（デフォルト値を使用）
EMBEDDING_TYPE=dashscope
EMBEDDING_MODEL=tongyi-embedding-vision-plus
EMBEDDING_DIMENSION=1024
VLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
MODEL=qwen-vl-max

2. 環境の初期化

このコマンドは、OceanBase データベースコンテナを起動し、すべての依存関係をインストールします。

make init

3. アプリケーションの起動

make start

4. 画像データの処理と保存

アプリケーション画面が開いたら、左側のサイドバーにある "Image Base" 入力欄に、用意した画像ディレクトリの絶対パスを入力し、"画像を読み込む" ボタンをクリックしてください。アプリケーションが画像を処理して保存し、画面に進捗が表示されます。

5. 画像検索を使用

画像の処理が完了すると、画面中央上部にアップロード欄が表示されます。検索したい画像をアップロードすると、データベース内から最も類似した画像（デフォルトで上位10枚）が返されます。

image_search_ui

その他のコマンド

アプリケーションの停止

make stop

リソースのクリーンアップ

make clean

よくある質問

1. Docker のインストールで問題が発生した場合は？

Docker のインストールや OceanBase コンテナの起動で問題が発生した場合は、OceanBase OBI にてサポートを確認してください。