Essential Techniques for Production Vector Search Systems, Part 4: Multi-Vector Search

pip install qdrant-client fastembed numpy

# Add to your ~/.bashrc or ~/.zshrc
export QDRANT_URL="https://your-cluster-url.cloud.qdrant.io:6333"
export QDRANT_API_KEY="your-api-key-here"

# .env file
QDRANT_URL=https://your-cluster-url.cloud.qdrant.io:6333
QDRANT_API_KEY=your-api-key-here

from qdrant_client import QdrantClient
from dotenv import load_dotenv
import os

# Load environment variables from .env file
load_dotenv()

# Initialize client
client = QdrantClient(
    url=os.getenv("QDRANT_URL"),
    api_key=os.getenv("QDRANT_API_KEY"),
)

# Test connection
try:
    collections = client.get_collections()
    print(f" Connected successfully!")
    print(f"   Current collections: {len(collections.collections)}")
except Exception as e:
    print(f" Connection failed: {e}")
    print("   Check your .env file has QDRANT_URL and QDRANT_API_KEY")

python verify-connection.py
Connected successfully!
   Current collections: 2

"""
Example usage of the multi_vector module.

This demonstrates Named Vectors (Multi-Field Vector Search) with Qdrant,
and shows concrete value: when title-only or description-only search misses
relevant results, and how multi-vector fixes it.
"""

from multi_vector import (
    multi_vector_search,
    single_vector_search,
    display_multi_vector_results,
    get_qdrant_client,
    get_collection_vector_names,
    create_demo_collection,
    cleanup_demo_collection,
)
from dotenv import load_dotenv

load_dotenv()

client = get_qdrant_client()
EXISTING_COLLECTION_NAME = "automotive_parts"
DEMO_COLLECTION_NAME = "multi_vector_demo"

# --- Collection setup ---
available_vectors = get_collection_vector_names(EXISTING_COLLECTION_NAME, client)
print("=" * 80)
print("COLLECTION CONFIGURATION CHECK")
print("=" * 80)

use_demo_collection = False
if available_vectors:
    print(f"✓ Found named vectors in '{EXISTING_COLLECTION_NAME}': {', '.join(available_vectors)}")
    COLLECTION_NAME = EXISTING_COLLECTION_NAME
    vector_names = available_vectors[:2]
    if len(vector_names) == 1:
        vector_names = [vector_names[0], vector_names[0]]
    weights = {name: 1.0 / len(vector_names) for name in vector_names}
else:
    print(f"⚠️  No named vectors in '{EXISTING_COLLECTION_NAME}'. Using demo collection.")
    print()
    if create_demo_collection(DEMO_COLLECTION_NAME, client, force_recreate=False):
        COLLECTION_NAME = DEMO_COLLECTION_NAME
        vector_names = ["title", "description"]
        weights = {"title": 0.6, "description": 0.4}
        use_demo_collection = True
        print("Demo collection ready. Running value demonstrations.\n")
    else:
        print("Failed to create demo collection. Exiting.")
        exit(1)

LIMIT = 5


def _name(payload):
    return payload.get("part_name", payload.get("name", "Unknown"))


def run_value_demo(query: str, title_hint: str, description_hint: str):
    """Run title-only, description-only, and multi-vector search; show misses and value."""
    title_results = single_vector_search(
        COLLECTION_NAME, query, vector_name="title", client=client, limit=LIMIT
    )
    desc_results = single_vector_search(
        COLLECTION_NAME, query, vector_name="description", client=client, limit=LIMIT
    )
    multi_results = multi_vector_search(
        COLLECTION_NAME, query, vector_names=vector_names, weights=weights, client=client, limit=LIMIT
    )

    title_ids = {r["id"] for r in title_results}
    desc_ids = {r["id"] for r in desc_results}

    # Items in description top but not in title top → "missed by title-only"
    missed_by_title = [r for r in desc_results if r["id"] not in title_ids]
    # Items in title top but not in description top → "missed by description-only"
    missed_by_desc = [r for r in title_results if r["id"] not in desc_ids]
    # Items in multi top 3 that weren't in both single-field top 3
    title_top3_ids = {r["id"] for r in title_results[:3]}
    desc_top3_ids = {r["id"] for r in desc_results[:3]}
    both_top3 = title_top3_ids & desc_top3_ids
    multi_only_top = [r for r in multi_results[:3] if r["id"] not in both_top3]

    print(f"Query: \"{query}\"")
    print("-" * 80)
    print("Title-only (top {}):".format(LIMIT))
    for i, r in enumerate(title_results, 1):
        print(f"  {i}. {_name(r['payload'])} (score: {r['score']:.4f})")
    print()
    print("Description-only (top {}):".format(LIMIT))
    for i, r in enumerate(desc_results, 1):
        print(f"  {i}. {_name(r['payload'])} (score: {r['score']:.4f})")
    print()
    print("Multi-vector / fused (top {}):".format(LIMIT))
    for i, r in enumerate(multi_results, 1):
        print(f"  {i}. {_name(r['payload'])} (fused: {r['score']:.4f})")
    print()

    if missed_by_title:
        print("Value of multi-vector:")
        print(f"  • Found by DESCRIPTION but not in title-only top {LIMIT}:")
        for r in missed_by_title[:3]:
            print(f"    - {_name(r['payload'])} (description score: {r['score']:.4f})")
        print(f"  → {title_hint}")
    if missed_by_desc:
        print(f"  • Found by TITLE but not in description-only top {LIMIT}:")
        for r in missed_by_desc[:3]:
            print(f"    - {_name(r['payload'])} (title score: {r['score']:.4f})")
        print(f"  → {description_hint}")
    if not missed_by_title and not missed_by_desc and multi_only_top:
        print("Value of multi-vector:")
        print("  • Multi-vector ranking surfaces the best overall match even when single-field rankings differ.")
    print()


