Como criar uma base de conhecimento com RAG no Supabase e pgvector

A recuperação aumentada por geração (RAG, ou Retrieval-Augmented Generation) consolidou-se como o padrão técnico mais confiável para conectar modelos de inteligência artificial a bases de conhecimento internas de empresas sem recorrer a treinamentos caros de modelos próprios. Em vez de permitir que o modelo invente fatos quando questionado sobre políticas internas ou catálogos de produtos, o pipeline de RAG busca trechos relevantes nos documentos da empresa e os entrega como contexto factual antes de gerar a resposta.

Entre as alternativas modernas para armazenar e consultar representações vetoriais de texto (embeddings), a combinação do Supabase com a extensão de código aberto pgvector oferece uma das soluções mais produtivas e seguras para equipes de engenharia de software no Brasil. Por estar fundamentada no banco de dados relacional PostgreSQL, essa pilha tecnológica dispensa a contratação de bancos vetoriais dedicados e isolados, permitindo cruzar buscas semânticas vetoriais com filtros relacionais tradicionais de permissões de usuário, datas e departamentos na mesma instrução SQL. Aprenda a estruturar uma base corporativa de conhecimento com essa arquitetura passo a passo.

Resumo rápido

• O RAG une modelos de linguagem ao banco de dados da empresa para eliminar respostas inventadas e alucinações.
• O Supabase facilita a criação de bases vetoriais ativando a extensão nativa pgvector sobre o banco PostgreSQL.
• O processo envolve três etapas centrais: divisão de documentos (chunking), vetorização (embeddings) e busca por similaridade.
• A busca por similaridade de cosseno identifica os trechos de manuais e políticas mais pertinentes à pergunta do usuário.
• Permite aplicar filtros relacionais (como departamento, data e perfil de acesso) junto com a busca semântica em uma única query.
• Garante total controle de privacidade e conformidade com a LGPD ao manter dados corporativos sob regras estritas de banco.

Fundamentos da arquitetura RAG com PostgreSQL e pgvector

Para construir um sistema de RAG que realmente funcione no dia a dia operacional, é necessário compreender como os dados transitam entre o texto escrito em português e os cálculos matemáticos de similaridade no banco. Um modelo de linguagem não pesquisa em bancos relacionais usando comandos SELECT tradicionais por palavras-chave exatas, pois uma busca por termos literais falharia caso o usuário utilizasse sinônimos ou fizesse perguntas conceituais.

A solução para esse desafio é o uso de modelos de incorporação (embeddings). Modelos de embeddings convertem blocos de texto em vetores numéricos de ponto flutuante em um espaço multidimensional (frequentemente de 1.536 ou 3.072 dimensões). Textos que possuem significado semântico semelhante acabam posicionados muito próximos uns dos outros nessa geometria matemática, mesmo que utilizem palavras completamente diferentes.

É aqui que a extensão pgvector entra em ação no Supabase. O pgvector adiciona um tipo de dado nativo chamado vector ao PostgreSQL, juntamente com operadores matemáticos especializados para calcular distâncias geométricas, como a distância euclidiana (L2), o produto interno e a distância de cosseno. Dessa forma, encontrar os parágrafos mais relevantes de um manual corporativo resume-se a calcular quais vetores de documentos salvos no banco estão geometricamente mais próximos do vetor da pergunta feita pelo colaborador.

Para entender o conceito matemático e as aplicações de vetores semânticos, recomendamos a leitura de nosso artigo sobre embeddings e como usar em busca e recomendação.

Supabase com pgvector vs bancos vetoriais dedicados

Muitas equipes iniciam projetos de inteligência artificial contratando bancos vetoriais especializados e independentes, como Pinecone, Qdrant ou Milvus. No entanto, em ambientes corporativos reais, a necessidade de sincronizar dados entre o banco relacional principal e o banco vetorial secundário costuma gerar complexidade de arquitetura e brechas de segurança. A tabela comparativa a seguir destaca as vantagens e desvantagens de cada abordagem:

Para compreender como o RAG se posiciona diante de outras técnicas de adaptação de inteligência artificial, veja nosso guia sobre RAG na prática e conexão de documentos sem alucinar.

Passo a passo da implementação no Supabase

