Archivio vettoriale in Azure Cosmos DB per MongoDB vCore

Articolo
12/03/2024
Si applica a:

✅ MongoDB vCore

Usare il database vettoriale integrato in Azure Cosmos DB per MongoDB (vCore) per connettere facilmente le applicazioni basate su intelligenza artificiale ai dati archiviati in Azure Cosmos DB. Questa integrazione può includere applicazioni create usando gli incorporamenti OpenAI di Azure. Il database vettoriale integrato in modo nativo consente di archiviare, indicizzare ed eseguire query su dati vettoriali altamente dimensionali archiviati direttamente in Azure Cosmos DB per MongoDB (vCore), insieme ai dati originali da cui vengono creati i dati vettoriali. Elimina la necessità di trasferire i dati in archivi vettoriali alternativi e comporta costi aggiuntivi.

Che cos'è un archivio di vettori?

Un archivio vettoriale o un database vettoriale è un database progettato per archiviare e gestire incorporamenti vettoriali, che sono rappresentazioni matematiche dei dati in uno spazio ad alta dimensionalità. In questo spazio, ogni dimensione corrisponde a una caratteristica dei dati e decine di migliaia di dimensioni possono essere usate per rappresentare dati sofisticati. La posizione di un vettore in questo spazio rappresenta le sue caratteristiche. Parole, frasi o interi documenti, immagini, audio e altri tipi di dati possono essere vettorizzati.

Come funziona un archivio vettoriale?

In un archivio vettoriale, gli algoritmi di ricerca vettoriale vengono usati per indicizzare ed eseguire query sugli incorporamenti. Alcuni algoritmi di ricerca vettoriale noti includono Hierarchical Navigable Small World (HNSW), Inverted File (IVF), DiskANN e così via. La ricerca vettoriale è un metodo che consente di trovare elementi simili in base alle caratteristiche dei dati anziché in base alle corrispondenze esatte in un campo di proprietà. Questa tecnica è utile nelle applicazioni come la ricerca di testi simili o di immagini correlate, la creazione di elementi consigliati o anche il rilevamento di anomalie. Viene usato per eseguire query sui vettori di incorporamento (elenchi dei numeri) dei dati, creati usando un modello di Machine Learning usando un'API di incorporamento. Esempi di API di incorporamento sono gli incorporamenti OpenAI di Azure o Hugging Face in Azure. La ricerca vettoriale misura quindi la distanza tra i vettori di dati e i vettori di query. I vettori di dati più vicini al vettore di query sono quelli che risultano più simili dal punto di vista semantico.

Nel database vettoriale integrato in Azure Cosmos DB per MongoDB (vCore), gli incorporamenti possono essere archiviati, indicizzati ed sottoposti a query insieme ai dati originali. Questo approccio elimina il costo aggiuntivo della replica dei dati in un database vettoriale puro separato. Inoltre, questa architettura mantiene insieme gli incorporamenti vettoriali e i dati originali, che facilitano meglio le operazioni di dati multi modale e consentono una maggiore coerenza, scalabilità e prestazioni dei dati.

Eseguire una ricerca di somiglianza vettoriale

Azure Cosmos DB per MongoDB (vCore) offre potenti funzionalità di ricerca vettoriale, consentendo di eseguire ricerche di somiglianza ad alta velocità in set di dati complessi. Per eseguire la ricerca vettoriale in Azure Cosmos DB per MongoDB, è prima necessario creare un indice vettoriale. Cosmos DB supporta attualmente tre tipi di indici vettoriali:

DiskANN (scelta consigliata): ideale per set di dati su larga scala, sfruttando le unità SSD per un utilizzo efficiente della memoria mantenendo al tempo stesso un richiamo elevato nelle ricerche ann (near-neighbor) approssimative.
HNSW: adatto per set di dati di dimensioni moderate che richiedono un richiamo elevato, con una struttura basata su grafo che bilancia l'accuratezza e l'efficienza delle risorse.
IVF: usa il clustering per ottimizzare la velocità di ricerca in set di dati estesi, concentrandosi sulle ricerche all'interno dei cluster di destinazione per accelerare le prestazioni.

