Setup Guide

Complete Setup Instructions

1. Clone Repository

git clone <your-repo-url>
cd localRagComosDB

2. Install Python Dependencies

# Create virtual environment (recommended)
python -m venv .venv

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Install and Setup Ollama

Windows / Mac / Linux

1. Download from https://ollama.com/
2. Install and start Ollama
3. Pull required models:

ollama pull mxbai-embed-large
ollama pull llama3

Verify:

ollama list

4. Setup Environment Variables

Copy the example file:

cp .env.example .env

The .env file is already configured with defaults that work for the emulator.

5. Choose Your Implementation

Option A: Simple (FAISS) - No Docker Required

# Load data
python simple/simple_load_data.py

# Test search
python simple/simple_vector_search.py "What is vector search?"

# Run interactive chat
python simple/simple_rag_chain.py

Option B: Cosmos DB - Docker Required

Step 1: Start Cosmos DB Emulator

Using Docker Compose (recommended):

docker-compose up -d

Or using Docker directly:

docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --name cosmos-emulator \
    --env AZURE_COSMOS_EMULATOR_PARTITION_COUNT=10 \
    --env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Step 2: Wait for emulator to start (60-90 seconds)

Check status:

docker logs cosmos-emulator

Look for: "Started"

Step 3: Run the application

# Load data
python cosmosdb/load_data.py

# Test search
python cosmosdb/vector_search.py "vector embedding policy"

# Run interactive chat
python cosmosdb/cosmos_rag_chain.py

Troubleshooting

Cosmos DB Connection Timeout

Error:

Connection to 172.17.0.2 timed out

Fix: Make sure you started the emulator with:

--env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1

This is already included in docker-compose.yml.

Ollama Not Found

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Restart Ollama
ollama serve

Import Errors

Make sure you installed dependencies:

pip install -r requirements.txt

Certificate Errors

The code automatically handles self-signed certificates with connection_verify=False. No manual certificate installation needed!

Next Steps

• Read README.md for detailed documentation
• Explore the code in simple/ for FAISS implementation
• Explore the code in cosmosdb/ for Cosmos DB implementation
• Customize the data sources in load_data.py files
• Adjust RAG parameters in .env file

Quick Reference

Environment Variables

USE_EMULATOR=true              # Use local emulator vs cloud
DATABASE_NAME=rag_local_llm_db # Database name
CONTAINER_NAME=docs            # Container name
EMBEDDINGS_MODEL=mxbai-embed-large  # Ollama embedding model
DIMENSIONS=1024                # Vector dimensions
CHAT_MODEL=llama3              # Ollama chat model
TOP_K=5                        # Number of context docs to retrieve

Docker Commands

# Start emulator
docker-compose up -d

# Stop emulator
docker-compose down

# View logs
docker logs cosmos-emulator

# Access Cosmos DB Explorer
# Open in browser: https://localhost:8081/_explorer/index.html

Project Commands

# Simple version
python simple/simple_load_data.py
python simple/simple_vector_search.py "your query"
python simple/simple_rag_chain.py

# Cosmos DB version
python cosmosdb/load_data.py
python cosmosdb/vector_search.py "your query"
python cosmosdb/cosmos_rag_chain.py