Skip to content

Commit 2a67c18

Browse files
strawberry-codestrawberry-code
committed
docs: aggiorna README EN e IT con architetture Ollama, collection multiple, setup completo e diagrammi
1 parent 3bc5e59 commit 2a67c18

File tree

2 files changed

+193
-42
lines changed

2 files changed

+193
-42
lines changed

‎README.it.md‎

Lines changed: 145 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,23 @@
1-
# Piattaforma RAG - Ricerca Documentazione Self-Hosted
1+
# RAG Platform - Ricerca Documentazione Self-Hosted
22

33
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
44
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
55

66
> 🇬🇧 **English Version**: [README.md](README.md)
77
8-
Una piattaforma RAG (Retrieval-Augmented Generation) completa per indicizzare e interrogare documentazione locale usando ricerca semantica con embeddings vettoriali.
8+
Una piattaforma RAG (Retrieval-Augmented Generation) completa per indicizzare e cercare documentazione locale usando ricerca semantica con vector embeddings.
99

10-
## Avvio Rapido
10+
## Quick Start
1111

12-
### 1. Verifica Prerequisiti
12+
### 1. Installa Dipendenze
13+
14+
```bash
15+
python3 -m venv .venv
16+
source .venv/bin/activate
17+
pip install -r requirements.txt
18+
```
19+
20+
### 2. Verifica Prerequisiti
1321

1422
```bash
1523
python3 ragify.py doctor
@@ -20,26 +28,35 @@ Questo verifica:
2028
- Java (per Apache Tika)
2129
- Ollama con modello nomic-embed-text
2230
- Database vettoriale Qdrant
23-
- Spazio su disco
31+
- Spazio disco
2432

25-
Usa `--fix` per auto-installare i pacchetti Python mancanti.
33+
Usa `--fix` per installare automaticamente i pacchetti Python mancanti.
2634

27-
### 2. Indicizza la Documentazione
35+
### 3. Indicizza la Documentazione
2836

2937
```bash
30-
python3 ragify.py index ./docs
38+
python3 ragify.py index ./docs # → collection "docs"
3139
```
3240

3341
Ragify:
34-
- Estrae testo da oltre 1000 formati di file (PDF, DOCX, MD, codice)
35-
- Divide in chunks semantici
42+
- Estrae testo da 1000+ formati (PDF, DOCX, MD, file codice)
43+
- Divide in chunk semantici
3644
- Genera embeddings con Ollama
37-
- Archivia in Qdrant per recupero veloce
45+
- Salva in Qdrant per ricerca veloce
46+
47+
**Collection multiple**: Il nome della cartella diventa automaticamente il nome della collection. Questo permette di organizzare i contenuti per argomento ed evitare bias nei risultati - una ricerca nella collection fisica non restituirà risultati di matematica:
48+
49+
```bash
50+
python3 ragify.py index ./fisica # → collection "fisica"
51+
python3 ragify.py index ./matematica # → collection "matematica"
52+
python3 ragify.py index ./docs --collection custom # → nome esplicito
53+
```
3854

39-
### 3. Interroga i Documenti
55+
### 4. Interroga i Documenti
4056

4157
```bash
4258
python3 ragify.py query "come funziona l'autenticazione?"
59+
python3 ragify.py query "calcolo integrale" --collection matematica
4360
```
4461

4562
**📖 Documentazione completa**: [docs/RAGIFY.md](docs/RAGIFY.md) | **⚡ Guida rapida**: [docs/QUICK_GUIDE.md](docs/QUICK_GUIDE.md)
@@ -52,20 +69,20 @@ python3 ragify.py query "come funziona l'autenticazione?"
5269

5370
- ✅ **Nessun server HTTP** - Accesso diretto al filesystem
5471
- ✅ **Formati universali** - PDF, DOCX, codice, markdown (via Apache Tika)
55-
- ✅ **Deduplicazione intelligente** - Aggiornamenti incrementali basati su hash SHA-256
72+
- ✅ **Deduplicazione smart** - Aggiornamenti incrementali basati su hash SHA-256
5673
- ✅ **Chunking semantico** - Strategie specifiche per tipo di file
57-
- ✅ **CLI tutto-in-uno** - Comandi index, query, list, reset
74+
- ✅ **CLI all-in-one** - Comandi index, query, list, reset
5875

5976
### Come Funziona
6077

6178
```
6279
Documenti Locali
6380
↓
64-
[ragify index] → Estrai testo, chunking, embeddings
81+
[ragify index] → Estrai testo, chunk, embed
6582
↓
6683
[Ollama nomic-embed-text] → Genera vettori (768-dim)
6784
↓
68-
[Qdrant] → Archivia vettori + metadata
85+
[Qdrant] → Salva vettori + metadati
6986
↓
7087
[ragify query] → Ricerca semantica
7188
```
@@ -76,10 +93,28 @@ Documenti Locali
7693

7794
### Prerequisiti
7895

79-
1. **Docker** - Per il database vettoriale Qdrant
80-
2. **Ollama** - Per gli embeddings ([ollama.ai](https://ollama.ai/))
96+
1. **Docker + Qdrant** - Database vettoriale
97+
```bash
98+
# Installa Docker: https://docs.docker.com/engine/install/
99+
docker run -d --name qdrant --restart unless-stopped \
100+
-p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
101+
```
102+
2. **Ollama** - Per embeddings ([ollama.ai](https://ollama.ai/))
103+
```bash
104+
curl -fsSL https://ollama.ai/install.sh | sh
105+
ollama pull nomic-embed-text
106+
# Ollama gira come servizio systemd, parte automaticamente al boot
107+
sudo systemctl enable ollama && sudo systemctl start ollama
108+
```
81109
3. **Python 3.10+** - Con pip
82-
4. **Java 8+** - Per Apache Tika (opzionale ma consigliato)
110+
4. **Java 21** - Per Apache Tika (opzionale ma consigliato)
111+
```bash
112+
# Installa via sdkman (https://sdkman.io)
113+
sudo apt install zip unzip -y # Ubuntu/Debian
114+
curl -s "https://get.sdkman.io" | bash
115+
source "$HOME/.sdkman/bin/sdkman-init.sh"
116+
sdk install java 21-zulu
117+
```
83118

84119
### Setup
85120

@@ -90,52 +125,96 @@ docker run -d -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdran
90125
# 2. Installa Ollama e scarica il modello
91126
ollama pull nomic-embed-text
92127

93-
# 3. Installa le dipendenze Python
128+
# 3. Installa dipendenze Python
94129
pip install -r requirements.txt
95130

96-
# 4. Verifica il sistema
131+
# 4. Verifica sistema
97132
python3 ragify.py doctor
98133
```
99134