Gli indici DiskANN sono disponibili nei livelli M40 e versioni successive. Per creare l'indice DiskANN, impostare il "kind" parametro "vector-diskann" su come segue il modello seguente:

{ 
    "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>, 
            } 
        } 
    ] 
}

Campo	Tipo	Descrizione
`index_name`	stringa	Nome univoco dell'indice.
`path_to_property`	string	Percorso della proprietà che contiene il vettore. Questo percorso può essere una proprietà di primo livello o un percorso di notazione con punto per la proprietà. I vettori devono essere un `number[]` oggetto da indicizzare e usare nei risultati della ricerca vettoriale. L'utilizzo di tipi diversi, ad esempio `double[]`, impedisce l'indicizzazione del documento. I documenti non indicizzati non verranno restituiti nei risultati di una ricerca vettoriale.
`kind`	string	Tipo di indice vettoriale da creare. Le opzioni sono `vector-ivf`, `vector-hnsw` e `vector-diskann`.
`dimensions`	integer	Numero di dimensioni per la somiglianza di vettore. DiskANN supporta fino a 2000 dimensioni, con il supporto futuro previsto per 40.000+.
`similarity`	string	Metrica di somiglianza da usare con l'indice. Le opzioni possibili sono `COS` (distanza coseno), `L2` (distanza euclidea) e `IP` (prodotto interno).
`maxDegree`	integer	Numero massimo di archi per nodo nel grafico. Questo parametro varia da 20 a 2048 (il valore predefinito è 32). Maggiore `maxDegree` è adatto per i set di dati con requisiti di accuratezza elevata e/o dimensionalità elevata.
`lBuild`	integer	Imposta il numero di vicini candidati valutati durante la costruzione dell'indice DiskANN. Questo parametro, compreso tra 10 e 500 (il valore predefinito è 50), bilancia l'accuratezza e l'overhead di calcolo: i valori più elevati migliorano la qualità e l'accuratezza dell'indice, ma aumentano il tempo di compilazione

Eseguire una ricerca vettoriale con DiskANN

Per eseguire una ricerca vettoriale, usare la fase della $search pipeline di aggregazione ed eseguire query con l'operatore cosmosSearch . DiskANN consente ricerche ad alte prestazioni in set di dati di grandi dimensioni con filtri facoltativi , ad esempio filtri geospaziali o basati su testo.

{
  "$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>]}}}
      ]}
    }
  }
},

Campo	Tipo	Descrizione
`lSearch`	integer	Specifica le dimensioni dell'elenco dei candidati dinamici per la ricerca. Il valore predefinito è `40`, con un intervallo configurabile compreso tra `10` e `1000`. L'aumento del valore migliora il richiamo, ma può ridurre la velocità di ricerca.
`k`	integer	Definisce il numero di risultati della ricerca da restituire. Il `k` valore deve essere minore o uguale a `lSearch`.

Abilitazione di DiskANN in un nuovo cluster

Per abilitare l'indice vettoriale DiskANN in un cluster Azure Cosmos DB per MongoDB (vCore), seguire questa procedura per eseguire una registrazione a livello di cluster tramite l'interfaccia della riga di comando di Azure:

Accedere all'interfaccia della riga di comando di Azure

az login

Recuperare le impostazioni correnti per i flag di funzionalità nel cluster. In questo modo si garantisce di mantenere tutti i flag esistenti durante l'aggiunta della nuova funzionalità.

az resource show --ids "/subscriptions/<sub id>/resourceGroups/<resource group name>/providers/Microsoft.DocumentDB/mongoClusters/<resource name of your Cosmos DB for MongoDB cluster>" --api-version <cluster's api version>

