Base de Conhecimento

A Base de Conhecimento permite ao seu agente acessar documentos, tabelas e sites internos por meio de RAG (Retrieval-Augmented Generation). Em vez de confiar apenas em prompts, o agente faz buscas semânticas em vetores que representam seus conteúdos, recuperando trechos relevantes e inserindo-os no contexto da conversa.

O que é RAG? RAG combina recuperação de documentos (via similaridade semântica) com geração de texto. Você armazena seus materiais como vetores; ao receber uma pergunta, o agente busca os vetores mais semelhantes e, com esses trechos, gera respostas mais precisas e fundamentadas. 🔗 Saiba mais sobre RAG (Wikipedia)

Escopo por Projeto

As bases de conhecimento pertencem ao projeto ativo. Quando você cria uma tabela, ela é associada ao projeto atualmente selecionado no Project Switcher. Membros só podem ver e gerenciar bases de conhecimento dentro dos seus projetos atribuídos.

A lista de bases de conhecimento exibe uma coluna Criado por mostrando qual membro da equipe criou cada tabela. Usuários não-admin com a permissão knowledge:read:own podem filtrar a lista para mostrar apenas suas próprias tabelas usando o filtro Criado por mim.

TIP

Se você precisa da mesma base de conhecimento em múltiplos projetos, pode exportá-la (CSV) e reimportá-la em outro projeto.

Exemplos de Uso

Manuais e políticas internas: PDFs, DOCX, Markdown.
FAQs e bases de suporte: CSV ou JSON exportados de sistemas legados.
Dashboards de métricas: planilhas com indicadores que o agente pode consultar.

Modelos de Embedding Disponíveis

A escolha do modelo de embedding impacta diretamente precisão, custo e tempo de vetorização:

Modelos Grandes
text-embedding-3-large
- Prós: captura nuances semânticas complexas, ideal para textos longos ou altamente técnicos.
- Contras: custo elevado (R$1.20/1M tokens) e vetorização mais lenta.
Modelos Médios
bge-en-icl
- Prós: bom equilíbrio entre precisão e custo (R$0.185/1M tokens).
- Contras: leve perda de acurácia em casos extremamente específicos.
Modelos Pequenos
text-embedding-3-small
- Prós: baixo custo (R$0.185/1M tokens) e vetorização rápida, ideal para volumes muito grandes.
- Contras: menor fidelidade em similaridade semântica detalhada.

Modelo	Custo	Uso recomendado
text-embedding-3-large	R$1.20 / 1M tok.	Documentos longos, alta sensibilidade semântica
bge-en-icl	R$0.185 / 1M tok.	Aplicações gerais, bom trade-off custo/precisão
text-embedding-3-small	R$0.185 / 1M tok.	Volumes enormes, custo mínimo

Atenção: trocar de modelo recria todos os vetores da tabela, gerando custos adicionais. Confira o consumo no Dashboard após a sincronização.

Criando uma Tabela

Por que “tabela” e não “documento”?

Cada tabela é um conjunto de linhas (ou “chunks”) vetorizados — pense nela como um CSV interno:

Flexibilidade: você pode mesclar vários arquivos, planilhas e páginas numa única fonte.
Granularidade: cada linha é um fragmento de texto, evitando que o agente traga trechos irrelevantes ou tenha que ler um documento inteiro para encontrar uma resposta.
Edição: edite, remova ou adicione linhas individuais sem reimportar tudo.
Visualização: A representação por tabela permite entender de maneira intuitiva a forma como os dados serão consultados e utilizados pelo agente.

Clique em + Criar Tabela (🔝 canto superior direito) e escolha:

Tabela Vazia

Nome: identificador único (snake_case).
Descrição: orienta o agente quando decidir usar esta tabela.
Modelo de Embedding: selecione um dos modelos acima.
Salvar: a tabela aparece sem conteúdo; prossiga para importar ou inserir manualmente.

Carregar Arquivo

Formatos: PDF, DOCX, TXT, MD, JSON, CSV.
Defina Nome, Descrição e Modelo.
Faça upload ou arraste o arquivo.
Split by page (aplica-se apenas a PDF e DOCX): divide o documento por página em chunks de até 20 000 caracteres, com 100 caracteres de sobreposição por padrão.
Salvar: popula a tabela com esses chunks.

