Armazenamento vectorial integrado no Azure DocumentDB

Podes usar índices DiskANN em níveis M30 e superiores. Para criar o índice DiskANN, defina o "kind" parâmetro para "vector-diskann" de acordo com este modelo.

{ 
    "createIndexes": "<collection_name>",
    "indexes": [
        {
            "name": "<index_name>",
            "key": {
                "<path_to_property>": "cosmosSearch"
            },
            "cosmosSearchOptions": { 
                "kind": "vector-diskann", 
                "dimensions": <integer_value>,
                "similarity": <string_value>,
                "maxDegree" : <integer_value>, 
                "lBuild" : <integer_value>, 
            } 
        } 
    ] 
}

Executar uma pesquisa vetorial com o DiskANN

Para executar uma pesquisa vetorial, use o estágio de agregação $search no pipeline e consulte o operador cosmosSearch. O DiskANN permite pesquisas de alto desempenho em conjuntos de dados massivos com filtragem opcional , como filtros geoespaciais ou baseados em texto.

{
  "$search": {
    "cosmosSearch": {
      "path": "<path_to_property>",
      "query": "<query_vector>",  
      "k": <num_results_to_return>,  
      "filter": {"$and": [
        { "<attribute_1>": { "$eq": <value> } },
        {"<location_attribute>": {"$geoWithin": {"$centerSphere":[[<longitude_integer_value>, <latitude_integer_value>], <radius>]}}}
      ]}
    }
  }
},

Exemplo de uso de um índice DiskANN com filtragem

Adicionar vetores ao seu banco de dados

Para usar a pesquisa vetorial com filtros geoespaciais, adicione documentos que incluam incorporações vetoriais e coordenadas de localização. Você pode criar as incorporações usando seu próprio modelo, incorporações do Azure OpenAI ou uma API como o Hugging Face no Azure.

from pymongo import MongoClient

client = MongoClient("<your_connection_string>")
db = client["test"]
collection = db["testCollection"]

documents = [
    {"name": "Eugenia Lopez", "bio": "CEO of AdventureWorks", "is_open": 1, "location": [-118.9865, 34.0145], "contentVector": [0.52, 0.20, 0.23]},
    {"name": "Cameron Baker", "bio": "CFO of AdventureWorks", "is_open": 1, "location": [-0.1278, 51.5074], "contentVector": [0.55, 0.89, 0.44]},
    {"name": "Jessie Irwin", "bio": "Director of Our Planet initiative", "is_open": 0, "location": [-118.9865, 33.9855], "contentVector": [0.13, 0.92, 0.85]},
    {"name": "Rory Nguyen", "bio": "President of Our Planet initiative", "is_open": 1, "location": [-119.0000, 33.9855], "contentVector": [0.91, 0.76, 0.83]}
]

collection.insert_many(documents)

Criar um índice vetorial DiskANN

O exemplo a seguir demonstra como configurar um índice vetorial DiskANN com recursos de filtragem. Este exemplo inclui criar o índice vetorial para pesquisa por similaridade, adicionar documentos com propriedades vetoriais e geoespaciais, e indexar campos para mais filtragem.

db.command({
    "createIndexes": "testCollection",
    "indexes": [
        {
            "name": "DiskANNVectorIndex",
            "key": {
                "contentVector": "cosmosSearch"
            },
            "cosmosSearchOptions": {
                "kind": "vector-diskann",
                "dimensions": 3,
                "similarity": "COS",
                "maxDegree": 32,
                "lBuild": 64
            }
        },
        { 
            "name": "is_open",
            "key": { 
                "is_open": 1 
            }      
        },
        {
            "name": "locationIndex",
            "key": {
                "location": 1
            }
        }
    ]
})

Este comando cria um índice vetorial DiskANN no contentVector campo em exampleCollection, permitindo pesquisas de similaridade. Acrescenta ainda:

• Um índice no is_open campo, para que possas filtrar os resultados com base em se as empresas estão abertas.
• Um índice geoespacial no location campo para filtrar por proximidade geográfica.

Realizar uma pesquisa vetorial

Para encontrar documentos com vetores semelhantes dentro de um raio geográfico específico, especifique a queryVector pesquisa de semelhança e inclua um filtro geoespacial.

query_vector = [0.52, 0.28, 0.12]
pipeline = [
    {
        "$search": {
            "cosmosSearch": {
                "path": "contentVector",
                "vector": query_vector,
                "k": 5,
                "filter": {
                    "$and": [
                        {"is_open": {"$eq": 1}},
                        {"location": {"$geoWithin": {"$centerSphere": [[-119.7192861804, 34.4102485028], 100 / 3963.2]}}}
                    ]
                }
            }
        }
    }
]

results = list(collection.aggregate(pipeline))
for result in results:
    print(result)