Aggiungere il DiskANNIndex flag all'elenco delle funzionalità di anteprima senza rimuovere quelle esistenti.

az resource patch --ids "/subscriptions/<sub id>/resourceGroups/<resource group name>/providers/Microsoft.DocumentDB/mongoClusters/<resource name of your Cosmos DB for MongoDB cluster>" --api-version <cluster's api version> --properties "{\"previewFeatures\": [\"GeoReplicas\", \"DiskANNIndex\"]}"

Esempio di utilizzo di un indice DiskANN con filtro

Aggiungere vettori al database

Per usare la ricerca vettoriale con filtri geospaziali, aggiungere documenti che includono incorporamenti di vettori e coordinate di posizione. È possibile creare gli incorporamenti usando un modello personalizzato, incorporamenti di Azure OpenAI o un'altra API , ad esempio Hugging Face in 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)

Creare un indice vettoriale DiskANN

Nell'esempio seguente viene illustrato come configurare un indice vettoriale DiskANN con funzionalità di filtro. Ciò include la creazione dell'indice vettoriale per la ricerca di somiglianza, l'aggiunta di documenti con proprietà vettoriali e geospaziali e l'indicizzazione dei campi per un filtro aggiuntivo.

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
            }
        }
    ]
})

Questo comando crea un indice vettoriale DiskANN nel contentVector campo in exampleCollection, abilitando le ricerche di somiglianza. Aggiunge anche:

Un indice nel is_open campo, che consente di filtrare i risultati in base al fatto che le aziende siano aperte.
Indice geospaziale nel location campo da filtrare in base alla prossimità geografica.

Eseguire una ricerca vettoriale

Per trovare documenti con vettori simili all'interno di un raggio geografico specifico, specificare per la queryVector ricerca di somiglianza e includere un filtro geospaziale.

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)

In questo esempio, la ricerca di somiglianza vettoriale restituisce i vettori più k vicini in base alla metrica di somiglianza specificata COS , mentre filtrando i risultati in modo da includere solo le aziende aperte entro un raggio di 100 miglia.

[
  {
    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]
    }
  }
]

Questo risultato mostra i documenti più simili a queryVector, vincolati a un raggio di 100 miglia e aziende aperte. Ogni risultato include il punteggio di somiglianza e i metadati, dimostrando in che modo DiskANN in Cosmos DB per MongoDB supporta query di ricerca combinate con vettori e geospaziali per esperienze di ricerca arricchite e sensibili alla posizione.

È possibile creare indici HNSW (Gerarchica Navigable Small World) nei livelli del cluster M40 e versioni successive. Per creare l'indice HNSW, è necessario creare un indice vettoriale con il parametro "kind" impostato su "vector-hnsw" seguendo il modello seguente:

{ 
    "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> 
            } 
        } 
    ] 
}

Campo	Tipo	Descrizione
`m`	integer	Il numero massimo di connessioni per livello (`16` per impostazione predefinita, il valore minimo è `2`, il valore massimo è `100`). Un valore m più alto è adatto per i set di dati con elevata dimensionalità e/o requisiti di elevata precisione.
`efConstruction`	integer	La dimensione dell'elenco di candidati dinamici per la costruzione del grafo (`64` per impostazione predefinita, il valore minimo è `4`, il valore massimo è `1000`). Un valore `efConstruction` più alto comporterà una migliore qualità e una maggiore accuratezza dell'indice, ma aumenterà anche il tempo necessario per compilare l'indice. `efConstruction` deve essere almeno `2 * m`

Eseguire una ricerca vettoriale con HNSW

Per eseguire una ricerca vettoriale, utilizzare la $searchfase della pipeline di aggregazione per organizzare la query con l'operatore cosmosSearch.

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

Campo	Tipo	Descrizione
`efSearch`	integer	Dimensioni dell'elenco dei candidati dinamici per la ricerca (`40` per impostazione predefinita). Un valore più alto fornisce un richiamo migliore a scapito della velocità.

