VertexAIMatchingEngine class

A vector store that uses Vertex AI Vector Search (former Vertex AI Matching Engine).

Vertex AI Vector Search provides a high-scale low latency vector database.

This vector stores relies on two GCP services:

Vertex AI Matching Engine: to store the vectors and perform similarity searches.
Google Cloud Storage: to store the documents and the vectors to add to the index.

Vertex AI Matching Engine documentation: https://cloud.google.com/vertex-ai/docs/matching-engine/overview

Currently it only supports Batch Updates, it doesn't support Streaming Updates. Batch Updates take around 1h to be applied to the index. See: https://cloud.google.com/vertex-ai/docs/matching-engine/update-rebuild-index#update_index_content_with_batch_updates

Set up your Google Cloud Platform project

Create your Vertex AI Vector Search index

To use this vector store, first you need to create a Vertex AI Vector Search index and expose it in a Vertex AI index endpoint.

You can use vertex_ai Dart package to do that.

Check out this sample script that creates the index and index endpoint ready to be used with LangChains.dart: https://github.com/davidmigloz/langchain_dart/tree/main/examples/vertex_ai_matching_engine_setup

Authentication

To create an instance of VertexAIMatchingEngine you need to provide an HTTP client that handles authentication. The easiest way to do this is to use AuthClient from the googleapis_auth package.

There are several ways to obtain an AuthClient depending on your use case. Check out the googleapis_auth package documentation for more details.

Example using a service account JSON:

final serviceAccountCredentials = ServiceAccountCredentials.fromJson(
  json.decode(serviceAccountJson),
);
final authClient = await clientViaServiceAccount(
  serviceAccountCredentials,
  VertexAIMatchingEngine.cloudPlatformScopes,
);
final vectorStore = VertexAIMatchingEngine(
  httpClient: authClient,
  project: 'your-project-id',
  location: 'europe-west1',
  indexId: 'your-index-id',
  gcsBucketName: 'your-gcs-bucket-name',
  embeddings: embeddings,
);

The minimum required permissions for the service account if you just need to query the index are:

aiplatform.indexes.get
aiplatform.indexEndpoints.get
aiplatform.indexEndpoints.queryVectors
storage.objects.get

If you also need to add new vectors to the index, the service account should have the following permissions as well:

aiplatform.indexes.update
storage.objects.create
storage.objects.update

The requiredOAuth2 scope is:

https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/devstorage.full_control

You can use the constant VertexAIMatchingEngine.cloudPlatformScopes.

Vector attributes filtering

Vertex AI Matching Engine allows you to add attributes to the vectors that you can later use to restrict vector matching searches to a subset of the index.

To add attributes to the vectors, add a restricts key to the document metadata with the attributes that you want to add. For example:

final doc = Document(
 id: 'doc1',
 pageContent: 'The cat is a domestic species of small carnivorous mammal',
 metadata: {
   'restricts': [
     {
       'namespace': 'class',
       'allow': ['cat', 'pet']
     },
     {
       'namespace': 'category',
       'allow': ['feline']
     }
   ],
   'otherMetadata': '...',
 },
);

Check out the documentation for more details: https://cloud.google.com/vertex-ai/docs/matching-engine/filtering

After adding the attributes to the documents, you can use the use them to restrict the similarity search results. Example:

final vectorStore = VertexAIMatchingEngine(...);
final res = await vectorStore.similaritySearch(
  query: 'What should I feed my cat?',
  config: VertexAIMatchingEngineSimilaritySearch(
    k: 5,
    scoreThreshold: 0.8,
    filters: [
      const VertexAIMatchingEngineFilter(
        namespace: 'class',
        allowList: ['cat'],
      ),
    ],
  ),
);

Constructors

VertexAIMatchingEngine.new({required Client httpClient, required String project, required String location, String? rootUrl, String? queryRootUrl, required String indexId, String? indexEndpointId, String? deployedIndexId, required String gcsBucketName, String gcsDocumentsFolder = 'documents', String gcsIndexesFolder = 'indexes', bool completeOverwriteWhenAdding = false, required Embeddings embeddings}): Creates a new Vertex AI Matching Engine vector store.

Properties

completeOverwriteWhenAdding → bool: If true, when new vectors are added to the index, the previous ones are deleted. If false, the new vectors are added to the index without deleting the previous ones.
final
embeddings → Embeddings: The embeddings model used to embed documents.
finalinherited
gcsBucketName → String: The Google Cloud Storage bucket to use.
final
gcsDocumentsFolder → String: The folder in the Google Cloud Storage bucket where the documents are stored.
final
gcsIndexesFolder → String: The folder in the Google Cloud Storage bucket where the vectors to add to the index are stored.
final
hashCode → int: The hash code for this object.
no setterinherited
indexId → String: The id of the index to use.
final
location → String: The Google Cloud location to use. Vertex AI and Cloud Storage should have the same location.
final
project → String: The ID of the Google Cloud project to use.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

addDocuments({required List<Document> documents}) → Future<List<String>>: Runs more documents through the embeddings and add to the vector store.
inherited
addVectors({required List<List<double>> vectors, required List<Document> documents}) → Future<List<String>>: Runs more texts through the embeddings and add to the vector store.
asRetriever({VectorStoreRetrieverOptions defaultOptions = const VectorStoreRetrieverOptions()}) → VectorStoreRetriever<VectorStore>: Returns a VectorStoreRetriever that uses this vector store.
inherited
delete({required List<String> ids}) → Future<void>: Delete by vector ID.
maxMarginalRelevanceSearch({required String query, VectorStoreMMRSearch config = const VectorStoreMMRSearch()}) → Future<List<Document>>: Returns docs selected using the maximal marginal relevance algorithm (MMR) for the given query.
inherited
maxMarginalRelevanceSearchByVector({required List<double> embedding, VectorStoreMMRSearch config = const VectorStoreMMRSearch()}) → List<Document>: Returns docs selected using the maximal marginal relevance algorithm (MMR) for the given embedding vector.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
search({required String query, required VectorStoreSearchType searchType}) → Future<List<Document>>: Returns docs most similar to query using specified search type.
inherited
similaritySearch({required String query, VectorStoreSimilaritySearch config = const VectorStoreSimilaritySearch()}) → Future<List<Document>>: Returns docs most similar to query using similarity.
inherited
similaritySearchByVector({required List<double> embedding, VectorStoreSimilaritySearch config = const VectorStoreSimilaritySearch()}) → Future<List<Document>>: Returns docs most similar to embedding vector using similarity.
inherited
similaritySearchByVectorWithScores({required List<double> embedding, VectorStoreSimilaritySearch config = const VectorStoreSimilaritySearch()}) → Future<List<(Document, double)>>: Returns docs and relevance scores in the range [0, 1], 0 is dissimilar, 1 is most similar.
similaritySearchWithScores({required String query, VectorStoreSimilaritySearch config = const VectorStoreSimilaritySearch()}) → Future<List<(Document, double)>>: Returns docs and relevance scores in the range [0, 1]. 0 is dissimilar, 1 is most similar.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Constants

cloudPlatformScopes → const List<String>: Scopes required for Vertex AI and Cloud Storage API calls.