Neste exemplo, a pesquisa de semelhança de vetores retorna os k principais vetores mais próximos com base na métrica de semelhança especificada COS , enquanto filtra os resultados para incluir apenas empresas abertas em um raio de 100 milhas.

[
  {
    similarityScore: 0.9745354109084544,
    document: {
      _id: ObjectId("645acb54413be5502badff94"),
      name: 'Eugenia Lopez',
      bio: 'CEO of AdventureWorks',
      is_open: 1,
      location: [-118.9865, 34.0145],
      contentVector: [0.52, 0.20, 0.23]
    }
  },
  {
    similarityScore: 0.9006955671333992,
    document: {
      _id: ObjectId("645acb54413be5502badff97"),
      name: 'Rory Nguyen',
      bio: 'President of Our Planet initiative',
      is_open: 1,
      location: [-119.7302, 34.4005],
      contentVector: [0.91, 0.76, 0.83]
    }
  }
]

Este resultado apresenta os documentos mais semelhantes a queryVector, limitados a um raio de 100 milhas e a empresas em atividade. Cada resultado inclui a pontuação de similaridade e os metadados, demonstrando como o DiskANN no Azure DocumentDB suporta consultas vetoriais e geoespaciais combinadas para experiências de pesquisa enriquecidas e sensíveis à localização.

Você pode criar índices HNSW em camadas de cluster M30 e superiores. Para criar o índice vetorial Hierárquico Navegável de Pequenos Mundos (HNSW), precisa de configurar o parâmetro "kind" para "vector-hnsw", seguindo este modelo.

{ 
    "createIndexes": "<collection_name>",
    "indexes": [
        {
            "name": "<index_name>",
            "key": {
                "<path_to_property>": "cosmosSearch"
            },
            "cosmosSearchOptions": { 
                "kind": "vector-hnsw", 
                "m": <integer_value>, 
                "efConstruction": <integer_value>, 
                "similarity": "<string_value>", 
                "dimensions": <integer_value> 
            } 
        } 
    ] 
}

Realizar uma pesquisa vetorial com HNSW

Para executar uma pesquisa vetorial, use o estágio de $search do pipeline de agregação e o operador cosmosSearch.

{
    "$search": {
        "cosmosSearch": {
            "vector": <query_vector>,
            "path": "<path_to_property>",
            "k": <num_results_to_return>,
            "efSearch": <integer_value>
        },
    }
}

Exemplo usando um índice HNSW

Os exemplos a seguir mostram como indexar vetores, adicionar documentos com propriedades vetoriais, executar uma pesquisa vetorial e recuperar a configuração de índice.

use test;

db.createCollection("exampleCollection");

db.runCommand({ 
    "createIndexes": "exampleCollection",
    "indexes": [
        {
            "name": "VectorSearchIndex",
            "key": {
                "contentVector": "cosmosSearch"
            },
            "cosmosSearchOptions": { 
                "kind": "vector-hnsw", 
                "m": 16, 
                "efConstruction": 64, 
                "similarity": "COS", 
                "dimensions": 3
            } 
        } 
    ] 
});

Este comando cria um índice HNSW em relação à contentVector propriedade nos documentos armazenados na coleção especificada, exampleCollection. A cosmosSearchOptions propriedade especifica os parâmetros para o índice vetorial HNSW. Se o documento tiver o vetor armazenado em uma propriedade aninhada, você poderá definir essa propriedade usando um caminho de notação de ponto. Por exemplo, você pode usar text.contentVector if contentVector é uma subpropriedade de text.

Adicionar vetores ao seu banco de dados

Para adicionar vetores à coleção do seu banco de dados, primeiro você precisa criar as incorporações usando seu próprio modelo, incorporações do Azure OpenAI ou uma API como o Hugging Face no Azure. Neste exemplo, você adiciona novos documentos através de embeddings de amostra:

db.exampleCollection.insertMany([
  {name: "Eugenia Lopez", bio: "Eugenia is the CEO of AdvenureWorks.", contentVector: [0.51, 0.12, 0.23]},
  {name: "Cameron Baker", bio: "Cameron Baker CFO of AdvenureWorks.", contentVector: [0.55, 0.89, 0.44]},
  {name: "Jessie Irwin", bio: "Jessie Irwin is the former CEO of AdventureWorks and now the director of the Our Planet initiative.", contentVector: [0.13, 0.92, 0.85]},
  {name: "Rory Nguyen", bio: "Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.", contentVector: [0.91, 0.76, 0.83]},
]);

Realizar uma pesquisa vetorial

