From 1790c84f63c7ad93c589e6e018eb65b51a1983aa Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Thu, 8 May 2025 16:14:43 -0700 Subject: [PATCH 1/8] PGVector support for vector db storage --- README.md | 1 + docker/.env.example | 11 +++++-- .../GeneralSettings/VectorDatabase/index.jsx | 31 +++++++++++++------ .../Steps/DataHandling/index.jsx | 10 +++++- locales/README.fa-IR.md | 1 + locales/README.ja-JP.md | 1 + locales/README.tr-TR.md | 1 + locales/README.zh-CN.md | 1 + server/.env.example | 5 +++ server/models/systemSettings.js | 5 +++ server/utils/helpers/index.js | 3 ++ server/utils/helpers/updateENV.js | 30 +++++++++++++++++- 12 files changed, 85 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index e533203e536..8cf7ad09b56 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,7 @@ AnythingLLM divides your documents into objects called `workspaces`. A Workspace **Vector Databases:** - [LanceDB](https://github.com/lancedb/lancedb) (default) +- [PGVector](https://github.com/pgvector/pgvector) - [Astra DB](https://www.datastax.com/products/datastax-astra) - [Pinecone](https://pinecone.io) - [Chroma](https://trychroma.com) diff --git a/docker/.env.example b/docker/.env.example index 117a46133b2..755437c2e33 100644 --- a/docker/.env.example +++ b/docker/.env.example @@ -189,6 +189,14 @@ GID='1000' ########################################### ######## Vector Database Selection ######## ########################################### +# Enable all below if you are using vector database: LanceDB. +# VECTOR_DB="lancedb" + +# Enable all below if you are using vector database: Weaviate. +# VECTOR_DB="pgvector" +# PGVECTOR_CONNECTION_STRING="postgresql://dbuser:dbuserpass@localhost:5432/yourdb" +# PGVECTOR_TABLE_NAME="anythingllm_vectors" # optional, but can be defined + # Enable all below if you are using vector database: Chroma. # VECTOR_DB="chroma" # CHROMA_ENDPOINT='http://host.docker.internal:8000' @@ -200,9 +208,6 @@ GID='1000' # PINECONE_API_KEY= # PINECONE_INDEX= -# Enable all below if you are using vector database: LanceDB. -# VECTOR_DB="lancedb" - # Enable all below if you are using vector database: Weaviate. # VECTOR_DB="weaviate" # WEAVIATE_ENDPOINT="http://localhost:8080" diff --git a/frontend/src/pages/GeneralSettings/VectorDatabase/index.jsx b/frontend/src/pages/GeneralSettings/VectorDatabase/index.jsx index 11e70d8fd7d..51018cab22d 100644 --- a/frontend/src/pages/GeneralSettings/VectorDatabase/index.jsx +++ b/frontend/src/pages/GeneralSettings/VectorDatabase/index.jsx @@ -3,30 +3,34 @@ import Sidebar from "@/components/SettingsSidebar"; import { isMobile } from "react-device-detect"; import System from "@/models/system"; import showToast from "@/utils/toast"; +import { useModal } from "@/hooks/useModal"; +import CTAButton from "@/components/lib/CTAButton"; +import { CaretUpDown, MagnifyingGlass, X } from "@phosphor-icons/react"; +import { useTranslation } from "react-i18next"; +import PreLoader from "@/components/Preloader"; +import ChangeWarningModal from "@/components/ChangeWarning"; +import ModalWrapper from "@/components/ModalWrapper"; +import VectorDBItem from "@/components/VectorDBSelection/VectorDBItem"; + +import LanceDbLogo from "@/media/vectordbs/lancedb.png"; import ChromaLogo from "@/media/vectordbs/chroma.png"; import PineconeLogo from "@/media/vectordbs/pinecone.png"; -import LanceDbLogo from "@/media/vectordbs/lancedb.png"; import WeaviateLogo from "@/media/vectordbs/weaviate.png"; import QDrantLogo from "@/media/vectordbs/qdrant.png"; import MilvusLogo from "@/media/vectordbs/milvus.png"; import ZillizLogo from "@/media/vectordbs/zilliz.png"; import AstraDBLogo from "@/media/vectordbs/astraDB.png"; -import PreLoader from "@/components/Preloader"; -import ChangeWarningModal from "@/components/ChangeWarning"; -import { CaretUpDown, MagnifyingGlass, X } from "@phosphor-icons/react"; +import PGVectorLogo from "@/media/vectordbs/pgvector.png"; + import LanceDBOptions from "@/components/VectorDBSelection/LanceDBOptions"; import ChromaDBOptions from "@/components/VectorDBSelection/ChromaDBOptions"; import PineconeDBOptions from "@/components/VectorDBSelection/PineconeDBOptions"; -import QDrantDBOptions from "@/components/VectorDBSelection/QDrantDBOptions"; import WeaviateDBOptions from "@/components/VectorDBSelection/WeaviateDBOptions"; -import VectorDBItem from "@/components/VectorDBSelection/VectorDBItem"; +import QDrantDBOptions from "@/components/VectorDBSelection/QDrantDBOptions"; import MilvusDBOptions from "@/components/VectorDBSelection/MilvusDBOptions"; import ZillizCloudOptions from "@/components/VectorDBSelection/ZillizCloudOptions"; -import { useModal } from "@/hooks/useModal"; -import ModalWrapper from "@/components/ModalWrapper"; import AstraDBOptions from "@/components/VectorDBSelection/AstraDBOptions"; -import CTAButton from "@/components/lib/CTAButton"; -import { useTranslation } from "react-i18next"; +import PGVectorOptions from "@/components/VectorDBSelection/PGVectorOptions"; export default function GeneralVectorDatabase() { const [saving, setSaving] = useState(false); @@ -114,6 +118,13 @@ export default function GeneralVectorDatabase() { description: "100% local vector DB that runs on the same instance as AnythingLLM.", }, + { + name: "PGVector", + value: "pgvector", + logo: PGVectorLogo, + options: , + description: "Vector search powered by PostgreSQL.", + }, { name: "Chroma", value: "chroma", diff --git a/frontend/src/pages/OnboardingFlow/Steps/DataHandling/index.jsx b/frontend/src/pages/OnboardingFlow/Steps/DataHandling/index.jsx index 76372e83956..40d8bfaaec7 100644 --- a/frontend/src/pages/OnboardingFlow/Steps/DataHandling/index.jsx +++ b/frontend/src/pages/OnboardingFlow/Steps/DataHandling/index.jsx @@ -36,7 +36,7 @@ import QDrantLogo from "@/media/vectordbs/qdrant.png"; import MilvusLogo from "@/media/vectordbs/milvus.png"; import VoyageAiLogo from "@/media/embeddingprovider/voyageai.png"; import PPIOLogo from "@/media/llmprovider/ppio.png"; - +import PGVectorLogo from "@/media/vectordbs/pgvector.png"; import React, { useState, useEffect } from "react"; import paths from "@/utils/paths"; import { useNavigate } from "react-router-dom"; @@ -237,6 +237,14 @@ export const LLM_SELECTION_PRIVACY = { }; export const VECTOR_DB_PRIVACY = { + pgvector: { + name: "PGVector", + description: [ + "Your vectors and document text are stored on your PostgreSQL instance", + "Access to your instance is managed by you", + ], + logo: PGVectorLogo, + }, chroma: { name: "Chroma", description: [ diff --git a/locales/README.fa-IR.md b/locales/README.fa-IR.md index 9769e8b5353..c28abf648ae 100644 --- a/locales/README.fa-IR.md +++ b/locales/README.fa-IR.md @@ -137,6 +137,7 @@ AnythingLLM اسناد شما را به اشیایی به نام `workspaces` ت **پایگاه‌های داده برداری:** - [LanceDB](https://github.com/lancedb/lancedb) (پیش‌فرض) +- [PGVector](https://github.com/pgvector/pgvector) - [Astra DB](https://www.datastax.com/products/datastax-astra) - [Pinecone](https://pinecone.io) - [Chroma](https://trychroma.com) diff --git a/locales/README.ja-JP.md b/locales/README.ja-JP.md index 3938a20b1a6..8920b218fda 100644 --- a/locales/README.ja-JP.md +++ b/locales/README.ja-JP.md @@ -120,6 +120,7 @@ AnythingLLMは、ドキュメントを`ワークスペース`と呼ばれるオ **ベクトルデータベース：** - [LanceDB](https://github.com/lancedb/lancedb)（デフォルト） +- [PGVector](https://github.com/pgvector/pgvector) - [Astra DB](https://www.datastax.com/products/datastax-astra) - [Pinecone](https://pinecone.io) - [Chroma](https://trychroma.com) diff --git a/locales/README.tr-TR.md b/locales/README.tr-TR.md index 8dc59730415..9f539779503 100644 --- a/locales/README.tr-TR.md +++ b/locales/README.tr-TR.md @@ -132,6 +132,7 @@ AnythingLLM, belgelerinizi **"çalışma alanları" (workspaces)** adı verilen **Vektör Databases:** - [LanceDB](https://github.com/lancedb/lancedb) (default) +- [PGVector](https://github.com/pgvector/pgvector) - [Astra DB](https://www.datastax.com/products/datastax-astra) - [Pinecone](https://pinecone.io) - [Chroma](https://trychroma.com) diff --git a/locales/README.zh-CN.md b/locales/README.zh-CN.md index cd21e00aa1a..5164a24ed58 100644 --- a/locales/README.zh-CN.md +++ b/locales/README.zh-CN.md @@ -131,6 +131,7 @@ AnythingLLM将您的文档划分为称为`workspaces` (工作区)的对象。工 **支持的向量数据库：** - [LanceDB](https://github.com/lancedb/lancedb) （默认） +- [PGVector](https://github.com/pgvector/pgvector) - [Astra DB](https://www.datastax.com/products/datastax-astra) - [Pinecone](https://pinecone.io) - [Chroma](https://trychroma.com) diff --git a/server/.env.example b/server/.env.example index 51f8c05d4ef..ef6292c5415 100644 --- a/server/.env.example +++ b/server/.env.example @@ -206,6 +206,11 @@ SIG_SALT='salt' # Please generate random string at least 32 chars long. # Enable all below if you are using vector database: LanceDB. VECTOR_DB="lancedb" +# Enable all below if you are using vector database: Weaviate. +# VECTOR_DB="pgvector" +# PGVECTOR_CONNECTION_STRING="postgresql://dbuser:dbuserpass@localhost:5432/yourdb" +# PGVECTOR_TABLE_NAME="anythingllm_vectors" # optional, but can be defined + # Enable all below if you are using vector database: Weaviate. # VECTOR_DB="weaviate" # WEAVIATE_ENDPOINT="http://localhost:8080" diff --git a/server/models/systemSettings.js b/server/models/systemSettings.js index 5f8c761c984..01fe0a743d5 100644 --- a/server/models/systemSettings.js +++ b/server/models/systemSettings.js @@ -7,6 +7,7 @@ const { isValidUrl, safeJsonParse } = require("../utils/http"); const prisma = require("../utils/prisma"); const { v4 } = require("uuid"); const { MetaGenerator } = require("../utils/boot/MetaGenerator"); +const { PGVector } = require("../utils/vectorDbProviders/pgvector"); function isNullOrNaN(value) { if (value === null) return true; @@ -427,6 +428,10 @@ const SystemSettings = { // AstraDB Keys AstraDBApplicationToken: process?.env?.ASTRA_DB_APPLICATION_TOKEN, AstraDBEndpoint: process?.env?.ASTRA_DB_ENDPOINT, + + // PGVector Keys + PGVectorConnectionString: !!PGVector.connectionString() || false, + PGVectorTableName: PGVector.tableName(), }; }, diff --git a/server/utils/helpers/index.js b/server/utils/helpers/index.js index 6fc7f00e01a..cedbba2c654 100644 --- a/server/utils/helpers/index.js +++ b/server/utils/helpers/index.js @@ -107,6 +107,9 @@ function getVectorDbClass(getExactly = null) { case "astra": const { AstraDB } = require("../vectorDbProviders/astra"); return AstraDB; + case "pgvector": + const { PGVector } = require("../vectorDbProviders/pgvector"); + return PGVector; default: throw new Error("ENV: No VECTOR_DB value found in environment!"); } diff --git a/server/utils/helpers/updateENV.js b/server/utils/helpers/updateENV.js index ed9f9696b87..c32be2c64ab 100644 --- a/server/utils/helpers/updateENV.js +++ b/server/utils/helpers/updateENV.js @@ -371,7 +371,6 @@ const KEY_MAPPING = { }, // Astra DB Options - AstraDBApplicationToken: { envKey: "ASTRA_DB_APPLICATION_TOKEN", checks: [isNotEmpty], @@ -381,6 +380,21 @@ const KEY_MAPPING = { checks: [isNotEmpty], }, + /* + PGVector Options + - Does very simple validations - we should expand this in the future + - to ensure the connection string is valid and the table name is valid + - via direct query + */ + PGVectorConnectionString: { + envKey: "PGVECTOR_CONNECTION_STRING", + checks: [isNotEmpty, looksLikePostgresConnectionString], + }, + PGVectorTableName: { + envKey: "PGVECTOR_TABLE_NAME", + checks: [isNotEmpty], + }, + // Together Ai Options TogetherAiApiKey: { envKey: "TOGETHER_AI_API_KEY", @@ -802,6 +816,7 @@ function supportedVectorDB(input = "") { "milvus", "zilliz", "astra", + "pgvector", ]; return supported.includes(input) ? null @@ -880,6 +895,19 @@ async function handleVectorStoreReset(key, prevValue, nextValue) { return false; } +/** + * Validates the Postgres connection string for the PGVector options. + * @param {string} input - The Postgres connection string to validate. + * @returns {string} - An error message if the connection string is invalid, otherwise null. + */ +async function looksLikePostgresConnectionString(connectionString = null) { + if (!connectionString || !connectionString.startsWith("postgresql://")) + return "Invalid Postgres connection string. Must start with postgresql://"; + if (connectionString.includes(" ")) + return "Invalid Postgres connection string. Must not contain spaces."; + return null; +} + // This will force update .env variables which for any which reason were not able to be parsed or // read from an ENV file as this seems to be a complicating step for many so allowing people to write // to the process will at least alleviate that issue. It does not perform comprehensive validity checks or sanity checks From 3cf4a8be5aef5a8cecee9df023753f35ffe1a37b Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Thu, 8 May 2025 16:14:52 -0700 Subject: [PATCH 2/8] forgot files --- .../PGVectorOptions/index.jsx | 103 +++ frontend/src/media/vectordbs/pgvector.png | Bin 0 -> 47152 bytes .../utils/vectorDbProviders/pgvector/SETUP.md | 58 ++ .../utils/vectorDbProviders/pgvector/index.js | 678 ++++++++++++++++++ 4 files changed, 839 insertions(+) create mode 100644 frontend/src/components/VectorDBSelection/PGVectorOptions/index.jsx create mode 100644 frontend/src/media/vectordbs/pgvector.png create mode 100644 server/utils/vectorDbProviders/pgvector/SETUP.md create mode 100644 server/utils/vectorDbProviders/pgvector/index.js diff --git a/frontend/src/components/VectorDBSelection/PGVectorOptions/index.jsx b/frontend/src/components/VectorDBSelection/PGVectorOptions/index.jsx new file mode 100644 index 00000000000..c2e9e09d650 --- /dev/null +++ b/frontend/src/components/VectorDBSelection/PGVectorOptions/index.jsx @@ -0,0 +1,103 @@ +import { Info } from "@phosphor-icons/react"; +import { Tooltip } from "react-tooltip"; + +export default function PGVectorOptions({ settings }) { + return ( +
+
+
+
+ + + +

+ This is the connection string for the Postgres database in the + format of
+ postgresql://username:password@host:port/database +
+
+ The user for the database must have the following permissions: +

    +
  • Read access to the database
    • +
  • Read access to the database schema
    • +
  • Create access to the database
    • +
+
+ + You must have the pgvector extension installed on the + database. + +

+ +
+ +
+ +
+
+ + + +

+ This is the name of the table in the Postgres database that will + store the vectors. +
+
+ By default, the table name is anythingllm_vectors. +
+
+ + This table must not already exist on the database - it will be + created automatically. + +

+ +
+ +
+
+
+ ); +} diff --git a/frontend/src/media/vectordbs/pgvector.png b/frontend/src/media/vectordbs/pgvector.png new file mode 100644 index 0000000000000000000000000000000000000000..67918df7a77905a065d286802efe3055969ec266 GIT binary patch literal 47152 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

