GPU-accelerated vector index build v1.3.3

Overview

Note: This capability was previously part of AIDB and has moved into a separate extension/product called PGPU. EDB open sourced this extension and the code is publicly available at https://github.com/EnterpriseDB/pgpu.

Building a vector index is a compute‑intensive process that can run for hours or days on very large tables. EDB Postgres AI – PGPU can use NVIDIA GPUs to accelerate vector index creation for the VectorChord vchordq index type.

Use GPU acceleration when creating indexes on large vector columns to significantly reduce build time.

Requirements

Before using GPU acceleration, ensure the environment meets these requirements:

• Supported OS: Ubuntu 24.04, Debian 12, RHEL 9.
• CPU architecture: x86_64.
• Supported NVIDIA GPU architectures: 8.9, 9.0, 10.0, 10.3, 12.0, 12.1 (includes L40S, L40, L20, L4, L2, H200, H100, GH200, B200, B100, GB20x, GB10 and other compatible models).
• NVIDIA GPU driver version 525 or newer installed and functional.
• NVIDIA CUDA runtime 12.9 or newer installed (at minimum libcublas and libcudart).
• VectorChord extension version 1.0.0 or newer available on the system (for the vchordq index type). This package is available in EDB repositories.

Installing the extension

Create the extension in the Postgres database:

CREATE EXTENSION pgpu;

Quick start example

The following example creates a table with a vector column, inserts sample data, and builds a GPU‑accelerated VectorChord index.

1. Create a test table:

   → WrapCopy

   CREATE TABLE test_10k_vecs (
     id        bigserial PRIMARY KEY,
     embedding vector(2000)
   );

   1. Insert sample vectors:

   → WrapCopy

   INSERT INTO test_10k_vecs (embedding)
   SELECT arr.embedding
   FROM generate_series(1, 10000) AS g(i)
   CROSS JOIN LATERAL (
     SELECT array_agg(((g.i - 1) * 3 + gs.j)::real)
     FROM generate_series(1, 2000) AS gs(j)
   ) AS arr(embedding);

2. Build the GPU‑accelerated index:

   → WrapCopy

   SELECT pgpu.create_vector_index_on_gpu(
     table_name      => 'public.test_10k_vecs',
     column_name     => 'embedding',
     cluster_count   => 10
   );

When the function completes, the table has a VectorChord vchordq index ready for use. The centroids that PGPU computed to support building the index are stored in public.test_10k_vecs_centroids. Use \d public.test_10k_vecs in psql to inspect the table and the index settings.

Function reference

The pgpu.create_vector_index_on_gpu() function runs the entire VectorChord index build on the GPU. It is analogous to CREATE INDEX for VectorChord.

Signature example with all parameters:

SELECT pgpu.create_vector_index_on_gpu(
  table_name        => 'public.test_10k_vecs',
  column_name       => 'embedding',
  cluster_count     => 10,
  sampling_factor   => 256,
  kmeans_iterations => 10,
  kmeans_nredo      => 1,
  distance_operator => 'ip',
  batch_size        => 1000000
);

Parameters:

• table_name: Fully qualified table name (schema.table).
• column_name: Name of the vector column to index.
• cluster_count: Number of clusters to use for the index (VectorChord “lists”).
• sampling_factor: Optional. Number of sample vectors for k‑means. Default: 256.
• kmeans_iterations: Optional. Number of k‑means iterations. Default: 10.
• kmeans_nredo: Optional. Number of k‑means restarts. Default: 1.
• distance_operator: Optional. Distance metric. One of ip (inner product), l2 (Euclidean), or cos (cosine). Default: ip.
• batch_size: Optional. Controls processing batch size. Larger batches increase memory use but can improve throughput.

Verification

After the function returns, verify that the index exists and is usable.

1. List indexes on the table:

   → WrapCopy

   SELECT indexname, indexdef
   FROM pg_indexes
   WHERE schemaname = 'public' AND tablename = 'test_10k_vecs';

2. Run an example query with your intended distance operator and use EXPLAIN to confirm index usage.

Verify index usage with EXPLAIN

Replace :query_vec with a query vector literal or parameter of the same dimension as your column. Choose the operator that matches the distance_operator you used for index creation.

• L2 distance (l2):

EXPLAIN
SELECT id
FROM test_10k_vecs
ORDER BY embedding <-> :query_vec
LIMIT 10;

• Inner product (ip):

EXPLAIN
SELECT id
FROM test_10k_vecs
ORDER BY embedding <#> :query_vec
LIMIT 10;

• Cosine distance (cos):

EXPLAIN
SELECT id
FROM test_10k_vecs
ORDER BY embedding <=> :query_vec
LIMIT 10;

The plan should indicate an index‑assisted path (for example, Index Scan) rather than a full sequential scan. If needed for testing, temporarily set SET enable_seqscan = off; to encourage index usage while validating.

For details on vector distance operators <-> (L2), <#> (inner product), and <=> (cosine), see the Vector Engine documentation.

Tuning and guidance

• Cluster count: Choose a value appropriate for your data size and query patterns, following VectorChord guidance for the number of lists.
• Batch size: Increase for faster builds when sufficient GPU memory is available; reduce if you encounter out‑of‑memory conditions.
• Distance operator: Match to how you plan to query the data (ip, l2, or cos).

Troubleshooting

• No compatible GPU detected: Verify NVIDIA drivers and CUDA runtime installation.

• Missing VectorChord components: Ensure the VectorChord extension and its index type are installed on the node.

• Invalid arguments: Confirm the vector column exists, has a fixed dimension, and the table name is fully qualified.

• Debugging: PGPU logs debug info at Postgres debug levels 1 and 2. For more detail, SET client_min_messages TO debug2;.

Notes and limitations

• GPU acceleration currently applies to VectorChord vchordq index builds.
• Supported hardware and OS are limited to the platforms listed in Requirements.
• The function runs synchronously and returns when the index build completes or fails.