Importação Demorada

Bulk upload pode levar vários minutos, pois cada arquivo é dividido, vetorizado e enviado para armazenamento.

Visualizando e Editando

Clique no nome da tabela para abrir a interface de gerenciamento:

Visão Geral

Título da Tabela e ícone ✏️ para editar Nome, Descrição e Modelo.
Contador de documentos (linhas) e modelo em uso.

Barra de Ações

🔁 Restaurar: desfaz alterações locais e retorna ao último estado sincronizado.
🔍 Consultar: abre o modal de busca semântica (ver seção 5).
⬇️ Download: exporta toda a tabela em CSV.
➕ Importar: adiciona mais arquivos sem sair da página.
🔄 Sincronizar: reprocessa todos os fragments e atualiza vetores.

Linhas (Chunks)

Cada linha exibe um fragmento de texto (+ metadados opcionais).
🗑️ Remover: exclui fragments irrelevantes.
✏️ Editar: ajuste manual do texto ou identificação.
➕ + Linha: crie manualmente novos fragments.

Testando Busca Semântica (Prototipagem)

Clique em Consultar.
Insira sua Consulta (pergunta ou termo).
Defina Número de Resultados (N).
Clique em Consultar e examine:
- Trechos retornados com distância semântica (quanto menor, mais próximo).
- Contexto: veja se o agente terá informação suficiente.

💡 Dicas sobre Chunks e N
Tamanho Máximo do Chunk: ⚠️ Não ultrapasse 20 000 caracteres — modelos de embedding têm limite de tokens e falham ao vetorar trechos maiores.
Chunks Menores: reduzem consumo de tokens, mas podem faltar contexto.
Chunks Maiores: entregam mais contexto, mas custam mais tokens.
N: usar valor baixo (1–3) economiza tokens; usar valor alto melhora cobertura mas aumenta custo.

Exemplo Prático: FAQ “Vibe Criativa”

Para ilustrar todo o fluxo, use este arquivo CSV de FAQ (empresa fictícia Vibe Criativa):

🔗 Baixe o CSV: faq_vibe_criativa.csv

Passo a passo

Importe o CSV
- Em Base de Conhecimento → + Criar Tabela → Carregar Arquivo.
- Nome: faq_vibe_criativa
- Descrição: “Perguntas frequentes sobre serviços da Empresa Vibe Criativa”
- Modelo: text-embedding-3-large
- Faça upload de vibe_criativa_faq.csv e clique em Salvar.
Prototipe uma Consulta
- Clique em Consultar, insira contato, defina 3 resultados e confirme.
- Verifique se os trechos retornados correspondem às informações de contato no FAQ.

Dica: ao usar text-embedding-3-large, você terá respostas mais precisas em perguntas de negócio, mas vetorização e custo por token serão maiores. Ajuste conforme seu volume e orçamento.

Integrando com Agentes

A forma mais poderosa de usar a Base de Conhecimento é conectá-la diretamente a um Agente. Quando configurado como ferramenta, o agente pode consultar automaticamente a base durante uma conversa, recuperando informações relevantes sem intervenção manual.

Adicionando uma Ferramenta de Conhecimento

Navegue até Agentes e selecione ou crie um agente
Acesse a aba Ferramentas
Clique em + Nova Ferramenta
Selecione Base de Conhecimento (RAG) no módulo
Configure os parâmetros:

Parâmetro	Descrição
Base de Conhecimento	Selecione a tabela que deseja conectar
Número de Resultados	Quantos trechos retornar (1-20). Mais resultados = mais contexto, porém maior custo
Instruções Adicionais	Orientações para o agente sobre quando e como usar esta ferramenta

Clique em Salvar

Como o Agente Usa a Base de Conhecimento

Quando um usuário faz uma pergunta:

O agente analisa se a pergunta pode ser respondida com a base de conhecimento
Se sim, formula uma consulta semântica otimizada
A consulta retorna os N trechos mais relevantes
O agente usa esses trechos como contexto para formular uma resposta precisa