xK0k(o)B2 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 E11Pf9Pyhe` literal 0 HcmV?d00001 diff --git a/server/utils/vectorDbProviders/pgvector/SETUP.md b/server/utils/vectorDbProviders/pgvector/SETUP.md new file mode 100644 index 00000000000..b5330c9a396 --- /dev/null +++ b/server/utils/vectorDbProviders/pgvector/SETUP.md @@ -0,0 +1,58 @@ +# Setting up `PGVector` for AnythingLLM + +Setting up PGVector for anythingllm to use as your vector database is quite easy. At a minimum, you will need the following: + +- PostgreSQL v12+ +- [`pgvector`](https://github.com/pgvector/pgvector) extension installed on DB +- User with DB table creation perms and READ access + +## Setup on Mac (example) + +### Install pgvector extension on PostgreSQL DB + +```bash +brew install postgresql +brew services start postgresql +brew install pgvector + +# assuming you have a database already set up + a user +psql +CREATE EXTENSION vector; +``` + +### Set PG as your vector db + +_this can be done via the UI or by directly editing the `.env` file_ + +First, obtain a valid connection string for the user, credentials, and db you want to target. +eg: `postgresql://dbuser:dbuserpass@localhost:5432/yourdb` + +> ![NOTE] +> The table in your tables **must not exist** AnythingLLM will create and manage this table **for you**. +> The pgvector table requires a dimension value be set and therefore we cannot use an existing table automatically. + +_optional_ - set a table name you wish to have AnythingLLM store vectors to. By default this is `anythingllm_vectors` + +## Troubleshooting + +### Cannot connect to DB + +- Ensure the connection string is valid +- Ensure the user has access to the database +- Ensure the pgvector extension is installed + +### Cannot create table + +- Ensure the user has `CREATE TABLE` permissions + +### Cannot insert vector + +- Ensure the user has `INSERT` permissions in the database +- Ensure the table has a dimension value set and this matches the dimension of the embedder in AnythingLLM +- Ensure the table has a vector column set + +### Cannot query vector + +- Ensure the user has `SELECT` permissions in the database +- Ensure the table has a vector column set +- Ensure the table has a dimension value set and this matches the dimension of the embedder in AnythingLLM diff --git a/server/utils/vectorDbProviders/pgvector/index.js b/server/utils/vectorDbProviders/pgvector/index.js new file mode 100644 index 00000000000..98a88f0c1cf --- /dev/null +++ b/server/utils/vectorDbProviders/pgvector/index.js @@ -0,0 +1,678 @@ +const pgsql = require("pg"); +const { toChunks, getEmbeddingEngineSelection } = require("../../helpers"); +const { TextSplitter } = require("../../TextSplitter"); +const { v4: uuidv4 } = require("uuid"); +const { sourceIdentifier } = require("../../chats"); + +/* + Embedding Table Schema (table name defined by user) + - id: UUID PRIMARY KEY + - namespace: TEXT + - embedding: vector(xxxx) + - metadata: JSONB + - created_at: TIMESTAMP +*/ + +const PGVector = { + name: "PGVector", + /** + * Get the table name for the PGVector database. + * - Defaults to "anythingllm_vectors" if no table name is provided. + * @returns {string} + */ + tableName: () => process.env.PGVECTOR_TABLE_NAME || "anythingllm_vectors", + + /** + * Get the connection string for the PGVector database. + * - Requires a connection string to be present in the environment variables. + * @returns {string | null} + */ + connectionString: () => process.env.PGVECTOR_CONNECTION_STRING, + + // Possible for this to be a user-configurable option in the future. + // Will require a handler per operator to ensure scores are normalized. + operator: { + l2: "<->", + innerProduct: "<#>", + cosine: "<=>", + l1: "<+>", + hamming: "<~>", + jaccard: "<%>", + }, + getTablesSql: + "SELECT * FROM pg_catalog.pg_tables WHERE schemaname = 'public'", + createTableSql: (dimensions) => + `CREATE TABLE IF NOT EXISTS "${PGVector.tableName()}" (id UUID PRIMARY KEY, namespace TEXT, embedding vector(${Number(dimensions)}), metadata JSONB, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)`, + + log: function (message = null, ...args) { + console.log(`\x1b[35m[PGVectorDb]\x1b[0m ${message}`, ...args); + }, + + client: function (connectionString = null) { + return new pgsql.Client({ + connectionString: connectionString || PGVector.connectionString(), + }); + }, + + /** + * Validate the connection to the database and verify that the table does not already exist. + * so that anythingllm can manage the table directly. + * + * TODO: handling changes to the connection string so that we only validate what is being changed. + * + * @param {{connectionString: string | null, tableName: string | null}} params + * @returns {{error: string | null, success: boolean}} + */ + validateConnection: async function ({ + connectionString = null, + tableName = null, + }) { + if (!connectionString) throw new Error("No connection string provided"); + if (!tableName) throw new Error("No table name provided"); + + let pgClient = null; + try { + pgClient = this.client(connectionString); + await pgClient.connect(); + const result = await pgClient.query(this.getTablesSql); + + if (result.rows.length !== 0 && !!tableName) { + const tableExists = result.rows.some( + (row) => row.tablename === tableName + ); + if (!!tableExists) + throw new Error( + `The vector table ${tableName} already exists. Please use a table name that does not already exist in the database.` + ); + } + + return { error: null, success: true }; + } catch (err) { + return { error: err.message, success: false }; + } finally { + if (pgClient) await pgClient.end(); + } + }, + + /** + * Test the connection to the database directly. + * @returns {{error: string | null, success: boolean}} + */ + testConnectionToDB: async function () { + try { + const pgClient = await this.connect(); + await pgClient.query(this.getTablesSql); + await pgClient.end(); + return { error: null, success: true }; + } catch (err) { + return { error: err.message, success: false }; + } + }, + + /** + * Connect to the database. + * - Throws an error if the connection string or table name is not provided. + * @returns {Promise} + */ + connect: async function () { + if (!PGVector.connectionString()) + throw new Error("No connection string provided"); + if (!PGVector.tableName()) throw new Error("No table name provided"); + + const client = this.client(); + await client.connect(); + return client; + }, + + /** + * Test the connection to the database with already set credentials via ENV + * @returns {{error: string | null, success: boolean}} + */ + heartbeat: async function () { + return this.testConnectionToDB(); + }, + + /** + * Check if the anythingllm embedding table exists in the database + * @returns {Promise} + */ + dbTableExists: async function () { + let connection = null; + try { + connection = await this.connect(); + const tables = await connection.query(this.getTablesSql); + if (tables.rows.length === 0) return false; + const tableExists = tables.rows.some( + (row) => row.tablename === PGVector.tableName() + ); + return !!tableExists; + } catch (err) { + return false; + } finally { + if (connection) await connection.end(); + } + }, + + totalVectors: async function () { + if (!(await this.dbTableExists())) return 0; + let connection = null; + try { + connection = await this.connect(); + const result = await connection.query( + `SELECT COUNT(id) FROM "${PGVector.tableName()}"` + ); + return result.rows[0].count; + } catch (err) { + return 0; + } finally { + if (connection) await connection.end(); + } + }, + + // Distance for cosine is just the distance for pgvector. + distanceToSimilarity: function (distance = null) { + if (distance === null || typeof distance !== "number") return 0.0; + if (distance >= 1.0) return 1; + if (distance < 0) return 1 - Math.abs(distance); + return 1 - distance; + }, + + namespaceCount: async function (namespace = null) { + if (!(await this.dbTableExists())) return 0; + let connection = null; + try { + connection = await this.connect(); + const result = await connection.query( + `SELECT COUNT(id) FROM "${PGVector.tableName()}" WHERE namespace = $1`, + [namespace] + ); + return result.rows[0].count; + } catch (err) { + return 0; + } finally { + if (connection) await connection.end(); + } + }, + + /** + * Performs a SimilaritySearch on a give LanceDB namespace. + * @param {Object} params + * @param {pgsql.Client} params.client + * @param {string} params.namespace + * @param {number[]} params.queryVector + * @param {number} params.similarityThreshold + * @param {number} params.topN + * @param {string[]} params.filterIdentifiers + * @returns + */ + similarityResponse: async function ({ + client, + namespace, + queryVector, + similarityThreshold = 0.25, + topN = 4, + filterIdentifiers = [], + }) { + const result = { + contextTexts: [], + sourceDocuments: [], + scores: [], + }; + + const embedding = `[${queryVector.map(Number).join(",")}]`; + const response = await client.query( + `SELECT embedding ${this.operator.cosine} $1 AS _distance, metadata FROM "${PGVector.tableName()}" WHERE namespace = $2 ORDER BY _distance ASC LIMIT $3`, + [embedding, namespace, topN] + ); + response.rows.forEach((item) => { + if (this.distanceToSimilarity(item._distance) < similarityThreshold) + return; + if (filterIdentifiers.includes(sourceIdentifier(item.metadata))) { + this.log( + "A source was filtered from context as it's parent document is pinned." + ); + return; + } + + result.contextTexts.push(item.metadata.text); + result.sourceDocuments.push({ + ...item.metadata, + score: this.distanceToSimilarity(item._distance), + }); + result.scores.push(this.distanceToSimilarity(item._distance)); + }); + + return result; + }, + + normalizeVector: function (vector) { + const magnitude = Math.sqrt( + vector.reduce((sum, val) => sum + val * val, 0) + ); + if (magnitude === 0) return vector; // Avoid division by zero + return vector.map((val) => val / magnitude); + }, + + /** + * Update or create a collection in the database + * @param {pgsql.Connection} connection + * @param {{id: number, vector: number[], metadata: Object}[]} submissions + * @param {string} namespace + * @returns {Promise} + */ + updateOrCreateCollection: async function ({ + connection, + submissions, + namespace, + dimensions = 384, + }) { + await this.createTableIfNotExists(connection, dimensions); + this.log(`Updating or creating collection ${namespace}`); + + try { + // Create a transaction of all inserts + await connection.query(`BEGIN`); + for (const submission of submissions) { + const embedding = `[${submission.vector.map(Number).join(",")}]`; // stringify the vector for pgvector + await connection.query( + `INSERT INTO "${PGVector.tableName()}" (id, namespace, embedding, metadata) VALUES ($1, $2, $3, $4)`, + [submission.id, namespace, embedding, submission.metadata] + ); + } + this.log(`Committing ${submissions.length} vectors to ${namespace}`); + await connection.query(`COMMIT`); + } catch (err) { + this.log( + `Rolling back ${submissions.length} vectors to ${namespace}`, + err + ); + await connection.query(`ROLLBACK`); + } + return true; + }, + + /** + * create a table if it doesn't exist + * @param {pgsql.Client} connection + * @param {number} dimensions + * @returns + */ + createTableIfNotExists: async function (connection, dimensions = 384) { + this.log(`Creating embedding table with ${dimensions} dimensions`); + await connection.query(this.createTableSql(dimensions)); + return true; + }, + + /** + * Get the namespace from the database + * @param {pgsql.Client} connection + * @param {string} namespace + * @returns {Promise<{name: string, vectorCount: number}>} + */ + namespace: async function (connection, namespace = null) { + if (!namespace) throw new Error("No namespace provided"); + const result = await connection.query( + `SELECT COUNT(id) FROM "${PGVector.tableName()}" WHERE namespace = $1`, + [namespace] + ); + return { name: namespace, vectorCount: result.rows[0].count }; + }, + + /** + * Check if the namespace exists in the database + * @param {string} namespace + * @returns {Promise} + */ + hasNamespace: async function (namespace = null) { + if (!namespace) throw new Error("No namespace provided"); + let connection = null; + try { + connection = await this.connect(); + return await this.namespaceExists(connection, namespace); + } catch (err) { + return false; + } finally { + if (connection) await connection.end(); + } + }, + + /** + * Check if the namespace exists in the database + * @param {pgsql.Client} connection + * @param {string} namespace + * @returns {Promise} + */ + namespaceExists: async function (connection, namespace = null) { + if (!namespace) throw new Error("No namespace provided"); + const result = await connection.query( + `SELECT COUNT(id) FROM "${PGVector.tableName()}" WHERE namespace = $1 LIMIT 1`, + [namespace] + ); + return result.rows[0].count > 0; + }, + + /** + * Delete all vectors in the namespace + * @param {pgsql.Client} connection + * @param {string} namespace + * @returns {Promise} + */ + deleteVectorsInNamespace: async function (connection, namespace = null) { + if (!namespace) throw new Error("No namespace provided"); + await connection.query( + `DELETE FROM "${PGVector.tableName()}" WHERE namespace = $1`, + [namespace] + ); + return true; + }, + + addDocumentToNamespace: async function ( + namespace, + documentData = {}, + fullFilePath = null, + skipCache = false + ) { + const { DocumentVectors } = require("../../../models/vectors"); + const { + storeVectorResult, + cachedVectorInformation, + } = require("../../files"); + let connection = null; + + try { + const { pageContent, docId, ...metadata } = documentData; + if (!pageContent || pageContent.length == 0) return false; + connection = await this.connect(); + + this.log("Adding new vectorized document into namespace", namespace); + if (!skipCache) { + const cacheResult = await cachedVectorInformation(fullFilePath); + let vectorDimensions; + if (cacheResult.exists) { + const { chunks } = cacheResult; + const documentVectors = []; + const submissions = []; + + for (const chunk of chunks.flat()) { + if (!vectorDimensions) vectorDimensions = chunk.values.length; + const id = uuidv4(); + const { id: _id, ...metadata } = chunk.metadata; + documentVectors.push({ docId, vectorId: id }); + submissions.push({ id: id, vector: chunk.values, metadata }); + } + + await this.updateOrCreateCollection({ + connection, + submissions, + namespace, + dimensions: vectorDimensions, + }); + await DocumentVectors.bulkInsert(documentVectors); + return { vectorized: true, error: null }; + } + } + + // If we are here then we are going to embed and store a novel document. + // We have to do this manually as opposed to using LangChains `xyz.fromDocuments` + // because we then cannot atomically control our namespace to granularly find/remove documents + // from vectordb. + const { SystemSettings } = require("../../../models/systemSettings"); + const EmbedderEngine = getEmbeddingEngineSelection(); + const textSplitter = new TextSplitter({ + chunkSize: TextSplitter.determineMaxChunkSize( + await SystemSettings.getValueOrFallback({ + label: "text_splitter_chunk_size", + }), + EmbedderEngine?.embeddingMaxChunkLength + ), + chunkOverlap: await SystemSettings.getValueOrFallback( + { label: "text_splitter_chunk_overlap" }, + 20 + ), + chunkHeaderMeta: TextSplitter.buildHeaderMeta(metadata), + }); + const textChunks = await textSplitter.splitText(pageContent); + + console.log("Chunks created from document:", textChunks.length); + const documentVectors = []; + const vectors = []; + const submissions = []; + const vectorValues = await EmbedderEngine.embedChunks(textChunks); + let vectorDimensions; + + if (!!vectorValues && vectorValues.length > 0) { + for (const [i, vector] of vectorValues.entries()) { + if (!vectorDimensions) vectorDimensions = vector.length; + const vectorRecord = { + id: uuidv4(), + values: vector, + metadata: { ...metadata, text: textChunks[i] }, + }; + + vectors.push(vectorRecord); + submissions.push({ + id: vectorRecord.id, + vector: vectorRecord.values, + metadata: vectorRecord.metadata, + }); + documentVectors.push({ docId, vectorId: vectorRecord.id }); + } + } else { + throw new Error( + "Could not embed document chunks! This document will not be recorded." + ); + } + + if (vectors.length > 0) { + const chunks = []; + for (const chunk of toChunks(vectors, 500)) chunks.push(chunk); + + console.log("Inserting vectorized chunks into LanceDB collection."); + await this.updateOrCreateCollection({ + connection, + submissions, + namespace, + dimensions: vectorDimensions, + }); + await storeVectorResult(chunks, fullFilePath); + } + + await DocumentVectors.bulkInsert(documentVectors); + return { vectorized: true, error: null }; + } catch (err) { + this.log("addDocumentToNamespace", err.message); + return { vectorized: false, error: err.message }; + } finally { + if (connection) await connection.end(); + } + }, + + /** + * Delete a document from the namespace + * @param {string} namespace + * @param {string} docId + * @returns {Promise} + */ + deleteDocumentFromNamespace: async function (namespace, docId) { + if (!namespace) throw new Error("No namespace provided"); + if (!docId) throw new Error("No docId provided"); + + let connection = null; + try { + connection = await this.connect(); + const exists = await this.namespaceExists(connection, namespace); + if (!exists) + throw new Error( + `PGVector:deleteDocumentFromNamespace - namespace ${namespace} does not exist.` + ); + + const { DocumentVectors } = require("../../../models/vectors"); + const vectorIds = (await DocumentVectors.where({ docId })).map( + (record) => record.vectorId + ); + if (vectorIds.length === 0) return; + + try { + await connection.query(`BEGIN`); + for (const vectorId of vectorIds) + await connection.query( + `DELETE FROM "${PGVector.tableName()}" WHERE id = $1`, + [vectorId] + ); + await connection.query(`COMMIT`); + } catch (err) { + await connection.query(`ROLLBACK`); + throw err; + } + + this.log( + `Deleted ${vectorIds.length} vectors from namespace ${namespace}` + ); + return true; + } catch (err) { + this.log( + `Error deleting document from namespace ${namespace}: ${err.message}` + ); + return false; + } finally { + if (connection) await connection.end(); + } + }, + + performSimilaritySearch: async function ({ + namespace = null, + input = "", + LLMConnector = null, + similarityThreshold = 0.25, + topN = 4, + filterIdentifiers = [], + }) { + let connection = null; + if (!namespace || !input || !LLMConnector) + throw new Error("Invalid request to performSimilaritySearch."); + + try { + connection = await this.connect(); + const exists = await this.namespaceExists(connection, namespace); + if (!exists) { + this.log( + `The namespace ${namespace} does not exist or has no vectors. Returning empty results.` + ); + return { + contextTexts: [], + sources: [], + message: null, + }; + } + + const queryVector = await LLMConnector.embedTextInput(input); + const result = await this.similarityResponse({ + client: connection, + namespace, + queryVector, + similarityThreshold, + topN, + filterIdentifiers, + }); + + const { contextTexts, sourceDocuments } = result; + const sources = sourceDocuments.map((metadata, i) => { + return { metadata: { ...metadata, text: contextTexts[i] } }; + }); + return { + contextTexts, + sources: this.curateSources(sources), + message: false, + }; + } catch (err) { + return { error: err.message, success: false }; + } finally { + if (connection) await connection.end(); + } + }, + + "namespace-stats": async function (reqBody = {}) { + const { namespace = null } = reqBody; + if (!namespace) throw new Error("namespace required"); + if (!(await this.dbTableExists())) + return { message: "No table found in database" }; + + let connection = null; + try { + connection = await this.connect(); + if (!(await this.namespaceExists(connection, namespace))) + throw new Error("Namespace by that name does not exist."); + const stats = await this.namespace(connection, namespace); + return stats + ? stats + : { message: "No stats were able to be fetched from DB for namespace" }; + } catch (err) { + return { + message: `Error fetching stats for namespace ${namespace}: ${err.message}`, + }; + } finally { + if (connection) await connection.end(); + } + }, + + "delete-namespace": async function (reqBody = {}) { + const { namespace = null } = reqBody; + if (!namespace) throw new Error("No namespace provided"); + + let connection = null; + try { + const existingCount = await this.namespaceCount(namespace); + if (existingCount === 0) + return { + message: `Namespace ${namespace} does not exist or has no vectors.`, + }; + + connection = await this.connect(); + await this.deleteVectorsInNamespace(connection, namespace); + return { + message: `Namespace ${namespace} was deleted along with ${existingCount} vectors.`, + }; + } catch (err) { + return { + message: `Error deleting namespace ${namespace}: ${err.message}`, + }; + } finally { + if (connection) await connection.end(); + } + }, + + /** + * Reset the entire vector database table associated with anythingllm + * @returns {Promise<{reset: boolean}>} + */ + reset: async function () { + let connection = null; + try { + connection = await this.connect(); + await connection.query(`DROP TABLE IF EXISTS "${PGVector.tableName()}"`); + return { reset: true }; + } catch (err) { + return { reset: false }; + } finally { + if (connection) await connection.end(); + } + }, + + curateSources: function (sources = []) { + const documents = []; + for (const source of sources) { + const { text, vector: _v, _distance: _d, ...rest } = source; + const metadata = rest.hasOwnProperty("metadata") ? rest.metadata : rest; + if (Object.keys(metadata).length > 0) { + documents.push({ + ...metadata, + ...(text ? { text } : {}), + }); + } + } + + return documents; + }, +}; + +module.exports.PGVector = PGVector; From f98d67a04258d9b85335a7f211d91cc221f5fcb3 Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Thu, 8 May 2025 16:20:35 -0700 Subject: [PATCH 3/8] comments --- server/utils/vectorDbProviders/pgvector/index.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/server/utils/vectorDbProviders/pgvector/index.js b/server/utils/vectorDbProviders/pgvector/index.js index 98a88f0c1cf..8393f015d3c 100644 --- a/server/utils/vectorDbProviders/pgvector/index.js +++ b/server/utils/vectorDbProviders/pgvector/index.js @@ -195,7 +195,7 @@ const PGVector = { }, /** - * Performs a SimilaritySearch on a give LanceDB namespace. + * Performs a SimilaritySearch on a given PGVector namespace. * @param {Object} params * @param {pgsql.Client} params.client * @param {string} params.namespace @@ -433,7 +433,7 @@ const PGVector = { }); const textChunks = await textSplitter.splitText(pageContent); - console.log("Chunks created from document:", textChunks.length); + this.log("Chunks created from document:", textChunks.length); const documentVectors = []; const vectors = []; const submissions = []; @@ -467,7 +467,7 @@ const PGVector = { const chunks = []; for (const chunk of toChunks(vectors, 500)) chunks.push(chunk); - console.log("Inserting vectorized chunks into LanceDB collection."); + this.log("Inserting vectorized chunks into PGVector collection."); await this.updateOrCreateCollection({ connection, submissions, From 62c5b7092db17a3a35bb2bf2177272a266e3f113 Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Thu, 8 May 2025 16:21:14 -0700 Subject: [PATCH 4/8] dev build --- .github/workflows/dev-build.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/dev-build.yaml b/.github/workflows/dev-build.yaml index daa422db88a..e4ff3689ce1 100644 --- a/.github/workflows/dev-build.yaml +++ b/.github/workflows/dev-build.yaml @@ -6,7 +6,7 @@ concurrency: on: push: - branches: ['2237-auto-stt-submit-preference'] # put your current branch to create a build. Core team only. + branches: ['873-pgvector-support'] # put your current branch to create a build. Core team only. paths-ignore: - '**.md' - 'cloud-deployments/*' From 0b380327bfd0a01c36d8fe140ed8f7d74dd684fd Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Fri, 9 May 2025 11:41:19 -0700 Subject: [PATCH 5/8] Add ENV connection and table schema validations for vector table add .reset call to drop embedding table when changing the AnythingLLM embedder update instrutions Add preCheck error reporting in UpdateENV add timeout to pg connection --- server/utils/helpers/updateENV.js | 72 ++++++++- .../utils/vectorDbProviders/pgvector/SETUP.md | 4 +- .../utils/vectorDbProviders/pgvector/index.js | 148 +++++++++++++++--- .../utils/vectorStore/resetAllVectorStores.js | 21 ++- 4 files changed, 214 insertions(+), 31 deletions(-) diff --git a/server/utils/helpers/updateENV.js b/server/utils/helpers/updateENV.js index c32be2c64ab..cd43b8bfce1 100644 --- a/server/utils/helpers/updateENV.js +++ b/server/utils/helpers/updateENV.js @@ -389,10 +389,12 @@ const KEY_MAPPING = { PGVectorConnectionString: { envKey: "PGVECTOR_CONNECTION_STRING", checks: [isNotEmpty, looksLikePostgresConnectionString], + preUpdate: [validatePGVectorConnectionString], }, PGVectorTableName: { envKey: "PGVECTOR_TABLE_NAME", checks: [isNotEmpty], + preUpdate: [validatePGVectorTableName], }, // Together Ai Options @@ -908,6 +910,57 @@ async function looksLikePostgresConnectionString(connectionString = null) { return null; } +/** + * Validates the Postgres connection string for the PGVector options. + * @param {string} key - The ENV key we are validating. + * @param {string} prevValue - The previous value of the key. + * @param {string} nextValue - The next value of the key. + * @returns {string} - An error message if the connection string is invalid, otherwise null. + */ +async function validatePGVectorConnectionString(key, prevValue, nextValue) { + const envKey = KEY_MAPPING[key].envKey; + + if (prevValue === nextValue) return; // If the value is the same as the previous value, don't validate it. + if (!nextValue) return; // If the value is not set, don't validate it. + if (nextValue === process.env[envKey]) return; // If the value is the same as the current connection string, don't validate it. + + const { PGVector } = require("../vectorDbProviders/pgvector"); + const { error, success } = await PGVector.validateConnection({ + connectionString: nextValue, + }); + if (!success) return error; + + // Set the ENV variable for the PGVector connection string early so we can use it in the table check. + process.env[envKey] = nextValue; + return null; +} + +/** + * Validates the Postgres table name for the PGVector options. + * - Table should not already exist in the database. + * @param {string} key - The ENV key we are validating. + * @param {string} prevValue - The previous value of the key. + * @param {string} nextValue - The next value of the key. + * @returns {string} - An error message if the table name is invalid, otherwise null. + */ +async function validatePGVectorTableName(key, prevValue, nextValue) { + const envKey = KEY_MAPPING[key].envKey; + + if (prevValue === nextValue) return; // If the value is the same as the previous value, don't validate it. + if (!nextValue) return; // If the value is not set, don't validate it. + if (nextValue === process.env[envKey]) return; // If the value is the same as the current table name, don't validate it. + if (!process.env.PGVECTOR_CONNECTION_STRING) return; // if connection string is not set, don't validate it since it will fail. + + const { PGVector } = require("../vectorDbProviders/pgvector"); + const { error, success } = await PGVector.validateConnection({ + connectionString: process.env.PGVECTOR_CONNECTION_STRING, + tableName: nextValue, + }); + if (!success) return error; + + return null; +} + // This will force update .env variables which for any which reason were not able to be parsed or // read from an ENV file as this seems to be a complicating step for many so allowing people to write // to the process will at least alleviate that issue. It does not perform comprehensive validity checks or sanity checks @@ -929,15 +982,28 @@ async function updateENV(newENVs = {}, force = false, userId = null) { } = KEY_MAPPING[key]; const prevValue = process.env[envKey]; const nextValue = newENVs[key]; + let errors = await executeValidationChecks(checks, nextValue, force); - const errors = await executeValidationChecks(checks, nextValue, force); + // If there are any errors from regular simple validation checks + // exit early. if (errors.length > 0) { error += errors.join("\n"); break; } - for (const preUpdateFunc of preUpdate) - await preUpdateFunc(key, prevValue, nextValue); + // Accumulate errors from preUpdate functions + errors = []; + for (const preUpdateFunc of preUpdate) { + const errorMsg = await preUpdateFunc(key, prevValue, nextValue); + if (!!errorMsg && typeof errorMsg === "string") errors.push(errorMsg); + } + + // If there are any errors from preUpdate functions + // exit early. + if (errors.length > 0) { + error += errors.join("\n"); + break; + } newValues[key] = nextValue; process.env[envKey] = nextValue; diff --git a/server/utils/vectorDbProviders/pgvector/SETUP.md b/server/utils/vectorDbProviders/pgvector/SETUP.md index b5330c9a396..0b2503fd313 100644 --- a/server/utils/vectorDbProviders/pgvector/SETUP.md +++ b/server/utils/vectorDbProviders/pgvector/SETUP.md @@ -28,8 +28,8 @@ First, obtain a valid connection string for the user, credentials, and db you wa eg: `postgresql://dbuser:dbuserpass@localhost:5432/yourdb` > ![NOTE] -> The table in your tables **must not exist** AnythingLLM will create and manage this table **for you**. -> The pgvector table requires a dimension value be set and therefore we cannot use an existing table automatically. +> If you have an existing table that you want to use as a vector database, AnythingLLM **requires** that the table be +> at least minimally conform to the expected schema - this can be seen in the [index.js](./index.js) file. _optional_ - set a table name you wish to have AnythingLLM store vectors to. By default this is `anythingllm_vectors` diff --git a/server/utils/vectorDbProviders/pgvector/index.js b/server/utils/vectorDbProviders/pgvector/index.js index 8393f015d3c..370eb950686 100644 --- a/server/utils/vectorDbProviders/pgvector/index.js +++ b/server/utils/vectorDbProviders/pgvector/index.js @@ -15,6 +15,7 @@ const { sourceIdentifier } = require("../../chats"); const PGVector = { name: "PGVector", + connectionTimeout: 30_000, /** * Get the table name for the PGVector database. * - Defaults to "anythingllm_vectors" if no table name is provided. @@ -41,6 +42,8 @@ const PGVector = { }, getTablesSql: "SELECT * FROM pg_catalog.pg_tables WHERE schemaname = 'public'", + getEmbeddingTableSchemaSql: + "SELECT column_name,data_type FROM information_schema.columns WHERE table_name = $1", createTableSql: (dimensions) => `CREATE TABLE IF NOT EXISTS "${PGVector.tableName()}" (id UUID PRIMARY KEY, namespace TEXT, embedding vector(${Number(dimensions)}), metadata JSONB, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)`, @@ -54,43 +57,146 @@ const PGVector = { }); }, + /** + * Validate the existing embedding table schema. + * @param {pgsql.Client} pgClient + * @param {string} tableName + * @returns {Promise} + */ + validateExistingEmbeddingTableSchema: async function (pgClient, tableName) { + const result = await pgClient.query(this.getEmbeddingTableSchemaSql, [ + tableName, + ]); + + // Minimum expected schema for an embedding table. + // Extra columns are allowed but the minimum exact columns are required + // to be present in the table. + const expectedSchema = [ + { + column_name: "id", + expected: "uuid", + validation: function (dataType) { + return dataType.toLowerCase() === this.expected; + }, + }, + { + column_name: "namespace", + expected: "text", + validation: function (dataType) { + return dataType.toLowerCase() === this.expected; + }, + }, + { + column_name: "embedding", + expected: "vector", + validation: function (dataType) { + return !!dataType; + }, + }, // just check if it exists + { + column_name: "metadata", + expected: "jsonb", + validation: function (dataType) { + return dataType.toLowerCase() === this.expected; + }, + }, + { + column_name: "created_at", + expected: "timestamp", + validation: function (dataType) { + return dataType.toLowerCase().includes(this.expected); + }, + }, + ]; + + if (result.rows.length === 0) + throw new Error( + `The table '${tableName}' was found but does not contain any columns or cannot be accessed by role. It cannot be used as an embedding table in AnythingLLM.` + ); + + for (const rowDef of expectedSchema) { + const column = result.rows.find( + (c) => c.column_name === rowDef.column_name + ); + if (!column) + throw new Error( + `The column '${rowDef.column_name}' was expected but not found in the table '${tableName}'.` + ); + if (!rowDef.validation(column.data_type)) + throw new Error( + `Invalid data type for column: '${column.column_name}'. Got '${column.data_type}' but expected '${rowDef.expected}'` + ); + } + + this.log( + `✅ The pgvector table '${tableName}' was found and meets the minimum expected schema for an embedding table.` + ); + return true; + }, + /** * Validate the connection to the database and verify that the table does not already exist. * so that anythingllm can manage the table directly. * - * TODO: handling changes to the connection string so that we only validate what is being changed. - * * @param {{connectionString: string | null, tableName: string | null}} params - * @returns {{error: string | null, success: boolean}} + * @returns {Promise<{error: string | null, success: boolean}>} */ validateConnection: async function ({ connectionString = null, tableName = null, }) { if (!connectionString) throw new Error("No connection string provided"); - if (!tableName) throw new Error("No table name provided"); - let pgClient = null; try { - pgClient = this.client(connectionString); - await pgClient.connect(); - const result = await pgClient.query(this.getTablesSql); + const timeoutPromise = new Promise((resolve) => { + setTimeout(() => { + resolve({ + error: `Connection timeout (${(PGVector.connectionTimeout / 1000).toFixed(0)}s). Please check your connection string and try again.`, + success: false, + }); + }, PGVector.connectionTimeout); + }); - if (result.rows.length !== 0 && !!tableName) { - const tableExists = result.rows.some( - (row) => row.tablename === tableName - ); - if (!!tableExists) - throw new Error( - `The vector table ${tableName} already exists. Please use a table name that does not already exist in the database.` - ); - } + const connectionPromise = new Promise(async (resolve) => { + let pgClient = null; + try { + pgClient = this.client(connectionString); + await pgClient.connect(); + const result = await pgClient.query(this.getTablesSql); + + if (result.rows.length !== 0 && !!tableName) { + const tableExists = result.rows.some( + (row) => row.tablename === tableName + ); + if (tableExists) + await this.validateExistingEmbeddingTableSchema( + pgClient, + tableName + ); + } + resolve({ error: null, success: true }); + } catch (err) { + resolve({ error: err.message, success: false }); + } finally { + if (pgClient) await pgClient.end(); + } + }); - return { error: null, success: true }; + // Race the connection attempt against the timeout + const result = await Promise.race([connectionPromise, timeoutPromise]); + return result; } catch (err) { - return { error: err.message, success: false }; - } finally { - if (pgClient) await pgClient.end(); + this.log("Validation Error:", err.message); + let readableError = err.message; + switch (true) { + case err.message.includes("ECONNREFUSED"): + readableError = + "The host could not be reached. Please check your connection string and try again."; + break; + default: + break; + } + return { error: readableError, success: false }; } }, diff --git a/server/utils/vectorStore/resetAllVectorStores.js b/server/utils/vectorStore/resetAllVectorStores.js index 3bb9a5ec4ce..f47fc970b2c 100644 --- a/server/utils/vectorStore/resetAllVectorStores.js +++ b/server/utils/vectorStore/resetAllVectorStores.js @@ -30,11 +30,22 @@ async function resetAllVectorStores({ vectorDbKey }) { vectorDbKey ); const VectorDb = getVectorDbClass(vectorDbKey); - for (const workspace of workspaces) { - try { - await VectorDb["delete-namespace"]({ namespace: workspace.slug }); - } catch (e) { - console.error(e.message); + + if (vectorDbKey === "pgvector") { + /* + pgvector has a reset method that drops the entire embedding table + which is required since if this function is called we will need to + reset the embedding column VECTOR dimension value and you cannot change + the dimension value of an existing vector column. + */ + await VectorDb.reset(); + } else { + for (const workspace of workspaces) { + try { + await VectorDb["delete-namespace"]({ namespace: workspace.slug }); + } catch (e) { + console.error(e.message); + } } } From cfb14755f467d0b58e4b99d1b7d75817369f5f31 Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Fri, 9 May 2025 11:54:52 -0700 Subject: [PATCH 6/8] update setup --- .../utils/vectorDbProviders/pgvector/SETUP.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/server/utils/vectorDbProviders/pgvector/SETUP.md b/server/utils/vectorDbProviders/pgvector/SETUP.md index 0b2503fd313..898ce92c429 100644 --- a/server/utils/vectorDbProviders/pgvector/SETUP.md +++ b/server/utils/vectorDbProviders/pgvector/SETUP.md @@ -33,6 +33,37 @@ eg: `postgresql://dbuser:dbuserpass@localhost:5432/yourdb` _optional_ - set a table name you wish to have AnythingLLM store vectors to. By default this is `anythingllm_vectors` +## Common Questions + +### Can I use an existing table as a vector database? + +Yes, you can use an existing table as a vector database. However, AnythingLLM **requires** that the table be at least minimally conform to the expected schema - this can be seen in the [index.js](./index.js) file. + +It is **absolutely critical** that the `embedding` column's `VECTOR(XXXX)` dimensions match the dimension of the embedder in AnythingLLM. The default embedding model is 384 dimensions. However, if you are using a custom embedder, you will need to ensure that the dimension value is set correctly. + +### Validate the connection to the database + +When setting the connection string in or table name via the AnythingLLM UI, the following validations will be attempted: + +- Validate the connection string +- Validate the table name +- Run test connection to ensure the table exists and is accessible by the connection string used +- Check if the table name already exists and if so, validate that it is an embedding table with the correct schema + +### My embedding table is not present in the DB + +The embedding storage table is created by AnythingLLM **on the first upsert** of a vector. If you have not yet embedding any documents, the table will not be present in the DB. + +### How do I reset my vector database? + +_at the workspace level in Settings > Vector Database_ + +You can use the "Reset Vector Database" button in the AnythingLLM UI to reset your vector database. This will drop all vectors within that workspace, but the table will remain in the DB. + +_reset the vector database at the db level_ + +For this, you will need to `DROP TABLE` from the command line or however you manage your DB. Once the table is dropped, it will be recreated by AnythingLLM on the next upsert. + ## Troubleshooting ### Cannot connect to DB From 151803f43b2fd058254abedf3f562382c48971f5 Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Fri, 9 May 2025 11:56:05 -0700 Subject: [PATCH 7/8] update README --- server/utils/vectorDbProviders/pgvector/SETUP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/server/utils/vectorDbProviders/pgvector/SETUP.md b/server/utils/vectorDbProviders/pgvector/SETUP.md index 898ce92c429..ce6d2c7304e 100644 --- a/server/utils/vectorDbProviders/pgvector/SETUP.md +++ b/server/utils/vectorDbProviders/pgvector/SETUP.md @@ -27,7 +27,7 @@ _this can be done via the UI or by directly editing the `.env` file_ First, obtain a valid connection string for the user, credentials, and db you want to target. eg: `postgresql://dbuser:dbuserpass@localhost:5432/yourdb` -> ![NOTE] +> [!IMPORTANT] > If you have an existing table that you want to use as a vector database, AnythingLLM **requires** that the table be > at least minimally conform to the expected schema - this can be seen in the [index.js](./index.js) file. From e6951e8cfd8b20680a777463305f3fa99652b1d0 Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Fri, 9 May 2025 12:14:20 -0700 Subject: [PATCH 8/8] update doc --- .../utils/vectorDbProviders/pgvector/SETUP.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/server/utils/vectorDbProviders/pgvector/SETUP.md b/server/utils/vectorDbProviders/pgvector/SETUP.md index ce6d2c7304e..fb7b3b6e5ed 100644 --- a/server/utils/vectorDbProviders/pgvector/SETUP.md +++ b/server/utils/vectorDbProviders/pgvector/SETUP.md @@ -35,6 +35,23 @@ _optional_ - set a table name you wish to have AnythingLLM store vectors to. By ## Common Questions +### I cannot connect to the DB (Running AnythingLLM in Docker) + +If you are running AnythingLLM in Docker, you will need to ensure that the DB is accessible from the container. +If you are running your DB in another Docker container **or** on the host machine, you will need to ensure that the container can access the DB. + +`localhost` will not work in this case as it will attempt to connect to the DB _inside the AnythingLLM container_ instead of the host machine or another container. + +You will need to use the `host.docker.internal` (or `172.17.0.1` on Linux/Ubuntu) address. + +``` +on Mac or Windows: +postgresql://dbuser:dbuserpass@localhost:5432/yourdb => postgresql://dbuser:dbuserpass@host.docker.internal:5432/yourdb + +on Linux: +postgresql://dbuser:dbuserpass@localhost:5432/yourdb => postgresql://dbuser:dbuserpass@172.17.0.1:5432/yourdb +``` + ### Can I use an existing table as a vector database? Yes, you can use an existing table as a vector database. However, AnythingLLM **requires** that the table be at least minimally conform to the expected schema - this can be seen in the [index.js](./index.js) file.