Per il parsing di documenti PDF tecnici (come manuali ingegneristici, datasheet, specifiche software o articoli scientifici), le impostazioni standard di Open WebUI sono spesso insufficienti. I testi tecnici si distinguono per formati a due colonne, tabelle complesse, blocchi di codice e formule matematiche che i parser di testo standard tendono a frammentare o distruggere.
Per ottimizzare la qualità del RAG (Retrieval-Augmented Generation) su documentazione tecnica, segui questa configurazione all’interno dell’Admin Panel -> Settings -> Documents: [1, 2]
1. Il Motore di Estrazione (Content Extraction)
Evita assolutamente l’engine nativo predefinito, che confonde l’ordine di lettura delle colonne e distrugge le tabelle.
- Scelta Consigliata: Docling Document Extraction
- Perché: È lo strumento migliore in assoluto per documenti tecnici. Docling non si limita a “leggere” il testo, ma comprende il layout visivo. Mantiene intatta la struttura delle tabelle, riconosce le formule matematiche e non unisce erroneamente il testo scritto su due colonne separate.
- Come configurarlo: Richiede il deploy di un container Docker separato (
docling-serve). Nelle impostazioni dei documenti di Open WebUI dovrai inserire l’URL (es.http://host.docker.internal:5001) e attivare il motore. [1]
- Alternativa Veloce: Apache Tika
2. Parametri di Chunking (Frammentazione del testo)
Il testo deve essere spezzato in parti logiche (“chunks”) prima di essere memorizzato nel database vettoriale. Per la documentazione tecnica, i blocchi devono essere più grandi del normale per non isolare formule, definizioni o passaggi di codice. [1]
- Chunk Size (Dimensione del blocco):
1000–1500token- Motivazione: I concetti tecnici hanno bisogno di contesto. Se un frammento di codice o una spiegazione viene tagliata a metà, il modello non capirà il funzionamento.
- Chunk Overlap (Sovrapposizione):
150–200token- Motivazione: Una sovrapposizione generosa assicura che i concetti espressi a cavallo tra un blocco e l’altro mantengano la continuità semantica.
- Chunk Min Size Target: Abilitato / Impostato alto
- Motivazione: Questa opzione unisce in modo intelligente i paragrafi molto piccoli rimasti isolati dopo lo splitting semantico, evitando frammenti di testo privi di significato. [1]
3. Parametri di Ricerca Semantica (Query Parameters)
Quando fai una domanda su un manuale tecnico, l’AI ha bisogno di raccogliere molti dettagli da più sezioni diverse del documento.
- Top K:
8–12(Default solitamente è 4)- Motivazione: Il valore Top K indica quanti blocchi di testo rilevanti vengono inviati al modello per generare la risposta. Per i PDF tecnici, aumentare questo valore a circa 10 è fondamentale: permette all’AI di consultare contemporaneamente l’introduzione di un componente, i suoi dati elettrici e le note a piè di pagina sparsi nel manuale. [1]
- Embedding Model: Assicurati di utilizzare un modello di embedding moderno e con una finestra di contesto adeguata (ad esempio
bge-large-en-v1.5o modelli multilingua equivalenti se i tuoi documenti sono in italiano), in modo che le sfumature del gergo tecnico vengano indicizzate correttamente.
⚠️ Un ultimo dettaglio cruciale
I documenti tecnici sono spesso pieni di grafici o diagrammi di flusso. Se usi Docling, all’interno del campo di configurazione JSON (DOCLING_PARAMS) puoi attivare la voce picture_description. Se configurata con un modello di Vision (anche locale tramite Ollama), questa opzione genererà una descrizione testuale automatica dei diagrammi presenti nel PDF, rendendo ricercabili anche le immagini tecniche che altrimenti l’AI ignorerebbe del tutto. [1]
Hai la possibilità di avviare container Docker aggiuntivi sul tuo server (per installare Docling o Tika), oppure preferisci ottimizzare al massimo le opzioni già interne a Open WebUI senza installare altri servizi?
Aggiungere il numero di pagina alle risposte
Per fare in modo che il RAG di Open WebUI estragga i numeri di pagina dai PDF, li memorizzi e permetta al modello di vederli e citarli nelle sue risposte, devi configurare una variabile d’ambiente specifica a livello di server ed assicurarti di usare un motore di estrazione compatibile. [1, 2]
La procedura si articola in tre passaggi fondamentali:
Passaggio 1: Attivare i metadati della pagina nel server
Di base, Open WebUI estrae il testo ma non passa esplicitamente le chiavi dei metadati (come il numero di pagina) all’interno del contesto inviato al Modello. Per forzarlo a farlo, devi inserire una variabile d’ambiente nel sistema in cui gira Open WebUI (ad esempio nel tuo file docker-compose.yaml o nei parametri di avvio di Docker): [1]
env
RAG_SOURCE_METADATA_KEYS=page,page_label
Usa il codice con cautela.
- A cosa serve: Questa variabile dice a Open WebUI di prendere il valore
page(strutturato durante il parsing del PDF) e inserirlo direttamente all’interno dei tag<source>invisibili che circondano il testo inviato al modello. In questo modo, l’AI saprà esattamente da quale pagina proviene ogni singola informazione. - Nota: Essendo una variabile d’ambiente legata al backend, richiede il riavvio del container/server per essere applicata. [1, 2]
Passaggio 2: Utilizzare Docling per il parsing
Il motore di estrazione PDF predefinito non sempre mappa correttamente i numeri di pagina nel database vettoriale. Il metodo nativo più affidabile per l’estrazione strutturata delle pagine è Docling Document Extraction. [1]
Docling analizza visivamente il PDF e assegna a ogni blocco di testo un indicatore preciso della pagina (page number integer). [1]
- Importante: Se avevi già caricato i PDF prima di attivare Docling o la variabile d’ambiente, la semplice funzione “Reindex” da pannello amministrativo non basterà perché riutilizza il testo vecchio. Dovrai eliminare i PDF dalla Knowledge Base e caricarli nuovamente da capo per generare i nuovi metadati con i numeri di pagina. [1]
Passaggio 3: Istruire il Modello (System Prompt)
Anche se il modello ora riceve i numeri di pagina nascosti nei tag del RAG, potrebbe ignorarli se non esplicitamente istruito a mostrarli. Modifica il System Prompt del tuo modello o del tuo utente inserendo questa istruzione:
“Quando rispondi utilizzando i documenti di contesto forniti (RAG), racchiudi sempre le tue affermazioni inserendo una citazione precisa che includa il nome del file e il numero di pagina esatto da cui hai tratto l’informazione (es. [NomeDocumento.pdf, Pagina X]).”
🔍 Come verificare se funziona
Una volta completata la configurazione:
- Fai una domanda sul documento all’interno della chat.
- Quando il modello risponde, clicca sulla citazione numerica (il piccolo numero o icona che compare sotto o accanto al testo generato).
- Nel popup dei dettagli della fonte che si aprirà a schermo, vedrai il blocco di testo estratto e, in alto o tra i metadati del chunk, il numero di pagina corrispondente. [1, 2, 3]
Quale metodo utilizzi attualmente per avviare Open WebUI? Se usi Docker Compose, posso fornirti direttamente lo snippet di codice pronto da copiare sotto la voce environment:.
