Dados vetoriais em .NET – Blocos de construção para IA, parte 2

Bem-vindo de volta aos blocos de construção da série AI na série .NET! Na primeira parte, exploramos o Microsoft Extensions for AI (MEAI) e como ele fornece uma interface unificada para trabalhar com grandes modelos de linguagem. Hoje, estamos mergulhando no segundo bloco de construção: Microsoft.Extensions.VectorData.

No primeiro post, aprendemos como fazer perguntas e até compartilhar algum conteúdo para contextualizar com um LLM. A maioria dos aplicativos, entretanto, exige mais do que apenas uma simples pergunta ou um pequeno arquivo markdown para contextualizar. Você pode querer que o LLM tenha acesso a todos os manuais de seus produtos para ajudar a solucionar problemas dos clientes ou fornecer o manual do funcionário para um chatbot de RH.

Outro recurso comum em aplicativos inteligentes é a pesquisa semântica. Uma pesquisa semântica utiliza o significado de uma consulta, e não apenas as palavras ou letras, para conduzir a pesquisa. Ele faz isso convertendo texto em incorporações que são representações numéricas do significado semântico do texto e vetores que fornecem insights sobre como eles estão relacionados.

Imagine que você tem um banco de dados simples com apenas três entradas:

1. Passe de corredor
2. Passagem de montanha
3. Passar (verbo)

Uma abordagem tradicional para encontrar a resposta para perguntas como “Como faço para superar o passe?” ou “Onde posso pegar um passe?” divide a consulta em partes a serem pesquisadas. A palavra “passar” aparece em todos os três itens do banco de dados, então recebo todas as três entradas de volta, apesar dos diferentes contextos das minhas consultas. Aqui está uma visualização simplificada:

"How do I get over the pass?" 
How | do | I | get | over | the | pass 
Pass - matches all three entries 

"Where do I pick up my pass?"
Where | do | I | pick | up | my | pass 
Pass - matches all three entries 

Agora vamos supor que eu use uma incorporação para codificar o significado semântico da palavra. O banco de dados já foi codificado, mas preciso criar embeddings a partir da minha consulta. Desta vez, porém, os embeddings me fornecem um resultado semântico, não baseado em texto. A abordagem semântica é assim:

"How do I get over the pass?" 
0 | 5 | etc. | 2 
2 - matches the 2nd entry, "Mountain pass" 

"Where do I pick up my pass?" 
6 | 9 | etc. | 1   
1 - matches the 1st entry, "Hall pass" 

Um modelo de embeddings especial é usado para criar os embeddings e é treinado para compreender o significado semântico das palavras por meio do contexto, como os termos relacionados que aparecem antes e depois dele. Em vez de gerar embeddings toda vez que o aplicativo é executado, faz muito mais sentido armazená-los em um banco de dados. Isso tem a vantagem adicional de poder usar a capacidade do banco de dados para consultar e retornar resultados, em vez de codificar a lógica sozinho ou fazê-lo de maneira abaixo do ideal.

Bancos de dados vetoriais são projetados especificamente para armazenar vetores e embeddings. Qdrant, Redis, SQL Server e Cosmos DB são exemplos de serviços e produtos que suportam o armazenamento de dados vetoriais. Assim como o acesso LLM unificado MEAI, as extensões de dados vetoriais fornecem uma abstração comum para trabalhar com armazenamentos de vetores.

Por que os vetores são importantes para aplicações de IA

Antes de entrarmos no código, vamos examinar um pouco mais de perto os vetores. Quando você faz uma pergunta a um LLM sobre a documentação da sua empresa, o modelo não conhece magicamente o seu conteúdo. Em vez disso, seu aplicativo normalmente:

1. Converte seus documentos em incorporações – representações numéricas que capturam significado semântico
2. Armazena essas incorporações em um banco de dados vetorial junto com o conteúdo original
3. Converte a consulta do usuário em uma incorporação usando o mesmo modelo
4. Executa uma pesquisa de similaridade para encontrar os documentos mais relevantes
5. Passa o contexto relevante para o LLM junto com a consulta do usuário

Esse padrão, conhecido como RAG (Retrieval-Augmented Generation), permite que os modelos forneçam respostas precisas e fundamentadas com base em seus dados específicos. O desafio? Cada banco de dados vetorial possui seu próprio SDK, estruturas de dados e padrões de consulta. É aí que entra Microsoft.Extensions.VectorData.

Uma interface, muitos armazenamentos de vetores

A biblioteca Microsoft Extensions for Vector Data fornece abstrações que funcionam em diferentes provedores de banco de dados vetoriais. Aqui está o que isso parece na prática. Primeiro, vamos usar um exemplo de banco de dados vetorial, Qdrant, diretamente e sem as abstrações:

var qdrantClient = new QdrantClient("localhost", 6334);