Nota

La creazione di un indice HSNW con set di dati di grandi dimensioni può comportare l'esaurimento della memoria della risorsa vCore di Azure Cosmos DB for MongoDB oppure limitare le prestazioni di altre operazioni in esecuzione nel database. Se si verificano problemi di questo tipo, questi possono essere mitigati ridimensionando la risorsa a un livello cluster superiore o creando un nuovo indice vettoriale DiskANN.

Esempio di utilizzo di un indice HNSW

Gli esempi seguenti illustrano come indicizzare i vettori, aggiungere documenti con proprietà vettoriali, eseguire una ricerca vettoriale e recuperare la configurazione dell'indice.

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
            } 
        } 
    ] 
});

Questo comando crea un indice HNSW rispetto alla proprietà contentVector nei documenti archiviati nell'insieme specificato, come exampleCollection. La proprietà cosmosSearchOptions specifica i parametri per l'indice vettoriale HNSW. Se il documento contiene il vettore archiviato in una proprietà annidata, è possibile configurare questa proprietà usando un percorso di notazione con punto. Ad esempio, è possibile usare text.contentVector se contentVector è una sottoproprietà di text.

Aggiungere vettori al database

Per aggiungere vettori alla raccolta del database, è necessario creare innanzitutto gli incorporamenti usando il modello che si possiede, gli incorporamenti OpenAI di Azure o un'altra API (ad esempio Hugging Face in Azure). Nell'esempio riportato di seguito vengono aggiunti nuovi documenti tramite incorporamenti di esempio:

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]},
]);

Eseguire una ricerca vettoriale

Continuando con l'ultimo esempio, creare un altro vettore: queryVector. La ricerca vettoriale misura la distanza tra queryVector e i vettori nel percorso contentVector dei documenti. È possibile impostare il numero di risultati restituiti dalla ricerca configurando il parametro k, qui impostato su 2. È anche possibile impostare efSearch, ovvero un numero intero che controlla le dimensioni dell'elenco di vettori candidati. Un valore più alto può migliorare l'accuratezza, di conseguenza però la ricerca sarà più lenta. Si tratta di un parametro facoltativo e il valore predefinito è 40.

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

In questo esempio viene eseguita una ricerca vettoriale usando queryVector come input tramite Mongo Shell. Il risultato della ricerca è un elenco di due elementi che sono più simili al vettore di query, ordinati in base al punteggio di somiglianza.

[
  {
    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 ]
    }
  }
]

Per creare un indice vettoriale usando l'algoritmo IVF (Inverted File), usare il modello seguente createIndexes e impostare il "kind" parametro su "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>
      }
    }
  ]
}

Campo	Tipo	Descrizione
`numLists`	integer	Questo numero intero è il numero di cluster utilizzati dall'indice di file invertito (IVF) per raggruppare i dati di vettore. È consigliabile impostare `numLists` su `documentCount/1000` per un massimo di 1 milione di documenti e su `sqrt(documentCount)` per più di 1 milione di documenti. L'uso di un valore `numLists` di `1` è simile all'esecuzione di una ricerca di forza bruta, con prestazioni limitate.

Importante

Impostare correttamente il parametro numLists è importante per ottenere accuratezza e prestazioni ottimali. È consigliabile numLists impostare su documentCount/1000 per un massimo di 1 milione di documenti. Per più di 1 milione di documenti, è consigliabile usare l'indice vettoriale DiskANN per ottenere risultati ottimali.

Man mano che aumenta il numero di elementi nel database, è necessario aumentare le dimensioni di numLists per ottenere prestazioni di latenza ottimali per la ricerca vettoriale.

