llama-index-vector-stores-vertexaivectorsearch 0.4.0

llama-index vector_stores Vertex AI Vector Search integration

LlamaIndex Vector Stores Integration: Vertex AI Vector Search

Vertex AI Vector Search is a fully managed, highly scalable vector similarity search service on Google Cloud.

Overview

This integration supports both Vertex AI Vector Search architectures:

• v1.0 (default): Index + Endpoint architecture
• v2.0 (opt-in): Collection-based architecture (simpler setup, more features)

The v2.0 support is opt-in and maintains 100% backward compatibility with existing v1.0 code.

Installation

Basic Installation (v1 only)

pip install llama-index-vector-stores-vertexaivectorsearch

With v2 Support

pip install 'llama-index-vector-stores-vertexaivectorsearch[v2]'

Quick Start

v1.0 (Default)

from llama_index.vector_stores.vertexaivectorsearch import VertexAIVectorStore

vector_store = VertexAIVectorStore(
    project_id="my-project",
    region="us-central1",
    index_id="projects/.../indexes/123",
    endpoint_id="projects/.../indexEndpoints/456",
    gcs_bucket_name="my-staging-bucket",  # Required for batch updates
)

v2.0 (New - Simpler Setup)

from llama_index.vector_stores.vertexaivectorsearch import VertexAIVectorStore

vector_store = VertexAIVectorStore(
    api_version="v2",  # Opt-in to v2
    project_id="my-project",
    region="us-central1",
    collection_id="my-collection",
    # No GCS bucket needed!
)

Usage with LlamaIndex

from llama_index.core import VectorStoreIndex, StorageContext, Document
from llama_index.vector_stores.vertexaivectorsearch import VertexAIVectorStore

# Create vector store (v1 or v2)
vector_store = VertexAIVectorStore(
    api_version="v2",
    project_id="my-project",
    region="us-central1",
    collection_id="my-collection",
)

# Create storage context
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# Build index from documents
index = VectorStoreIndex.from_documents(
    documents, storage_context=storage_context
)

# Query
query_engine = index.as_query_engine()
response = query_engine.query("What is LlamaIndex?")

v1 vs v2 Comparison

Feature	v1	v2
Required Resources	Index + Endpoint	Collection only
GCS Bucket	Required for batch	Not needed
clear() method	Not supported	Supported
Setup Complexity	Higher	Lower

Parameters

v1 Parameters

• project_id: Google Cloud project ID
• region: Google Cloud region
• index_id: Vertex AI index resource name
• endpoint_id: Vertex AI endpoint resource name
• gcs_bucket_name: GCS bucket for batch updates

v2 Parameters

• api_version: Set to "v2"
• project_id: Google Cloud project ID
• region: Google Cloud region
• collection_id: Vertex AI collection name

Hybrid Search (V2 Only)

V2 supports hybrid search, combining vector similarity with text-based search for improved retrieval quality.

Enable Hybrid Search

from llama_index.vector_stores.vertexaivectorsearch import VertexAIVectorStore

vector_store = VertexAIVectorStore(
    api_version="v2",
    project_id="my-project",
    region="us-central1",
    collection_id="my-collection",
    enable_hybrid=True,
    text_search_fields=["title", "content"],  # Fields for text search
)

Query Modes

from llama_index.core.vector_stores.types import (
    VectorStoreQuery,
    VectorStoreQueryMode,
)

# DEFAULT: Vector similarity search only
query = VectorStoreQuery(
    query_embedding=embedding,
    mode=VectorStoreQueryMode.DEFAULT,
)

# TEXT_SEARCH: Full-text keyword search only
query = VectorStoreQuery(
    query_str="search terms",
    mode=VectorStoreQueryMode.TEXT_SEARCH,
)

# HYBRID: Vector + Text search combined with RRF
query = VectorStoreQuery(
    query_embedding=embedding,
    query_str="search terms",
    mode=VectorStoreQueryMode.HYBRID,
    alpha=0.5,  # 0=text only, 1=vector only
)

# SEMANTIC_HYBRID: Vector + Semantic search
query = VectorStoreQuery(
    query_embedding=embedding,
    query_str="search terms",
    mode=VectorStoreQueryMode.SEMANTIC_HYBRID,
)

Ranker Options

Two ranker options are available for combining search results:

# RRF (default) - uses alpha for weighting
vector_store = VertexAIVectorStore(
    ...,
    hybrid_ranker="rrf",
    default_hybrid_alpha=0.5,  # 0=text only, 1=vector only
)

# VertexRanker - AI-powered semantic ranking
vector_store = VertexAIVectorStore(
    ...,
    hybrid_ranker="vertex",
    vertex_ranker_model="semantic-ranker-default@latest",
    vertex_ranker_title_field="title",
    vertex_ranker_content_field="content",
)

Hybrid Search Parameters

Parameter	Type	Default	Description
enable_hybrid	bool	False	Enable hybrid search modes
text_search_fields	List[str]	None	Data fields for TextSearch
embedding_field	str	"embedding"	Vector field name in collection
default_hybrid_alpha	float	0.5	Default RRF weight (0=text, 1=vector)
hybrid_ranker	str	"rrf"	Ranker type: "rrf" or "vertex"
semantic_task_type	str	"RETRIEVAL_QUERY"	Task type for SemanticSearch
vertex_ranker_model	str	"semantic-ranker-default@latest"	VertexRanker model ID
vertex_ranker_title_field	str	None	Field for VertexRanker title
vertex_ranker_content_field	str	None	Field for VertexRanker content

For a complete working example with hybrid search, see the v2 example notebook.

Documentation

• v1.0 Usage: See the v1 example notebook
• v2.0 Usage: See the v2 example notebook
• v2.0 Migration: See V2_MIGRATION.md for detailed migration guide
• API Reference: See the Google Cloud Documentation