Usuário: "Qual o horário de funcionamento?"
         ↓
Agente formula consulta: "horário funcionamento atendimento"
         ↓
Base de Conhecimento retorna: 3 trechos sobre horários
         ↓
Agente responde: "Nosso horário de atendimento é..."

Instruções Adicionais Eficazes

Use o campo Instruções Adicionais para orientar o agente:

Exemplos de Instruções

Use esta ferramenta sempre que o usuário perguntar sobre
políticas, procedimentos ou informações da empresa.

Consulte esta base antes de responder perguntas sobre
produtos, preços ou disponibilidade.

Se a informação não for encontrada na base, informe ao
usuário que você não tem essa informação específica.

Múltiplas Bases de Conhecimento

Um agente pode ter várias ferramentas de conhecimento configuradas, cada uma conectada a uma tabela diferente:

Tabela	Uso Recomendado
`faq_geral`	Perguntas frequentes sobre a empresa
`catalogo_produtos`	Informações de produtos e preços
`politicas_rh`	Políticas internas (para agentes de RH)
`manual_tecnico`	Documentação técnica (para suporte)

O agente automaticamente escolhe qual base consultar com base no contexto da pergunta.

Boas Práticas de Integração

Descrições claras nas tabelas: A descrição da tabela ajuda o agente a decidir quando usá-la
Chunks bem dimensionados: Trechos muito grandes consomem tokens; muito pequenos perdem contexto
N equilibrado: Comece com 3-5 resultados e ajuste conforme necessário
Teste no Playground: Valide as respostas antes de implantar em produção
Monitore custos: Cada consulta consome tokens de embedding e do LLM

Consulta via API

Você pode incorporar essa consulta em qualquer fluxo do seu sistema — automações em CRMs, bots de Slack, triggers por webhook, rotinas agendadas, integrações com dashboards, etc. Basta chamar o endpoint sempre que precisar de dados da sua base de conhecimento.

Exemplo de Uso

Imagine uma rotina agendada que envia um email com as respostas para as perguntas mais frequentes:

Rotina é executada
Backend chama POST /v1/knowledge/faq_vibe_criativa/query para cada pergunta
Email é enviado com as respostas do JSON retornado

TypeScriptPython

typescript

// Consulta semântica via API
async function queryKB(
  tableName: string,
  query: string,
  n = 3
): Promise<any> {
  const res = await fetch(
    `https://api.sippulse.ai/v1/knowledge/${tableName}/query`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'api-key': process.env.SIPPULSE_API_KEY!
      },
      body: JSON.stringify({ query, n })
    }
  );
  if (!res.ok) throw new Error(`Erro ${res.status}`);
  return res.json();
}

// Uso de exemplo
(async () => {
  const tableName = 'faq_vibe_criativa';
  const result = await queryKB(tableName, 'contato', 3);
  console.log(result);
})();

python

import os
import requests

def query_kb(table_name: str, query: str, n: int = 3) -> dict:
    """
    Consulta semântica via API.
    - table_name: nome da tabela de conhecimento
    - query: texto de busca
    - n: número de resultados
    """
    url = f"https://api.sippulse.ai/v1/knowledge/{table_name}/query"
    resp = requests.post(
        url,
        headers={
            'Content-Type': 'application/json',
            'api-key': os.getenv('SIPPULSE_API_KEY')
        },
        json={'query': query, 'n': n}
    )
    resp.raise_for_status()
    return resp.json()

if __name__ == '__main__':
    table_name = 'faq_vibe_criativa'
    result = query_kb(table_name, 'contato', 3)
    print(result)

Exemplo de Resposta

json

// Resposta esperada (simplificada)
[
    {
        "content": "{\"question\":\"A VibeCriativa tem um canal de atendimento via WhatsApp?\",\"answer\":\"Sim, nosso WhatsApp é (11) 98765-4321, disponível no horário comercial.\"}",
        "distance": 1.1357711969228341,
    },
    {
        "content": "{\"question\":\"A VibeCriativa tem cases de sucesso disponíveis?\",\"answer\":\"Sim, temos cases de sucesso disponíveis no site e podemos enviar exemplos por e-mail sob demanda.\"}",
        "distance": 1.200524422602051,
    },
    {
        "content": "{\"question\":\"Como posso solicitar um orçamento personalizado?\",\"answer\":\"Você pode solicitar um orçamento através do formulário em nosso site ou enviando um e-mail para orcamento@vibecriativa.com.\"}",
        "distance": 1.2048347495936975,
    }
]

