Skip to content

feat(PGVector): add support for IVFFlat vector index for ANN search in PGVector #4772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
franciscojavierarceo merged 1 commit into from
Jan 29, 2026
Merged

feat(PGVector): add support for IVFFlat vector index for ANN search in PGVector #4772

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 34 additions & 2 deletions docs/docs/providers/vector_io/remote_pgvector.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,15 +82,29 @@ description: |
```

2. Pull pgvector image with that tag you want:

Via Podman:
```bash
podman pull pgvector/pgvector:0.8.1-pg18-trixie
```

Via Docker:
```bash
docker pull pgvector/pgvector:0.8.1-pg18-trixie
Copy link
Contributor

@nathan-weinberg nathan-weinberg Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason we are pulling this particular tag for the pgvector container?

Copy link
Contributor Author

@r3v5 r3v5 Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @nathan-weinberg ! No, there is no particular reason. As far as I understand it’s simply the latest image of pgvector available. That’s why I chose it and used.

Copy link
Contributor

@nathan-weinberg nathan-weinberg Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm yeah, weird they don't have some latest image: https://hub.docker.com/r/pgvector/pgvector/tags

Fine from my side in this case then - thanks!

```

3. Run container with PGVector:

Via Podman
```bash
podman run -d --name pgvector -e POSTGRES_PASSWORD=password -e POSTGRES_USER=user -e POSTGRES_DB=testvectordb -p 5432:5432 -v pgvector_data:/var/lib/postgresql pgvector/pgvector:0.8.1-pg18-trixie
```

Via Docker
```bash
docker run -d --name pgvector -e POSTGRES_PASSWORD=password -e POSTGRES_USER=user -e POSTGRES_DB=testvectordb -p 5432:5432 -v pgvector_data:/var/lib/postgresql pgvector/pgvector:0.8.1-pg18-trixie
```

## Documentation
See [PGVector's documentation](https://github.com/pgvector/pgvector) for more details about PGVector in general.
sidebar_label: Remote - Pgvector
Expand Down Expand Up @@ -184,15 +198,29 @@ export PGVECTOR_PASSWORD=password
```

2. Pull pgvector image with that tag you want:

Via Podman:
```bash
podman pull pgvector/pgvector:0.8.1-pg18-trixie
```

Via Docker:
```bash
docker pull pgvector/pgvector:0.8.1-pg18-trixie
```

3. Run container with PGVector:

Via Podman
```bash
podman run -d --name pgvector -e POSTGRES_PASSWORD=password -e POSTGRES_USER=user -e POSTGRES_DB=testvectordb -p 5432:5432 -v pgvector_data:/var/lib/postgresql pgvector/pgvector:0.8.1-pg18-trixie
```

Via Docker
```bash
docker run -d --name pgvector -e POSTGRES_PASSWORD=password -e POSTGRES_USER=user -e POSTGRES_DB=testvectordb -p 5432:5432 -v pgvector_data:/var/lib/postgresql pgvector/pgvector:0.8.1-pg18-trixie
```

