Guia de Uso da Extensão pgvector no PostgreSQL no ServBay

O pgvector é uma poderosa extensão de terceiros para o banco de dados PostgreSQL, trazendo ao PostgreSQL o suporte nativo ao tipo de dado vetorial e métodos de indexação avançados como IVFFlat e HNSW. Dessa forma, o PostgreSQL passa a suportar armazenamento e buscas por similaridade envolvendo vetores — tornando-se uma solução ideal para desenvolvimento de aplicações de IA, sistemas de recomendação, reconhecimento de imagem e processamento de linguagem natural que lidam com vetores de alta dimensão.

O ServBay, integrado como ambiente local de desenvolvimento Web, já vem com PostgreSQL e a extensão pgvector pré-instalados, simplificando sobremaneira o processo para ativar e usar bancos de dados vetoriais localmente. Este artigo mostra, passo a passo, como aproveitar o pgvector no ServBay.

O que é pgvector? E por que é importante?

Em muitos aplicativos modernos, os dados vão além de simples texto estruturado e números. Especialmente com o avanço da inteligência artificial e do machine learning, os dados frequentemente são representados como vetores de alta dimensão, chamados de “embeddings”. Esses vetores capturam a semântica ou características dos dados — por exemplo, os traços visuais de uma imagem, o significado de um texto ou preferências de usuários.

A extensão pgvector permite ao PostgreSQL armazenar esses vetores diretamente e realizar buscas de similaridade eficiente (busca pelos “vizinhos mais próximos”). Isso significa que você pode usar SQL para procurar os itens mais parecidos com um vetor de referência, sem precisar recorrer a bancos de dados vetoriais externos, simplificando sua stack tecnológica.

Pré-requisitos

Antes de começar a usar o pgvector, verifique se atende aos seguintes pré-requisitos:

1. Ter o ServBay instalado e rodando no macOS.
2. Ter o pacote PostgreSQL ativado na lista de “Pacotes” do ServBay. Se não estiver habilitado, localize o PostgreSQL na interface do ServBay e marque-o como “Habilitado”.

Ativando a extensão pgvector no PostgreSQL do ServBay

O ServBay já inclui os arquivos da extensão pgvector no diretório de instalação do PostgreSQL, dispensando downloads ou compilações manuais. Basta ativá-la no banco de dados onde você deseja utilizar o pgvector.

Confira os passos para habilitar a extensão pgvector no PostgreSQL do ServBay:

1. Conecte-se ao banco de dados PostgreSQL: Utilize o terminal e o utilitário psql para se conectar à instância PostgreSQL do ServBay. A configuração padrão permite conexões locais. O usuário padrão normalmente é postgres ou servbay, e a porta padrão é 5432. Caso sua configuração seja diferente, consulte a documentação do ServBay.

   Execute o comando a seguir (ajuste conforme seu usuário e nome do banco):

   psql -U servbay -d your_database_name -h localhost -p 5432

   • -U servbay: Especifica o usuário (servbay ou postgres).
   • -d your_database_name: Nome do banco de dados. Se não existir, crie antes (exemplo: CREATE DATABASE servbay_demo_db;).
   • -h localhost: Conexão local.
   • -p 5432: Porta padrão.

2. Crie a extensão vector: Após conectar, rode este comando SQL no prompt do psql para habilitar o pgvector:

   CREATE EXTENSION vector;

   Caso a extensão já exista, você verá um aviso correspondente.

3. Confirme a instalação: Para checar se a extensão foi instalada com sucesso, liste as extensões:

   \dx

   Procure na saída pelo nome vector e sua versão, por exemplo:

                          List of installed extensions
      Name   | Version |   Schema   |                         Description
   ----------+---------+------------+--------------------------------------------------------------
    plpgsql  | 1.0     | pg_catalog | PL/pgSQL procedural language
    vector   | 0.7.0   | public     | vector data type and ivfflat and hnsw access methods
   (2 rows)

   (Obs.: A versão pode variar conforme o pacote do ServBay.)

Configuração e uso do pgvector

Depois de habilitar a extensão, você poderá criar e gerenciar dados vetoriais no banco.

Criando uma tabela para dados vetoriais

Crie uma tabela que armazene vetores usando o novo tipo VECTOR(dimensions), onde dimensions é o número de dimensões.

Exemplo para criar uma tabela chamada embeddings, armazenando vetores de 3 dimensões:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Define uma coluna vetorial com 3 dimensões
    vector VECTOR(3)
);

Insira dados de exemplo:

INSERT INTO embeddings (vector) VALUES
('[0.1, 0.2, 0.3]'),
('[0.4, 0.5, 0.6]'),
('[0.7, 0.8, 0.9]'),
('[0.15, 0.25, 0.35]'),
('[0.6, 0.5, 0.4]'); -- Insira mais dados para explorar outros exemplos de consulta

Obs.: Os valores dos vetores devem estar entre colchetes [] e separados por vírgulas.

Criando índices vetoriais para melhor desempenho

Se a tabela tiver muitos vetores, criar índices é vital para acelerar buscas por similaridade. O pgvector dá suporte aos tipos de índice IVFFlat e HNSW. A escolha depende das necessidades do seu projeto (velocidade, tempo de construção, memória, qualidade da busca).

• IVFFlat (Inverted File Index com compressão Flat): Indicado para grandes volumes de dados, com tolerância à perda de recall. Construção rápida.
• HNSW (Hierarchical Navigable Small World): Geralmente tem melhor recall e consultas mais rápidas, mas indexação pode ser mais lenta e consumir mais memória.

Veja como criar índices IVFFlat e HNSW para a coluna vector da tabela embeddings:

1. Criando índice IVFFlat:

   -- Antes de criar o índice, rode ANALYZE para coletar estatísticas
   ANALYZE embeddings;
   
   -- Crie o índice IVFFlat
   -- WITH (lists = 100): Número de listas invertidas. Ajuste conforme tamanho do seu dataset.
   -- Quanto mais listas, mais lento para construir e consultar, mas o recall tende a ser maior.
   -- Recomenda-se lists = sqrt(número de linhas).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. Criando índice HNSW:

   -- Crie o índice HNSW
   -- WITH (m = 16, ef_construction = 200): Parâmetros do HNSW.
   -- m: Máximo de conexões por nó (impacta conectividade, performance e memória).
   -- ef_construction: Range de busca na construção do índice (impacta tempo, memória e qualidade).
   -- Ajuste conforme sua base e requisitos.
   CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

   Atenção: Parâmetros como lists, m e ef_construction impactam fortemente resultado e performance. Escolha com base no entendimento do seu dado e faça testes. Consulte a documentação oficial do pgvector para detalhes sobre ajustes.

Consultas vetoriais com pgvector

O pgvector fornece operadores para calcular distância entre vetores e fazer buscas por similaridade. Os principais são:

• <->: Distância L2 (Euclidiana). Mede a distância “reta” entre os vetores.
• <#>: Produto interno (Inner Product). Relacionado à similaridade por cosseno, útil para direção.
• <=>: Distância de cosseno. Representa 1 - similaridade por cosseno, útil para comparar direção dos vetores independente do tamanho.

Exemplos comuns de consulta:

Busca pelos vizinhos mais próximos (Nearest Neighbor Search)

Procure os vetores mais parecidos (menor distância) com um vetor de consulta. Utilize ORDER BY com o operador desejado e LIMIT para limitar os resultados.

1. Encontrar os 5 vetores mais próximos de [0.2, 0.3, 0.4] usando L2:

   SELECT
       id,
       vector,
       -- Calcula a distância L2 com o vetor de consulta
       vector <-> '[0.2, 0.3, 0.4]' AS distance
   FROM
       embeddings
   ORDER BY
       distance -- Ordem crescente (mais próximo primeiro)
   LIMIT 5;

Busca por similaridade vetorial

Parecido com vizinhos mais próximos, mas enfatiza a pontuação de similaridade.

1. Encontrar os 5 vetores com menor distância de cosseno para [0.2, 0.3, 0.4]:

   SELECT
       id,
       vector,
       -- Calcula a distância de cosseno para o vetor de consulta
       vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
   FROM
       embeddings
   ORDER BY
       cosine_distance -- Ordem crescente (mais próximo primeiro)
   LIMIT 5;

Visualização de dados vetoriais (opcional)

Visualizar os vetores ajuda a entender distribuição e agrupamento. Vetores de 2D ou 3D podem ser representados com gráficos de dispersão. Para dimensões maiores, use técnicas como PCA ou t-SNE para reduzir para 2D/3D antes de visualizar.

Exemplo de como visualizar vetores 3D usando Python e Matplotlib:

1. Prepare o ambiente Python: Configure um ambiente Python dentro ou fora do ServBay. Se usar o pacote Python do ServBay, certifique-se que está habilitado. Instale as bibliotecas psycopg2 (PostgreSQL) e matplotlib:

   # Com Python do sistema ou de sua instalação
   pip install psycopg2 matplotlib
   
   # Com Python do ServBay, execute via o comando específico ou pip no diretório bin
   # /Applications/ServBay/pacotes/python/bin/pip install psycopg2 matplotlib

   Ajuste o caminho do pip conforme o seu ambiente.