# --- Example 1: Query where DESCRIPTION field shines ---
print("=" * 80)
print("EXAMPLE 1: Query Where DESCRIPTION Field Adds Value")
print("=" * 80)
print("Query: \"device that monitors exhaust gases\"")
print("Many relevant items describe exhaust monitoring in the description but not in the short title.")
print("Title-only search can miss them; description-only and multi-vector find them.\n")

run_value_demo(
    "device that monitors exhaust gases",
    title_hint="Title-only misses these because 'exhaust' is in the description, not the title.",
    description_hint="Description-only finds these; multi-vector combines both signals.",
)

# --- Example 2: Query where TITLE field shines ---
print("=" * 80)
print("EXAMPLE 2: Query Where TITLE Field Adds Value")
print("=" * 80)
print("Query: \"brake pad\"")
print("Products with 'brake pad' in the title are easy for title search; description may be generic.")
print("Title-only finds them; multi-vector keeps them at the top.\n")

run_value_demo(
    "brake pad",
    title_hint="Description-only may rank these lower; title has the exact phrase.",
    description_hint="Multi-vector keeps title matches at the top while still using description signal.",
)

# --- Example 3: Query that needs DESCRIPTION (short title) ---
print("=" * 80)
print("EXAMPLE 3: Query That Matches DESCRIPTION, Not Title")
print("=" * 80)
print("Query: \"device that measures air flow\"")
print("MAF Sensor has a short title ('MAF Sensor'); the phrase 'air flow' is in the description.")
print("Description-only finds it; title-only may miss or rank it lower.\n")

run_value_demo(
    "device that measures air flow",
    title_hint="Title 'MAF Sensor' doesn't contain 'air flow'; description does.",
    description_hint="Multi-vector finds this item by combining title and description.",
)

# --- Example 4: Multi-vector search only (summary) ---
print("=" * 80)
print("EXAMPLE 4: Multi-Vector Search (Single View)")
print("=" * 80)
print("One query, multi-vector result: combines title and description for best relevance.\n")

multi_only = multi_vector_search(
    collection_name=COLLECTION_NAME,
    query="engine sensor",
    vector_names=vector_names,
    weights=weights,
    client=client,
    limit=5,
)
display_multi_vector_results(
    multi_only,
    "engine sensor",
    show_fields=["part_name", "part_id", "category", "description"],
)

# --- Summary ---
print("\n" + "=" * 80)
print("SUMMARY: When Multi-Vector Search Adds Value")
print("=" * 80)
print("""
• Example 1: \"exhaust monitoring\" → Description field finds O2/exhaust items
  that title-only misses. Multi-vector includes them and ranks well.

• Example 2: \"brake pad\" → Title field finds brake pads; multi-vector
  keeps them at top while still using description.

• Example 3: \"measures air flow\" → Description finds MAF/air flow sensor
  (title is just \"MAF Sensor\"). Multi-vector combines both.

• Takeaway: Users search in different ways. Single-vector (title OR description)
  can miss relevant results. Multi-vector (title + description, fused) covers
  both short/keyword and detailed/contextual queries.
""")

if use_demo_collection:
    print("=" * 80)
    print("DEMO COLLECTION")
    print("=" * 80)
    print(f"Collection '{DEMO_COLLECTION_NAME}' is available for further runs.")
    print(f"To delete: cleanup_demo_collection('{DEMO_COLLECTION_NAME}', client)")
    print("To force refresh data: create_demo_collection('{DEMO_COLLECTION_NAME}', client, force_recreate=True)")