IA: RAG com pgvector — assistente com documentos da empresa

1. O que é RAG (e o que não é)

RAG (Retrieval-Augmented Generation) combina busca + geração. Em vez de depender só do conhecimento treinado no modelo, o sistema:

1. Recebe a pergunta do usuário
2. Busca trechos relevantes em uma base de documentos (PDFs, Markdown, tickets, etc.)
3. Injeta esses trechos no contexto do prompt
4. Pede ao modelo para responder usando apenas o material recuperado, citando fontes

Não é fine-tuning. Não é treinar um modelo do zero. É um padrão de arquitetura que reduz alucinações e permite atualizar a base sem re-treinar nada.

2. Arquitetura mínima

Para um protótipo sério, quatro peças bastam:

• Store de documentos — arquivos + metadados (título, origem, data)
• Índice vetorial — embeddings dos chunks (aqui: pgvector)
• Retriever — busca por similaridade + filtros opcionais
• Gerador — LLM com prompt que força uso das fontes e citações

PostgreSQL + extensão pgvector é uma escolha sólida: você já tem o banco, ACID, backups e SQL. Para muitos casos (até dezenas/centenas de milhares de chunks) não precisa de Pinecone ou similar.

3. Preparar o PostgreSQL + pgvector

No Postgres 16+ (ou 15 com a extensão instalada):

-- Habilitar a extensão
CREATE EXTENSION IF NOT EXISTS vector;

-- Tabela de documentos (metadados)
CREATE TABLE documents (
  id          bigserial PRIMARY KEY,
  title       text NOT NULL,
  source      text,          -- caminho do arquivo, URL, etc.
  created_at  timestamptz DEFAULT now()
);

-- Chunks com embedding
-- dimension 1536 = text-embedding-3-small (OpenAI)
CREATE TABLE chunks (
  id          bigserial PRIMARY KEY,
  document_id bigint REFERENCES documents(id) ON DELETE CASCADE,
  content     text NOT NULL,
  embedding   vector(1536),
  chunk_index int,
  token_count int
);

-- Índice HNSW para busca aproximada (bom equilíbrio qualidade/velocidade)
CREATE INDEX ON chunks
  USING hnsw (embedding vector_cosine_ops);

Ajuste a dimensão conforme o modelo de embedding que você usar (OpenAI, Voyage, nomic, etc.).

4. Chunking e embeddings

Documentos longos precisam ser divididos. Regras práticas:

• Tamanho típico: 400–800 tokens por chunk
• Overlap de 10–20% para não cortar frases no meio
• Preferir quebrar em títulos/parágrafos (não no meio de tabelas ou código)
• Guardar chunk_index e referência ao documento original

Exemplo mínimo em Python (usando a API oficial da OpenAI):

from openai import OpenAI
import psycopg2

client = OpenAI()

def embed(texts: list[str]) -> list[list[float]]:
    res = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [d.embedding for d in res.data]

# após chunkar o PDF/Markdown:
embeddings = embed([c["content"] for c in chunks])
# inserir no Postgres com psycopg2 ou SQLAlchemy

5. Retrieval + geração

Fluxo de uma pergunta:

-- 1. Embedding da pergunta
-- (feito na aplicação)

-- 2. Busca dos k chunks mais próximos
SELECT content, document_id, 1 - (embedding <=> $1) AS score
FROM chunks
ORDER BY embedding <=> $1
LIMIT 6;

O operador <=> é distância de cosseno no pgvector. Depois monte o prompt:

Você é um assistente técnico. Responda APENAS com base nos trechos abaixo.
Se a informação não estiver nos trechos, diga que não encontrou.
Cite a fonte no formato [doc:ID].

Trechos:
---
[doc:42] ...conteúdo do chunk...
[doc:17] ...conteúdo do chunk...
---

Pergunta do usuário: {pergunta}

Envie para o modelo (GPT-4o-mini, Claude, Gemini, etc.) com temperatura baixa (0–0.3) e, se possível, response format estruturado.

6. Quando RAG não é a solução certa

• Perguntas que exigem raciocínio multi-hop complexo sem evidência direta nos docs
• Base muito pequena e estável — às vezes um prompt com o texto inteiro basta
• Necessidade de respostas em tempo real com dados transacionais (aí é melhor function calling + SQL)
• Documentos extremamente ruidosos ou mal estruturados (priorize limpeza antes de indexar)

7. Próximos passos

1. Adicionar hybrid search (BM25 + vetor) para termos exatos (códigos de erro, nomes de serviços)
2. Filtros por metadados (departamento, data, produto)
3. Avaliação: conjunto de perguntas + respostas esperadas e métricas de retrieval (recall@k, MRR)
4. Observabilidade: logar quais chunks foram usados e se o usuário aceitou a resposta

Com esse esqueleto você já tem um assistente interno utilizável. O resto é iteração sobre qualidade dos chunks, modelo de embedding e prompt de geração.

8. O SQL e o código explicados

No Python, OpenAI() lê a chave da variável de ambiente OPENAI_API_KEY. A chamada client.embeddings.create(model=..., input=texts) aceita uma lista de textos e devolve um vetor por texto em res.data, o que permite processar em lote.

9. Erros comuns e como resolver

← voltar ao hub de IA · próximo: Copilot local com Ollama →