Base de conhecimento (RAG)

Actualizado el 24 de septiembre de 2026

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 (Claude/GPT-4o lê a imagem e gera descrição textual).

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

3.Chunkificação no Agno: 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 via OpenAI text-embedding-3-small. -Custo: ~$0.02 / 1 milhão de tokens (irrisório).

5.Storage: chunks + embeddings ficam em tabela agent_knowledge_chunks no PostgreSQL com **** (índice ivfflat, distância cosseno).

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

[IMAGEM AQUI]diagrama mostrando upload → extração → chunks → embeddings → busca → contexto pro LLM

Tipos de arquivo aceitos

Tipo	Extensões	Como é processado
PDF	`.pdf`	Smalot PdfParser → texto
Word	`.doc`, `.docx`	PhpWord IOFactory → iteração de elements
Texto	`.txt`, `.csv`	Leitura direta
Imagens	`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`	LLM Vision descreve conteúdo

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.

[IMAGEM AQUI]seção "Base de Conhecimento" com textarea preenchida e 3 arquivos listados abaixo

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

Status	Significado
Pendente	Upload concluído, processamento em andamento
Pronto ✓	Texto extraído + indexado no Agno
Falha	Erro na extração ou indexação

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 (custo OpenAI):

-~150 tokens / chunk em média. -100k chars ≈ 200 chunks ≈ 30k tokens. -Custo: ~$0.0006 por arquivo grande (super baixo).

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:

Comando disponível só pra time Syncro via SSH. Se precisa, contate suporte.

Diferença entre texto livre e arquivos

Aspecto	Texto livre (textarea)	Arquivos (RAG)
Tamanho	Limitado (cabe no system prompt)	Ilimitado (chunks selecionados)
Sempre presente	Sim	Só chunks relevantes
Custo de tokens	Por mensagem (proporcional ao tamanho)	Indexação 1x + busca barata
Bom pra	Persona, regras, contexto curto	Catálogo, manual, FAQ longa

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.