Continuando com o último exemplo, crie outro vetor, queryVector. A pesquisa vetorial mede a distância entre queryVector e os vetores no caminho contentVector dos seus documentos. Você pode definir o número de resultados que a pesquisa retorna definindo o parâmetro k, que é definido como 2 aqui. Você também pode definir efSearch, que é um inteiro que controla o tamanho da lista de vetores candidatos. Um valor mais alto pode melhorar a precisão, mas a pesquisa é mais lenta como resultado. Este parâmetro é opcional, com um valor padrão de 40.

const queryVector = [0.52, 0.28, 0.12];
db.exampleCollection.aggregate([
  {
    "$search": {
        "cosmosSearch": {
            "vector": queryVector,
            "path": "contentVector",
            "k": 2,
            "efSearch": 40
        },
    }
  }
}
]);

Neste exemplo, realizas uma pesquisa vetorial usando queryVector como entrada através do shell Mongo. O resultado da pesquisa é uma lista de dois itens que são mais semelhantes ao vetor de consulta, classificados por suas pontuações de semelhança.

[
  {
    similarityScore: 0.9465376,
    document: {
      _id: ObjectId("645acb54413be5502badff94"),
      name: 'Eugenia Lopez',
      bio: 'Eugenia is the CEO of AdvenureWorks.',
      vectorContent: [ 0.51, 0.12, 0.23 ]
    }
  },
  {
    similarityScore: 0.9006955,
    document: {
      _id: ObjectId("645acb54413be5502badff97"),
      name: 'Rory Nguyen',
      bio: 'Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.',
      vectorContent: [ 0.91, 0.76, 0.83 ]
    }
  }
]

Para criar um índice vetorial usando o algoritmo FIV, use o seguinte createIndexes modelo e defina o "kind" parâmetro como "vector-ivf":

{
  "createIndexes": "<collection_name>",
  "indexes": [
    {
      "name": "<index_name>",
      "key": {
        "<path_to_property>": "cosmosSearch"
      },
      "cosmosSearchOptions": {
        "kind": "vector-ivf",
        "numLists": <integer_value>,
        "similarity": "<string_value>",
        "dimensions": <integer_value>
      }
    }
  ]
}

Realizar uma pesquisa vetorial com IVF

Para executar uma pesquisa vetorial, use o estágio de pipeline de agregação $search em uma consulta do MongoDB. Para usar o cosmosSearch índice, use o novo cosmosSearch operador.

{
  {
  "$search": {
    "cosmosSearch": {
        "vector": <query_vector>,
        "path": "<path_to_property>",
        "k": <num_results_to_return>,
      },
      "returnStoredSource": True }},
  {
    "$project": { "<custom_name_for_similarity_score>": {
           "$meta": "searchScore" },
            "document" : "$$ROOT"
        }
  }
}

Para recuperar a pontuação de semelhança (searchScore) juntamente com os documentos encontrados pela pesquisa vetorial, use o $project operador para incluí-la searchScore e renomeá-la como <custom_name_for_similarity_score> nos resultados. Em seguida, o documento também é projetado como objeto aninhado. A pontuação de similaridade é calculada usando a métrica definida no índice vetorial.

Exemplo usando um índice de FIV

A indexação de arquivo invertido (FIV) é um método que organiza vetores em clusters. Durante uma pesquisa vetorial, o vetor de consulta é primeiro comparado com os centros desses clusters. A pesquisa é então conduzida dentro do cluster cujo centro está mais próximo do vetor de consulta.

O numLists parâmetro determina o número de clusters a serem criados. Um único cluster implica que a pesquisa é realizada contra todos os vetores da base de dados; sendo semelhante a uma pesquisa por força bruta ou kNN. Essa configuração fornece a maior precisão, mas também a maior latência.

Aumentar o numLists valor resulta em mais clusters, cada um contendo menos vetores. Por exemplo, se numLists=2, cada cluster contém mais vetores do que se numLists=3, e assim por diante. Menos vetores por cluster aceleram a pesquisa (menor latência, mais consultas por segundo). No entanto, isto aumenta a probabilidade de falhar na identificação do vetor mais semelhante na sua base de dados em comparação com o vetor de consulta. Este problema deve-se à natureza imperfeita do agrupamento, onde a pesquisa pode focar-se num cluster enquanto o vetor "mais próximo" reside num cluster diferente.

O nProbes parâmetro controla o número de clusters a pesquisar. Por defeito, o valor é 1, o que significa que pesquisa apenas o cluster com o centro mais próximo do vetor de consulta. Aumentar esse valor permite que a pesquisa cubra mais clusters, melhorando a precisão, mas também aumentando a latência (diminuindo assim as consultas por segundo) à medida que mais clusters e vetores estão sendo pesquisados.

Os exemplos a seguir mostram como indexar vetores, adicionar documentos com propriedades vetoriais, executar uma pesquisa vetorial e recuperar a configuração de índice.

Criar um índice de vetores