Controle de Custos

Dashboard: monitore consumo de tokens e gastos por importação/sincronização.
Auto-Sync: desative para evitar vetorização a cada pequeno ajuste.

Boas Práticas

Chunk size: 20 000 caracteres (máx.) com 100 de overlap costuma funcionar bem.
Descrições claras: ajudam o agente a filtrar tabelas corretas.
Sincronização consciente: use Auto-Sync em bases de baixa volatilidade.
Validação periódica: teste consultas-chave antes de liberar.

Perguntas Frequentes

Posso agrupar vários arquivos em uma única tabela?

Sim — importe quantos quiser e sincronize tudo de uma vez.

Como saber se um chunk está muito grande?

Se o trecho não couber no contexto do LLM, reduza o tamanho em caracteres.

Qual o impacto do Auto-Sync?

Cada edição dispara vetorização imediata, gerando custos extras.

Agentes

Configuração

Ferramentas

Avançado

Implantando Agentes

Configurações

Base de Conhecimento

Escopo por Projeto

Exemplos de Uso

Modelos de Embedding Disponíveis

Modelos Grandes

Modelos Médios

Modelos Pequenos

Criando uma Tabela

Por que “tabela” e não “documento”?

Tabela Vazia

Carregar Arquivo

Visualizando e Editando

Visão Geral

Barra de Ações

Linhas (Chunks)

Testando Busca Semântica (Prototipagem)

Exemplo Prático: FAQ “Vibe Criativa”

Passo a passo

Integrando com Agentes

Adicionando uma Ferramenta de Conhecimento

Como o Agente Usa a Base de Conhecimento

Instruções Adicionais Eficazes

Múltiplas Bases de Conhecimento

Boas Práticas de Integração

Consulta via API

Exemplo de Resposta

Controle de Custos

Boas Práticas

Perguntas Frequentes

Configuração

Ferramentas

Avançado

Implantando Agentes

Base de Conhecimento ​

Escopo por Projeto ​

Exemplos de Uso ​

Modelos de Embedding Disponíveis ​

Modelos Grandes ​

Modelos Médios ​

Modelos Pequenos ​

Criando uma Tabela ​

Por que “tabela” e não “documento”? ​

Tabela Vazia ​

Carregar Arquivo ​

Visualizando e Editando ​

Visão Geral ​

Barra de Ações ​

Linhas (Chunks) ​

Testando Busca Semântica (Prototipagem) ​

Exemplo Prático: FAQ “Vibe Criativa” ​

Passo a passo ​

Integrando com Agentes ​

Adicionando uma Ferramenta de Conhecimento ​

Como o Agente Usa a Base de Conhecimento ​

Instruções Adicionais Eficazes ​

Múltiplas Bases de Conhecimento ​

Boas Práticas de Integração ​

Consulta via API ​

Exemplo de Resposta ​

Controle de Custos ​

Boas Práticas ​

Perguntas Frequentes ​

Base de Conhecimento

Escopo por Projeto

Exemplos de Uso

Modelos de Embedding Disponíveis

Modelos Grandes

Modelos Médios

Modelos Pequenos

Criando uma Tabela

Por que “tabela” e não “documento”?

Tabela Vazia

Carregar Arquivo

Visualizando e Editando

Visão Geral

Barra de Ações

Linhas (Chunks)

Testando Busca Semântica (Prototipagem)

Exemplo Prático: FAQ “Vibe Criativa”

Passo a passo

Integrando com Agentes

Adicionando uma Ferramenta de Conhecimento

Como o Agente Usa a Base de Conhecimento

Instruções Adicionais Eficazes

Múltiplas Bases de Conhecimento

Boas Práticas de Integração

Consulta via API

Exemplo de Resposta

Controle de Custos

Boas Práticas

Perguntas Frequentes