100135
---
101136

102137
## Integrazione MCP (Opzionale)
103138

104-
Interroga i documenti indicizzati da Claude Desktop o altri client MCP.
139+
Interroga i documenti indicizzati da Claude Desktop o Claude Code via MCP.
140+
141+
### Installazione
105142

106-
### Installa MCP Server
143+
Nessuna installazione necessaria - usa [uvx](https://github.com/astral-sh/uv):
107144

108145
```bash
109-
npm install -g @qpd-v/mcp-server-ragdocs
146+
curl -LsSf https://astral.sh/uv/install.sh | sh
110147
```
111148

112-
### Configura Claude Desktop
149+
### Configurazione
113150

114-
Aggiungi a `~/Library/Application Support/Claude/claude_desktop_config.json`:
151+
Aggiungi alla config MCP:
152+
- **Claude Code**: `.mcp.json` nella root del progetto
153+
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
115154

116155
```json
117156
{
118157
"mcpServers": {
119-
"ragdocs": {
120-
"command": "/path/to/node",
121-
"args": ["/path/to/mcp-server-ragdocs/build/index.js"],
158+
"ragify": {
159+
"command": "uvx",
160+
"args": ["ragify-mcp"],
122161
"env": {
123162
"QDRANT_URL": "http://127.0.0.1:6333",
124-
"QDRANT_COLLECTION": "documentation",
125163
"OLLAMA_URL": "http://localhost:11434"
126164
}
127165
}
128166
}
129167
}
130168
```
131169

132-
Trova i percorsi:
133-
```bash
134-
which node # Percorso Node
135-
npm root -g # Percorso node_modules globale
170+
**📖 Setup MCP dettagliato**: [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
171+
172+
### Perché Ollama + nomic-embed-text è Necessario
173+
174+
Claude è un modello di generazione testo - non può produrre vector embeddings. La ricerca semantica richiede la conversione delle query in vettori numerici.
175+
176+
**Architettura A: Singolo Ollama Remoto (consigliata)**
177+
```
178+
┌────────────────┐ ┌─────────────────────────────────────────┐
179+
│ TUA MACCHINA │ │ SERVER REMOTO │
180+
│ │ │ │
181+
│ Claude │ query │ ┌─────────────────┐ ┌─────────┐ │
182+
│ │───────────────────────► │ Ollama + nomic │ ───► │ Qdrant │ │
183+
│ │ │ │ └─────────────────┘ └────┬────┘ │
184+
│ │◄──────────────────────────────────────────────────────┘ │
185+
│ │ risultati│ ▲ │
186+
│ │ │ │ indicizzazione │
187+
│ ragify index ─────────────────────►│ │
188+
│ │ │ │
189+
└────────────────┘ └─────────────────────────────────────────┘
136190
```
137191

138-
**📖 Setup MCP dettagliato**: [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
192+
**Architettura B: Ollama Locale per Query**
193+
```
194+
┌──────────────────────────┐ ┌─────────────────────────────┐
195+
│ TUA MACCHINA │ │ SERVER REMOTO │
196+
│ │ │ │
197+
│ Claude │ │ │
198+
│ │ "cerca X" │ │ │
199+
│ ▼ │ │ │
200+
│ ┌─────────────────┐ │ vettore │ ┌─────────┐ │
201+
│ │ Ollama + nomic │ ───────────────► │ Qdrant │ │
202+
│ │ (embedding) │ │ │ └────┬────┘ │
203+
│ └─────────────────┘ │ │ │ risultati │
204+
│ ▲ │ │ ▼ │
205+
│ └───────────────────────────────────────── │
206+
│ │ │ │
207+
│ │ │ ┌─────────────────┐ │
208+
│ ragify index ─────────────────────►│ │ Ollama + nomic │ │
209+
│ │ │ └─────────────────┘ │
210+
└──────────────────────────┘ └─────────────────────────────┘
211+
```
212+
213+
**Perché nomic-embed-text:** Embeddings allo stato dell'arte, solo ~274MB, ~50ms per query, 768 dimensioni.
214+
215+
Entrambe le architetture richiedono lo stesso modello `nomic-embed-text` per garantire la compatibilità dei vettori.
216+
217+
> **Sicurezza:** Se esponi Ollama remotamente, usa regole firewall, VPN, o reverse proxy con autenticazione.
139218
140219
---
141220

@@ -144,31 +223,56 @@ npm root -g # Percorso node_modules globale
144223
- **Ragify** - CLI per indicizzazione documenti (Python)
145224
- **Qdrant** - Database vettoriale (Docker)
146225
- **Ollama** - Embeddings locali (nomic-embed-text, 768-dim)
147-
- **MCP Server** - Interfaccia query per client MCP (opzionale)
226+
- **[ragify-mcp](https://pypi.org/project/ragify-mcp/)** - Server MCP per Claude Desktop/Code (opzionale)
148227

149228
---
150229

151230
## Documentazione
152231

153232
- **[Documentazione Ragify](docs/RAGIFY.md)** - Guida completa
154-
- **[Guida Rapida](docs/QUICK_GUIDE.md)** - Cheatsheet comandi
233+
- **[Riferimento Rapido](docs/QUICK_GUIDE.md)** - Cheatsheet comandi
155234
- **[Setup MCP](docs/MCP_SETUP.md)** - Integrazione Claude Desktop
156235

157236
---
158237

159238
## Variabili d'Ambiente
160239

240+
| Variabile | Default | Descrizione |
241+
|-----------|---------|-------------|
242+
| `QDRANT_URL` | http://localhost:6333 | URL server Qdrant |
243+
| `QDRANT_API_KEY` | - | API key per autenticazione Qdrant (opzionale) |
244+
| `OLLAMA_URL` | http://localhost:11434 | URL server Ollama |
245+
161246
```bash
162-
export OLLAMA_URL=http://localhost:11434
163-
export QDRANT_URL=http://localhost:6333
164-
export QDRANT_API_KEY=your-key # Opzionale, per Qdrant Cloud
247+
# Esempio: connessione a Qdrant remoto con API key
248+
export QDRANT_URL=http://tuo-server:6333
249+
export QDRANT_API_KEY=tua-chiave-segreta
250+
python3 ragify.py index ./docs
251+
```
252+
253+
---
254+
255+
## Indicizzazioni Lunghe (SSH)
256+
257+
Usa tmux per mantenere l'indicizzazione attiva dopo la disconnessione SSH:
258+
259+
```bash
260+
# Avvia sessione tmux
261+
tmux new -s ragify
262+
263+
# Esegui indicizzazione
264+
source .venv/bin/activate
265+
python3 ragify.py index ./docs
266+
267+
# Stacca: Ctrl+B, poi D
268+
# Riconnetti dopo: tmux attach -t ragify
165269
```
166270

167271
---
168272

169273
## Licenza
170274

171-
Licenza MIT - Vedi [LICENSE](LICENSE)
275+
MIT License - Vedi [LICENSE](LICENSE)
172276

173277
---
174278

‎README.md‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,53 @@ Add to your MCP config:
169169

170170
**📖 Detailed MCP setup**: [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
171171

172+
### Why Ollama + nomic-embed-text is Required
173+
174+
Claude is a text generation model - it cannot produce vector embeddings. Semantic search requires converting queries into numerical vectors.
175+
176+
**Architecture A: Single Remote Ollama (recommended)**
177+
```
178+
┌────────────────┐ ┌─────────────────────────────────────────┐
179+
│ YOUR MACHINE │ │ REMOTE SERVER │
180+
│ │ │ │
181+
│ Claude │ query │ ┌─────────────────┐ ┌─────────┐ │
182+
│ │───────────────────────► │ Ollama + nomic │ ───► │ Qdrant │ │
183+
│ │ │ │ └─────────────────┘ └────┬────┘ │
184+
│ │◄──────────────────────────────────────────────────────┘ │
185+
│ │ results │ ▲ │
186+
│ │ │ │ indexing │
187+
│ ragify index │
188+
│ │ │ │
189+
└────────────────┘ └─────────────────────────────────────────┘
190+
```
191+
192+
**Architecture B: Local Ollama for Queries**
193+
```
194+
┌──────────────────────────┐ ┌─────────────────────────────┐
195+
│ YOUR MACHINE │ │ REMOTE SERVER │
196+
│ │ │ │
197+
│ Claude │ │ │
198+
│ │ "search X" │ │ │
199+
│ ▼ │ │ │
200+
│ ┌─────────────────┐ │ vector │ ┌─────────┐ │
201+
│ │ Ollama + nomic │ ───────────────► │ Qdrant │ │
202+
│ │ (embedding) │ │ │ └────┬────┘ │
203+
│ └─────────────────┘ │ │ │ results │
204+
│ ▲ │ │ ▼ │
205+
│ └───────────────────────────────────────── │
206+
│ │ │ │
207+
│ │ │ ┌─────────────────┐ │
208+
│ ragify index ─────►│ │ Ollama + nomic │ │
209+
│ │ │ └─────────────────┘ │
210+
└──────────────────────────┘ └─────────────────────────────┘
211+
```
212+
213+
**Why nomic-embed-text:** State-of-the-art embeddings, only ~274MB, ~50ms per query, 768 dimensions.
214+
215+
Both architectures require the same `nomic-embed-text` model to ensure vector compatibility.
216+
217+
> **Security:** If exposing Ollama remotely, use firewall rules, VPN, or authenticated reverse proxy.
218+
172219
---
173220

174221
## Components
@@ -193,7 +240,7 @@ Add to your MCP config:
193240
| Variable | Default | Description |
194241
|----------|---------|-------------|
195242
| `QDRANT_URL` | http://localhost:6333 | Qdrant server URL |
196-
| `QDRANT_API_KEY` | - | API key for Qdrant authentication |
243+
| `QDRANT_API_KEY` | - | API key for Qdrant authentication (optional) |
197244
| `OLLAMA_URL` | http://localhost:11434 | Ollama server URL |
198245

199246
```bash

0 commit comments

Comments
 (0)