{"id":45157404,"url":"https://github.com/couchbase-examples/rag-demo-llama-index","last_synced_at":"2026-02-20T05:02:39.614Z","repository":{"id":220556520,"uuid":"751932494","full_name":"couchbase-examples/rag-demo-llama-index","owner":"couchbase-examples","description":"A RAG demo using LlamaIndex that allows you to chat with your uploaded PDF documents","archived":false,"fork":false,"pushed_at":"2026-02-17T08:37:20.000Z","size":162,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-17T13:44:26.502Z","etag":null,"topics":["chatbot","couchbase","llama-index","rag","streamlit"],"latest_commit_sha":null,"homepage":"","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/couchbase-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-02-02T16:36:36.000Z","updated_at":"2026-02-17T08:37:17.000Z","dependencies_parsed_at":"2024-02-02T18:46:36.765Z","dependency_job_id":"8bd72bef-6dd2-4d17-88db-f6a3ebdb5f94","html_url":"https://github.com/couchbase-examples/rag-demo-llama-index","commit_stats":null,"previous_names":["couchbase-examples/rag-demo-llama-index"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/rag-demo-llama-index","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Frag-demo-llama-index","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Frag-demo-llama-index/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Frag-demo-llama-index/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Frag-demo-llama-index/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/rag-demo-llama-index/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Frag-demo-llama-index/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["chatbot","couchbase","llama-index","rag","streamlit"],"created_at":"2026-02-20T05:02:35.747Z","updated_at":"2026-02-20T05:02:39.608Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## RAG Demo using Couchbase, Streamlit, LlamaIndex, and OpenAI\n\nThis is a demo app built to chat with your custom PDFs using the vector search capabilities of Couchbase to augment the OpenAI results in a Retrieval-Augmented-Generation (RAG) model.\n\n## Two Vector Search Implementations\n\nThis demo provides two implementations showcasing different Couchbase vector search approaches:\n\n1. **FTS-Based Vector Search** (`FTS/chat_with_pdf_search.py`) - Uses Full Text Search indexes\n2. **GSI-Based Vector Search** (`GSI/chat_with_pdf_query.py`) - Uses Global Secondary Indexes\n\n### How does it work?\n\nYou can upload your PDFs with custom data \u0026 ask questions about the data in the chat box.\n\nFor each question, you will get two answers:\n\n- one using RAG (Couchbase logo)\n- one using pure LLM - OpenAI (🤖).\n\nFor RAG, we are using LlamaIndex, Couchbase Vector Search \u0026 OpenAI. We fetch parts of the PDF relevant to the question using Vector search \u0026 add it as the context to the LLM. The LLM is instructed to answer based on the context from the Vector Store.\n\n## Setup Instructions\n\n### Install dependencies\n\n`pip install -r requirements.txt`\n\n### Set the environment secrets\n\nCopy the `secrets.example.toml` file in `.streamlit` folder and rename it to `secrets.toml` and replace the placeholders with the actual values for your environment.\n\n**For FTS Vector Search** (`FTS/chat_with_pdf_search.py`):\n\n```toml\nOPENAI_API_KEY = \"\u003copen_ai_api_key\u003e\"\nDB_CONN_STR = \"\u003cconnection_string_for_couchbase_cluster\u003e\"\nDB_USERNAME = \"\u003cusername_for_couchbase_cluster\u003e\"\nDB_PASSWORD = \"\u003cpassword_for_couchbase_cluster\u003e\"\nDB_BUCKET = \"\u003cname_of_bucket_to_store_documents\u003e\"\nDB_SCOPE = \"\u003cname_of_scope_to_store_documents\u003e\"\nDB_COLLECTION = \"\u003cname_of_collection_to_store_documents\u003e\"\nINDEX_NAME = \"\u003cname_of_fts_index_with_vector_support\u003e\"\nAUTH_ENABLED = \"False\"\nLOGIN_PASSWORD = \"\u003cpassword_to_access_the_streamlit_app\u003e\"\n# Required for streamlit cloud as downloads are restricted to default locations\nNLTK_DATA = \"/tmp/nltk-corpora\"\nTIKTOKEN_CACHE_DIR = \"/tmp/tiktoken-cache\"\n```\n\n**For GSI Vector Search** (`GSI/chat_with_pdf_query.py`):\n\n```toml\nOPENAI_API_KEY = \"\u003copen_ai_api_key\u003e\"\nDB_CONN_STR = \"\u003cconnection_string_for_couchbase_cluster\u003e\"\nDB_USERNAME = \"\u003cusername_for_couchbase_cluster\u003e\"\nDB_PASSWORD = \"\u003cpassword_for_couchbase_cluster\u003e\"\nDB_BUCKET = \"\u003cname_of_bucket_to_store_documents\u003e\"\nDB_SCOPE = \"\u003cname_of_scope_to_store_documents\u003e\"\nDB_COLLECTION = \"\u003cname_of_collection_to_store_documents\u003e\"\nAUTH_ENABLED = \"False\"\nLOGIN_PASSWORD = \"\u003cpassword_to_access_the_streamlit_app\u003e\"\n# Required for streamlit cloud as downloads are restricted to default locations\nNLTK_DATA = \"/tmp/nltk-corpora\"\nTIKTOKEN_CACHE_DIR = \"/tmp/tiktoken-cache\"\n```\n\n\u003e Note: GSI approach does not require the `INDEX_NAME` parameter.\n\nThe last two parameters are required only if you are deploying on the streamlit cloud.\n\n## Approach 1: FTS-Based Vector Search\n\n### Prerequisites\n\n- Couchbase Server 7.6+ or Couchbase Capella\n\n### FTS Index Creation\n\nThe application **automatically creates the FTS index** when it starts up using the `create_fts_index()` function. The index is created with the following configuration:\n\n- **Index Name**: Specified by the `INDEX_NAME` environment variable\n- **Vector field**: `embedding` with 1536 dimensions\n- **Text field**: `text` (indexed and stored)\n- **Similarity metric**: `dot_product`\n- **Vector optimization**: Optimized for recall\n\nThe index definition uses dynamic type mapping based on your scope and collection names (e.g., `{scope_name}.{collection_name}`).\n\nIf you prefer to create the index manually through the Couchbase UI, you can do so:\n\n- [Couchbase Capella](https://docs.couchbase.com/cloud/search/import-search-index.html)\n\n  - Import the `index.json` file in FTS fodler in Capella using the instructions in the above documentation.\n\n### Run the FTS application\n\n```bash\nstreamlit run FTS/chat_with_pdf_search.py\n```\n\n---\n\n## Approach 2: GSI-Based Vector Search\n\n### Prerequisites\n\n- Couchbase Server 8.0+ or Couchbase Capella\n\nThis approach uses `CouchbaseQueryVectorStore` which leverages Global Secondary Index (GSI) for vector search. The vector search is performed using SQL++ queries with cosine similarity distance metric.\n\n### Understanding Vector Index Types\n\nCouchbase offers different types of vector indexes for GSI-based vector search:\n\n**Hyperscale Vector Indexes (BHIVE)**\n\n- Best for pure vector searches - content discovery, recommendations, semantic search\n- High performance with low memory footprint - designed to scale to billions of vectors\n- Optimized for concurrent operations - supports simultaneous searches and inserts\n- Use when: You primarily perform vector-only queries without complex scalar filtering\n- Ideal for: Large-scale semantic search, recommendation systems, content discovery\n\n**Composite Vector Indexes**\n\n- Best for filtered vector searches - combines vector search with scalar value filtering\n- Efficient pre-filtering - scalar attributes reduce the vector comparison scope\n- Use when: Your queries combine vector similarity with scalar filters that eliminate large portions of data\n- Ideal for: Compliance-based filtering, user-specific searches, time-bounded queries\n\n**Choosing the Right Index Type**\n\n- Start with Hyperscale Vector Index for pure vector searches and large datasets\n- Use Composite Vector Index when scalar filters significantly reduce your search space\n- Consider your dataset size: Hyperscale scales to billions, Composite works well for tens of millions to billions\n\nFor more details, see the [Couchbase Vector Index documentation](https://docs.couchbase.com/server/current/vector-index/use-vector-indexes.html).\n\n\u003e **Important:** The vector index should be created after ingesting the documents (uploading PDFs).\n\n**Example of Creating Vector Index via SQL++:**\n\nAfter uploading your PDFs, vector index is create using the below SQL++ query executed through the application. The application includes a `create_vector_index()` function that creates the index with the following configuration:\n\n```python\n# Example of how the vector index is created in the code\ncreate_query_string = f\"\"\"\nCREATE INDEX `idx_vector_embedding` \nON `{collection_name}` (vector VECTOR) \nUSING GSI \nWITH {{\n  \"dimension\": 1536,\n  \"description\": \"IVF,SQ8\",\n  \"similarity\": \"cosine\"\n}}\n\"\"\"\n```\n\nThe function:\n- Checks if the index already exists before creating\n- Creates a GSI vector index on the `vector` field\n- Configures the index with 1536 dimensions (matching OpenAI embeddings)\n- Uses cosine similarity for distance calculations\n- Applies IVF,SQ8 quantization for optimized performance\n\n**Understanding Index Configuration Parameters:**\n\nThe `description` parameter controls how Couchbase optimizes vector storage and search performance:\n\nFormat: `'IVF[\u003ccentroids\u003e],{PQ|SQ}\u003csettings\u003e'`\n\n**Centroids (IVF - Inverted File):**\n- Controls how the dataset is subdivided for faster searches\n- More centroids = faster search, slower training\n- Fewer centroids = slower search, faster training\n- If omitted (like `IVF,SQ8`), Couchbase auto-selects based on dataset size\n\n**Quantization Options:**\n- SQ (Scalar Quantization): `SQ4`, `SQ6`, `SQ8` (4, 6, or 8 bits per dimension)\n- PQ (Product Quantization): `PQ\u003csubquantizers\u003ex\u003cbits\u003e` (e.g., `PQ32x8`)\n- Higher values = better accuracy, larger index size\n\n**Common Examples:**\n- `IVF,SQ8` - Auto centroids, 8-bit scalar quantization (good default)\n- `IVF1000,SQ6` - 1000 centroids, 6-bit scalar quantization\n- `IVF,PQ32x8` - Auto centroids, 32 subquantizers with 8 bits\n\nFor detailed configuration options, see the [Quantization \u0026 Centroid Settings](https://docs.couchbase.com/server/current/vector-index/hyperscale-vector-index.html#algo_settings).\n\n\u003e **Note:** In GSI vector search, the distance represents the vector distance between the query and document embeddings. Lower distance indicates higher similarity, while higher distance indicates lower similarity. This demo uses cosine similarity for measuring document relevance.\n\n### Run the GSI application\n\n```bash\nstreamlit run GSI/chat_with_pdf_query.py\n```\n\n---\n\n\u003e **Note:** Upload a PDF document before asking questions, however the application still works if the data is already present in the capella.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Frag-demo-llama-index","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Frag-demo-llama-index","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Frag-demo-llama-index/lists"}