Vetores de índice e consulta no Azure Cosmos DB para NoSQL em Python
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 SDK Python do Azure Cosmos DB.
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
As etapas a seguir pressupõem que você saiba como configurar uma conta NoSQL do Cosmos DB e criar um banco de dados. O recurso de pesquisa vetorial não é suportado atualmente nos contêineres existentes, portanto, você precisa criar um novo contêiner e especificar a política de incorporação vetorial no nível do contêiner e a política de indexação de vetores no momento da criação do contêiner.
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 definiremos 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. Isso 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:
vector_embedding_policy = {
"vectorEmbeddings": [
{
"path": "/coverImageVector",
"dataType": "float32",
"distanceFunction": "dotproduct",
"dimensions": 8
},
{
"path": "/contentVector",
"dataType": "float32",
"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. Neste exemplo, a política de indexação teria a seguinte aparência:
indexing_policy = {
"includedPaths": [
{
"path": "/*"
}
],
"excludedPaths": [
{
"path": "/\"_etag\"/?",
"path": "/coverImageVector/*",
"path": "/contentVector/*"
}
],
"vectorIndexes": [
{"path": "/coverImageVector",
"type": "quantizedFlat"
},
{"path": "/contentVector",
"type": "quantizedFlat"
}
]
}
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.
Importante
Atualmente, a pesquisa vetorial no Azure Cosmos DB para NoSQL é suportada apenas em novos contêineres. Você precisa definir a política de vetor de contêiner e qualquer política de indexação de vetores durante o tempo de criação do contêiner, pois ela não pode ser modificada posteriormente.
Criar contêiner com política de vetor
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.
try:
container = db.create_container_if_not_exists(
id=CONTAINER_NAME,
partition_key=PartitionKey(path='/id'),
indexing_policy=indexing_policy,
vector_embedding_policy=vector_embedding_policy)
print('Container with id \'{0}\' created'.format(id))
except exceptions.CosmosHttpResponseError:
raise
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 em Python:
query_embedding = [1,2,3,4,5,6,7,8,9,10]
# Query for items
for item in container.query_items(
query='SELECT c.title, VectorDistance(c.contentVector,@embedding) AS SimilarityScore FROM c ORDER BY VectorDistance(c.contentVector,@embedding)',
parameters=[
{"name": "@embedding", "value": query_embedding}
],
enable_cross_partition_query=True):
print(json.dumps(item, indent=True))