Crafter.ai
Torna alla documentazione

Linee Guida per la Strutturazione di Documenti (RAG)

Ultimo aggiornamento: 03/12/2025

Linee Guida per la Strutturazione di Documenti per Crafter.ai Introduzione Le seguenti linee guida sono pensate per ottimizzare la struttura dei document...

linee guida RAG documents in crafter.ailinea guida documenti RAG

Linee Guida per la Strutturazione di Documenti per Crafter.ai

Introduzione

Le seguenti linee guida sono pensate per ottimizzare la struttura dei documenti da utilizzare con la piattaforma Crafter.ai. Sfruttando i principi di chiarezza e strutturazione, è possibile migliorare drasticamente l'efficacia della sua funzionalità di Document Management e la qualità delle risposte generate.

L'obiettivo è rendere i documenti "Crafter.ai-friendly": facili da indicizzare e cercare per il sistema di Retrieval interno e, una volta trovati, facili da interpretare e utilizzare per il motore di Generation della piattaforma.

Principio di Modularità e Responsabilità Singola

Concetto chiave:La piattaforma Crafter.ai offre performance migliori quando i documenti sono granulari e focalizzati. Un documento che tenta di coprire troppi argomenti disparati in modo disorganizzato è difficile da indicizzare correttamente e da "comprendere" per il sistema.

Best Practices Principio di Modularità e Responsabilità Singola:

  • Un Concetto per Sezione: Struttura il documento in modo che ogni sezione (delimitata da un titolo H2 o H3) tratti un singolo argomento, concetto o domanda specifica.
  • File Focalizzati: Per argomenti molto vasti e complessi, valuta la possibilità di suddividerli in più file distinti. Ad esempio, invece di un unico file Manuale_Prodotto.pdf, potresti avere Installazione.md, Risoluzione_Problemi.md e Funzionalità_Avanzate.md. Questo migliora drasticamente la precisione del recupero.
  • Paragrafi Autocontenuti: Ogni paragrafo dovrebbe idealmente esprimere un'idea completa e iniziare con una frase-chiave (topic sentence) che ne riassuma il contenuto.

Gerarchia e Struttura Esplicita

Concetto chiave: Crafter.ai interpreta in modo più efficace i documenti che presentano una struttura chiara e gerarchica. Un documento ben formattato fornisce una mappa delle informazioni che il sistema può navigare e utilizzare per costruire risposte precise.

Best Practices Gerarchia e Struttura Esplicita:

  • Uso Corretto dei Titoli: Utilizza i tag di intestazione (H1, H2, H3, etc.) in modo gerarchico e coerente.(1)
  • Elenchi Puntati e Numerati: Per processi, liste di caratteristiche o passaggi, usa elenchi puntati o numerati. Questa formattazione "spezza" il testo e presenta le informazioni in un formato facilmente digeribile.
  • Tabelle per Dati Strutturati: Se devi presentare dati comparativi o tabulari, usa tabelle in formato Markdown. Sono molto più efficaci di una descrizione testuale.

Esempio di Struttura:

Guida alla Funzionalità X

2.1. Panoramica

Breve descrizione di cosa fa la funzionalità X.

Requisiti di Sistema

  • Sistema Operativo: Windows 11, macOS 13+
  • Memoria RAM: Minimo 8GB

2.3. Procedura di Configurazione

  1. Aprire il pannello Impostazioni.
  2. Navigare alla sezione "Integrazioni".
  3. Inserire la chiave API...

Chiarezza del Contenuto e Zero Ambiguità

Concetto chiave: La precisione di Crafter.ai dipende direttamente dalla chiarezza dei documenti sorgente. Il testo deve essere il più diretto e privo di ambiguità possibile per evitare interpretazioni errate da parte del sistema.

Best Practices Chiarezza del Contenuto e Zero Ambiguità:

Linguaggio Diretto: Scrivi frasi semplici e dirette. Evita costruzioni complesse, linguaggio eccessivamente metaforico o gergo non necessario.

  • ✅ Esempio (Cosa fare): "Per attivare la funzione, clicca sul pulsante 'Salva'."
  • ❌ Esempio (Cosa non fare): "L'attivazione della suddetta funzionalità è subordinata all'interazione dell'utente con l'elemento grafico preposto al salvataggio dei dati."
  • Definizioni Esplicite: Definisci tutti gli acronimi e i termini tecnici la prima volta che compaiono.
    • ✅ Esempio (Cosa fare): "Il nostro sistema usa un'interfaccia a riga di comando (CLI) per le operazioni avanzate."
    • ❌ Esempio (Cosa non fare): "Per le operazioni avanzate devi usare la CLI."
  • Consistenza Terminologica: Usa sempre lo stesso termine per riferirti allo stesso concetto all'interno del documento e, idealmente, in tutta la base di conoscenza.
    • ✅ Esempio (Cosa fare): "Apri il Pannello Utente. Dal Pannello Utente puoi modificare la password."
    • ❌ Esempio (Cosa non fare): "Apri il Pannello Utente. Dalla Dashboard Cliente puoi modificare la password."

Arricchimento con Metadati (Front Matter)

Concetto chiave: Fornire a Crafter.ai un contesto completo è fondamentale. I metadati all'inizio di un file fungono da "contesto a colpo d'occhio", aiutando sia il sistema di ricerca che il motore di generazione a capire immediatamente di cosa tratta il documento.

Best Practices (Front Matter):

  • Aggiungi un Front Matter: Inizia i tuoi documenti (specialmente se in formato Markdown) con un blocco di metadati in formato YAML.
  • Campi Utili: Includi campi come title, version, last_updated, author, tags (parole chiave), e un breve summary. I tag sono particolarmente potenti per migliorare il recupero delle informazioni.

Esempio di Front Matter YAML:

---
title: Guida alla Configurazione dell'API
version: 2.1
last_updated: 2025-10-08
author: Mario Rossi
tags: [api, configurazione, backend, sicurezza]
summary: Questo documento spiega come configurare e mettere in sicurezza gli endpoint dell'API per l'ambiente di produzione.
---

# Titolo del Documento
...

Note

(1) Nei file di tipo Markdown, i livelli di titolo sono definiti dal carattere cancelletto (#). Un singolo cancelletto definisce il titolo principale (H1 = # Titolo), due cancelletti definiscono un sotto-titolo di primo livello (H2 = ## Sotto-titolo), e così via.

Appendice: Lavorare con i File Markdown (.md)

Cos'è un File Markdown?

Un file Markdown (con estensione .md) è un semplice file di testo. Il suo punto di forza è la possibilità di aggiungere formattazione (come titoli, grassetto, elenchi) usando caratteri facili da digitare. È un formato molto più leggero e gestibile di un .pdf o .docx, ed è ideale per la documentazione perché la sua struttura è esplicita e facilmente interpretabile dai sistemi automatici come Crafter.ai.

Come Creare un File .md

Non servono programmi speciali per creare un file .md. Puoi usare gli editor di testo base inclusi nel tuo sistema operativo.

  • Su Windows:
    1. Apri il Blocco note (Notepad).
    2. Scrivi o incolla il tuo testo.
    3. Vai su File > Salva con nome....
    4. Nella casella "Salva come", seleziona "Tutti i file (.)".
    5. Nel campo "Nome file", scrivi il nome che preferisci seguito da .md (es: guida_prodotto.md).
    6. Clicca su Salva.
  • Su macOS:
    1. Apri TextEdit.
    2. Scrivi o incolla il tuo testo.
    3. Vai nel menu Formato > Converti in formato solo testo.
    4. Vai su File > Salva....
    5. Nel campo "Salva col nome", scrivi il nome che preferisci seguito da .md (es: guida_prodotto.md).
    6. Clicca su Salva.

Conclusione: Perché Queste Pratiche Funzionano con Crafter.ai?

Adottare queste linee guida porta a tre vantaggi principali quando si utilizza la piattaforma Crafter.ai:

  1. Recupero più Preciso: Documenti modulari e arricchiti con metadati permettono alla funzionalità di Document Management di Crafter.ai di identificare con maggiore precisione i "chunk" di testo più pertinenti alla domanda dell'utente.
  2. Generazione più Pertinente: Fornendo al sistema un contesto pulito, ben strutturato e privo di ambiguità, si riduce il rischio di risposte imprecise e si ottengono risultati più accurati e fedeli alla fonte.
  3. Efficienza della Piattoforma: Un contesto chiaro e ben organizzato permette a Crafter.ai di elaborare le informazioni e generare risposte in modo più rapido e coerente.