Indexar e consultar vetores no Azure Cosmos DB for NoSQL no Python
Antes de usar a indexação e a busca em vetores, primeiro você deve habilitar o recurso. Este artigo aborda as seguintes etapas:
- Como habilitar o recurso Busca em Vetores no Azure Cosmos DB for NoSQL
- Configurando o contêiner do Azure Cosmos DB para busca em vetores
- Criação de política de incorporação de vetores
- Adicionando índices vetoriais à política de indexação de contêiner
- Criando um contêiner com índices vetoriais e política de incorporação de vetores
- Executando uma busca em vetores nos dados armazenados
Esse guia percorre o processo de criação de dados vetoriais, indexação dos dados e consulta dos dados em um contêiner.
Pré-requisitos
- Uma conta do Azure Cosmos DB for NoSQL.
- Se não tiver uma assinatura do Azure, Experimente o Azure Cosmos DB for NoSQL gratuitamente.
- Se tiver uma assinatura existente do Azure, crie uma conta nova do Azure Cosmos DB for NoSQL.
- Versão mais recente do SDK do Python do Azure Cosmos DB.
habilitar o recurso
A busca em vetores para o Azure Cosmos DB for NoSQL requer habilitar o recurso concluindo as seguintes etapas:
- Navegue até a página de recursos do Azure Cosmos DB for NoSQL.
- Selecione o painel "Recursos" no item de menu "Configurações".
- Selecione "Busca em vetores no Azure Cosmos DB for NoSQL".
- Leia a descrição do recurso para confirmar que deseja se inscrever na versão prévia.
- Selecione "Habilitar" para ativar a busca em vetores no Azure Cosmos DB for NoSQL.
Dica
Como alternativa, use a CLI do Azure para atualizar os recursos da sua conta para dar suporte à busca em vetores NoSQL.
az cosmosdb update \
--resource-group <resource-group-name> \
--name <account-name> \
--capabilities EnableNoSQLVectorSearch
Observação
A solicitação de inscrição será aprovada automaticamente, porém pode levar 15 minutos para entrar em vigor.
Compreendendo as etapas envolvidas na busca em vetores
As etapas a seguir pressupõem que você saiba como configurar uma conta NoSQL do Cosmos DB e criar um banco de dados. Atualmente, o recurso de busca em vetores não é compatível com os contêineres existentes, portanto, é necessário criar um novo contêiner e especificar a política de incorporação de vetores no nível do contêiner e a política de indexação de vetores no momento da criação do contêiner.
Vejamos um exemplo de criação de um banco de dados para uma livraria baseada na Internet e você armazena Título, Autor, ISBN e Descrição para cada livro. Também definiremos duas propriedades para conter inserções de vetor. A primeira é a propriedade “contentVector”, que contém embeddings de texto gerados a partir do conteúdo de texto do livro (por exemplo, concatenando as propriedades “title” “author” “isbn” e “description” antes de criar o embedding). O segundo é o “coverImageVector”, que é gerado a partir de imagens da capa do livro.
- Crie e armazene incorporações de vetores para os campos nos quais deseja realizar a busca em vetores.
- Especifique os caminhos de incorporação de vetores na política de incorporação de vetores.
- Inclua quaisquer índices vetoriais desejados na política de indexação do contêiner.
Nas seções subsequentes deste artigo, consideraremos 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 de vetores para seu contêiner.
Em seguida, você precisa definir uma política de vetor de contêiner. Essa política fornece informações que são usadas para informar ao mecanismo de consulta do Azure Cosmos DB como lidar com propriedades vetoriais nas funções do sistema VectorDistance. Isso também informa a política de indexação de vetores sobre as informações necessárias, caso você opte por especificar uma. As seguintes informações estão incluídas na política de vetores contidos:
- “caminho”: o caminho da propriedade que contém vetores
- “datatype”: O tipo dos elementos do vetor (padrão Float32)
- “dimensões”: O comprimento de cada vetor no caminho (padrão 1536)
- “distanceFunction”: A métrica usada para calcular distância/semelhança (cosseno padrão)
Para nosso exemplo com detalhes do livro, a política vetorial pode ser semelhante ao 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
Uma vez decididos os caminhos de incorporação do vetor, os índices vetoriais precisam ser adicionados à política de indexação. Para este exemplo, a política de indexação seria semelhante a esta:
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 a inserção. Não adicionar o caminho do vetor a "excludedPaths" resultará em maior cobrança de RU e latência para inserções de vetores.
Importante
Atualmente, a busca em vetores no Azure Cosmos DB for NoSQL só tem suporte em novos contêineres. Você precisa definir a política de vetor de contêiner e qualquer política de indexação de vetor durante o momento da criação do contêiner, pois ela não pode ser modificada posteriormente.
Criar contêiner com a política de vetor
Atualmente, o recurso de busca em vetores do Azure Cosmos DB for NoSQL só tem suporte em novos contêineres; portanto, você precisa aplicar a política de vetor durante a 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 similaridade vetorial
Depois de criar um contêiner com a política vetorial desejada e inserir dados vetoriais no contêiner, você poderá realizar uma busca em vetores usando a função do sistema Distância vetorial em uma consulta. Suponha que você queira pesquisar livros sobre receitas de comida olhando a descrição. Primeiro você precisa obter os embeddings para o texto da sua consulta. Nesse caso, você pode querer gerar embeddings para o texto da consulta – “receita de comida”. Depois de incorporar a sua consulta de pesquisa, você pode usá-la na função VectorDistance na consulta de busca em vetores e obter todos os itens 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])
Essa consulta recupera os títulos dos livros junto com as pontuações de similaridade em relação à sua consulta. Aqui está um exemplo no 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))