Knowledge base
Data store — sorgenti, formati, OCR, chunking, indicizzazione, metadati, permessi, qualità delle risposte e limiti.
La knowledge base (data store) è l'insieme dei contenuti che l'assistente consulta prima di rispondere. Senza knowledge base l'assistente conosce solo ciò che è scritto nel prompt di sistema: con una knowledge base indicizzata risponde citando i tuoi documenti aziendali.
Come vengono usati i documenti
A ogni messaggio la piattaforma cerca i passaggi più pertinenti, li inserisce nel contesto del modello e chiede di rispondere solo sulla base di quei passaggi. Il modello non memorizza i tuoi documenti e non li usa per l'addestramento.
Prima di iniziare
- Progetto esistente
- Documenti aggiornati e privi di informazioni contraddittorie
- Ruolo con permesso identity:datastore:write
Creare una knowledge base
Nome e descrizione
Usa un nome che identifichi l'ambito, ad esempio Listino e preparazioni 2026.
Una knowledge base per ambito è preferibile a un unico contenitore.
Lingua principale
Determina il modello di embedding e le regole di segmentazione. Per contenuti multilingua seleziona Automatico.
Aggiungi le sorgenti
Carica file, collega un sito web, un database o una API.
Attendi l'indicizzazione
Il conteggio dei documenti pronti si aggiorna in tempo reale.
Collega al progetto
Vai su Progetti, seleziona il progetto e aggiungi la knowledge base.
Tipi di sorgente
| Tipo | Cosa collega | Aggiornamento | Note |
|---|---|---|---|
| File | Documenti caricati manualmente o via API | Manuale | Adatto a listini, procedure, manuali |
| Sito web | Pagine raggiunte da una sitemap o da un crawl | Pianificato | Rispetta robots.txt |
| Database | Righe di una vista o di una query SQL | Pianificato o su evento | Sola lettura, credenziali cifrate |
| API | Risposta JSON di un endpoint | Pianificato | Utile per cataloghi dinamici |
| Cartella cloud | SharePoint, Google Drive, Dropbox | Continuo | Rispetta i permessi di origine |
Sorgente sito web
Parametri del crawler
| Parametro | Tipo | Obblig. | Default | Descrizione |
|---|---|---|---|---|
start_url | string | Sì | — | URL iniziale o sitemap, ad esempio https://www.acme.it/sitemap.xml |
max_depth | number | No | — | Profondità massima di navigazione dal punto di partenza. Predefinito 3. |
include_patterns | array | No | — | Espressioni di percorso da includere, ad esempio /servizi/ e /faq/ |
exclude_patterns | array | No | — | Percorsi da escludere, tipicamente /carrello/, /account/, /cerca |
respect_robots | boolean | No | — | Rispetta le direttive di robots.txt. Predefinito attivo. |
render_js | boolean | No | — | Esegue il JavaScript della pagina. Necessario per i siti a singola pagina. |
schedule | string | No | — | Frequenza di ripasso: manuale, giornaliera, settimanale, mensile. |
content_selector | string | No | — | Selettore CSS del contenuto principale, per escludere menu e piè di pagina. |
Escludi il rumore
Senza content_selector il crawler indicizza anche menu, banner e piè di pagina,
che compaiono in ogni pagina e degradano la ricerca. Indica il contenitore
dell'articolo, ad esempio main oppure .content.
Formati supportati
| Formato | Estensioni | Estrazione | Note |
|---|---|---|---|
| PDF testuale | .pdf | Testo, tabelle, struttura | Ottimale |
| PDF scansionato | .pdf | OCR | Vedi sezione dedicata |
| Word | .docx, .doc | Testo, tabelle, intestazioni | — |
| Excel | .xlsx, .xls, .csv | Righe come record | Prima riga come intestazione |
| PowerPoint | .pptx | Testo delle slide e note | — |
| Testo e Markdown | .txt, .md | Testo integrale | Formato consigliato |
| HTML | .html, .htm | Contenuto principale | Script e stili rimossi |
| JSON | .json, .jsonl | Campi mappabili | Serve una mappatura |
.eml, .msg | Corpo e allegati | Allegati elaborati a parte | |
| Immagini | .png, .jpg, .tiff | OCR | Solo se contengono testo |
Limiti per file: 100 MB, 2.000 pagine, 20 milioni di caratteri.
OCR per documenti scansionati
L'OCR si attiva automaticamente quando un PDF contiene meno di 100 caratteri estraibili per pagina.
| Impostazione | Valori | Effetto |
|---|---|---|
| Motore | Standard, Avanzato | Avanzato riconosce tabelle e moduli, costa di più |
| Lingue | Elenco di lingue | Migliora l'accuratezza; massimo 3 lingue |
| Correzione dell'inclinazione | Attiva, disattiva | Raddrizza le pagine acquisite storte |
| Riconoscimento tabelle | Attivo, disattivo | Preserva la struttura tabellare |
| Soglia di confidenza | Da 0 a 1 | Sotto la soglia il testo viene segnalato come incerto |
Qualità della scansione
Sotto i 200 DPI l'accuratezza crolla. Se disponi degli originali digitali, usali: l'OCR è sempre un ripiego.
Chunking e indicizzazione
Ogni documento viene diviso in chunk (passaggi) e trasformato in vettori numerici che consentono la ricerca semantica.
| Strategia | Come divide | Adatta a |
|---|---|---|
| Per paragrafo | Rispetta i confini dei paragrafi | Testo discorsivo, FAQ |
| Per intestazione | Usa la gerarchia dei titoli | Manuali, procedure |
| Dimensione fissa | Blocchi di lunghezza costante | Testo non strutturato |
| Per riga | Una riga uguale a un chunk | CSV, listini, cataloghi |
| Semantica | Divide dove cambia l'argomento | Documenti eterogenei |
| Parametro | Predefinito | Intervallo | Nota |
|---|---|---|---|
| Dimensione del chunk | 800 token | 200 – 2000 | Chunk grandi diluiscono la rilevanza |
| Sovrapposizione | 120 token | 0 – 400 | Evita di spezzare i concetti a metà |
| Chunk recuperati per domanda | 6 | 1 – 20 | Più chunk aumentano costo e latenza |
| Soglia minima di somiglianza | 0.68 | 0 – 1 | Sotto la soglia il risultato è scartato |
Stato di indicizzazione
| Stato | Significato | Azione |
|---|---|---|
| In coda | In attesa di elaborazione | Attendi |
| In elaborazione | Estrazione e segmentazione in corso | Attendi |
| Indicizzato | Consultabile dall'assistente | Nessuna |
| Parziale | Alcune pagine non estratte | Verifica il rapporto di elaborazione |
| Errore | Elaborazione fallita | Vedi il codice di errore |
| Obsoleto | Il sorgente è cambiato dopo l'indicizzazione | Reindicizza |
| Codice di errore | Causa | Rimedio |
|---|---|---|
PASSWORD_PROTECTED | PDF protetto | Rimuovi la protezione e ricarica |
UNSUPPORTED_FORMAT | Formato non gestito | Converti in PDF o Markdown |
FILE_TOO_LARGE | Oltre 100 MB | Dividi il documento |
EMPTY_CONTENT | Nessun testo estraibile | Attiva l'OCR |
SOURCE_UNREACHABLE | URL o database non raggiungibile | Verifica rete e credenziali |
QUOTA_EXCEEDED | Limite del piano superato | Rimuovi documenti o aggiorna il piano |
L'evento document.failed notifica gli errori ai tuoi sistemi: vedi
Webhook.
Aggiornamento incrementale e reindicizzazione
| Modalità | Cosa elabora | Quando usarla |
|---|---|---|
| Incrementale | Solo i documenti nuovi o modificati | Aggiornamenti ordinari |
| Completa | Tutti i documenti | Dopo aver cambiato la segmentazione |
| Singolo documento | Il documento selezionato | Correzione puntuale |
La reindicizzazione completa non interrompe il servizio: l'indice precedente resta attivo finché il nuovo non è pronto, poi lo scambio è istantaneo.
Rilevamento delle modifiche
Per file e cartelle cloud la piattaforma confronta l'impronta del contenuto: ricaricare un file identico non consuma quota di elaborazione.
Metadati e filtri
I metadati consentono di restringere la ricerca a un sottoinsieme di documenti.
| Metadato | Tipo | Esempio | Uso |
|---|---|---|---|
categoria | stringa | preparazioni | Filtro per argomento |
sede | stringa | MI01 | Contenuti specifici di una sede |
lingua | stringa | it | Ricerca nella lingua della conversazione |
valido_dal | data | 2026-01-01 | Esclude i documenti non ancora in vigore |
valido_al | data | 2026-12-31 | Esclude i documenti scaduti |
riservatezza | stringa | pubblico | Controllo di accesso |
versione | stringa | 3.1 | Distingue le revisioni |
{
"filters": {
"all": [
{ "field": "riservatezza", "op": "eq", "value": "pubblico" },
{ "field": "valido_al", "op": "gte", "value": "$today" }
],
"any": [
{ "field": "sede", "op": "eq", "value": "$context.sede" },
{ "field": "sede", "op": "empty" }
]
}
}Permessi di accesso ai documenti
| Livello | Chi vede il contenuto | Uso tipico |
|---|---|---|
pubblico | Tutti gli utenti del widget | Listini, orari, FAQ |
autenticato | Solo utenti identificati | Condizioni contrattuali |
interno | Solo operatori nella Console | Procedure operative |
per_gruppo | Utenti con l'attributo indicato | Documentazione per rivenditori |
Il filtro non è una barriera
Non caricare in una knowledge base collegata a un progetto pubblico documenti che non possono essere divulgati. Un filtro mal configurato o una domanda formulata in modo insolito possono esporli. Usa knowledge base separate.
Valutazione della qualità delle risposte
Costruisci un set di domande di riferimento
Almeno 30 domande reali, con la risposta corretta e il documento che la contiene. Puoi importarle da un CSV.
Esegui la valutazione
La piattaforma esegue le domande e confronta le risposte con quelle attese.
Leggi le metriche
Copertura, precisione delle citazioni, tasso di fallback, latenza media.
Correggi le lacune
Per ogni domanda senza risposta: manca il documento, il chunk è troppo grande o il testo è ambiguo.
| Metrica | Definizione | Valore accettabile |
|---|---|---|
| Copertura | Domande con almeno un chunk pertinente | Superiore al 90% |
| Precisione delle citazioni | Risposte la cui citazione contiene davvero l'informazione | Superiore all'85% |
| Tasso di fallback | Risposte in cui l'assistente dichiara di non sapere | Inferiore al 10% |
| Somiglianza media | Punteggio medio dei chunk recuperati | Superiore a 0.72 |
| Latenza di recupero | Tempo della sola ricerca | Inferiore a 400 millisecondi |
Citazioni obbligatorie
Attiva Richiedi citazioni nel progetto: l'assistente non può affermare nulla che non sia supportato da un chunk recuperato, e mostra la fonte all'utente.
Buone pratiche di strutturazione
- Un argomento per documento. Un file con 12 argomenti produce chunk confusi.
- Titoli espliciti. "Preparazione all'ecografia addominale" batte "Sezione 4.2".
- Risposte autoconsistenti. Ogni paragrafo deve reggersi da solo: evita "come detto sopra" e "vedi il capitolo precedente".
- Niente tabelle complesse. Le tabelle con celle unite si segmentano male: convertile in elenchi.
- Un solo documento per informazione. Il listino deve esistere in un unico file. Le versioni duplicate producono risposte contraddittorie.
- Date esplicite. Scrivi "valido dal 1 gennaio 2026", non "da quest'anno".
- Rimuovi l'obsoleto. Archivia i documenti superati invece di lasciarli indicizzati.
- Glossario aziendale. Un documento che spiega sigle e nomi commerciali migliora la ricerca in modo sproporzionato rispetto alla sua dimensione.
Caricamento via API
/identity/v1/datastores/{datastoreId}/documentsAPI KeyCarica un documento nella knowledge base con metadati personalizzati.
/identity/v1/datastores/{datastoreId}/reindexAPI KeyAvvia una reindicizzazione completa o incrementale.
Identificativo della knowledge base
dst_6c4a80f19e2b47d3Usalo nel percorso delle chiamate API e nella configurazione del progetto.
Limiti
| Limite | Starter | Business | Enterprise |
|---|---|---|---|
| Documenti per knowledge base | 200 | 5.000 | 100.000 |
| Dimensione totale | 500 MB | 20 GB | 500 GB |
| Dimensione per file | 25 MB | 100 MB | 250 MB |
| Sorgenti web | 1 | 10 | 50 |
| Pagine per crawl | 200 | 5.000 | 50.000 |
| Reindicizzazioni complete al mese | 4 | 30 | Illimitate |
| Pagine OCR al mese | 200 | 5.000 | Da contratto |
Passi successivi
- Modelli AI — imposta le regole di uso delle fonti nel prompt.
- Progetti — collega la knowledge base e attiva le citazioni.
- Conformità — conservazione, cancellazione e trattamento dei dati.