var collection = "my_collection";
await qdrantClient.CreateCollectionAsync(collection, new VectorParams
{
    Size = 1536,
    Distance = Distance.Cosine
});

var points = new List
{
    new()
    {
        Id = new PointId { Uuid = Guid.NewGuid().ToString() },
        Vectors = embedding,
        Payload =
        {
            ("text") = "Sample document text",
            ("category") = "documentation"
        }
    }
};

await qdrantClient.UpsertAsync(collection, points);

var searchResults = await qdrantClient.SearchAsync(collection, queryEmbedding, limit: 5);

Agora vamos ver a mesma coisa usando as abstrações universais:

// Configure embedding generation once on the vector store
var embeddingGenerator = new OpenAIClient(apiKey)
    .GetEmbeddingClient("text-embedding-3-small")
    .AsIEmbeddingGenerator();

var vectorStore = new QdrantVectorStore(
    new QdrantClient("localhost"),
    ownsClient: true,
    new QdrantVectorStoreOptions { EmbeddingGenerator = embeddingGenerator });

var collection = vectorStore.GetCollection("my_collection");
await collection.EnsureCollectionExistsAsync();

var record = new DocumentRecord
{
    Key = Guid.NewGuid().ToString(),
    Text = "Sample document text",
    Category = "documentation"
};

await collection.UpsertAsync(record);

var searchResults = collection.SearchAsync("find documents about sample topics", top: 5);

O segundo exemplo funciona com qualquer armazenamento de vetores suportado, simplesmente alterando o VectorStore implementação. Sua lógica de negócios permanece a mesma.

Definindo seu modelo de dados

As abstrações de dados vetoriais usam atributos para mapear suas classes C# para esquemas de banco de dados vetoriais. Aqui está um exemplo prático para um armazenamento de documentos:

public class DocumentRecord
{
    (VectorStoreKey)
    public string Key { get; set; }

    (VectorStoreData)
    public string Text { get; set; }

    (VectorStoreData(IsIndexed = true))
    public string Category { get; set; }

    (VectorStoreData(IsIndexed = true))
    public DateTimeOffset Timestamp { get; set; }

    // The vector is automatically generated from Text when an
    // IEmbeddingGenerator is configured on the collection or vector store
    (VectorStoreVector(1536, DistanceFunction.CosineSimilarity))
    public string Embedding => this.Text;
}

Os atributos informam à biblioteca:

• VectorStoreKey – Esta propriedade identifica exclusivamente cada registro
• VectorStoreData – Estes são campos de metadados que você pode filtrar e recuperar
• VectorStoreVector – Este é o vetor de incorporação com suas dimensões e função de distância

Trabalhando com coleções

Depois de definir seu modelo de dados, trabalhar com coleções será simples. A biblioteca fornece uma interface consistente, independentemente do seu armazenamento de vetores subjacente:

// Get or create a collection
var collection = vectorStore.GetCollection("documents");

// Check if the collection exists
bool exists = await collection.CollectionExistsAsync();
await collection.EnsureCollectionExistsAsync();

// Insert or update records
await collection.UpsertAsync(documentRecord);

// Batch operations are supported
await collection.UpsertBatchAsync(documentRecords);

// Retrieve by key
var record = await collection.GetAsync("some-key");

// Delete records
await collection.DeleteAsync("some-key");
await collection.DeleteBatchAsync(("key1", "key2", "key3"));

Pesquisa semântica

O verdadeiro poder surge quando você realiza pesquisas semânticas usando o SearchAsync método. Quando um IEmbeddingGenerator está configurado no armazenamento ou coleção de vetores, basta passar o texto da sua consulta e os embeddings são gerados automaticamente:

// Embeddings are generated automatically when IEmbeddingGenerator is configured
await foreach (var result in collection.SearchAsync("What is semantic search?", top: 5))
{
    Console.WriteLine($"Score: {result.Score}, Text: {result.Record.Text}");
}

Se você já possui um pré-calculado ReadOnlyMemory incorporação – por exemplo, ao agrupar incorporações em lote – você pode passá-la diretamente:

// Pass a pre-computed embedding vector directly
ReadOnlyMemory precomputedEmbedding = /* your embedding */;
await foreach (var result in collection.SearchAsync(precomputedEmbedding, top: 5))
{
    Console.WriteLine($"Score: {result.Score}, Text: {result.Record.Text}");
}

Filtrando resultados

Você pode combinar similaridade vetorial com filtragem de metadados para restringir os resultados:

var searchOptions = new VectorSearchOptions
{
    Filter = r => r.Category == "documentation" &&
                  r.Timestamp > DateTimeOffset.UtcNow.AddDays(-30)
};

var results = collection.SearchAsync("find relevant documentation", top: 10, searchOptions);

