Vetores de índice e consulta no Azure Cosmos DB para NoSQL no .NET
Antes de usar a indexação vetorial e a pesquisa, você deve primeiro habilitar o recurso. Este artigo aborda as seguintes etapas:
- Habilitando o recurso Pesquisa vetorial no Azure Cosmos DB para NoSQL.
- Configurando o contêiner do Azure Cosmos DB para pesquisa vetorial
- Política de incorporação de vetores de criação
- Adicionando índices de vetor à política de indexação de contêiner
- Criando um contêiner com índices vetoriais e política de incorporação de vetores
- Realizar uma pesquisa vetorial nos dados armazenados
Este guia percorre o processo de criação de dados vetoriais, indexação dos dados e, em seguida, consulta dos dados em um contêiner.
Pré-requisitos
- Uma conta existente do Azure Cosmos DB para NoSQL.
- Se você não tiver uma assinatura do Azure, experimente o Azure Cosmos DB para NoSQL gratuitamente.
- Se você tiver uma assinatura existente do Azure, crie uma nova conta do Azure Cosmos DB para NoSQL.
- Versão mais recente do Azure Cosmos DB .NET SDK (Versão: 3.45.0 ou posterior, Pré-visualização: 3.46.0-preview.0 ou posterior).
Ativar a funcionalidade
A pesquisa vetorial do Azure Cosmos DB para NoSQL requer a habilitação do recurso concluindo as seguintes etapas:
- Navegue até a página de recursos do Azure Cosmos DB para NoSQL.
- Selecione o painel "Recursos" no item de menu "Configurações".
- Selecione "Pesquisa vetorial no Azure Cosmos DB para NoSQL".
- Leia a descrição do recurso para confirmar que deseja ativá-lo.
- Selecione "Ativar" para ativar a pesquisa vetorial no Azure Cosmos DB para NoSQL.
Gorjeta
Como alternativa, use a CLI do Azure para atualizar os recursos da sua conta para dar suporte à pesquisa vetorial NoSQL.
az cosmosdb update \
--resource-group <resource-group-name> \
--name <account-name> \
--capabilities EnableNoSQLVectorSearch
Nota
O pedido de inscrição será autoaprovado; no entanto, pode demorar 15 minutos a fazer efeito.
Compreender as etapas envolvidas na pesquisa vetorial
Vamos dar um exemplo de criação de um banco de dados para uma livraria baseada na Internet e você está armazenando Título, Autor, ISBN e Descrição para cada livro. Também definimos duas propriedades para conter incorporações vetoriais. A primeira é a propriedade "contentVector", que contém incorporações de texto geradas a partir do conteúdo de texto do livro (por exemplo, concatenando as propriedades "title", "author", "isbn" e "description" antes de criar a incorporação). O segundo é "coverImageVector", que é gerado a partir de imagens da capa do livro.
- Crie e armazene incorporações vetoriais para os campos nos quais você deseja executar a pesquisa vetorial.
- Especifique os caminhos de incorporação de vetor na política de incorporação de vetores.
- Inclua quaisquer índices de vetor desejados na política de indexação para o contêiner.
Para as seções subsequentes deste artigo, consideramos a estrutura abaixo para os itens armazenados em nosso contêiner:
{
"title": "book-title",
"author": "book-author",
"isbn": "book-isbn",
"description": "book-description",
"contentVector": [2, -1, 4, 3, 5, -2, 5, -7, 3, 1],
"coverImageVector": [0.33, -0.52, 0.45, -0.67, 0.89, -0.34, 0.86, -0.78]
}
Criando uma política de incorporação vetorial para seu contêiner
Em seguida, você precisa definir uma política de vetor de contêiner. Esta política fornece informações que são usadas para informar o mecanismo de consulta do Azure Cosmos DB como manipular propriedades de vetor nas funções do sistema VectorDistance. Esta política também informa a política de indexação vetorial das informações necessárias, caso você opte por especificar uma. As seguintes informações estão incluídas na política de vetores contidos:
- "path": o caminho da propriedade que contém vetores
- "datatype": O tipo dos elementos do vetor (padrão Float32)
- "dimensions": O comprimento de cada vetor no caminho (padrão 1536)
- "distanceFunction": A métrica usada para calcular distância/semelhança (padrão Cosine)
Para o nosso exemplo com detalhes do livro, a política de vetor pode se parecer com o exemplo JSON abaixo:
Database db = await client.CreateDatabaseIfNotExistsAsync("vector-benchmarking");
List<Embedding> embeddings = new List<Embedding>()
{
new Embedding()
{
Path = "/coverImageVector",
DataType = VectorDataType.Float32,
DistanceFunction = DistanceFunction.Cosine,
Dimensions = 8,
},
new Embedding()
{
Path = "/contentVector",
DataType = VectorDataType.Float32,
DistanceFunction = DistanceFunction.Cosine,
Dimensions = 10,
}
};
Criando um índice vetorial na política de indexação
Depois que os caminhos de incorporação vetorial forem decididos, os índices vetoriais precisam ser adicionados à política de indexação. Atualmente, o recurso de pesquisa vetorial para o Azure Cosmos DB para NoSQL é suportado apenas em novos contêineres, portanto, você precisa aplicar a política de vetor durante o tempo de criação do contêiner e ela não pode ser modificada posteriormente. Neste exemplo, a política de indexação teria a seguinte aparência:
Collection<Embedding> collection = new Collection<Embedding>(embeddings);
ContainerProperties properties = new ContainerProperties(id: "vector-container", partitionKeyPath: "/id")
{
VectorEmbeddingPolicy = new(collection),
IndexingPolicy = new IndexingPolicy()
{
VectorIndexes = new()
{
new VectorIndexPath()
{
Path = "/vector",
Type = VectorIndexType.QuantizedFlat,
}
}
},
};
properties.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
properties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/vector/*" });
Importante
O caminho do vetor adicionado à seção "excludedPaths" da política de indexação para garantir um desempenho otimizado para inserção. Não adicionar o caminho do vetor a "excludedPaths" resultará em maior carga de RU e latência para inserções vetoriais.
Executando consulta de pesquisa de semelhança vetorial
Depois de criar um contêiner com a política de vetor desejada e inserir dados vetoriais no contêiner, você pode realizar uma pesquisa vetorial usando a função do sistema Distância vetorial em uma consulta. Suponha que você queira pesquisar livros sobre receitas de alimentos olhando para a descrição, você primeiro precisa obter as incorporações para o seu texto de consulta. Nesse caso, talvez você queira gerar incorporações para o texto da consulta – "receita de comida". Depois de ter a incorporação para sua consulta de pesquisa, você pode usá-la na função VectorDistance na consulta de pesquisa vetorial e obter todos os itens que são semelhantes à sua consulta, conforme mostrado aqui:
SELECT TOP 10 c.title, VectorDistance(c.contentVector, [1,2,3,4,5,6,7,8,9,10]) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.contentVector, [1,2,3,4,5,6,7,8,9,10])
Esta consulta recupera os títulos dos livros, juntamente com pontuações de semelhança em relação à sua consulta. Aqui está um exemplo no .NET:
float[] embedding = {1f,2f,3f,4f,5f,6f,7f,8f,9f,10f};
var queryDef = new QueryDefinition(
query: $"SELECT c.title, VectorDistance(c.contentVector,@embedding) AS SimilarityScore FROM c ORDER BY VectorDistance(c.contentVector,@embedding)"
).WithParameter("@embedding", embedding);
using FeedIterator<Object> feed = container.GetItemQueryIterator<Object>(
queryDefinition: queryDef
);
while (feed.HasMoreResults)
{
FeedResponse<Object> response = await feed.ReadNextAsync();
foreach ( Object item in response)
{
Console.WriteLine($"Found item:\t{item}");
}
}