事前準備

それでは、ハンズオンの準備から行っていきます。まずは、ターミナル / コマンドプロンプトの開き方を確認してください。

ターミナル / コマンドプロンプトの開き方

この後の手順では、IBM Bob 内蔵のターミナル、またはシステムのターミナル / コマンドプロンプトを使用します。

IBM Bob でターミナル / コマンドプロンプトを開く:

次のいずれかの方法で開くことができます:

• メニューバーから ターミナル → 新しいターミナル
• Ctrl + `（バッククォート）
• 右上のアイコンをクリック（パネルの切り替え）

画面下部に黒い画面（ターミナル / コマンドプロンプト）が表示されます。

システムのターミナル / コマンドプロンプトを開く:

Mac Windows

1. Cmd + Space で Spotlight を開く
2. 「ターミナル」と入力
3. Enter を押す

または:

• アプリケーション → ユーティリティ → ターミナル

1. Win + R を押す
2. 「cmd」と入力
3. Enter を押す

または:

• スタートメニュー → 「コマンドプロンプト」を検索

必要なもの

1. Vector Search Builder モード

Vector Search Builder は、Building Blocks の一部として提供されていた、ベクトル検索機能を簡単に構築できる IBM Bob のカスタムモードです。

このモードの配布について

Building Blocks は 2026 年 4 月 30 日版を最後にこのモードの配布を終えました（ibm-self-serve-assets/building-blocks、b64ca4c）。このハンズオンでは最終版を MilvusClient API と作業環境に合わせて更新し、同梱・保守しています。

Vector Search Builder の概要

提供元: IBM Build Engineering Team

含まれる機能:

• Milvus データベースのセットアップと管理
• Hugging Face Transformers によるローカル埋め込みモデルの統合
• データ取り込みパイプラインの構築
• ベクトル検索の最適化
• サンプル商品データの投入ワークフロー

IBM Bob との連携:

• Vector Search に特化した AI アシスタント
• Building Blocks の機能を理解した上でコード生成
• ベストプラクティスに基づいた実装支援

Building Blocks の利点

Milvus のドキュメントを読み、SDK を学習し、コードを一から書く（数日）代わりに、Vector Search Builder をインストールして IBM Bob に自然言語で指示します（数分）。

ステップ 1: Vector Search Builder をインストール

1. 配布された vector-search-builder-ja.zip をデスクトップにコピー

2. zip ファイルを解凍

   Mac Windows

   GUI: ダブルクリック

   ターミナル / コマンドプロンプト:

   cd ~/Desktop
   mkdir -p vector-search-builder-ja
   unzip vector-search-builder-ja.zip -d vector-search-builder-ja
   

   GUI: 右クリック →「すべて展開」

   ※ ダブルクリックで開いただけでは展開されないため、「すべて展開」を実行してください

   ターミナル / コマンドプロンプト:

   cd %USERPROFILE%\Desktop
   mkdir vector-search-builder-ja
   tar -xf vector-search-builder-ja.zip -C vector-search-builder-ja
   

3. vector-search-builder-ja フォルダが作成され、その中に .bob フォルダがあることを確認

重要

.bob フォルダはプロジェクトフォルダ（このハンズオンでは vector-search-builder-ja）の直下に配置する必要があります。

vector-search-builder-ja.zip の内容

• .bob/: Vector Search Builder モード定義（Building Blocks）
• setup/participant/: 参加者用スクリプト、検索画面つきの FastAPI デモアプリ、日本語のサンプル商品データ（PARTICIPANT_LANGUAGE=ja）
• setup/participant/.env.example: 接続情報設定テンプレート

Building Blocks のインストール方法

通常、Building Blocks は以下の方法でインストールします:

• グローバルインストール: ~/.config/IBM Bob/User/globalStorage/ibm.bob-code/
• プロジェクトローカル: .bob/（このハンズオンの方法）

このハンズオンでは、プロジェクトローカルにインストールすることで、環境を汚さず、簡単にクリーンアップできます。

ステップ 2: IBM Bob で vector-search-builder-ja フォルダを開く

使用する IBM Bob のバージョン

このハンズオンは IBM Bob 2.2.1（2026 年 10 月）で動作を確認しています。バージョンが異なると、モードの一覧、承認の表示、IBM Bob の提案内容が変わることがあります。

1. IBM Bob を起動

2. vector-search-builder-ja フォルダを開く

   Mac Windows

   GUI: ファイル → 開く... で vector-search-builder-ja フォルダを選択、または ⌘ + O でフォルダ選択ダイアログを開く。

   GUI: ファイル → 開く... で vector-search-builder-ja フォルダを選択、または Ctrl + O でフォルダ選択ダイアログを開く。

3. IBM Bob のパネルで、チャット入力欄の下にあるモードの選択を開き、Vector Search Builder を選択

Vector Search Builder モード

Vector Search Builder モードを選択すると Building Blocks 専用のカスタムモードが有効になり、IBM Bob は Milvus の操作、ベクトル検索のベストプラクティス、埋め込みモデルの統合に関するルールに沿って作業します。

2. 接続情報

Milvus（ベクトルデータベース）

講師から配布された IP アドレスを設定します。

実践: 接続情報を設定します

Milvus に接続するための設定ファイルを作成し、講師から配布された IP アドレスを入力します。

1. setup/participant フォルダを開く

2. .env.example をコピーし、コピーしたファイル名を .env に変更

   Mac Windows

   GUI: Finder で .env.example を右クリック →「複製」→ ファイル名を .env に変更

   ターミナル / コマンドプロンプト:

   cd setup/participant
   cp .env.example .env
   

   GUI: エクスプローラーで .env.example を右クリック →「コピー」→「貼り付け」→ ファイル名を .env に変更

   ターミナル / コマンドプロンプト:

   cd setup\participant
   copy .env.example .env
   

3. .env ファイルを開き、講師から配布された接続情報を入力

   同一ネットワーク（会場内）リモート（ngrok）

   # Milvus 接続情報
   MILVUS_HOST=192.168.1.100  # ← 講師から配布された IP アドレスに変更
   MILVUS_PASSWORD=AbCd123XyZ # ← 講師から配布されたパスワードに変更
   
   # コレクション名（Milvus は全参加者で共有されています）
   COLLECTION_NAME=products_taro  # ← 自分専用の一意な名前に変更
   
   # 以下は変更不要
   MILVUS_PORT=19530
   MILVUS_USER=root
   EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2
   PARTICIPANT_LANGUAGE=ja
   

   # Milvus 接続情報
   MILVUS_HOST=0.tcp.jp.ngrok.io  # ← 講師から配布されたホスト名に変更
   MILVUS_PORT=24051              # ← 講師から配布されたポート番号に変更
   MILVUS_PASSWORD=AbCd123XyZ     # ← 講師から配布されたパスワードに変更
   
   # コレクション名（Milvus は全参加者で共有されています）
   COLLECTION_NAME=products_taro  # ← 自分専用の一意な名前に変更
   
   # 以下は変更不要
   MILVUS_USER=root
   EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2
   PARTICIPANT_LANGUAGE=ja
   

   一意なコレクション名を設定してください

   全参加者が講師の管理する同じ Milvus サーバーに接続します。 COLLECTION_NAME には自分専用の一意な名前（例: products_taro、英数字とアンダースコア）を設定してください。 他の参加者と同じ名前を使うと、サンプルデータ投入時にお互いのコレクションを上書きしてしまいます。

   ngrok 接続時の注意

   ngrok を使用する場合、企業 VPN や Cisco Umbrella などの DNS セキュリティ製品により、ngrok の TCP トンネルへの接続がブロックされたり、ホスト名が正しく解決されなかったりすることがあります。VPN を切断しても Cisco Umbrella などが有効なままの場合は、接続できないことがあります。接続できない場合は、所属組織のルールに従い、同一ネットワークでの接続など講師から案内された代替方法を使用してください。

4. ファイルを保存

   Mac Windows

   Cmd + S

   Ctrl + S

埋め込みモデル（テキストを数値に変換する AI）

Hugging Face Transformers を使用します（API キー不要、無料）。

埋め込みモデルとは: テキストの「意味」を数値（ベクトル）に変換する AI モデルです。

• モデル: paraphrase-multilingual-MiniLM-L12-v2
• 次元数: 384（384 個の数値で意味を表現）
• 特徴: 多言語対応

3. Python 環境のセットアップ

ステップ 1: Python のインストール確認

まず、Python がインストールされているか確認します。

Mac Windows

ターミナル / コマンドプロンプト:

python3 --version

ターミナル / コマンドプロンプト:

python --version

期待される出力:

Python 3.10.x 以上（3.11 推奨）

Python 3.10 以上がインストールされていない場合は、インストールしてから次へ進んでください。

Mac Windows

公式サイトからインストーラーをダウンロードしてインストールします。

公式サイト: https://www.python.org/downloads/

Homebrew を使用している場合は、以下でもインストールできます。

brew install python3

公式サイトからインストーラーをダウンロードして実行します。

公式サイト: https://www.python.org/downloads/

インストール時の注意

インストーラーの最初の画面で Add python.exe to PATH にチェックを入れてから、Install Now をクリックしてください。チェックを入れないと、コマンドプロンプトから python や pip を実行できない場合があります。

ステップ 2: 仮想環境の作成（重要）

グローバル環境を破壊しないために

必ず仮想環境を使用してください。グローバル環境に直接インストールすると、他のプロジェクトに影響を与える可能性があります。

仮想環境を作成し、その中でパッケージをインストールします。

Mac Windows

ターミナル / コマンドプロンプト:

cd ~/Desktop/vector-search-builder-ja/setup/participant
python3 -m venv venv
source venv/bin/activate

ターミナル / コマンドプロンプト:

cd %USERPROFILE%\Desktop\vector-search-builder-ja\setup\participant
python -m venv venv
venv\Scripts\activate

プロンプト表示について

仮想環境を有効化すると、環境によってはプロンプトの先頭に (venv) が表示されることがあります。ただし、ターミナルやシェルの設定によって表示されない場合もあります。

仮想環境の利点

パッケージはこのプロジェクトの venv フォルダに入るため、ほかのプロジェクトに影響せず、フォルダを削除すればまとめて消せます。

ステップ 3: 必要なパッケージのインストール

venv 内の Python を直接指定して、Python パッケージをインストールします。

1. venv フォルダが作成されていることを確認

2. ターミナルで以下を実行:

   Mac Windows

   cd ~/Desktop/vector-search-builder-ja/setup/participant
   venv/bin/python -m pip install -r requirements.txt
   

   cd %USERPROFILE%\Desktop\vector-search-builder-ja\setup\participant
   venv\Scripts\python -m pip install -r requirements.txt
   

3. インストールが完了するまで待ちます（数分かかる場合があります）

Linux の方: CPU 版 torch を先にインストール

Linux ではデフォルトの torch ホイールに CUDA ライブラリが含まれるため数 GB になります。pip install -r requirements.txt の前に以下を実行すると、大幅に小さく高速にインストールできます。requirements.txt で指定した版の torch の CPU 版が入ります:

venv/bin/python -m pip install "torch==$(grep -E '^torch==' requirements.txt | cut -d= -f3)" --index-url https://download.pytorch.org/whl/cpu

venv 内の Python を直接指定する理由

仮想環境を有効化していても、別のターミナルや AI ツールが実行するコマンドにはその状態が引き継がれない場合があります。venv/bin/python または venv\Scripts\python を直接指定すると、確実に venv にインストールできます。

インストールされるパッケージ

主要パッケージは pymilvus（Milvus クライアント）、sentence-transformers と torch（埋め込み）、fastapi と uvicorn（Web アプリ）、python-dotenv（.env の読み込み）です。transformers、huggingface-hub、pydantic、scikit-learn などの依存パッケージは自動でインストールされます。

仮想環境の無効化

作業が終わったら以下を実行します。次回は setup/participant で source venv/bin/activate（Mac）または venv\Scripts\activate（Windows）を実行して再度有効化します。

deactivate

準備完了チェックリスト

• IBM Bob がインストールされ、使用できる
• Python 3.10 以上がインストールされている
• vector-search-builder-ja.zip を解凍した
• .bob フォルダが存在する
• IBM Bob で vector-search-builder-ja フォルダを開いた
• 「Vector Search Builder」モードが表示される
• setup/participant/.env ファイルに接続情報を入力した
• 仮想環境を作成し、有効化した（venv フォルダが作成されている）
• 仮想環境内で Python パッケージをインストールした

FAQ

Vector Search Builder モードが表示されない

1. .bob フォルダが存在するか確認
2. IBM Bob をリロード（ ⌘ + Shift + P / Ctrl + Shift + P →「Reload Window」）
3. プロジェクトフォルダを開き直す

接続情報をどこに入力すればいいか分からない

1. プロジェクトフォルダ内の setup/participant フォルダを開く
2. .env ファイルを探す（見つからない場合は .env.example をコピー）

次へ →