Se si sta sperimentando un nuovo scenario o si sta creando una demo di piccole dimensioni, è possibile iniziare con numLists impostato su 1 per eseguire una ricerca di forza bruta su tutti i vettori. Questo dovrebbe fornire i risultati più accurati della ricerca vettoriale, tuttavia è necessario tenere presente che la velocità e la latenza di ricerca saranno lente. Dopo la configurazione iniziale, è necessario procedere e ottimizzare il parametro numLists usando le indicazioni illustrate in precedenza.

Eseguire una ricerca vettoriale con IVF

Per eseguire una ricerca vettoriale, usare la fase della pipeline di aggregazione $search in una query MongoDB. Per usare l'indice cosmosSearch, usare il nuovo operatore cosmosSearch.

{
  {
  "$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"
        }
  }
}

Per recuperare il punteggio di somiglianza (searchScore) insieme ai documenti trovati dalla ricerca vettoriale, utilizzare l'operatore $project per includere searchScore e rinominarlo come <custom_name_for_similarity_score> nei risultati. Il documento viene quindi proiettato anche come oggetto annidato. Tenere presente che il punteggio di somiglianza viene calcolato usando la metrica definita nell'indice vettoriale.

Importante

I vettori devono essere un number[] da indicizzare. L'utilizzo di tipi diversi, ad esempio double[], impedisce l'indicizzazione del documento. I documenti non indicizzati non verranno restituiti nei risultati di una ricerca vettoriale.

Esempio di utilizzo di un indice IVF

L'indicizzazione IVF (Inverted File) è un metodo che organizza i vettori in cluster. Durante una ricerca vettoriale, il vettore di query viene prima confrontato con i centri di questi cluster. La ricerca viene quindi eseguita all'interno del cluster il cui centro è più vicino al vettore di query.

Il parametro numListdetermina il numero di cluster da creare. Un singolo cluster implica che la ricerca viene eseguita su tutti i vettori nel database, simile a una ricerca di forza bruta o kNN. Questa impostazione offre l'accuratezza più elevata, ma anche la latenza più elevata.

Aumentando il valore numLists si ottengono più cluster, ognuno contenente un numero inferiore di vettori. Ad esempio, se numLists=2, ogni cluster contiene più vettori di se numLists=3e così via. Un minor numero di vettori per cluster accelera la ricerca (minore latenza, query più elevate al secondo). In questo modo, tuttavia, aumenta la probabilità di mancanza del vettore più simile nel database al vettore di query. Ciò è dovuto alla natura imperfetta del clustering, in cui la ricerca potrebbe concentrarsi su un cluster mentre il vettore "più vicino" effettivo risiede in un cluster differente.

Il parametro nProbes controlla il numero di cluster da cercare. Per impostazione predefinita, è impostato su 1, ovvero cerca solo il cluster con il centro più vicino al vettore di query. L'aumento di questo valore consente alla ricerca di coprire più cluster, migliorando l'accuratezza, ma aumentando anche la latenza (riducendo così le query al secondo) man mano che vengono ricercati più cluster e vettori.

Gli esempi seguenti illustrano come indicizzare i vettori, aggiungere documenti con proprietà vettoriali, eseguire una ricerca vettoriale e recuperare la configurazione dell'indice.

Creare un indice vettoriale

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
      }
    }
  ]
});

Questo comando crea un indice vector-ivf rispetto alla proprietà vectorContent nei documenti archiviati nell'insieme specificato, come exampleCollection. La proprietà cosmosSearchOptions specifica i parametri per l'indice vettoriale IVF. Se il documento contiene il vettore archiviato in una proprietà annidata, è possibile configurare questa proprietà usando un percorso di notazione con punto. Ad esempio, è possibile usare text.vectorContent se vectorContent è una sottoproprietà di text.

Aggiungere vettori al database

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]},
]);

Eseguire una ricerca vettoriale

Per eseguire una ricerca vettoriale, usare la fase della pipeline di aggregazione $search in una query MongoDB. Per usare l'indice cosmosSearch, usare il nuovo operatore cosmosSearch.

