Pular para o conteúdo principal

Busca Semântica e RAG

Quer que seu app entenda o significado do que o usuário digita, não só as palavras exatas? Quer que ele encontre "documentos parecidos com este" ou responda perguntas baseadas no conteúdo que o próprio usuário cadastrou? Esse é o terreno da busca semântica e do RAG (Retrieval-Augmented Generation), e o Skip suporta tudo isso nativamente em apps construídos com Skip Cloud.

Quando usar​

Procure por busca semântica quando o seu app precisar de qualquer uma destas capacidades:

  • Busca por significado, não por palavra exata. "Mostra minhas notas sobre produtividade" deve encontrar uma nota chamada "Gerenciando meu tempo" mesmo que a palavra "produtividade" não apareça nela.
  • "Encontre similares". "Artigos parecidos com este", "produtos similares", "clientes com perfil parecido".
  • Chat com seus dados (RAG). O usuário faz uma pergunta em linguagem natural e o app responde usando o conteúdo cadastrado como base — tipo um "ChatGPT que só conhece os meus documentos".
  • Deduplicação ou agrupamento por similaridade. "Agrupa estes chamados por assunto", "encontra anúncios duplicados".

Se o seu app só precisa de busca por palavra-chave (LIKE, match exato), você não precisa de busca semântica. Use um campo de texto normal e um filtro simples.

O que é preciso​

:::info Pré-requisitos

  1. Backend Skip Cloud — a busca semântica é uma funcionalidade exclusiva do Skip Cloud. Apps configurados com Supabase seguem um caminho diferente (pgvector) que também é suportado, mas esta página cobre apenas o Skip Cloud.

  2. Uma chave de API de um provedor de embeddings — o Skip precisa transformar o texto em "vetores" (os números que representam o significado), e isso é feito por um serviço externo. Você escolhe qual serviço usar:

    • OpenAI — platform.openai.com. É o mais comum e provavelmente o que o Skip vai sugerir se você não tiver preferência. Custo baixíssimo (centavos para milhares de documentos).
    • Cohere, Voyage AI, ou outros provedores equivalentes.
    • Ollama (self-hosted) — se você já roda um servidor Ollama próprio, o Skip pode usar ele e o custo é zero. Requer infraestrutura adicional.

    Qualquer um funciona — diga para o Skip qual você prefere quando pedir a feature.

:::

Configurando a chave do provedor​

Antes de pedir para o Skip construir a feature, adicione a chave do provedor escolhido como um secret no seu app:

  1. Abra seu app no Skip
  2. Vá em Skip Cloud → Secrets (no painel lateral)
  3. Clique em Adicionar secret
  4. Nome: dependendo do provedor, use um nome claro. Exemplos:
    • OpenAI → OPENAI_API_KEY
    • Cohere → COHERE_API_KEY
    • Voyage → VOYAGE_API_KEY
  5. Valor: a chave que você obteve no painel do provedor
  6. Salve

Esse secret fica protegido no servidor — ele nunca é exposto para o frontend nem para usuários do seu app. Só o código que o Skip gera no backend consegue usá-lo.

Como pedir para o Skip​

Depois que a chave estiver configurada, é só pedir em linguagem natural. Alguns exemplos de prompts que funcionam bem:

  • "Adiciona busca semântica nas notas usando OpenAI. Quero digitar uma frase e encontrar notas com significado parecido, não só palavras iguais."
  • "Transforma o meu app num RAG: o usuário faz uma pergunta e você responde usando os documentos que eu cadastrei como base de conhecimento. Use Cohere para os embeddings."
  • "Na listagem de produtos, adiciona um botão 'produtos similares' que mostra 5 produtos parecidos com o que o usuário está vendo."
  • "Quero uma caixa de pesquisa no topo da página que busca por significado nos meus artigos, não por palavra-chave."

