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)

Exemplos de Uso

Manuais e políticas internas: PDFs, DOCX, Markdown.
FAQs e bases de suporte: CSV ou JSON exportados de sistemas legados.
Documentação online: crawler de sites para intranet ou portais.
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.

Importar Website

URL: endereço inicial.
Seletores de Conteúdo: ex. body, article, #main. Extrai apenas o texto dentro desse seletor.
Profundidade: quantos níveis de links internos seguir (ex: 2 = página inicial + links dessas páginas).
Máximo de Links: limite de URLs por página (ex: 50) para evitar explorações infinitas.
Defina Nome, Descrição, Modelo e Salvar.

Importação Demorada

Bulk upload e web-scraping podem levar vários minutos, pois cada arquivo ou página é dividido, vetorado e enviado para armazenamento.

⚠️ Aviso
Se o site mudar, o conteúdo importado não se atualiza automaticamente. Reimporte e sincronize para refletir alterações.

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 ou websites 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.

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.

O que acontece se um site mudar?

O conteúdo importado não se atualiza sozinho: reimporte e sincronize.

Qual o impacto do Auto-Sync?

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

Agentes

Implantando Agentes

Configurações

Base de Conhecimento

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

Importar Website

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

Consulta via API

Exemplo de Resposta

Controle de Custos

Boas Práticas

Perguntas Frequentes

Implantando Agentes

Base de Conhecimento ​

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 ​

Importar Website ​

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 ​

Consulta via API ​

Exemplo de Resposta ​

Controle de Custos ​

Boas Práticas ​

Perguntas Frequentes ​

Base de Conhecimento

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

Importar Website

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

Consulta via API

Exemplo de Resposta

Controle de Custos

Boas Práticas

Perguntas Frequentes