{
  {
  "$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"
        }
  }
}

Vettori di query e distanze vettoriali (note anche come punteggi di similarità) che usano la funzione $search"

Continuando con l'ultimo esempio, creare un altro vettore: queryVector. La ricerca vettoriale misura la distanza tra queryVector e i vettori nel percorso vectorContent dei documenti. È possibile impostare il numero di risultati restituiti dalla ricerca configurando il parametro k, qui impostato su 2. È anche possibile impostare nProbes, ovvero un numero intero che controlla il numero di cluster nelle vicinanze che vengono esaminati in ogni ricerca. Un valore più alto può migliorare l'accuratezza, di conseguenza però la ricerca sarà più lenta. Si tratta di un parametro facoltativo con un valore predefinito pari a 1 e non può essere maggiore del valore numLists specificato nell'indice vettoriale.

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"
        }
  }
]);

[
  {
    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 ]
    }
  }
]

Ottenere definizioni di indice vettoriale

Per recuperare la definizione di indice vettoriale dalla raccolta, usare il comando listIndexes:

db.exampleCollection.getIndexes();

In questo esempio, vectorIndex viene restituito con tutti i parametri cosmosSearch usati per creare l'indice:

[
  { v: 2, key: { _id: 1 }, name: '_id_', ns: 'test.exampleCollection' },
  {
    v: 2,
    key: { vectorContent: 'cosmosSearch' },
    name: 'vectorSearchIndex',
    cosmosSearch: {
      kind: <index_type>, // options are `vector-ivf`, `vector-hnsw`, and `vector-diskann`
      numLists: 3,
      similarity: 'COS',
      dimensions: 3
    },
    ns: 'test.exampleCollection'
  }
]

Ricerca vettoriale filtrata (anteprima)

È ora possibile eseguire ricerche vettoriali con qualsiasi filtro di query supportato, ad esempio $lt, $lte, $eq, $neq, $gte, $gt, $in, $nine $regex. Abilitare la funzionalità "ricerca vettoriale filtrata" nella scheda "Funzionalità di anteprima" della sottoscrizione di Azure. Altre informazioni sulle funzionalità di anteprima qui.

In primo luogo, è necessario definire un indice per il filtro oltre a un indice vettoriale. Ad esempio, è possibile definire l'indice del filtro in una proprietà

db.runCommand({ 
     "createIndexes": "<collection_name",
    "indexes": [ {
        "key": { 
            "<property_to_filter>": 1 
               }, 
        "name": "<name_of_filter_index>" 
    }
    ] 
});

Successivamente, è possibile aggiungere il termine "filter" alla ricerca vettoriale, come illustrato di seguito. In questo esempio il filtro cerca i documenti in cui la proprietà "title" non è presente nell'elenco di ["not in this text", "or this text"].


db.exampleCollection.aggregate([
  {
      '$search': {
          "cosmosSearch": {
              "vector": "<query_vector>",
              "path": <path_to_vector>,
              "k": num_results,
              "filter": {<property_to_filter>: {"$nin": ["not in this text", "or this text"]}}
          },
          "returnStoredSource": True }},
      {'$project': { 'similarityScore': { '$meta': 'searchScore' }, 'document' : '$$ROOT' }
}
]);

Importante

Durante l'anteprima, la ricerca vettoriale filtrata potrebbe richiedere di modificare i parametri dell'indice vettoriale per ottenere un'accuratezza maggiore. Ad esempio, l'aumento di m, efConstruction o efSearch quando si usa HNSW o numLists o nProbes quando si usa IVF, può portare a risultati migliori. È necessario testare la configurazione prima di usare per assicurarsi che i risultati siano soddisfacenti.

Usare gli strumenti di orchestrazione LLM

Usare come database vettoriale con kernel semantico

È ora possibile utilizzare Kernel semantico per orchestrare il recupero delle informazioni da Azure Cosmos DB for MongoDB vCore e LLM. Altre informazioni qui.