Os filtros usam expressões LINQ padrão. As operações apoiadas incluem:

• Comparações de igualdade (==, !=)
• Consultas de intervalo (>, <, >=, <=)
• Operadores lógicos (&&, ||)
• Associação à coleção (.Contains())

Integrando com embeddings

A abordagem recomendada é configurar um IEmbeddingGenerator na loja ou coleção de vetores. Os embeddings são então gerados automaticamente durante o upsert e a pesquisa – sem necessidade de pré-processamento manual:

// Configure an embedding generator on the vector store
var embeddingGenerator = new OpenAIClient(apiKey)
    .GetEmbeddingClient("text-embedding-3-small")
    .AsIEmbeddingGenerator();

var vectorStore = new InMemoryVectorStore(new() { EmbeddingGenerator = embeddingGenerator });
var collection = vectorStore.GetCollection("documents");
await collection.EnsureCollectionExistsAsync();

// Embeddings are generated automatically on upsert
var record = new DocumentRecord
{
    Key = Guid.NewGuid().ToString(),
    Text = "Sample text to store"
};
await collection.UpsertAsync(record);

// Embeddings are also generated automatically on search
await foreach (var result in collection.SearchAsync("find similar text", top: 5))
{
    Console.WriteLine($"Score: {result.Score}, Text: {result.Record.Text}");
}

Implementando padrões RAG

Reunindo tudo, aqui está uma implementação RAG simplificada usando Microsoft.Extensions.AI e Microsoft.Extensions.VectorData:

public async Task AskQuestionAsync(string question)
{
    // Find relevant documents - embeddings are generated automatically
    var contextParts = new List();
    await foreach (var result in collection.SearchAsync(question, top: 3))
    {
        contextParts.Add(result.Record.Text);
    }

    // Build context from results
    var context = string.Join("nn", contextParts);

    // Create prompt with context
    var messages = new List
    {
        new(ChatRole.System, 
            "Answer questions based on the provided context. If the context doesn't contain relevant information, say so."),
        new(ChatRole.User, 
            $"Context:n{context}nnQuestion: {question}")
    };

    // Get response from LLM
    var response = await chatClient.GetResponseAsync(messages);
    return response.Message.Text;
}

Lojas de vetores suportadas

Microsoft.Extensions.VectorData funciona com uma ampla variedade de bancos de dados vetoriais por meio de conectores oficiais:

• Pesquisa de IA do Azure – Microsoft.Extensions.VectorData.AzureAISearch
• Qdrant – Microsoft.SemanticKernel.Connectors.Qdrant
• Redis – Microsoft.SemanticKernel.Connectors.Redis
• PostgreSQL – Microsoft.SemanticKernel.Connectors.Postgres
• Azure Cosmos DB (NoSQL) – Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL
• Servidor SQL – Microsoft.SemanticKernel.Connectors.SqlServer
• SQLite – Microsoft.SemanticKernel.Connectors.Sqlite
• Na memória – Microsoft.SemanticKernel.Connectors.InMemory (ótimo para teste e desenvolvimento)

Para obter a lista completa de conectores suportados — incluindo Elasticsearch, MongoDB, Weaviate, Pinecone e muito mais — consulte o documentação de conectores prontos para uso.

Por que separar-se das principais extensões de IA?

Você pode estar se perguntando por que os dados vetoriais estão em uma biblioteca separada do pacote principal Microsoft.Extensions.AI. A resposta é simples: nem toda aplicação inteligente precisa de armazenamento vetorial. Muitos cenários – como chatbots, geração de conteúdo ou tarefas de classificação – funcionam perfeitamente apenas com as abstrações do LLM. Ao manter os dados vetoriais separados, a biblioteca principal permanece leve e focada.

Quando você precisar de vetores para pesquisa semântica, RAG ou memória de longo prazo, poderá adicionar o pacote de dados vetoriais e se beneficiar imediatamente dos mesmos padrões consistentes que já está usando com MEAI.

Resumo

Microsoft.Extensions.VectorData traz aos bancos de dados vetoriais os mesmos benefícios que Microsoft.Extensions.AI traz aos LLMs: uma interface unificada e independente de provedor que torna seu código portátil e sua arquitetura flexível. Esteja você implementando padrões RAG, construindo pesquisa semântica ou criando memória de longo prazo para agentes de IA, essas abstrações permitem que você se concentre na lógica do seu aplicativo em vez de SDKs específicos do banco de dados.

Na próxima postagem, exploraremos o Microsoft Agent Framework e veremos como esses blocos de construção se unem para criar fluxos de trabalho de agente sofisticados. Até então, aqui estão alguns recursos para ajudá-lo a começar a usar dados vetoriais em .NET:

• Aprenda por código
• Aprenda seguindo tutoriais
• Aprenda assistindo vídeos

Boa codificação!