Description

This PR adds support for Vertex AI Vector Search v2.0 (collection-based architecture) while maintaining 100% backward compatibility with v1.0 (index/endpoint architecture).

Summary of Changes

• Routing Infrastructure: Added api_version parameter (default: "v1") that routes operations to v1 or v2 implementations
• V2 Operations: New _v2_operations.py with all CRUD operations using google-cloud-vectorsearch SDK
• Parameter Validation: v1 requires index_id/endpoint_id, v2 requires collection_id
• Lazy Loading: V2 SDK only loaded when v2 is used (zero impact on v1 users)
• Feature Flag: VERTEX_AI_ENABLE_V2 environment variable for safe rollback
• Retry Logic: Added retry decorator with exponential backoff for v2 operations
• Documentation: Added migration guide and v2 demo notebook

Dependencies

New optional dependency added:

• google-cloud-vectorsearch>=0.1.0 (only required for v2, installed via pip install 'llama-index-vector-stores-vertexaivectorsearch[v2]')

Fixes #

New Package?

Did I fill in the tool.llamahub section in the pyproject.toml and provide a detailed README.md for my new integration or package?

• Yes
• No

(This is not a new package - it's an update to the existing llama-index-vector-stores-vertexaivectorsearch package. The tool.llamahub section already existed. We updated pyproject.toml to add the [v2] optional dependency.)

Version Bump?

Did I bump the version in the pyproject.toml file of the package I am updating? (Except for the llama-index-core package)

• Yes
• No

(Version remains at 0.3.2. Only added [project.optional-dependencies] section for v2 SDK. Maintainers may want to bump version as part of merge.)

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

• I added new unit tests to cover this change
• I believe this change is already covered by existing unit tests

Test Details

• 23 new unit tests added for v2 functionality:

  • TestV2ParameterValidation (7 tests): Validates v2 requires collection_id, rejects v1 params
  • TestV2Routing (5 tests): Verifies correct routing based on api_version
  • TestV2SDKImport (2 tests): Tests lazy loading of v2 SDK
  • TestV2FeatureFlags (3 tests): Tests VERTEX_AI_ENABLE_V2 environment variable
  • TestV2SDKManager (3 tests): Tests SDK manager v2 client initialization
  • TestV2RetryDecorator (3 tests): Tests retry logic with exponential backoff

• All existing v1 tests pass (backward compatibility verified)

• V1 integration test passes

• V2 integration test passes

• V2 demo notebook tested (VertexAIVectorSearchV2Demo.ipynb) - verified collection creation, document insertion, querying, and metadata filtering work end-to-end

Suggested Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added Google Colab support for the newly added notebooks.
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I ran uv run make format; uv run make lint to appease the lint gods

Files Changed

Usage Examples

# V1 (default - unchanged)
vector_store = VertexAIVectorStore(
    project_id="my-project",
    region="us-central1",
    index_id="projects/.../indexes/123",
    endpoint_id="projects/.../indexEndpoints/456"
)

# V2 (opt-in)
vector_store = VertexAIVectorStore(
    api_version="v2",
    project_id="my-project",
    region="us-central1",
    collection_id="my-collection"
)

Installation

# V1 only (default)
pip install llama-index-vector-stores-vertexaivectorsearch

# V1 + V2 support
pip install 'llama-index-vector-stores-vertexaivectorsearch[v2]'

V1 vs V2 Comparison

Related Documentation

• Vertex AI Vector Search v2 Overview
• V2_MIGRATION.md - Migration guide
• VertexAIVectorSearchV2Demo.ipynb - Demo notebook