https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/memory/azure_cosmosdb

Usare come database vettoriale con LangChain

Utilizzare LangChain per orchestrare il recupero delle informazioni da Azure Cosmos DB for MongoDB vCore e LLM. Altre informazioni qui.

Usare come cache semantica con LangChain

Usare LangChain e Azure Cosmos DB per MongoDB (vCore) per orchestrare la memorizzazione nella cache semantica, usando risposte LLM registrate in precedenza che consentono di risparmiare sui costi dell'API LLM e ridurre la latenza per le risposte. Scopri di più qui

Funzionalità e limitazioni

Metriche di distanza supportate: L2 (euclideo), prodotto interno e coseno.
Metodi di indicizzazione supportati: IVFFLAT, HNSW e DiskANN (anteprima)
Indicizzazione di vettori con dimensioni fino a 2.000.
L'indicizzazione si applica a un solo vettore per percorso.
È possibile creare un solo indice per percorso vettoriale.

Riepilogo

Questa guida illustra come creare un indice vettoriale, aggiungere documenti con dati vettoriali, eseguire una ricerca di somiglianza e recuperare la definizione dell'indice. Il database di vettori integrato consente di indicizzare ed eseguire in maniera efficace query sui dati vettoriali di grandi dimensioni archiviati direttamente in Azure Cosmos DB for MongoDB vCore. Consente di sbloccare il potenziale completo dei dati tramite incorporamenti vettoriali e consente di creare applicazioni più accurate, efficienti e potenti.

Passaggio successivo

Creare un cluster vCore di livello gratuito lifetime per Azure Cosmos DB for MongoDB

Condividi tramite

Archivio vettoriale in Azure Cosmos DB per MongoDB vCore

Che cos'è un archivio di vettori?

Come funziona un archivio vettoriale?

Eseguire una ricerca di somiglianza vettoriale

Eseguire una ricerca vettoriale con DiskANN

Abilitazione di DiskANN in un nuovo cluster

Esempio di utilizzo di un indice DiskANN con filtro

Aggiungere vettori al database

Creare un indice vettoriale DiskANN

Eseguire una ricerca vettoriale

Eseguire una ricerca vettoriale con HNSW

Esempio di utilizzo di un indice HNSW

Aggiungere vettori al database

Eseguire una ricerca vettoriale

Eseguire una ricerca vettoriale con IVF

Esempio di utilizzo di un indice IVF

Creare un indice vettoriale

Aggiungere vettori al database

Eseguire una ricerca vettoriale

Vettori di query e distanze vettoriali (note anche come punteggi di similarità) che usano la funzione $search"

Ottenere definizioni di indice vettoriale

Ricerca vettoriale filtrata (anteprima)

Usare gli strumenti di orchestrazione LLM

Usare come database vettoriale con kernel semantico

Usare come database vettoriale con LangChain

Usare come cache semantica con LangChain

Funzionalità e limitazioni

Riepilogo

Passaggio successivo

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Archivio vettoriale in Azure Cosmos DB per MongoDB vCore

Che cos'è un archivio di vettori?

Come funziona un archivio vettoriale?

Eseguire una ricerca di somiglianza vettoriale

Eseguire una ricerca vettoriale con DiskANN

Abilitazione di DiskANN in un nuovo cluster

Esempio di utilizzo di un indice DiskANN con filtro

Aggiungere vettori al database

Creare un indice vettoriale DiskANN

Eseguire una ricerca vettoriale

Ottenere definizioni di indice vettoriale

Ricerca vettoriale filtrata (anteprima)

Usare gli strumenti di orchestrazione LLM

Usare come database vettoriale con kernel semantico

Usare come database vettoriale con LangChain

Usare come cache semantica con LangChain

Funzionalità e limitazioni

Riepilogo

Contenuto correlato

Passaggio successivo

Commenti e suggerimenti

Risorse aggiuntive