A montagem de uma base de conhecimento corporativa envolve a execução de etapas claras no console do Supabase e na aplicação cliente (geralmente escrita em Python, Node.js ou TypeScript):

1. Ativação da extensão e criação da tabela

No editor de SQL do Supabase, execute o comando de ativação da extensão pgvector e defina a estrutura da tabela que armazenará os pedaços de documentos (chunks) e seus respectivos vetores:

create extension if not exists vector;

create table if not exists documentos_conhecimento ( id bigserial primary key, titulo text not null, categoria text not null, conteudo text not null, embedding vector(1536), created_at timestamp with time zone default timezone('utc'::text, now()) not null );

A dimensão de 1536 é a padrão para modelos populares de mercado, como o text-embedding-3-small da OpenAI.

2. Criação do índice vetorial HNSW para consultas rápidas

Sem um índice adequado, o banco de dados precisará comparar a pergunta do usuário com todos os vetores da tabela um por um (busca exata por força bruta). Para acelerar as respostas em milissegundos mesmo com milhares de páginas salvas, crie um índice de aproximação por grafos (Hierarchical Navigable Small World – HNSW):

create index on documentos_conhecimento using hnsw (embedding vector_cosine_ops);

3. Criação da função de busca semântica em SQL

Para que a aplicação cliente possa consultar os documentos com um único comando remoto (RPC), criamos uma função no banco de dados que recebe o vetor da pergunta e o limite de resultados desejado:

create or replace function buscar_documentos(query_embedding vector(1536), match_threshold float, match_count int) returns table (id bigint, titulo text, categoria text, conteudo text, similaridade float) language sql stable as $$ select id, titulo, categoria, conteudo, 1 - (documentos_conhecimento.embedding <=> query_embedding) as similaridade from documentos_conhecimento where 1 - (documentos_conhecimento.embedding <=> query_embedding) > match_threshold order by similaridade desc limit match_count; $$;

O operador <=> calcula a distância de cosseno entre os dois vetores em velocidade máxima de hardware.

Divisão de documentos (Chunking) e geração de embeddings

Um dos fatores mais determinantes para o sucesso de uma base de conhecimento é a estratégia de fragmentação de documentos (chunking). Se você salvar um manual inteiro de cem páginas em um único registro no banco, o vetor resultante perderá todas as especificidades do texto. Por outro lado, se dividir o documento em frases soltas de dez palavras, o fragmento perderá o contexto de quem é o sujeito da ação.

A melhor prática consiste em fatiar o texto em blocos de 400 a 800 tokens com uma sobreposição (overlap) de 10% a 15% entre blocos consecutivos. Essa sobreposição garante que definições importantes localizadas na fronteira entre duas páginas não sejam cortadas no meio da frase, preservando a coerência semântica.

A cada bloco gerado, a aplicação chama a API de embeddings do provedor, recebe a lista de 1.536 números decimais e realiza a gravação no Supabase através do SDK oficial. Se a sua empresa busca mitigar completamente invenções de fatos nos assistentes, confira nosso artigo sobre alucinação em inteligência artificial e como reduzir.

Exemplo: clínica de saúde e medicina diagnóstica em Porto Alegre

Para visualizar a aplicação dessa arquitetura em uma empresa brasileira de porte médio, considere o caso de uma rede de clínicas médicas e exames laboratoriais localizada em Porto Alegre, Rio Grande do Sul.

A clínica possui mais de 180 protocolos médicos internos, diretrizes de preparo de exames (como jejum, restrição de medicamentos e coleta de sangue) e políticas de convênios de saúde. Diariamente, as recepcionistas e operadores de teleatendimento recebiam centenas de ligações de pacientes com dúvidas específicas sobre preparo de exames raros. Com frequência, os atendentes demoravam minutos folheando pastas em PDF compartilhadas na rede local ou repassavam informações imprecisas, gerando cancelamento de exames e retrabalho laboratorial.

A equipe de tecnologia da rede implementou um assistente interno de suporte aos atendentes utilizando Supabase com pgvector:

1. Vetorização de todos os manuais: Os manuais técnicos de preparo foram processados por um script em Python que limpou cabeçalhos duplicados, fragmentou os textos em pedaços de 500 tokens e gerou os embeddings no Supabase.
2. Consulta instantânea no atendimento: Quando um paciente pergunta pelo WhatsApp se precisa suspender anticoagulantes para realizar uma biópsia guiada por ultrassom, a recepcionista digita a pergunta no painel interno. O sistema calcula o embedding da dúvida em 40 milissegundos e localiza no banco os três parágrafos exatos do protocolo daquele procedimento médico.
3. Resposta fundamentada e auditável: O modelo de linguagem sintetiza a orientação em dois parágrafos claros em português e exibe na tela o nome do protocolo oficial e a data da última revisão assinada pelo diretor clínico responsável.

Essa rotina reduziu o tempo médio de espera no teleatendimento da clínica em 75% e zerou as ocorrências de pacientes que compareciam aos exames com preparo incorreto.

Erros comuns

• Não criar índices no banco vetorial: Deixar a tabela crescer sem índice HNSW ou IVFFlat fará com que as consultas fiquem lentas à medida que a base acumula milhares de fragmentos.
• Dividir o texto sem sobreposição (overlap): Cortar parágrafos de forma cega sem manter uma pequena faixa de palavras compartilhadas entre blocos consecutivos destrói referências gramaticais essenciais.
• Usar modelos de embeddings diferentes para gravar e consultar: O vetor da pergunta do usuário DEVE ser gerado rigorosamente pelo mesmo modelo e com a mesma dimensão utilizada na gravação dos documentos no banco.
• Não sanitizar o texto antes da vetorização: Manter tabelas desconfiguradas, quebras de linha em excesso e sequências de caracteres de controle reduz a qualidade dos embeddings gerados.
• Omitir o nível de corte de similaridade (threshold): Não estipular uma nota mínima de similaridade (como 0.70) fará com que o banco devolva documentos sem nenhuma relação com o tema caso a pergunta seja totalmente desconhecida.
• Deixar de proteger dados pessoais sensíveis: Subir contratos contendo CPFs e dados bancários de clientes sem permissões adequadas de acesso por usuário no Supabase.

Perguntas frequentes

O Supabase gratuito suporta a extensão pgvector?

Sim. O plano gratuito do Supabase inclui acesso completo à extensão pgvector e permite armazenar e consultar dezenas de milhares de vetores em projetos de desenvolvimento e testes corporativos.

Qual é a diferença entre os índices HNSW e IVFFlat no pgvector?

O índice IVFFlat divide os vetores em listas invertidas e é mais rápido para indexar, mas exige retreinar o índice quando o volume de dados cresce. O índice HNSW cria grafos navegáveis de alta performance, oferecendo maior taxa de acerto e consultas mais velozes para bases dinâmicas.

Posso usar embeddings gerados por modelos abertos locais no Supabase?

Sim. O pgvector é agnóstico ao modelo gerador. Você pode usar embeddings gerados pelo Ollama (como Nomic-Embed ou BGE) ou por APIs comerciais da OpenAI, Google ou Cohere, bastando configurar a dimensão correspondente da coluna no banco.

Como atualizar um documento na base quando a política interna muda?

A melhor prática é atribuir um identificador único de documento de origem a todos os pedaços gerados. Ao publicar uma versão nova do manual, apague os registros antigos vinculados àquele ID e insira os novos blocos vetorizados em uma única transação atômica.

É necessário enviar todos os documentos para o modelo a cada pergunta?

Não. A grande vantagem do RAG é recuperar apenas os três a cinco trechos mais relevantes do banco de dados e repassar estritamente esses fragmentos no prompt, mantendo o consumo de tokens baixo e o processamento veloz.

Para conhecer todas as integrações de ferramentas e plataformas inteligentes da empresa, consulte nosso índice detalhado de integrações da OpenAI e ChatGPT.

Fontes e leitura recomendada

• Documentação oficial do Supabase AI: desenvolvimento de inteligência artificial com PostgreSQL
• Repositório oficial do pgvector no GitHub: instalação, tipos e operadores de vetores
• Guia de embeddings da OpenAI: documentação de modelos text-embedding-3 e dimensões
• Guia de extensões do Supabase: ativando e configurando pgvector e índices HNSW