Base de Conhecimento

O que é uma Base de Conhecimento

Uma Base de Conhecimento (KB) é uma coleção de documentos que a IA do Fluxo Conversacional consulta durante a conversa para responder com informação proprietária do tenant — manuais, FAQs, planilhas de produto, páginas de site, contratos, runbooks operacionais. A técnica é conhecida como RAG (Retrieval-Augmented Generation): o motor busca trechos relevantes na base e passa esses trechos como contexto para a resposta.

Cada KB pertence a uma Operação. A propriedade fica clara na UI: a lista de Bases é submissa ao seletor global de Operação no topo do dashboard. Múltiplos Fluxos da mesma Operação podem autorizar a consulta da mesma KB.

Por que separar em Bases (e não jogar tudo num pote só)

A primeira tentação ao começar é criar uma KB chamada “Tudo” e empilhar documentos. Não funciona bem por dois motivos:

1. Contexto enviado ao LLM tem custo e limite. Bases focadas recuperam trechos mais relevantes; bases muito heterogêneas trazem ruído.
2. Permissão por Fluxo. Você pode autorizar Fluxos diferentes a consultar Bases diferentes — útil para isolar conhecimento sensível (ex.: planilha de comissão fica numa KB que só os Fluxos de back office consultam).

Boa unidade de Base: um assunto coerente (FAQ de Boletos, Catálogo 2026, Política de Garantia). Misture só quando os documentos realmente moram juntos.

Formatos suportados

A tabela abaixo lista os tipos aceitos no upload:

Tipo	Extensão	Observação
PDF	.pdf	Texto extraído, OCR não automático — PDFs escaneados precisam ser OCRizados antes.
Markdown	.md	Mantém estrutura de headings; ideal para conteúdo curado.
Texto plano	.txt	Sem formatação, usar quando o documento já é só texto.
HTML	.html	Tags são limpas; conteúdo textual é preservado.
URL	—	Buscador faz fetch da página e extrai texto. Útil para conteúdo de site.

Cada documento tem um status que evolui após o upload:

• pendente — recém-enviado, aguardando processamento.
• indexando — texto sendo extraído, segmentado e enviado para geração de embeddings.
• pronto — disponível para consulta pelos Fluxos autorizados.
• erro — algo falhou; uma mensagem de erro fica disponível para diagnóstico (formato inválido, fonte inacessível, etc.).

Indexação automática

Após o upload, o documento entra na fila de indexação automática. Não é necessário acionar nada manualmente — o processo roda em segundo plano e atualiza o status do documento conforme avança.

O processamento faz três coisas:

1. Segmentação em chunks. Cada documento é dividido em trechos menores; cada trecho ganha um identificador e mantém referência ao documento original.
2. Geração de embeddings. Cada chunk é convertido em vetor numérico por text-embedding-3-small (modelo de embeddings da OpenAI, 1536 dimensões).
3. Contextual retrieval. Antes de embedar, cada chunk recebe um prefixo contextual gerado por gpt-4o-mini que descreve o papel daquele trecho dentro do documento — melhora a relevância da busca em trechos curtos ou ambíguos.

A consulta no momento da Conversa é híbrida: combina busca por similaridade vetorial (embeddings) com busca textual full-text. Isso captura tanto significado parecido quanto termos exatos.

Anexar a um Fluxo

KB e Fluxo estão desacoplados — uma KB não fala com um Fluxo específico até você autorizar explicitamente.

Autorização por Fluxo

No builder do Fluxo Conversacional, abra Configurações globais → Conhecimento e selecione as Bases que esse Fluxo pode consultar. Cada vínculo tem um modo que define o uso (consulta global por padrão, ou consulta dirigida por nó).

Refinamento por nó

Em casos avançados, é possível excluir uma KB num nó específico do Fluxo — útil quando o Fluxo costuma usar várias KBs, mas em um nó específico você quer restringir o universo (ex.: nó de “consulta de fatura” não deve buscar em “FAQ de produtos”). O refinamento por nó é sempre uma exclusão; para incluir, ative a Base no nível do Fluxo.

Escopo padrão da Base

Cada KB tem um scope_default:

• opt-in (padrão) — Fluxos só consultam essa Base se autorizarem explicitamente. Mais seguro; recomendado.
• global — Fluxos da Operação consultam essa Base sem precisar autorizar. Útil para FAQs gerais que todo Fluxo deve cruzar.

Versionamento e atualização

• Cada documento tem version. Substituir o conteúdo (re-upload de URL, upload de novo PDF com mesmo nome) gera nova versão e dispara reindexação. Versões antigas são descartadas após o sucesso da nova indexação.
• Não há “branch” ou “draft” de Base — a versão atual é a que vale para qualquer Fluxo autorizado. Para experimentar, crie uma Base de teste em separado e autorize só num Fluxo de teste.

Boas práticas

• Limpeza importa mais do que volume. Páginas de “rodapé do site”, termos repetidos, listas de links viram ruído. Suba os documentos com o conteúdo enxuto.
• Atualize o que mudou. RAG não substitui curadoria — uma FAQ desatualizada gera respostas erradas com confiança. Inclua revisão periódica no ciclo da operação.
• Use Markdown para conteúdo curado. A estrutura de headings ajuda a segmentação e o contextual retrieval a entender o papel de cada trecho.
• Para URLs, prefira páginas estáveis. Páginas que mudam de layout com frequência reindexam ruído.
• Use uma Base por assunto. Vários assuntos misturados pioram a recuperação; várias bases focadas pioram a curadoria. O equilíbrio está em “um assunto coerente por base”.
• Bases sensíveis em opt-in. Use scope_default = opt-in (padrão) e autorize só os Fluxos que precisam.

Erros comuns

• Esperar resposta imediata após upload. A indexação é assíncrona; o Fluxo só começa a usar o documento depois do status virar pronto.
• Subir PDF escaneado e esperar respostas. Sem OCR prévio, o documento é texto vazio. Faça OCR antes de subir.
• Misturar conteúdo de marcas diferentes na mesma Base. Confunde a IA. Separe por marca, ou pelo menos por contexto.
• Esquecer de autorizar a Base no Fluxo. Sem o vínculo no builder do Fluxo (e com scope_default = opt-in), a IA não enxerga a Base — e você acha que a indexação falhou.
• Não retirar versões obsoletas. Documento antigo com mesma informação concorrente do novo gera resposta inconsistente.

Ver também

• Fluxos conversacionais
• Guardrails
• Materiais
• Fluxos: visão geral