🔬 TurboQuant Ollama RAG System

Sistema completo per Retrieval-Augmented Generation (RAG) che permette di interrogare il paper accademico TurboQuant usando modelli LLM locali tramite Ollama.

📋 Panoramica

Questo sistema ti permette di:

• Indicizzare il paper TurboQuant (o qualsiasi PDF)
• Fare domande in linguaggio naturale sul contenuto
• Ottenere risposte basate sul contesto del documento
• Chat interattiva per esplorazione approfondita

Cos'è TurboQuant?

TurboQuant è un metodo di quantizzazione vettoriale che comprime vettori ad alta dimensionalità minimizzando la distorsione, con applicazioni in:

• Quantizzazione KV cache in Large Language Models
• Nearest neighbor search efficiente
• Compressione di embeddings

🚀 Installazione Rapida

Prerequisiti

• Python 3.8+
• Ollama installato e in esecuzione

Installazione Automatica

cd turboquant_ollama_system
chmod +x install.sh
./install.sh

Installazione Manuale

# 1. Crea ambiente virtuale
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. Installa dipendenze
pip install -r requirements.txt

# 3. Scarica modelli Ollama
ollama pull nomic-embed-text
ollama pull llama3.2

📖 Utilizzo

1. Indicizza il Documento

python main.py index /mnt/okcomputer/upload/2504.19874v1.pdf

Opzioni avanzate:

python main.py index paper.pdf \
    --chunk-size 1000 \
    --chunk-overlap 200 \
    --embedding-model mxbai-embed-large

2. Fai una Domanda

python main.py query "Cos'è TurboQuant?"

Con opzioni:

python main.py query "Quali sono i vantaggi rispetto alla Product Quantization?" \
    --top-k 5 \
    --temperature 0.3 \
    --llm-model mistral

3. Chat Interattiva

python main.py chat

Esempio di sessione:

❓ Domanda: Spiega l'Algorithm 1

💡 Risposta (llama3.2, 3.45s):
L'Algorithm 1 descrive TurboQuant ottimizzato per MSE...

📚 Fonti:
  1. Pagina 10 (Methods) - Score: 0.892
  2. Pagina 11 (Methods) - Score: 0.845

4. Info Sistema

python main.py info

🏗️ Architettura

┌─────────────────────────────────────────────────────────────┐
│                      USER QUERY                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   EMBEDDING  │───▶│    FAISS     │───▶│   RETRIEVAL  │  │
│  │   (Ollama)   │    │  VECTOR DB   │    │   (Top-K)    │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   CONTEXT    │───▶│     LLM      │───▶│   RESPONSE   │  │
│  │   BUILDER    │    │   (Ollama)   │    │   (RAG)      │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
└─────────────────────────────────────────────────────────────┘

📁 Struttura del Progetto

turboquant_ollama_system/
├── main.py                 # CLI principale
├── pdf_extractor.py        # Estrazione testo da PDF
├── embeddings.py           # Gestione embeddings
├── vector_store.py         # Vector database (FAISS)
├── rag_engine.py           # Motore RAG
├── requirements.txt        # Dipendenze
├── install.sh              # Script installazione
├── setup.py                # Setup package
├── data/                   # Dati (creato automaticamente)
├── vector_store/           # Indice FAISS (creato automaticamente)
└── cache/                  # Cache embeddings (creato automaticamente)

⚙️ Configurazione

Modelli Supportati

Embeddings (Ollama):

• nomic-embed-text (default, 768 dim)
• mxbai-embed-large (1024 dim, migliore qualità)
• snowflake-arctic-embed (1024 dim)

LLM (Ollama):

• llama3.2 (default, 3B params, veloce)
• mistral (7B params, migliore ragionamento)
• llama3.1 (8B params)
• phi3 (Microsoft, 3.8B params)

Parametri Chunking

Parametro	Default	Descrizione
chunk_size	800	Caratteri per chunk
chunk_overlap	150	Sovrapposizione tra chunk
top_k	5	Numero di fonti recuperate
temperature	0.3	Creatività LLM (0-1)

🔧 API Python

from rag_engine import OllamaRAG

# Inizializza
rag = OllamaRAG(
    embedding_backend="ollama",
    embedding_model="nomic-embed-text",
    llm_model="llama3.2"
)

# Indicizza
rag.index_document("paper.pdf", chunk_size=800)

# Query
response = rag.query(
    "Quali sono i teoremi principali?",
    k=5,
    temperature=0.3
)

print(response.answer)
print(f"Fonti: {len(response.sources)}")

📊 Prestazioni

Su NVIDIA A100 con llama3.2:

• Indicizzazione: ~2 minuti per 15 pagine
• Query: ~2-4 secondi (incluso retrieval + generation)
• Memoria: ~500MB RAM per indice

🛠️ Troubleshooting

Ollama non risponde

# Verifica che Ollama sia in esecuzione
curl http://localhost:11434/api/tags

# Avvia Ollama
ollama serve

Modello non trovato

# Scarica il modello
ollama pull nomic-embed-text
ollama pull llama3.2

Errore di memoria

# Usa modelli più piccoli
python main.py query "..." --llm-model phi3

📚 Esempi di Query

# Concetti base
python main.py query "Cos'è la quantizzazione vettoriale?"

# Algoritmi
python main.py query "Spiega l'Algorithm 2 step by step"

# Teoremi
python main.py query "Enuncia il Theorem 1 e spiega la dimostrazione"

# Confronti
python main.py query "Confronta TurboQuant con Product Quantization"

# Applicazioni
python main.py query "Come si applica TurboQuant alla KV cache?"

# Metriche
python main.py query "Quali sono i bound di distorsione per MSE?"

🤝 Contribuire

1. Fork del repository
2. Crea un branch (git checkout -b feature/xyz)
3. Commit (git commit -am 'Add feature')
4. Push (git push origin feature/xyz)
5. Apri una Pull Request

📝 License

MIT License - Vedi LICENSE per dettagli.

🙏 Riconoscimenti

• Paper: TurboQuant: Online Vector Quantization
• Ollama: ollama.com
• FAISS: facebookresearch/faiss

---

Creato con ❤️ per la ricerca e l'apprendimento