Bases de Conhecimento (RAG)

Nível de acesso requerido

Gerente ou superior

O módulo de Bases de Conhecimento permite que os administradores façam upload de documentos da empresa (PDF, TXT e Markdown) para dar contexto aos Agentes de IA usando a tecnologia Retrieval-Augmented Generation (RAG).

A tela fica em Conteúdo, ao lado do CMS, e aparece para Gerente ou superior — base de conhecimento é conteúdo que alimenta o agente, não configuração de plataforma.

O papel é exigido no servidor

A barreira não é só do menu: os endpoints de bases do tenant exigem Gerente ou superior no próprio servidor, e quem chama a API direto sem esse papel recebe 403 — tanto na leitura da listagem quanto no upload, na exclusão e no vínculo com um processo. A base global continua com a exigência dela: só o Super Admin cria ou altera uma base global.

O mesmo vale para a base por processo, a que a aba RAG do catálogo alimenta em /a/definitions/{chave}/knowledge: subir e apagar documento, apagar a base inteira e mandar reindexar exigem Gerente ou superior, e ler a listagem também. É a mesma capacidade por outro caminho, e por isso o mesmo papel.

Ao anexar um documento a uma Base de Conhecimento, o Flowi Agentic realiza:

1. Extração de Texto: Leitura segura do conteúdo original.
2. Chunking: Divisão do texto em trechos de tamanho fixo, medido em tokens e não em parágrafos — um trecho pode começar no meio de uma frase, e é por isso que a orientação abaixo é escrever blocos que se sustentam sozinhos.
3. Embeddings: Conversão do texto em vetores matemáticos, salvos no banco de dados (pgvector).

Criando uma Base

1. Acesse o menu de Conteúdo > Bases de Conhecimento.
2. Clique em Nova Base.
3. Defina um nome e uma descrição clara para o escopo dessa base.

A base criada aqui pertence ao seu tenant e só ele a enxerga.

Bases globais

Além das suas próprias bases, a listagem mostra as bases globais — fornecidas pela plataforma e lidas por todos os tenants, normalmente acompanhando um template de processo global. Elas aparecem marcadas como Global e são somente leitura para o administrador do tenant: não dá para editá-las nem excluí-las, e o botão de excluir fica desabilitado explicando o motivo.

Quem cria e mantém base global é o administrador da plataforma, no menu Global (Super Admin) > Bases de Conhecimento Globais. A separação é proposital: cada papel configura apenas o escopo que ele responde por, e a tela do tenant não oferece a opção de marcar uma base como global.

Tudo que é global é visível a todos

Todos os tenants leem uma base global. Conteúdo que um cliente não pode ver não pertence ao escopo global — carregue-o na base do tenant.

Como escrever para a busca vetorial

A busca vetorial não lê o documento inteiro: ela recorta o texto em trechos e envia ao agente apenas os 3 trechos mais parecidos com a instrução daquela etapa. Todo o resto do documento fica de fora. Escrever pensando nesse recorte é o que separa uma base que ajuda de uma que atrapalha.

Escreva trechos que se sustentam sozinhos. Uma regra dividida em cinco seções de um manual não chega inteira — chegam no máximo três pedaços dela, possivelmente sem o começo. Prefira um bloco curto que enuncie a regra completa, com o contexto necessário dentro dele, a uma exposição longa que só faz sentido lida do início.

Base pequena e focada vence base completa. Não existe nota de corte: os 3 trechos mais próximos são enviados sempre, mesmo quando nenhum deles é bom. Uma base que mistura assuntos não fica neutra — ela ocupa o espaço com material irrelevante e empurra para fora o que importava. Prefira várias bases enxutas, vinculadas cada uma ao processo em que fazem sentido, a uma base única com tudo.

