Architettura (Guida per Vibe Coder)

Analisi approfondita della pipeline RAG per sviluppatori che vogliono capire come funziona.

Panoramica della Pipeline RAG

LaunchChat utilizza la Retrieval Augmented Generation (RAG) per rispondere alle domande sulla base della documentazione dell'utente.

1. Ingestione

Parsing → Suddivisione → Embedding → Archiviazione

2. Recupero

Query → Ricerca Vettoriale → Classificazione

3. Generazione

Contesto → LLM → Risposta + Citazioni

Pipeline di Ingestione

1. Parsing

I contenuti vengono analizzati da diverse fonti e convertiti in testo semplice:

Notion: parsing blocco per blocco con preservazione della gerarchia
DOCX: estrazione tramite mammoth.js
Markdown: parsing con remark/unified
Website: Sito Web: crawling e pulizia di navigazione/footer

2. Suddivisione in Frammenti

Il testo viene suddiviso in frammenti sovrapposti per un recupero ottimale:

{
  targetSize: 400,    // tokens per chunk
  overlap: 50,        // token overlap between chunks
  preserveHeadings: true,  // keep heading context
  minChunkSize: 100   // minimum viable chunk
}

Ogni frammento preserva la gerarchia delle intestazioni superiori per il contesto.

3. Embedding

I frammenti vengono convertiti in vettori a 1536 dimensioni:

Model: text-embedding-3-small
Dimensions: 1536
Provider: OpenAI (via OpenRouter)

4. Archiviazione

I vettori vengono archiviati in PostgreSQL con l'estensione pgvector:

-- content_chunks table
id: uuid
knowledge_base_id: uuid
page_id: string
page_title: string
content: text
embedding: vector(1536)
parent_heading: string

Strategia di Recupero

Ricerca Ibrida

Utilizziamo un processo di recupero a due fasi:

Vector Search: Ricerca Vettoriale: similarità coseno tramite l'operatore <=> di pgvector
Keyword Fallback: Fallback per Parole Chiave: se i risultati vettoriali hanno bassa similarità, aggiungiamo frammenti corrispondenti per parole chiave

Punteggio di Similarità

-- Vector similarity query
SELECT *, 1 - (embedding <=> query_embedding) as similarity
FROM content_chunks
WHERE knowledge_base_id = $1
ORDER BY embedding <=> query_embedding
LIMIT 5

Generazione della Risposta

Punteggio di Confidenza

Prima della generazione, calcoliamo un punteggio di confidenza:

confidence = bestSimilarity + (hasMultipleChunks ? 0.1 : 0) + 0.2
// Capped at 1.0

if (confidence < threshold) {
  return refusalMessage;  // Don't hallucinate
}

Estrazione delle Citazioni

L'LLM è istruito a utilizzare il formato [Source N]. Analizziamo queste citazioni e le colleghiamo alle pagine originali:

// Extract citations from answer
const citationPattern = /\[Source (\d+)\]/g;
const matches = answer.matchAll(citationPattern);

// Map to original pages
citations = matches.map(m => chunks[m[1] - 1])

Best Practice per la Documentazione

Strutturi la documentazione per un recupero IA ottimale:

Da Fare

Utilizzare intestazioni chiare e descrittive
Mantenere le sezioni focalizzate su un singolo argomento
Includere esempi e snippet di codice
Definire termini e acronimi
Aggiornare la documentazione quando le funzionalità cambiano

Da Evitare

Pagine molto lunghe senza struttura
Contenuti duplicati tra le pagine
Informazioni obsolete o contraddittorie
Uso eccessivo di immagini senza testo alternativo
Pagine di sola navigazione

Template Prompt IA

Copi questo prompt in Cursor, Windsurf o Claude Code per facilitare l'integrazione di LaunchChat:

I'm integrating LaunchChat, an AI-powered support widget.

Widget Setup:
1. Add to HTML: <script>window.LaunchChatConfig = {widgetId: "ID"}</script>
   <script src="https://domain.com/widget.js" async></script>

2. For React/Next.js, create a client component that:
   - Sets window.LaunchChatConfig
   - Dynamically loads widget.js
   - Cleans up on unmount

API Reference:
- window.LaunchChatWidget.open() - Open chat
- window.LaunchChatWidget.close() - Close chat
- window.LaunchChatWidget.on(event, callback) - Listen to events
- Events: 'open', 'close', 'message', 'escalate', 'feedback'

Help me integrate this into my [FRAMEWORK] app.