2. Crie o script Python: Crie um arquivo (por exemplo, visualize_vectors.py) e copie o código abaixo. Edite os parâmetros de conexão (dbname, user, password, host, port) conforme sua configuração no ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Importa módulo para grafo 3D
   
   # Parâmetros de conexão - ajuste conforme o ServBay
   db_params = {
       "dbname": "your_database_name", # Nome do banco de dados
       "user": "servbay",              # Usuário do PostgreSQL no ServBay (servbay ou postgres)
       "password": "",                 # Senha (pode estar em branco para conexão local)
       "host": "localhost",            # PostgreSQL normalmente roda em localhost
       "port": "5432"                  # Porta padrão do ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # Conecta ao banco PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Consulta os vetores
       # Obs: Por padrão, psycopg2 lê '[x, y, z]' como string.
       # Pode ser necessário tratamento manual, a menos que haja integração automática.
       cur.execute("SELECT vector FROM embeddings")
       vectors_raw = cur.fetchall()
   
       # Converte as strings dos vetores para lista de floats
       vectors = []
       for row in vectors_raw:
           vec_str = row[0].strip('[]')
           coords = [float(c) for c in vec_str.split(',')]
           vectors.append(coords)
   
       if not vectors:
           print("Nenhum vetor encontrado no banco.")
           exit()
   
       # Extrai coordenadas e verifica se são todos 3D
       if any(len(v) != 3 for v in vectors):
            print("Aviso: Vetores não são todos 3D. Não é possível mostrar o gráfico 3D.")
            # Pode-se optar por gráfico 2D ou sair
            exit()
   
   
       x = [v[0] for v in vectors]
       y = [v[1] for v in vectors]
       z = [v[2] for v in vectors]
   
       # Cria o gráfico de dispersão 3D
       fig = plt.figure()
       ax = fig.add_subplot(111, projection='3d')
       ax.scatter(x, y, z)
   
       ax.set_xlabel('Dimensão 1')
       ax.set_ylabel('Dimensão 2')
       ax.set_zlabel('Dimensão 3')
       ax.set_title('Visualização Vetorial 3D')
   
       plt.show()
   
   except psycopg2.Error as e:
       print(f"Erro de conexão ou consulta ao banco: {e}")
   except Exception as e:
       print(f"Ocorreu um erro: {e}")
   finally:
       # Fecha conexões
       if cur:
           cur.close()
       if conn:
           conn.close()

3. Execute o script: No terminal, rode o script Python:

   python visualize_vectors.py

   O script conecta ao seu banco PostgreSQL, lê vetores e gera uma visualização 3D com Matplotlib.

Perguntas Frequentes (FAQ)

• Pergunta: Não encontro a extensão vector na saída do comando \dx. E agora? Resposta: Verifique se executou corretamente o comando CREATE EXTENSION vector; e se não houve erros. Se não aparecer, cheque se o pacote PostgreSQL do ServBay está instalado e ativado. Os arquivos do pgvector devem estar no diretório share/extension do PostgreSQL — se estiverem faltando, tente reinstalar ou atualizar o pacote do ServBay.
• Pergunta: Recebo erro de autenticação ao conectar ao banco de dados. O que fazer? Resposta: Cheque se o usuário, senha, host e porta usados no psql ou no script Python correspondem à configuração do ServBay. Para conexões locais, geralmente o usuário é servbay ou postgres, e pode não exigir senha.
• Pergunta: Como escolher os parâmetros dos índices vetoriais (lists, m, ef_construction)? Resposta: Esses parâmetros impactam fortemente o desempenho e o recall. Não existe valor “ímpar” universal. Faça experimentações conforme sua base, dimensões, necessidade de velocidade e recall. Consulte a documentação oficial para dicas e recomendações detalhadas.

Conclusão

O pgvector traz capacidades avançadas de banco de dados vetorial para o PostgreSQL, robusto e estável, tornando possível trabalhar localmente com IA e aplicações relacionadas a vetores com facilidade e produtividade. Com o ServBay já fornecendo o pgvector pré-instalado, o processo de configuração é direto.

Seguindo este guia, você poderá ativar facilmente o pgvector no PostgreSQL do ServBay, criar tabelas para vetores, criar índices eficientes, realizar buscas e consultas por similaridade, além de visualizar dados vetoriais quando necessário. Combine essas ferramentas com os demais ambientes do ServBay para construir e testar aplicações modernas e intensivas em dados de forma muito mais eficiente.