Fale a língua da instrução do agente. Quem faz a busca é a instrução configurada na etapa, não uma pergunta do usuário. Se a instrução diz "prazo de entrega" e o documento diz "lead time", a proximidade cai e o trecho certo pode não entrar. Vale revisar os dois lados juntos e usar os mesmos termos.

Prefira o texto ao escaneado. PDF de imagem sem camada de texto não gera trecho nenhum: o documento sobe, aparece na lista e simplesmente nunca é recuperado.

Na prática

O mesmo conteúdo, escrito das duas formas:

<!-- ❌ o trecho não se sustenta: depende do que veio antes -->
Conforme descrito na seção anterior, o limite mencionado se aplica
integralmente. Nos demais casos, observa-se o disposto no parágrafo
precedente, ressalvadas as exceções já apontadas.

Se esse pedaço for um dos 3 escolhidos, o agente recebe "o limite mencionado" sem saber qual é o limite, qual seção, nem quais exceções.

<!-- ✅ o trecho responde sozinho -->
## Limite de aprovação — reembolso de viagem

Despesas de viagem até R$ 2.000 são aprovadas pelo gestor direto.
Acima de R$ 2.000 exigem aprovação do diretor da área.

Vale para todos os centros de custo, a partir de 01/2026.
Exceção: viagens internacionais sempre exigem aprovação do diretor,
independentemente do valor.

Título que nomeia o assunto, regra completa, faixa de valores explícita, vigência e exceção — tudo dentro do mesmo bloco. Se esse for o único trecho recuperado, ainda assim o agente decide certo.

O que NÃO deve ir para a Base de Conhecimento

Tabelas de códigos e identificadores — catálogo de produtos, centros de custo, códigos de município, tabela de cargos, tabela de preços. Elas parecem documentos, mas não funcionam por similaridade: códigos vizinhos têm descrições quase idênticas e milhares de linhas repetem termos genéricos como "Outros". Perguntar por um código específico devolve, com toda a confiança, uma linha sem relação.

Esse tipo de dado vai para o CMS, onde a consulta é exata. A regra prática é: identificador exato → CMS; texto que se interpreta → Base de Conhecimento.

Vinculando a Processos

Após popular a base de conhecimento com os documentos corporativos, você a vincula a uma definição de processo, não a um agente. O agente alcança a base porque roda dentro daquele processo — se a mesma base serve a mais de um processo, cada um precisa do seu próprio vínculo. Quando o agente for acionado, a IA pesquisa automaticamente nas bases vinculadas antes de responder, garantindo que as respostas sejam embasadas nas diretrizes da sua empresa e reduzindo o risco de alucinações.

O vínculo do processo define o conjunto ao alcance; dentro dele, cada etapa do fluxo pode reduzir as bases que consulta, ou declarar que não consulta nenhuma — veja Bases desta etapa.

Apagando uma base

Apagar uma base remove o cadastro imediatamente, mas os vetores gerados a partir dos documentos dela não somem no mesmo instante: ficam marcados como órfãos e são removidos por uma limpeza diária depois de uma janela de retenção — 30 dias por padrão, configurável em RAG_ORPHAN_VECTOR_RETENTION_DAYS.

Isso é proposital. Reconstruir um índice grande custa horas de processamento e o valor cobrado pelos embeddings, então a janela existe para dar tempo de recuperar uma base apagada por engano. Nesse intervalo os vetores não aparecem em nenhuma busca — a pesquisa só considera bases que estão vinculadas a algum processo, e uma base apagada não está vinculada a nada.

Uma base ainda vinculada a algum processo não é apagada: a plataforma recusa a exclusão e responde listando os processos que ainda a usam. Desvincule cada um deles e repita a exclusão.

Recarregando uma base inteira

Para trocar todo o conteúdo de uma base, crie uma base nova, carregue nela, vincule ao processo e só então desvincule a antiga. Carregar por cima da base existente acrescenta ao que já está lá: as versões antiga e nova dos mesmos documentos passam a conviver, e a busca devolve as duas.