{"id":17381863,"url":"https://github.com/daveebbelaar/pgvectorscale-rag-solution","last_synced_at":"2025-04-04T20:02:47.086Z","repository":{"id":257828089,"uuid":"859714381","full_name":"daveebbelaar/pgvectorscale-rag-solution","owner":"daveebbelaar","description":"An implementation of pgvectorscale to a build powerful RAG solutions.","archived":false,"fork":false,"pushed_at":"2024-11-06T15:25:56.000Z","size":81,"stargazers_count":150,"open_issues_count":1,"forks_count":88,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-28T19:04:43.570Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.timescale.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daveebbelaar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-19T06:44:29.000Z","updated_at":"2025-03-27T09:15:31.000Z","dependencies_parsed_at":"2024-12-13T19:44:54.357Z","dependency_job_id":"ccb39149-e97e-4108-96c5-87ac0fa6e2f4","html_url":"https://github.com/daveebbelaar/pgvectorscale-rag-solution","commit_stats":null,"previous_names":["daveebbelaar/pgvectorscale-rag-solution"],"tags_count":0,"template":false,"template_full_name":"datalumina/datalumina-project-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daveebbelaar%2Fpgvectorscale-rag-solution","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daveebbelaar%2Fpgvectorscale-rag-solution/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daveebbelaar%2Fpgvectorscale-rag-solution/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daveebbelaar%2Fpgvectorscale-rag-solution/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daveebbelaar","download_url":"https://codeload.github.com/daveebbelaar/pgvectorscale-rag-solution/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242657,"owners_count":20907130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-16T07:02:02.496Z","updated_at":"2025-04-04T20:02:47.056Z","avatar_url":"https://github.com/daveebbelaar.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Building a High-Performance RAG Solution with Pgvectorscale and Python\n\nThis tutorial will guide you through setting up and using `pgvectorscale` with Docker and Python, leveraging OpenAI's powerful `text-embedding-3-small` model for embeddings. You'll learn to build a cutting-edge RAG (Retrieval-Augmented Generation) solution, combining advanced retrieval techniques (including hybrid search) with intelligent answer generation based on the retrieved context. Perfect for AI engineers looking to enhance their projects with state-of-the-art vector search and generation capabilities with the power of PostgreSQL.\n\n## YouTube Tutorial\nYou can watch the full tutorial here on [YouTube](https://youtu.be/hAdEuDBN57g).\n\n## Pgvectorscale Documentation\n\nFor more information about using PostgreSQL as a vector database in AI applications with Timescale, check out these resources:\n\n- [GitHub Repository: pgvectorscale](https://github.com/timescale/pgvectorscale)\n- [Blog Post: PostgreSQL and Pgvector: Now Faster Than Pinecone, 75% Cheaper, and 100% Open Source](https://www.timescale.com/blog/pgvector-is-now-as-fast-as-pinecone-at-75-less-cost/)\n- [Blog Post: RAG Is More Than Just Vector Search](https://www.timescale.com/blog/rag-is-more-than-just-vector-search/)\n- [Blog Post: A Python Library for Using PostgreSQL as a Vector Database in AI Applications](https://www.timescale.com/blog/a-python-library-for-using-postgresql-as-a-vector-database-in-ai-applications/)\n\n## Why PostgreSQL?\n\nUsing PostgreSQL with pgvectorscale as your vector database offers several key advantages over dedicated vector databases:\n\n- PostgreSQL is a robust, open-source database with a rich ecosystem of tools, drivers, and connectors. This ensures transparency, community support, and continuous improvements.\n\n- By using PostgreSQL, you can manage both your relational and vector data within a single database. This reduces operational complexity, as there's no need to maintain and synchronize multiple databases.\n\n- Pgvectorscale enhances pgvector with faster search capabilities, higher recall, and efficient time-based filtering. It leverages advanced indexing techniques, such as the DiskANN-inspired index, to significantly speed up Approximate Nearest Neighbor (ANN) searches.\n\nPgvectorscale Vector builds on top of [pgvector](https://github.com/pgvector/pgvector), offering improved performance and additional features, making PostgreSQL a powerful and versatile choice for AI applications.\n\n## Prerequisites\n\n- Docker\n- Python 3.7+\n- OpenAI API key\n- PostgreSQL GUI client\n\n## Steps\n\n1. Set up Docker environment\n2. Connect to the database using a PostgreSQL GUI client (I use TablePlus)\n3. Create a Python script to insert document chunks as vectors using OpenAI embeddings\n4. Create a Python function to perform similarity search\n\n## Detailed Instructions\n\n### 1. Set up Docker environment\n\nCreate a `docker-compose.yml` file with the following content:\n\n```yaml\nservices:\n  timescaledb:\n    image: timescale/timescaledb-ha:pg16\n    container_name: timescaledb\n    environment:\n      - POSTGRES_DB=postgres\n      - POSTGRES_PASSWORD=password\n    ports:\n      - \"5432:5432\"\n    volumes:\n      - timescaledb_data:/var/lib/postgresql/data\n    restart: unless-stopped\n\nvolumes:\n  timescaledb_data:\n```\n\nRun the Docker container:\n\n```bash\ndocker compose up -d\n```\n\n### 2. Connect to the database using a PostgreSQL GUI client\n\n- Open client\n- Create a new connection with the following details:\n  - Host: localhost\n  - Port: 5432\n  - User: postgres\n  - Password: password\n  - Database: postgres\n\n### 3. Create a Python script to insert document chunks as vectors\n\nSee `insert_vectors.py` for the implementation. This script uses OpenAI's `text-embedding-3-small` model to generate embeddings.\n\n### 4. Create a Python function to perform similarity search\n\nSee `similarity_search.py` for the implementation. This script also uses OpenAI's `text-embedding-3-small` model for query embedding.\n\n## Usage\n\n1. Create a copy of `example.env` and rename it to `.env`\n2. Open `.env` and fill in your OpenAI API key. Leave the database settings as is\n3. Run the Docker container\n4. Install the required Python packages using `pip install -r requirements.txt`\n5. Execute `insert_vectors.py` to populate the database\n6. Play with `similarity_search.py` to perform similarity searches\n\n## Using ANN search indexes to speed up queries\n\nTimescale Vector offers indexing options to accelerate similarity queries, particularly beneficial for large vector datasets (10k+ vectors):\n\n1. Supported indexes:\n   - timescale_vector_index (default): A DiskANN-inspired graph index\n   - pgvector's HNSW: Hierarchical Navigable Small World graph index\n   - pgvector's IVFFLAT: Inverted file index\n\n2. The DiskANN-inspired index is Timescale's latest offering, providing improved performance. Refer to the [Timescale Vector explainer blog](https://www.timescale.com/blog/pgvector-is-now-as-fast-as-pinecone-at-75-less-cost/) for detailed information and benchmarks.\n\nFor optimal query performance, creating an index on the embedding column is recommended, especially for large vector datasets.\n\n## Cosine Similarity in Vector Search\n\n### What is Cosine Similarity?\n\nCosine similarity measures the cosine of the angle between two vectors in a multi-dimensional space. It's a measure of orientation rather than magnitude.\n\n- Range: -1 to 1 (for normalized vectors, which is typical in text embeddings)\n- 1: Vectors point in the same direction (most similar)\n- 0: Vectors are orthogonal (unrelated)\n- -1: Vectors point in opposite directions (most dissimilar)\n\n### Cosine Distance\n\nIn pgvector, the `\u003c=\u003e` operator computes cosine distance, which is 1 - cosine similarity.\n\n- Range: 0 to 2\n- 0: Identical vectors (most similar)\n- 1: Orthogonal vectors\n- 2: Opposite vectors (most dissimilar)\n\n### Interpreting Results\n\nWhen you get results from similarity_search:\n\n- Lower distance values indicate higher similarity.\n- A distance of 0 would mean exact match (rarely happens with embeddings).\n- Distances closer to 0 indicate high similarity.\n- Distances around 1 suggest little to no similarity.\n- Distances approaching 2 indicate opposite meanings (rare in practice).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaveebbelaar%2Fpgvectorscale-rag-solution","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaveebbelaar%2Fpgvectorscale-rag-solution","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaveebbelaar%2Fpgvectorscale-rag-solution/lists"}