Skip to content

Preparation

Let's start with the preparation for the hands-on.

First, please check how to open the terminal/command prompt.

How to Open Terminal/Command Prompt

In the following steps, use either IBM Bob's built-in terminal or your system terminal/command prompt.

Open Terminal/Command Prompt in IBM Bob:

You can open it using one of the following methods:

  • From the menu bar: Terminal → New Terminal
  • Ctrl + ` (backtick)
  • Click the icon in the upper right, or Cmd + J (toggle panel)

A black screen (terminal/command prompt) will appear at the bottom of the screen.

Open System Terminal/Command Prompt:

  1. Open Spotlight with Cmd + Space
  2. Type "Terminal"
  3. Press Enter

Or:

  • Applications → Utilities → Terminal
  1. Press Win + R
  2. Type "cmd"
  3. Press Enter

Or:

  • Start menu → Search for "Command Prompt"

Requirements

1. Vector Search Builder Mode

Vector Search Builder is a custom mode for IBM Bob provided as part of Building Blocks, making it easy to build vector search functionality.

Vector Search Builder Overview

Provider: IBM Build Engineering Team

Included features:

  • Milvus database setup and management
  • Local embedding model integration with Hugging Face Transformers
  • Data ingestion pipeline construction
  • Vector search optimization
  • Sample product data ingestion workflow

Integration with IBM Bob:

  • AI assistant specialized for Vector Search
  • Code generation with understanding of Building Blocks features
  • Implementation support based on best practices

Benefits of Building Blocks

Normal development: Read Milvus documentation, learn SDK, write code from scratch (days)

Using Building Blocks: Install Vector Search Builder and instruct IBM Bob in natural language (minutes)

Innovation in this hands-on: Instructor provides Milvus environment, participants join with only IBM Bob (no environment setup required)

Step 1: Install Vector Search Builder

  1. Copy the distributed vector-search-builder-en.zip to your desktop

  2. Extract the zip file

    GUI: Double-click

    Terminal/Command Prompt: 

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

    GUI: Right-click → "Extract All"

    ※ Simply opening by double-clicking does not extract, so please execute "Extract All"

    Terminal/Command Prompt: 

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

  3. Confirm that a vector-search-builder-en folder is created with a .bob folder inside

Important

The .bob folder must be placed directly under the project folder (in this hands-on, vector-search-builder-en).

Contents of vector-search-builder-en.zip

vector-search-builder-en.zip contains:

Building Blocks:

  • .bob/: Vector Search Builder mode definition

Participant setup files:

  • setup/participant/: Participant scripts, FastAPI demo app, and language-specific sample data
  • setup/participant/.env.example: Connection information configuration template
  • setup/participant/sample_products.py: Selects the sample product data to use
  • setup/participant/sample_products_en.py: English sample product data
  • PARTICIPANT_LANGUAGE=en: English sample product data and runtime messages are used
Building Blocks Installation Methods

Normally, Building Blocks are installed using the following methods:

  • Global installation: ~/.config/IBM Bob/User/globalStorage/ibm.bob-code/
  • Project local: .bob/ (this hands-on's method)

In this hands-on, installing locally to the project keeps the environment clean and allows easy cleanup.

Step 2: Open the vector-search-builder-en Folder in IBM Bob

IBM Bob Version Used

This hands-on uses IBM Bob 1.0.3. If you use a different version, some screens or command behavior may differ.

  1. Launch IBM Bob

  2. Open the vector-search-builder-en folder

    GUI: File → Open... and select the vector-search-builder-en folder, or press ⌘ + O to open the folder selection dialog.

    GUI: File → Open... and select the vector-search-builder-en folder, or press Ctrl + O to open the folder selection dialog.

  3. Confirm that "Vector Search Builder" appears in the "Mode" selector at the bottom right of the screen and select it

Vector Search Builder Mode

When you select Vector Search Builder mode from the "Mode" selector, the Building Blocks dedicated custom mode becomes active.

This mode enables IBM Bob to understand:

  • How to operate Milvus database
  • Vector search best practices
  • Embedding model integration methods
  • Building Blocks features and constraints

2. Connection Information

Milvus (Vector Database)

Configure the IP address distributed by the instructor.

Practice: Configure connection information

Create the configuration file for connecting to Milvus, then enter the IP address distributed by the instructor.

  1. Open the setup/participant folder

  2. Copy .env.example and rename the copied file to .env

    GUI: Right-click .env.example in Finder → "Duplicate" → Rename to .env

    Terminal/Command Prompt: 

    cd setup/participant
cp .env.example .env

    GUI: Right-click .env.example in Explorer → "Copy" → "Paste" → Rename to .env

    Terminal/Command Prompt: 

    cd setup\participant
copy .env.example .env

  3. Open the .env file and enter the connection information distributed by the instructor

    Milvus Connection Settings

    # Milvus connection information
MILVUS_HOST=192.168.1.100  # ← Change to IP address distributed by instructor
MILVUS_PASSWORD=AbCd123XyZ # ← Change to password distributed by instructor

# Collection name (Milvus is shared by all participants)
COLLECTION_NAME=products_taro  # ← Change to a name unique to you

# No changes needed below
MILVUS_PORT=19530
MILVUS_USER=root
EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2
PARTICIPANT_LANGUAGE=en

    # Milvus connection information
MILVUS_HOST=0.tcp.jp.ngrok.io  # ← Change to hostname distributed by instructor
MILVUS_PORT=24051              # ← Change to port number distributed by instructor
MILVUS_PASSWORD=AbCd123XyZ     # ← Change to password distributed by instructor

# Collection name (Milvus is shared by all participants)
COLLECTION_NAME=products_taro  # ← Change to a name unique to you

# No need to change below
MILVUS_USER=root
EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2
PARTICIPANT_LANGUAGE=en

    Set a unique collection name

    All participants connect to the same Milvus server managed by the instructor. Set COLLECTION_NAME to a name that is unique to you (e.g. products_taro, using letters, numbers, and underscores). If two participants use the same name, inserting sample data will overwrite each other's collection.

    ngrok Connection Note

    When using ngrok, a corporate VPN or DNS security product such as Cisco Umbrella may block access to the ngrok TCP tunnel or prevent the hostname from resolving correctly. Even after disconnecting the VPN, the connection may still fail if Cisco Umbrella or a similar security product remains active. If you cannot connect, follow your organization's rules and use an alternative method provided by the instructor, such as connecting from the same network.

  4. Save the file

    Cmd + S

    Ctrl + S

Embedding Model (AI that Converts Text to Numbers)

Uses Hugging Face Transformers (no API key required, free).

What is an embedding model: An AI model that converts the "meaning" of text into numbers (vectors).

  • Model: paraphrase-multilingual-MiniLM-L12-v2
  • Dimensions: 384 (represents meaning with 384 numbers)
  • Features: Multilingual support

3. Python Environment Setup

Step 1: Verify Python Installation

First, verify that Python is installed.

Terminal/Command Prompt: 

python3 --version

Terminal/Command Prompt: 

python --version

Expected output:

Python 3.10.x or higher (3.11 recommended)

If Python 3.10 or higher is not installed, install it before continuing.

Download and install the installer from the official site.

Official site: https://www.python.org/downloads/

If you use Homebrew, you can also install with:

brew install python3

Download and run the installer from the official site.

Official site: https://www.python.org/downloads/

Installation Note

On the first installer screen, check Add python.exe to PATH before clicking Install Now. Without this option, python and pip may not run from Command Prompt.

Step 2: Create Virtual Environment (Important)

To Avoid Breaking the Global Environment

Always use a virtual environment. Installing directly in the global environment may affect other projects.

Create a virtual environment and install packages within it.

Terminal/Command Prompt: 

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

Terminal/Command Prompt: 

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

About Prompt Display

When the virtual environment is activated, (venv) may appear at the beginning of the prompt depending on your environment. It may not appear depending on your terminal or shell settings.

Benefits of Virtual Environment

  • Isolation: Environment dedicated to this project
  • Safety: Does not break the global environment
  • Cleanup: Can be completely removed by just deleting the venv folder
  • Reproducibility: Can reproduce the same configuration in other environments

Step 3: Install Required Packages

Directly specify the Python executable inside venv to install Python packages.

  1. Verify that the venv folder has been created

  2. Run the following in the terminal:

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

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

  3. Wait for installation to complete (may take several minutes)

Linux users: install the CPU-only torch first

On Linux, the default torch wheel bundles CUDA libraries (several GB). Run the following before pip install -r requirements.txt for a much smaller, faster install:

venv/bin/python -m pip install torch==2.12.0 --index-url https://download.pytorch.org/whl/cpu
Why directly specify Python inside venv

Even if you activated the virtual environment in your terminal, another terminal or AI tool may not inherit that state. Specifying venv/bin/python or venv\Scripts\python directly ensures the packages are installed into venv.

Packages to be Installed

The following packages will be installed:

Main packages:

  • pymilvus: Milvus database client
  • sentence-transformers: Embedding models
  • torch: Machine learning framework
  • fastapi: Web framework
  • uvicorn: ASGI server
  • python-dotenv: Environment variable management

Dependencies (auto-installed):

  • transformers, huggingface-hub
  • pydantic, starlette
  • scikit-learn
  • And others
Deactivating Virtual Environment

When finished working, you can deactivate the virtual environment:

deactivate

Next time you work, activate it again:

cd ~/Desktop/vector-search-builder-en/setup/participant
source venv/bin/activate

cd %USERPROFILE%\Desktop\vector-search-builder-en\setup\participant
venv\Scripts\activate

Preparation Completion Checklist

  • IBM Bob is installed and available
  • Python 3.10 or higher is installed
  • Extracted vector-search-builder-en.zip
  • .bob folder exists
  • Opened vector-search-builder-en folder in IBM Bob
  • "Vector Search Builder" mode is displayed
  • Entered connection information in setup/participant/.env file
  • Created and activated virtual environment ((venv) is displayed in prompt)
  • Installed Python packages in virtual environment

FAQ

Q1: Vector Search Builder mode is not displayed

Solution:

  1. Verify .bob folder exists
  2. Reload IBM Bob ( ⌘ + Shift + P / Ctrl + Shift + P → "Reload Window")
  3. Reopen the project folder
Q2: Don't know where to enter connection information

Solution:

  1. Open the setup/participant folder in the project folder
  2. Look for the .env file (if not found, copy .env.example)

Next Steps

Once preparation is complete, proceed to Part 1: Environment Verification and Demo!