NOTíCIAS DA ACADEMIA

Construindo Busca Vetorial no .NET com PgVector, Um Guia para Desenvolvedores

Atualizado:

Se você está construindo aplicativos .NET que lidam com grandes volumes de dados, documentos, catálogos de produtos, registros de clientes ou arquivos escaneados, a pesquisa sempre é um desafio. A pesquisa por palavras-chave falha em captar o contexto. A pesquisa de texto completo tem seus limites. Mas a busca vetorial muda essa equação completamente.

Recentemente, encontramos um excelente guia de Milan Jovanović, uma das vozes mais respeitadas na comunidade .NET e um Microsoft MVP, que explica exatamente como implementar a busca vetorial no .NET usando o PgVector, uma extensão do PostgreSQL que traz capacidades de busca semântica diretamente para o seu banco de dados existente.

O que é busca vetorial e como ela funciona?

A busca tradicional corresponde a palavras ou frases exatas. Se um usuário busca por "fatura em atraso", uma busca por palavras-chave encontrará apenas documentos que contenham essas palavras exatas. Ela não trará à tona um documento que diga "pagamento pendente" ou "saldo devido", mesmo que tenham o mesmo significado.

A busca vetorial funciona diferente. Em vez de corresponder a palavras, ela corresponde ao significado.

Aqui está como o pipeline funciona na prática:

Primeiro, o texto é convertido em uma representação numérica chamada de embedding, um array de alta dimensão de números de ponto flutuante que captura o significado semântico do conteúdo. Por exemplo, as frases "fatura em atraso" e "pagamento pendente" produziriam embeddings que são matematicamente próximos entre si no espaço vetorial, mesmo que não compartilhem palavras comuns.

Esses embeddings são gerados por um modelo de aprendizado de máquina, tipicamente via uma API como os modelos de embedding de texto da OpenAI e são armazenados junto com seus dados no banco de dados.

Imagem 1

Quando um usuário executa uma consulta de pesquisa, essa consulta também é convertida em um embedding usando o mesmo modelo. O banco de dados então calcula a distância entre o embedding da consulta e todos os embeddings armazenados, retornando os resultados mais próximos no espaço vetorial, significando os mais semanticamente similares, não apenas correspondentes por palavras-chave.

PgVector permite isso diretamente dentro do PostgreSQL, suportando pesquisas de similaridade eficientes ao lado de seus dados relacionais, sem exigir um banco de dados vetorial dedicado.

Inicializando o Banco de Dados

Antes de armazenar vetores, habilite a extensão PgVector e configure a tabela.


var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddOllama("ollama")
    .WithLifetime(ContainerLifetime.Persistent)
    .WithDataVolume()
    .WithGPUSupport();

var embeddingModel = ollama.AddModel("qwen3-embedding:0.6b");

var postgres = builder.AddPostgres("postgres", port: 6432)
    .WithLifetime(ContainerLifetime.Persistent)
    .WithDataVolume()
    .WithImage("pgvector/pgvector", "pg17")
    .AddDatabase("articles");

builder.AddProject<Projects.PgVector_Articles>("pgvector-articles")
    .WithReference(embeddingModel)
    .WithReference(postgres)
    .WaitFor(embeddingModel)
    .WaitFor(postgres);

builder.Build().Run();

var builder = DistributedApplication.CreateBuilder(args);

var ollama = builder.AddOllama("ollama")
    .WithLifetime(ContainerLifetime.Persistent)
    .WithDataVolume()
    .WithGPUSupport();

var embeddingModel = ollama.AddModel("qwen3-embedding:0.6b");

var postgres = builder.AddPostgres("postgres", port: 6432)
    .WithLifetime(ContainerLifetime.Persistent)
    .WithDataVolume()
    .WithImage("pgvector/pgvector", "pg17")
    .AddDatabase("articles");

builder.AddProject<Projects.PgVector_Articles>("pgvector-articles")
    .WithReference(embeddingModel)
    .WithReference(postgres)
    .WaitFor(embeddingModel)
    .WaitFor(postgres);

builder.Build().Run();

Se você não estiver usando Aspire, você pode executar a mesma imagem pgvector/pgvector:pg17 via docker-compose e apontar para ela com uma string de conexão normal.

Esta seção é baseada no artigo original de Milan Jovanović. Exemplos de código completos e detalhes de implementação estão disponíveis lá.

Por que isso é importante para os clientes da Iron Software

Muitos de nossos clientes usam IronPDF, IronOCR e IronBarcode para processar grandes volumes de documentos; faturas, relatórios, registros digitalizados, etiquetas de envio.

Um fluxo de trabalho prático combinando bibliotecas da Iron Software com PgVector poderia se parecer com isto:

  1. Extract – Use o IronOCR para extrair texto de PDFs escaneados ou imagens
  2. Embed – Envie o texto extraído para um modelo de incorporação para gerar representações vetoriais
  3. Store – Economize incorporações juntamente com metadados de documentos no PostgreSQL usando Pgvector
  4. Search – Consultar por significado, retornando os documentos mais semanticamente relevantes em vez de correspondências exatas de palavras-chave

O resultado é um sistema de busca de documentos mais inteligente, totalmente construído dentro da sua pilha existente de .NET e PostgreSQL, sem necessidade de infraestrutura adicional.

O que o guia de Milan cobre

O artigo de Milan percorre a implementação completa em C#: configurando a extensão PgVector no PostgreSQL, configurando o Entity Framework Core com Npgsql, gerando embeddings, criando índices vetoriais para desempenho e executando consultas de similaridade. É prático, orientado para produção e imediatamente aplicável para qualquer desenvolvedor .NET.

A equipe de desenvolvimento da Iron Software compartilha regularmente recursos, tutoriais e insights de engenharia .NET com nossa comunidade.

Construindo fluxos de trabalho de documentos em .NET? Iron Suite tem tudo que você precisa.