From 450c6d57845ece28f78524f50fff90ca564f13dd Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 4 Jun 2026 14:39:12 +0200 Subject: [PATCH] docs: aggiorna CLAUDE.md e README secondari per rispecchiare architettura attuale Rimuove riferimenti a Stage 1/Stage 2, md_optimizer.py, fix_chunks.py, --skip-optimize, _clean.md e _content_list_v2.json (tutti obsoleti). Aggiorna pipeline diagram, comandi, tabella architettura e input MinerU. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 44 +++++++++++++++++++------------------------- ingestion/README.md | 2 +- ollama/README.md | 2 +- 3 files changed, 21 insertions(+), 27 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 56f5b42..4208212 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,12 +16,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Missione -Pipeline RAG su documenti accademici. La conversione PDF → Markdown è delegata a **MinerU** (tool esterno). Questo repository si occupa solo di: pulizia Markdown, chunking, vettorizzazione e retrieval/generazione. +Pipeline RAG su documenti accademici. La conversione PDF → Markdown è delegata a **MinerU** (tool esterno). Questo repository si occupa solo di: chunking, vettorizzazione e retrieval/generazione. ``` -MinerU (esterno) → sources//auto/ +MinerU (esterno) → sources/_output/auto/.md ↓ - chunker.py (Stage 1: _clean.md + Stage 2: chunks.json) + chunker.py (chunks.json) ↓ ingest.py (embedding → ChromaDB) ↓ @@ -34,7 +34,7 @@ MinerU (esterno) → sources//auto/ - **Venv:** Usa `.venv/bin/python`. Mai `pip`/`python` di sistema. - **Niente LLM nella pipeline:** chunking e pulizia devono essere rule-based e riproducibili. -- **Input immutabile:** Non modificare mai i file originali in `sources//auto/`. Il `chunker.py` scrive solo `_clean.md` (prodotto derivato) nella stessa cartella e `chunks.json` in `chunks//`. +- **Input immutabile:** Non modificare mai i file in `sources/`. Il `chunker.py` scrive solo in `chunks//`. --- @@ -43,11 +43,8 @@ MinerU (esterno) → sources//auto/ MinerU produce una cartella per ogni documento. Posizionarla in `sources/`: ``` -sources//auto/_content_list_v2.json ← struttura ricca (tipo, livello, bbox) [RICHIESTO] -sources//auto/_model.json ← label di layout (doc_title, abstract…) [RACCOMANDATO] -sources//auto/.md ← Markdown grezzo (non usato dalla pipeline) -sources//auto/_middle.json ← dati intermedi (non usato) -sources//auto/images/ ← immagini estratte +sources/_output/auto/.md ← Markdown strutturato (input della pipeline) +sources/_output/auto/images/ ← immagini estratte ``` `` = nome del documento, usato in tutti i comandi come identificatore. @@ -60,18 +57,13 @@ sources//auto/images/ ← immagini estratte # Setup python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt -# Chunking unificato: Stage 1 (_clean.md) + Stage 2 (chunks.json) +# Chunking .venv/bin/python chunks/chunker.py --stem .venv/bin/python chunks/chunker.py # tutti gli stem in sources/ -.venv/bin/python chunks/chunker.py --stem --force # rigenera tutto -.venv/bin/python chunks/chunker.py --stem --skip-optimize # salta Stage 1 +.venv/bin/python chunks/chunker.py --stem --force # rigenera anche se già presente -# Solo Stage 1 (se serve rigenerare solo il _clean.md) -.venv/bin/python chunks/md_optimizer.py --stem --force - -# Verifica e correzione chunk +# Verifica qualità chunk .venv/bin/python chunks/verify_chunks.py --stem -.venv/bin/python chunks/fix_chunks.py --stem # Vettorizzazione (richiede Ollama attivo) .venv/bin/python ingestion/ingest.py --stem @@ -90,15 +82,19 @@ python -m venv .venv && source .venv/bin/activate && pip install -r requirements | File | Responsabilità | |------|---------------| -| `chunker.py` | Entry point unificato: chiama `md_optimizer` (Stage 1) poi esegue il chunking (Stage 2) | -| `md_optimizer.py` | Modulo Stage 1: `_content_list_v2.json` + `_model.json` → `_clean.md` | -| `config.py` | Tutti i parametri: `MAX_CHARS`, `MIN_CHARS`, `OVERLAP_SENTENCES`, `FRONTMATTER_HEADINGS`, `SOMMARIO_PATTERNS`, label sets model.json | +| `chunker.py` | Legge `.md`, produce `chunks.json` con regole deterministiche | +| `config.py` | Parametri: `MAX_CHARS`, `MIN_CHARS`, `CONTEXT_DEPTH`, `SKIP_HEADINGS`, `ATOMIC_TYPES` | | `verify_chunks.py` | Verifica qualità chunk (lunghezze, frasi spezzate, prefissi) | -| `fix_chunks.py` | Correzioni post-chunking (merge incompleti, split lunghi) | -`md_optimizer.py` è generico rispetto al documento: usa le strutture comuni di tutti gli output MinerU (`_content_list_v2.json` e `_model.json`) senza dipendere da pattern testuali lingua-specifici. I parametri documento-specifici (es. `FRONTMATTER_HEADINGS` per documenti italiani) sono in `config.py`. +Regole applicate dal chunker: +- 1 paragrafo = 1 chunk; paragrafi di sezioni diverse non si mescolano +- Split a confine di frase se il paragrafo supera `MAX_CHARS` +- Frasi spezzate tra paragrafi consecutivi vengono ri-fuse automaticamente +- Paragrafi brevi (< `MIN_CHARS`) vengono accorpati al successivo (stesso contesto) +- Sezioni in `SKIP_HEADINGS` saltate completamente; contenuto pre-heading saltato se `SKIP_PRE_HEADING=True` +- Tabelle, liste e code block sono blocchi atomici -Output: `chunks//chunks.json`, `chunks//meta.json`, `chunks//report.json` +Output: `chunks//chunks.json`, `chunks//meta.json` ### Vettorizzazione — `ingestion/ingest.py` @@ -117,7 +113,6 @@ Legge `chunks//chunks.json`, genera embedding via Ollama (`EMBED_MODEL`), ``` chunks//chunks.json chunks//meta.json -chunks//report.json chroma_db// ← collection ChromaDB ``` @@ -126,4 +121,3 @@ chroma_db// ← collection ChromaDB ## Skills custom - `/prepare-md ` — corregge il Markdown MinerU: sillabazione, artefatti, header malformati, gerarchia incoerente. Opera su una copia, non sull'originale. -- `/post-chunk` — verifica e perfeziona i chunk prima della vettorizzazione. diff --git a/ingestion/README.md b/ingestion/README.md index 1e86ba0..befce33 100644 --- a/ingestion/README.md +++ b/ingestion/README.md @@ -43,7 +43,7 @@ EMBED_MODEL = "nomic-embed-text" # ← cambia qui # Vettorizza un singolo documento .venv/bin/python ingestion/ingest.py --stem -# Vettorizza tutti i documenti trovati in step-6/ +# Vettorizza tutti i documenti trovati in chunks/ .venv/bin/python ingestion/ingest.py # Sovrascrive una collection già esistente diff --git a/ollama/README.md b/ollama/README.md index f52b24b..6451b14 100644 --- a/ollama/README.md +++ b/ollama/README.md @@ -1,6 +1,6 @@ # Ollama — Verifica Ambiente -Prima di procedere con la vettorizzazione (step 8) devi avere installato: +Prima di procedere con la vettorizzazione devi avere installato: - **Ollama** — server locale per LLM e embedding - un **modello di embedding** (es. `qwen3-embedding:0.6b`, `bge-m3`)