O que são Embeddings e como usar pgvector com Docker

IA que entende contexto? Bem-vindo aos embeddings

Se você está começando a trabalhar com projetos de Inteligência Artificial, tem um conceito que precisa entrar logo na sua bagagem: embeddings.

Embeddings são representações numéricas de dados (textos, imagens, etc.) em um espaço vetorial.
Ou seja: eles transformam conteúdos em vetores, permitindo que a IA compare similaridades com base no significado, e não só em palavras-chave.

É graças aos embeddings que a IA consegue entender que “carro” e “automóvel” têm o mesmo significado, mesmo que as palavras sejam diferentes.
Eles são a base por trás de recursos como:

• Buscas inteligentes
• Assistentes com RAG
• Classificações semânticas
• Recomendações personalizadas

Mas onde armazenar esses vetores? É aí que entra o pgvector.

O que é o pgvector?

pgvector é uma extensão do PostgreSQL que permite armazenar e comparar vetores de alta dimensão direto no banco de dados.

Com ele, você pode:

• Armazenar embeddings (como os gerados pelo OpenAI ou Hugging Face)
• Fazer buscas por similaridade (distância euclidiana, cosseno, etc.)
• Construir pipelines de RAG, recomendação, sem precisar usar banco vetorial separado

E o melhor: você pode testar tudo isso em minutos com Docker.

Como instalar o pgvector com Docker

Aqui vai o passo a passo pra rodar tudo local:

1. Crie um arquivo docker-compose.yml

version: '3.9'
services:
  db:
    image: ankane/pgvector
    container_name: postgres-pgvector
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"

💡 Essa imagem já vem com o pgvector instalado.

2. Suba o container

docker-compose up -d

3. Acesse o banco

Você pode conectar via psql, DBeaver, TablePlus ou qualquer cliente PostgreSQL, usando:

• Host: localhost
• Porta: 5432
• Usuário: postgres
• Senha: postgres

4. Crie a extensão no seu schema

Dentro do seu banco, execute:

CREATE EXTENSION IF NOT EXISTS vector;

Pronto! Agora você pode criar colunas do tipo vector:

CREATE TABLE documentos (
  id SERIAL PRIMARY KEY,
  conteudo TEXT,
  embedding VECTOR(1536)
);

Inserir e buscar embeddings

Depois de gerar embeddings com sua IA favorita (ex: OpenAI ou transformers), basta salvar assim:

INSERT INTO documentos (conteudo, embedding)
VALUES (
  'Texto sobre carros elétricos',
  '[0.123, 0.998, -0.234, ...]' -- até 1536 dimensões, por exemplo
);

E pra buscar por similaridade:

SELECT conteudo
FROM documentos
ORDER BY embedding <-> '[0.111, 0.999, -0.210, …]'
LIMIT 5;

Você pode usar operadores como:

• <-> (distância euclidiana)
• <#> (distância de Manhattan)
• <=> (cosseno)

5. Caso prático: armazenando e consultando embeddings com Node.js e OpenAI

Vamos supor que você tenha uma lista de textos (ex: artigos, perguntas frequentes, resumos de atendimento) e queira permitir que a IA busque informações com base no significado e não só nas palavras.

Geração do embedding

Você pode usar a API da OpenAI para gerar os vetores com o modelo text-embedding-3-small ou text-embedding-ada-002.

Exemplo em Node.js:

import { OpenAI } from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function gerarEmbedding(texto: string) {
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: texto,
  });

  return response.data[0].embedding; // retorna um array com ~1536 floats
}

Armazenando no PostgreSQL com pgvector

Depois de gerar o embedding, você pode armazenar no banco com um INSERT:

import { Pool } from 'pg';

const pool = new Pool({
  user: 'postgres',
  password: 'postgres',
  host: 'localhost',
  port: 5432,
  database: 'mydb',
});

async function salvarDocumento(conteudo: string, embedding: number[]) {
  await pool.query(
    `INSERT INTO documentos (conteudo, embedding) VALUES ($1, $2)`,
    [conteudo, embedding]
  );
}

Lembre-se: a coluna embedding deve ser do tipo vector(1536) (ou o tamanho compatível com o modelo que você usar).

Consulta por similaridade

Agora imagine que você quer buscar no banco os textos mais parecidos com um novo input.

Você gera o embedding do input e faz uma consulta ordenando pela distância vetorial:

async function buscarMaisParecidos(embeddingConsulta: number[]) {
  const { rows } = await pool.query(
    `
    SELECT conteudo
    FROM documentos
    ORDER BY embedding <-> $1
    LIMIT 5
    `,
    [embeddingConsulta]
  );

  return rows;
}

Exemplo de uso completo:

const pergunta = "Quais são os benefícios de carros elétricos?";
const embedding = await gerarEmbedding(pergunta);

const resultados = await buscarMaisParecidos(embedding);

console.log("Resultados mais próximos:");
console.log(resultados);

Resultado

Em vez de depender de uma busca por palavras exatas, agora você tem um sistema que entende o contexto, retorna conteúdos relacionados com base em semelhança semântica e tudo isso usando IA + PostgreSQL.

É a base de qualquer sistema moderno de:

• FAQ inteligente
• Chat com base em documentos (RAG)
• Assistentes contextuais

E o melhor: sem complicação.

Conclusão

Se você está entrando no mundo da IA, entender embeddings e como armazená-los com eficiência é fundamental.
O pgvector com Docker te dá uma estrutura rápida e prática para começar a trabalhar com IA baseada em contexto.

Agora que você sabe o básico, que tal testar?
Em poucos minutos você já pode estar consultando dados com contexto semântico — e dando o primeiro passo pra construir um RAG próprio.