Skip to content

armgit / txtai

Public Imported from GitHub
0

💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows

Add pgvector ANN backend, closes #698

davidmezzettie24f4bc21d3e
diff --git a/setup.py b/setup.py
index 6af420f6..1714bf8d 100644
--- a/setup.py
+++ b/setup.py
@@ -30,6 +30,8 @@ extras["dev"] = [
extras["ann"] = [
"annoy>=1.16.3",
"hnswlib>=0.5.0",
+ "pgvector>=0.2.5",
+ "sqlalchemy>=2.0.20",
]
extras["api"] = [
@@ -47,7 +49,7 @@ extras["console"] = ["rich>=12.0.1"]
extras["database"] = ["duckdb>=0.7.1", "pillow>=7.1.2", "sqlalchemy>=2.0.20"]
-extras["graph"] = ["grand-cypher>=0.6.0", "networkx>=2.6.3", "python-louvain>=0.16"]
+extras["graph"] = ["grand-cypher>=0.6.0", "grand-graph>=0.5.0", "networkx>=2.6.3", "python-louvain>=0.16", "sqlalchemy>=2.0.20"]
extras["model"] = ["onnx>=1.11.0", "onnxruntime>=1.11.0"]
@@ -97,6 +99,7 @@ extras["workflow"] = [
"xmltodict>=0.12.0",
]
+# Backwards-compatible combination of ann and vectors extra
extras["similarity"] = extras["ann"] + extras["vectors"]
extras["all"] = (
diff --git a/src/python/txtai/ann/__init__.py b/src/python/txtai/ann/__init__.py
index cb46a789..ad25b6f3 100644
--- a/src/python/txtai/ann/__init__.py
+++ b/src/python/txtai/ann/__init__.py
@@ -8,4 +8,5 @@ from .factory import ANNFactory
from .faiss import Faiss
from .hnsw import HNSW
from .numpy import NumPy
+from .pgvector import PGVector
from .torch import Torch
diff --git a/src/python/txtai/ann/factory.py b/src/python/txtai/ann/factory.py
index 23fe5af9..d934cb76 100644
--- a/src/python/txtai/ann/factory.py
+++ b/src/python/txtai/ann/factory.py
@@ -8,6 +8,7 @@ from .annoy import Annoy
from .faiss import Faiss
from .hnsw import HNSW
from .numpy import NumPy
+from .pgvector import PGVector
from .torch import Torch
@@ -41,6 +42,8 @@ class ANNFactory:
ann = HNSW(config)
elif backend == "numpy":
ann = NumPy(config)
+ elif backend == "pgvector":
+ ann = PGVector(config)
elif backend == "torch":
ann = Torch(config)
else:
diff --git a/src/python/txtai/ann/pgvector.py b/src/python/txtai/ann/pgvector.py
new file mode 100644
index 00000000..661d04f8
--- /dev/null
+++ b/src/python/txtai/ann/pgvector.py
@@ -0,0 +1,127 @@
+"""
+PGVector module
+"""
+
+import os
+
+# Conditional import
+try:
+ from pgvector.sqlalchemy import Vector
+
+ from sqlalchemy import create_engine, delete, text, Column, Index, Integer, MetaData, StaticPool, Table
+ from sqlalchemy.orm import Session
+
+ PGVECTOR = True
+except ImportError:
+ PGVECTOR = False
+
+from .base import ANN
+
+
+class PGVector(ANN):
+ """
+ Builds an ANN index backed by a Postgres database.
+ """
+
+ def __init__(self, config):
+ super().__init__(config)
+
+ if not PGVECTOR:
+ raise ImportError('PGVector is not available - install "ann" extra to enable')
+
+ # Create engine
+ self.engine = create_engine(self.setting("url", os.environ.get("ANN_URL")), poolclass=StaticPool, echo=False)
+
+ # Initialize pgvector extension
+ self.database = Session(self.engine)
+ self.database.execute(text("CREATE EXTENSION IF NOT EXISTS vector" if self.engine.dialect.name == "postgresql" else "SELECT 1"))
+ self.database.commit()
+
+ # Table instance
+ self.table = None
+
+ def __del__(self):
+ if self.database:
+ self.database.close()
+
+ def load(self, path):
+ # Reset database to original checkpoint
+ self.database.rollback()
+
+ # Initialize tables
+ self.initialize()
+
+ def index(self, embeddings):
+ # Initialize tables
+ self.initialize(recreate=True)
+
+ self.database.execute(self.table.insert(), [{"indexid": x, "embedding": row} for x, row in enumerate(embeddings)])
+
+ # Add id offset and index build metadata
+ self.config["offset"] = embeddings.shape[0]
+
+ def append(self, embeddings):
+ self.database.execute(self.table.insert(), [{"indexid": x + self.config["offset"], "embedding": row} for x, row in enumerate(embeddings)])
+
+ self.config["offset"] += embeddings.shape[0]
+
+ def delete(self, ids):
+ self.database.execute(delete(self.table).where(self.table.c["indexid"].in_(ids)))
+
+ def search(self, queries, limit):
+ results = []
+ for query in queries:
+ # Run query
+ query = (
+ self.database.query(self.table.c["indexid"], self.table.c["embedding"].max_inner_product(query).label("score"))
+ .order_by("score")
+ .limit(limit)
+ )
+
+ # pgvector returns negative inner product since Postgres only supports ASC order index scans on operators
+ results.append([(indexid, -score) for indexid, score in query])
+
+ return results
+
+ def count(self):
+ return self.database.query(self.table.c["indexid"]).count()
+
+ def save(self, path):
+ self.database.commit()
+
+ def initialize(self, recreate=False):
+ """
+ Initializes a new database session.
+
+ Args:
+ recreate: Recreates the database tables if True
+ """
+
+ # Table name
+ table = self.setting("table", "vectors")
+
+ # Create vectors table
+ self.table = Table(
+ table,
+ MetaData(),
+ Column("indexid", Integer, primary_key=True, autoincrement=False),
+ Column("embedding", Vector(self.config["dimensions"])),
+ )
+
+ # Create ANN index - inner product is equal to cosine similarity on normalized vectors
+ index = Index(
+ f"{table}-index",
+ self.table.c["embedding"],
+ postgresql_using="hnsw",
+ postgresql_with={"m": self.setting("m", 16), "ef_construction": self.setting("efconstruction", 200)},
+ postgresql_ops={"embedding": "vector_ip_ops"},
+ )
+
+ # Drop and recreate table
+ if recreate:
+ self.table.drop(self.engine, checkfirst=True)
+ index.drop(self.engine, checkfirst=True)
+
+ # Create table and index
+ self.table.create(self.engine, checkfirst=True)
+ index.create(self.engine, checkfirst=True)
diff --git a/test/python/testann.py b/test/python/testann.py
index 1f642434..87b2b647 100644
--- a/test/python/testann.py
+++ b/test/python/testann.py
@@ -6,6 +6,8 @@ import os
import tempfile
import unittest
+from unittest.mock import patch
+
import numpy as np
from txtai.ann import ANNFactory, ANN
@@ -108,6 +110,40 @@ class TestANN(unittest.TestCase):
self.runTests("numpy")
+ @patch("sqlalchemy.orm.Query.limit")
+ def testPGVector(self, query):
+ """
+ Test PGVector backend
+ """
+
+ # Generate test record
+ data = np.random.rand(1, 300).astype(np.float32)
+
+ # Mock database query
+ query.return_value = [(x, -1.0) for x in range(data.shape[0])]
+
+ # Create ANN
+ path = os.path.join(tempfile.gettempdir(), "graph.sqlite")
+ ann = ANNFactory.create({"backend": "pgvector", "pgvector": {"url": f"sqlite:///{path}"}, "dimensions": 300})
+
+ # Test indexing
+ ann.index(data)
+ ann.append(data)
+
+ # Validate search results
+ self.assertEqual(ann.search(data, 1), [[(0, 1.0)]])
+
+ # Validate save/load/delete
+ ann.save(None)
+ ann.load(None)
+
+ # Validate count
+ self.assertEqual(ann.count(), 2)
+
+ # Test delete
+ ann.delete([0])
+ self.assertEqual(ann.count(), 1)
+
def testTorch(self):
"""
Test Torch backend