Generative AI Google Brain

embeddings-vector-search-quickstart

3 min read

Agent Platform Vector Search Quickstart

Source notebook

Repo path: embeddings/vector-search-quickstart.ipynb · Open on GitHub · intermediate

Builds and queries a streaming-update Vector Search index from product embeddings.

Summary

This notebook shows how to create an Agent Platform Vector Search index, deploy it to a public index endpoint, stream product embeddings into the index, and query nearest neighbors. It uses a precomputed JSONL file of TheLook product-name embeddings, upserts datapoints in batches, runs a semantic product similarity query, and then deletes the index resources to avoid costs.

Key code patterns

Initialize aiplatform

from google.cloud import aiplatform
 
aiplatform.init(project=PROJECT_ID, location=LOCATION)

Sets the project and region before creating Vector Search resources.

Create stream-update index

my_index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
    display_name=INDEX_NAME,
    dimensions=768,
    approximate_neighbors_count=10,
    index_update_method="STREAM_UPDATE",
)

Creates a 768-dimensional index that supports near real-time datapoint updates.

Deploy index endpoint

my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint.create(
    display_name=f"vs-quickstart-index-endpoint-{UID}",
    public_endpoint_enabled=True,
)
my_index_endpoint.deploy_index(
    index=my_index,
    deployed_index_id=DEPLOYED_INDEX_ID,
)

Creates a public IAM-secured endpoint and deploys the index for querying.

Batch upsert datapoints

for i in range(0, len(datapoints), 1000):
    my_index.upsert_datapoints(
        datapoints=datapoints[i : i + 1000]
    )

Uses the documented 1000-item batch limit for streaming updates.

Find nearest neighbors

response = my_index_endpoint.find_neighbors(
    deployed_index_id=DEPLOYED_INDEX_ID,
    queries=[query_emb],
    num_neighbors=10,
)

Queries the deployed index with an embedding to retrieve similar products.

Models & APIs used

  • APIs / services: Vertex AI, Compute Engine, Cloud Storage, Agent Platform Vector Search, Agent Platform Embeddings for Text, Agent Platform Workbench
  • SDKs / libraries: google-cloud-aiplatform

When to use this

Use this pattern when building semantic search or recommendation features over embeddings that need near real-time updates.

Gotchas & caveats

  • A Google Cloud project linked to billing is required.
  • The default compute service account needs Agent Platform User and Service Usage Admin roles.
  • Colab requires explicit user authentication; Workbench is pre-authenticated.
  • Compute Engine and aiplatform APIs must be enabled.
  • Index creation can take minutes or about 60 minutes or more depending on dataset size.
  • First index deployment to an endpoint can take around 30 minutes.
  • DEPLOYED_INDEX_ID only allows underscores, while INDEX_NAME may include dashes.
  • upsert_datapoints accepts up to 1000 items at a time.
  • Undeleted indexes, index endpoints, and Workbench instances can incur unexpected costs.

Best practices

  • Use STREAM_UPDATE when product catalog changes should appear in search results quickly.
  • Use a public endpoint unless there is a specific VPC requirement; it is IAM-secured by default.
  • Batch streaming upserts in chunks of 1000 datapoints.
  • Reuse existing indexes and endpoints if a Colab runtime disconnects during long operations.
  • Delete index endpoints and indexes after the tutorial to avoid unexpected costs.

Graph View

Backlinks