## Documentation
See [PGVector's documentation](https://github.com/pgvector/pgvector) for more details about PGVector in general.

Expand All @@ -207,8 +235,7 @@ See [PGVector's documentation](https://github.com/pgvector/pgvector) for more de
| `user` | `str \| None` | No | postgres | |
| `password` | `str \| None` | No | mysecretpassword | |
| `distance_metric` | `Literal[COSINE, L2, L1, INNER_PRODUCT] \| None` | No | COSINE | PGVector distance metric used for vector search in PGVectorIndex |
| `hnsw_m` | `int \| None` | No | 16 | PGVector's HNSW index parameter - maximum number of edges each vertex has to its neighboring vertices in the graph |
| `hnsw_ef_construction` | `int \| None` | No | 64 | PGVector's HNSW index parameter - size of the dynamic candidate list used for graph construction |
| `vector_index` | `PGVectorHNSWVectorIndex \| PGVectorIVFFlatVectorIndex \| None` | No | type=<PGVectorIndexType.HNSW: 'HNSW'> m=16 ef_construction=64 | PGVector vector index used for Approximate Nearest Neighbor (ANN) search |
| `persistence` | `KVStoreReference \| None` | No | | Config for KV store backend (SQLite only for now) |

## Sample Configuration
Expand All @@ -219,6 +246,11 @@ port: ${env.PGVECTOR_PORT:=5432}
db: ${env.PGVECTOR_DB}
user: ${env.PGVECTOR_USER}
password: ${env.PGVECTOR_PASSWORD}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
5 changes: 5 additions & 0 deletions src/llama_stack/distributions/ci-tests/config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ providers:
db: ${env.PGVECTOR_DB:=}
user: ${env.PGVECTOR_USER:=}
password: ${env.PGVECTOR_PASSWORD:=}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
5 changes: 5 additions & 0 deletions src/llama_stack/distributions/ci-tests/run-with-postgres-store.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ providers:
db: ${env.PGVECTOR_DB:=}
user: ${env.PGVECTOR_USER:=}
password: ${env.PGVECTOR_PASSWORD:=}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
5 changes: 5 additions & 0 deletions src/llama_stack/distributions/open-benchmark/config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,11 @@ providers:
db: ${env.PGVECTOR_DB:=}
user: ${env.PGVECTOR_USER:=}
password: ${env.PGVECTOR_PASSWORD:=}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
5 changes: 5 additions & 0 deletions src/llama_stack/distributions/starter-gpu/config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ providers:
db: ${env.PGVECTOR_DB:=}
user: ${env.PGVECTOR_USER:=}
password: ${env.PGVECTOR_PASSWORD:=}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
5 changes: 5 additions & 0 deletions src/llama_stack/distributions/starter-gpu/run-with-postgres-store.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ providers:
db: ${env.PGVECTOR_DB:=}
user: ${env.PGVECTOR_USER:=}
password: ${env.PGVECTOR_PASSWORD:=}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
5 changes: 5 additions & 0 deletions src/llama_stack/distributions/starter/config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ providers:
db: ${env.PGVECTOR_DB:=}
user: ${env.PGVECTOR_USER:=}
password: ${env.PGVECTOR_PASSWORD:=}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
5 changes: 5 additions & 0 deletions src/llama_stack/distributions/starter/run-with-postgres-store.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ providers:
db: ${env.PGVECTOR_DB:=}
user: ${env.PGVECTOR_USER:=}
password: ${env.PGVECTOR_PASSWORD:=}
distance_metric: COSINE
vector_index:
type: HNSW
m: 16
ef_construction: 64
persistence:
namespace: vector_io::pgvector
backend: kv_default
Expand Down
21 changes: 21 additions & 0 deletions src/llama_stack/providers/registry/vector_io.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -480,11 +480,20 @@ def available_providers() -> list[ProviderSpec]:
```
2. Pull pgvector image with that tag you want:
Via Podman:
```bash
podman pull pgvector/pgvector:0.8.1-pg18-trixie
```
Via Docker:
```bash
docker pull pgvector/pgvector:0.8.1-pg18-trixie
```
3. Run container with PGVector:
Via Podman
```bash
podman run -d \
--name pgvector \
Expand All @@ -496,6 +505,18 @@ def available_providers() -> list[ProviderSpec]:
pgvector/pgvector:0.8.1-pg18-trixie
```
Via Docker
```bash
docker run -d \
--name pgvector \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_USER=user \
-e POSTGRES_DB=testvectordb \
-p 5432:5432 \
-v pgvector_data:/var/lib/postgresql \
pgvector/pgvector:0.8.1-pg18-trixie
```
## Documentation
See [PGVector's documentation](https://github.com/pgvector/pgvector) for more details about PGVector in general.
""",
Expand Down
76 changes: 65 additions & 11 deletions src/llama_stack/providers/remote/vector_io/pgvector/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,70 @@
# This source code is licensed under the terms described in the LICENSE file in
# the root directory of this source tree.

from typing import Any, Literal
from enum import StrEnum
from typing import Annotated, Any, Literal, Self

from pydantic import BaseModel, Field
from pydantic import BaseModel, Field, model_validator

from llama_stack.core.storage.datatypes import KVStoreReference
from llama_stack_api import json_schema_type


class PGVectorIndexType(StrEnum):
"""Supported pgvector vector index types in Llama Stack."""

HNSW = "HNSW"
IVFFlat = "IVFFlat"


class PGVectorHNSWVectorIndex(BaseModel):
"""Configuration for PGVector HNSW (Hierarchical Navigable Small Worlds) vector index.
https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw
"""

type: Literal[PGVectorIndexType.HNSW] = PGVectorIndexType.HNSW
m: int | None = Field(
gt=0,
default=16,
description="PGVector's HNSW index parameter - maximum number of edges each vertex has to its neighboring vertices in the graph",
)
ef_construction: int | None = Field(
gt=0,
default=64,
description="PGVector's HNSW index parameter - size of the dynamic candidate list used for graph construction",
)


class PGVectorIVFFlatVectorIndex(BaseModel):
"""Configuration for PGVector IVFFlat (Inverted File with Flat Compression) vector index.
https://github.com/pgvector/pgvector?tab=readme-ov-file#ivfflat
"""

type: Literal[PGVectorIndexType.IVFFlat] = PGVectorIndexType.IVFFlat
lists: int | None = Field(
gt=0, default=100, description="PGVector's IVFFlat index parameter - number of lists index divides vectors into"
)
probes: int | None = Field(
gt=0,
default=10,
description="PGVector's IVFFlat index parameter - number of lists index searches through during ANN search",
)

@model_validator(mode="after")
def validate_probes(self) -> Self:
if self.probes >= self.lists:
raise ValueError(
"probes parameter for PGVector IVFFlat index can't be greater than or equal to the number of lists in the index to allow ANN search."
)
return self


PGVectorIndexConfig = Annotated[
PGVectorHNSWVectorIndex | PGVectorIVFFlatVectorIndex,
Field(discriminator="type"),
]


@json_schema_type
class PGVectorVectorIOConfig(BaseModel):
host: str | None = Field(default="localhost")
Expand All @@ -22,15 +78,9 @@ class PGVectorVectorIOConfig(BaseModel):
distance_metric: Literal["COSINE", "L2", "L1", "INNER_PRODUCT"] | None = Field(
default="COSINE", description="PGVector distance metric used for vector search in PGVectorIndex"
)
hnsw_m: int | None = Field(
gt=0,
default=16,
description="PGVector's HNSW index parameter - maximum number of edges each vertex has to its neighboring vertices in the graph",
)
hnsw_ef_construction: int | None = Field(
gt=0,
default=64,
description="PGVector's HNSW index parameter - size of the dynamic candidate list used for graph construction",
vector_index: PGVectorIndexConfig | None = Field(
default_factory=PGVectorHNSWVectorIndex,
description="PGVector vector index used for Approximate Nearest Neighbor (ANN) search",
)
persistence: KVStoreReference | None = Field(
description="Config for KV store backend (SQLite only for now)", default=None
Expand All @@ -53,6 +103,10 @@ def sample_run_config(
"db": db,
"user": user,
"password": password,
"distance_metric": "COSINE",
"vector_index": PGVectorHNSWVectorIndex(m=16, ef_construction=64).model_dump(
mode="json", exclude_none=True
),
"persistence": KVStoreReference(
backend="kv_default",
namespace="vector_io::pgvector",
Expand Down
Loading
Loading