Base de conhecimento (RAG)

A base de conhecimento é o que o agente sabe. Sem ela, ele só usa conhecimento geral do LLM (GPT-4o-mini, etc) — não sabe seus produtos, preços, políticas. Com ela, o agente vira especialista no seu negócio.

O Syncro implementa RAG (Retrieval-Augmented Generation): você sobe arquivos ou escreve texto, o sistema **indexa em **, e a cada mensagem do cliente o agente busca os trechos mais relevantes e usa como contexto pra responder. Isso permite ter base imensa (centenas de páginas de manuais) sem estourar o limite de tokens do LLM.

Pré-requisitos

• Agente IA criado.

• Permissão de admin ou manager.

Duas formas de alimentar conhecimento

1. Texto livre (campo "Base de Conhecimento")

Diretamente no agente, escreve tudo no textarea. Bom pra conteúdo curto e estruturado: descrição da empresa, lista curta de produtos, regras gerais.

2. Arquivos uploaded (RAG)

Upload de PDF, Word, TXT, CSV, imagens. Sistema extrai texto, chunkifica e indexa. Bom pra conteúdo extenso: catálogo completo, manuais, FAQ longa, documentação técnica.

💡 Dica: combine os dois. Texto livre pra essência ("Somos a Loja do João, especializada em...") + arquivos pra catálogo detalhado.

Como funciona o RAG (visão técnica)

Quando você sobe um arquivo:

1. Extração de texto:

• PDF: via biblioteca Smalot\PdfParser.

• DOCX / DOC: via PhpOffice\PhpWord.

• TXT / CSV: leitura direta.

• Imagens: descritas via LLM Vision.

2. Truncamento: máximo de 100.000 caracteres por arquivo (evita tokens excessivos).

3. Chunkificação: texto extraído é dividido em chunks de ~500 caracteres com overlap de 50:

• Splitter recursivo: parágrafos → sentenças → espaços.

• Cada chunk vira um "registro" indexável.

4. Embeddings:

• Cada chunk gera um vetor de 1536 dimensões.

5. Retrieval (busca semântica) — a cada mensagem do cliente:

• Mensagem é embedada com mesmo modelo.

• Sistema busca os top-5 chunks mais similares (cosine similarity ≥ 0.25).

• Chunks são injetados no system prompt do agente.

7. Generation: agente responde usando contexto + chunks relevantes + persona configurada.

Tipos de arquivo aceitos

Tamanho máximo: 20 MB por arquivo.

Não aceito (hoje):

• Excel/Planilhas (.xlsx) — solução: converte pra CSV antes.

• Formatos exóticos (.odt,.pages) — converte pra PDF/DOCX.

• Áudios e vídeos.

Acessar a base de conhecimento

Pelo wizard (criação)

No Passo 4 — Conhecimento e Ferramentas, há textarea grande pra texto livre.

Pelo form de edição (após criado)

1. Acesse /ia/agentes/{id}/editar.

2. Localize a seção Base de Conhecimento.

3. Você vê:

• Textarea com texto livre.

• Lista de arquivos uploaded com status (Pronto, Pendente, Erro).

• Botão upload ou dropzone.

Subir um arquivo

1. Na seção Base de Conhecimento, clique em Adicionar arquivo ou arraste pra dropzone.

2. Selecione arquivo do computador.

3. Sistema:

• Faz upload.

• Mostra status "Carregando...".

• Extrai texto (status muda pra "Processando...").

• Indexa no Agno (status final "✓ Pronto").

4. Arquivo aparece na lista com:

• Nome original

• Tamanho

• Status (✓ Pronto / ⏳ Pendente / ✗ Erro)

• Quantidade de chunks indexados

• Preview dos primeiros 300 chars do texto extraído

• Botão excluir

Status dos arquivos

Se status = Falha, hover mostra mensagem de erro (error_message).

Excluir um arquivo

1. Clique no botão Excluir ao lado.

2. Confirme.

3. Sistema:

• Apaga arquivo do storage.

• Apaga registro da AiAgentKnowledgeFile.

• Apaga chunks correspondentes do agent_knowledge_chunks (cascade).

4. Agente deixa de ter acesso ao conteúdo daquele arquivo nas próximas mensagens.

Como o agente usa os chunks

Quando o cliente manda mensagem:

1. Sistema embeda a mensagem.

2. Busca top-5 chunks mais similares.

3. Injeta no system prompt:

--- BASE DE CONHECIMENTO ---
[chunk 1 do arquivo "manual-produtos.pdf"]
[chunk 2 do arquivo "manual-produtos.pdf"]
[chunk 3 do arquivo "politicas.pdf"]
...
--- FIM DA BASE DE CONHECIMENTO ---

4. Agente lê contexto + responde.

Instrução adicional no prompt: "Use isso como FONTE DE VERDADE. Se não cobre a pergunta, diga que não tem essa info ao invés de inventar."

Threshold de similaridade

O sistema só usa chunks com similaridade cosseno ≥ 0.25 (escala 0-1). Abaixo disso, considera irrelevante e ignora.

Isso evita:

• Informação irrelevante poluindo o contexto.

• Alucinações baseadas em chunk forçado.

Boas práticas pra alimentar conhecimento

Estrutura clara nos arquivos

• Use headings (H1, H2, H3) em arquivos Word/PDF.

• Listas com bullets ou numeração.

• Tabelas simples (chunks captam estrutura básica).

Conteúdo focado

• Um arquivo = um tema (ex: catálogo, FAQ, política de devolução).

• Evite arquivos gigantes misturando tudo.

Linguagem do cliente

• Use vocabulário que seu cliente usa — quando ele perguntar, embed do query bate com chunks similares.

• Inclua sinônimos importantes ("frete", "envio", "entrega").

Atualize regularmente

• Produtos / preços / políticas mudam.

• Reupload do arquivo atualizado + delete do antigo.

• Sistema reindexar é rápido (segundos).

Custos de tokens — indexação

Cada arquivo indexado gasta tokens de embedding:

• ~150 tokens / chunk em média.

• 100k chars ≈ 200 chunks ≈ 30k tokens.

Esses tokens são registrados em ai_usage_logs com type='knowledge_indexing' mas não contam na sua quota mensal de chat (são separados).

Re-indexar arquivo

Se você suspeita que indexação falhou ou quer re-indexar:

Diferença entre texto livre e arquivos

Limitações conhecidas

• Sem reindex automático quando você atualiza arquivo (precisa deletar + reupload).

• Sem busca múltiplos arquivos simultânea (sistema unifica todos do agente).

• Imagens via LLM Vision podem ter inacurracies — verifique a descrição extraída.

• Tabelas complexas em PDF podem perder estrutura (chunks viram texto corrido).

Reset / limpar conhecimento

Pra resetar todo o conhecimento de um agente:

1. Texto livre: edite o agente e apague o textarea.

2. Arquivos: delete um a um na lista.

Não há botão "Limpar tudo" hoje — faz manualmente.

Próximos passos

• Pra subir arquivos passo a passo, veja Treinar com arquivos.

• Pra entender ações executáveis, veja Tools do agente.

Artigos relacionados

• Treinar com arquivos

• Criar um agente de IA

• Tools do agente