Se você não mencionar o provedor, o Skip provavelmente vai te perguntar ou sugerir OpenAI como ponto de partida.

O Skip vai:

  1. Adicionar um campo do tipo vetor na coleção relevante (ex: em notas, cria o campo embedding)
  2. Criar um hook que, toda vez que um registro é salvo, chama o provedor de embeddings para transformar o texto em um vetor e armazena no campo
  3. Criar uma rota de busca no backend que recebe a pergunta do usuário, converte em vetor (também via o provedor), e retorna os registros mais parecidos
  4. Adicionar um componente de busca no frontend que chama a nova rota e exibe os resultados

Tudo isso em uma única iteração, sem você precisar entender vetores, embeddings ou APIs de machine learning.

O que o Skip gera​

Para você ter uma noção do que acontece por baixo dos panos (sem precisar tocar no código):

  • No banco de dados, um campo do tipo vector é criado na coleção. Ele armazena uma lista de números (quantos depende do provedor — por exemplo, 1536 por registro com o modelo OpenAI mais comum) que representa o significado do texto.
  • No backend, um hook intercepta cada criação/atualização de registro, envia o texto para o provedor de embeddings, e salva o vetor retornado no campo.
  • Uma nova rota /backend/v1/search/<coleção> recebe perguntas em texto, converte para vetor via o mesmo provedor, e busca os registros mais próximos usando um índice otimizado embutido no Skip Cloud.
  • No frontend, um componente de busca (caixa de texto, botão, lista de resultados) consome essa rota.

O Skip cuida de todos os detalhes: criação do campo, manutenção dos vetores quando o texto muda, tratamento de erros, regras de acesso (quem pode ver seus dados continua seguindo as mesmas regras — a busca respeita autenticação), e ordenação por similaridade.

Testando a busca​

Depois que o Skip construir a feature:

  1. Cadastre alguns registros de exemplo com conteúdo variado. Para busca semântica funcionar bem, você precisa de pelo menos uns 10-20 registros — com muito pouco dado, os resultados não fazem sentido.
  2. Aguarde alguns segundos depois de cadastrar cada registro. Gerar o embedding leva uma fração de segundo, mas o hook roda em background em alguns casos.
  3. Digite uma busca usando palavras diferentes das que aparecem no conteúdo, para testar se a busca está mesmo entendendo o significado. Se você buscar "produtividade" e só encontrar registros que literalmente contêm essa palavra, a busca ainda está no modo "palavra-chave" — peça para o Skip revisar.
  4. Verifique a ordem. Os resultados mais similares devem aparecer primeiro. Se parecerem aleatórios, provavelmente está faltando o campo embedding estar sendo populado corretamente — peça para o Skip investigar.

Limitações​

  • Precisa de conteúdo em texto. Vetores são gerados a partir de texto. Para imagens, áudio ou vídeo, o caminho é diferente (modelos multi-modais) e fora do escopo desta página — pergunte ao Skip se precisar.
  • Custa (geralmente pouco) para cada embedding. Toda vez que o Skip envia texto para o provedor de embeddings, você paga pelo uso — o custo varia por provedor, mas para a maioria dos apps fica abaixo de US$ 1 por mil documentos. Se estiver preocupado com custo, provedores self-hosted como Ollama são grátis depois de configurados.
  • Busca semântica não substitui busca por palavra exata. Se o usuário precisa encontrar um número de pedido, um CPF ou um código, busca por palavra-chave é mais apropriada. Você pode combinar os dois — peça para o Skip adicionar "busca híbrida".
  • Trocar de provedor depois é destrutivo. Provedores diferentes geram vetores de tamanhos diferentes e os vetores não são compatíveis entre si. Se depois de implementado você quiser trocar OpenAI por Cohere (ou mudar de modelo dentro do mesmo provedor), o Skip precisa apagar todos os vetores existentes e regenerá-los do zero. Peça isso só quando tiver certeza.

Ainda com dúvidas?​