Arquitetura (Guia para Vibe Coders)

Mergulho profundo no pipeline RAG para desenvolvedores que querem entender como funciona.

Visão geral do pipeline RAG

O LaunchChat usa Retrieval Augmented Generation (RAG) para responder perguntas com base na sua documentação.

1. Ingestão

Parsing → Fragmentação → Embedding → Armazenamento

2. Recuperação

Consulta → Busca vetorial → Ranqueamento

3. Geração

Contexto → LLM → Resposta + Citações

Pipeline de Ingestão

1. Parsing

O conteúdo é extraído de diversas fontes em texto puro:

Notion: Parsing bloco a bloco preservando a hierarquia
DOCX: Extraído via mammoth.js
Markdown: Processado com remark/unified
Website: Site: Rastreado e limpo de navegação/rodapé

2. Fragmentação

O texto é dividido em fragmentos sobrepostos para recuperação otimizada:

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

Cada fragmento preserva a hierarquia de títulos para manter o contexto.

3. Embedding

Os fragmentos são convertidos em vetores de 1536 dimensões:

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

4. Armazenamento

Os vetores são armazenados no PostgreSQL com a extensão pgvector:

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

Estratégia de Recuperação

Busca Híbrida

Usamos um processo de recuperação em duas etapas:

Vector Search: Busca vetorial: Similaridade por cosseno usando o operador <=> do pgvector
Keyword Fallback: Fallback por palavras-chave: Se os resultados vetoriais tiverem baixa similaridade, adicionamos fragmentos correspondentes por palavras-chave

Pontuação de Similaridade

-- 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

Geração de Respostas

Pontuação de Confiança

Antes de gerar, calculamos uma pontuação de confiança:

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

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

Extração de Citações

O LLM é instruído a usar o formato [Source N]. Fazemos o parsing e vinculamos às páginas originais:

// 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])

Boas Práticas para Documentação

Estruture seus docs para recuperação otimizada pela IA:

Faça

Use títulos claros e descritivos
Mantenha seções focadas em um único tópico
Inclua exemplos e trechos de código
Defina termos e siglas
Atualize os docs quando funcionalidades mudarem

Evite

Páginas muito longas sem estrutura
Conteúdo duplicado entre páginas
Informações desatualizadas ou contraditórias
Uso excessivo de imagens sem texto alternativo
Páginas apenas de navegação

Template de Prompt para IA

Copie este prompt no Cursor, Windsurf ou Claude Code para ajudar na integração do 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.