use test;

db.createCollection("exampleCollection");

db.runCommand({
  createIndexes: 'exampleCollection',
  indexes: [
    {
      name: 'vectorSearchIndex',
      key: {
        "vectorContent": "cosmosSearch"
      },
      cosmosSearchOptions: {
        kind: 'vector-ivf',
        numLists: 3,
        similarity: 'COS',
        dimensions: 3
      }
    }
  ]
});

Este comando cria um vector-ivf índice em relação à vectorContent propriedade nos documentos armazenados na coleção especificada, exampleCollection. A cosmosSearchOptions propriedade especifica os parâmetros para o índice vetorial FIV. Se o documento tiver o vetor armazenado em uma propriedade aninhada, você poderá definir essa propriedade usando um caminho de notação de ponto. Por exemplo, você pode usar text.vectorContent if vectorContent é uma subpropriedade de text.

Adicionar vetores ao seu banco de dados

Para adicionar vetores à coleção do seu banco de dados, primeiro você precisa criar as incorporações usando seu próprio modelo, incorporações do Azure OpenAI ou uma API como o Hugging Face no Azure. Neste exemplo, você adiciona novos documentos através de embeddings de amostra:

db.exampleCollection.insertMany([
  {name: "Eugenia Lopez", bio: "Eugenia is the CEO of AdvenureWorks.", vectorContent: [0.51, 0.12, 0.23]},
  {name: "Cameron Baker", bio: "Cameron Baker CFO of AdvenureWorks.", vectorContent: [0.55, 0.89, 0.44]},
  {name: "Jessie Irwin", bio: "Jessie Irwin is the former CEO of AdventureWorks and now the director of the Our Planet initiative.", vectorContent: [0.13, 0.92, 0.85]},
  {name: "Rory Nguyen", bio: "Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.", vectorContent: [0.91, 0.76, 0.83]},
]);

Realizar uma pesquisa vetorial

Para executar uma pesquisa vetorial, use o estágio de pipeline de agregação $search em uma consulta do MongoDB. Para usar o cosmosSearch índice, use o novo cosmosSearch operador.

{
  {
  "$search": {
    "cosmosSearch": {
        "vector": <vector_to_search>,
        "path": "<path_to_property>",
        "k": <num_results_to_return>,
      },
      "returnStoredSource": True }},
  {
    "$project": { "<custom_name_for_similarity_score>": {
           "$meta": "searchScore" },
            "document" : "$$ROOT"
        }
  }
}

Para recuperar a pontuação de semelhança (searchScore) juntamente com os documentos encontrados pela pesquisa vetorial, use o $project operador para incluí-la searchScore e renomeá-la como <custom_name_for_similarity_score> nos resultados. Em seguida, o documento também é projetado como objeto aninhado. A pontuação de similaridade é calculada usando a métrica definida no índice vetorial.

Vetores de consulta e distâncias vetoriais (pontuações de similaridade) usando $search

Continuando com o último exemplo, crie outro vetor, queryVector. A pesquisa vetorial mede a distância entre queryVector e os vetores no caminho vectorContent dos seus documentos. Você pode definir o número de resultados que a pesquisa retorna definindo o parâmetro k, que é definido como 2 aqui. Você também pode definir nProbes, que é um número inteiro que controla o número de clusters próximos que são inspecionados em cada pesquisa. Um valor mais alto pode melhorar a precisão, mas a pesquisa é mais lenta como resultado. Este parâmetro é opcional com um valor padrão 1 e não pode ser maior do que o numLists valor especificado no índice vetorial.

const queryVector = [0.52, 0.28, 0.12];
db.exampleCollection.aggregate([
  {
    $search: {
      "cosmosSearch": {
        "vector": queryVector,
        "path": "vectorContent",
        "k": 2
      },
    "returnStoredSource": true }},
  {
    "$project": { "similarityScore": {
           "$meta": "searchScore" },
            "document" : "$$ROOT"
        }
  }
]);

Neste exemplo, realizas uma pesquisa vetorial usando queryVector como entrada através do shell Mongo. O resultado da pesquisa é uma lista de dois itens que são mais semelhantes ao vetor de consulta, classificados por suas pontuações de semelhança.

[
  {
    similarityScore: 0.9465376,
    document: {
      _id: ObjectId("645acb54413be5502badff94"),
      name: 'Eugenia Lopez',
      bio: 'Eugenia is the CEO of AdvenureWorks.',
      vectorContent: [ 0.51, 0.12, 0.23 ]
    }
  },
  {
    similarityScore: 0.9006955,
    document: {
      _id: ObjectId("645acb54413be5502badff97"),
      name: 'Rory Nguyen',
      bio: 'Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.',
      vectorContent: [ 0.91, 0.76, 0.83 ]
    }
  }
]