Indicizzare ed eseguire query vettoriali in Azure Cosmos DB for NoSQL in Python.

SI APPLICA A: NoSQL

Ricerca vettoriale in Azure Cosmos DB for NoSQL è attualmente una funzionalità di anteprima. Per poterla usare, è necessario registrarsi per l'anteprima. Questo articolo illustra i passaggi seguenti:

1. Registrazione per l'anteprima di Ricerca vettoriale in Azure Cosmos DB for NoSQL
2. Configurazione del contenitore Azure Cosmos DB per la ricerca vettoriale
3. Definizione dei criteri di incorporamento vettoriale
4. Aggiunta di indici vettoriali ai criteri di indicizzazione dei contenitori
5. Creazione di un contenitore con indici vettoriali e criteri di incorporamento vettoriale
6. Esecuzione di una ricerca vettoriale sui dati archiviati.
7. Questa guida illustra il processo di creazione di dati vettoriali, l'indicizzazione dei dati e quindi l'esecuzione di query sui dati in un contenitore.

Prerequisiti

• Un account Azure Cosmos DB per NoSQL già presente.
  • Se non si ha un abbonamento ad Azure, prova gratuitamente Azure Cosmos DB per NoSQL.
  • Se si ha già un abbonamento ad Azure, creare un nuovo account Azure Cosmos DB per NoSQL.
• La versione più recente dell'SDK di Python per Azure Cosmos DB.

Registrazione per l'anteprima

La ricerca vettoriale per Azure Cosmos DB for NoSQL richiede la registrazione della funzionalità di anteprima. Per effettuare la registrazione, seguire questa procedura:

1. Passare alla pagina della risorsa Azure Cosmos DB for NoSQL.

2. Selezionare il riquadro "Funzionalità" nella voce di menu "Impostazioni".

3. Selezionare "Ricerca vettoriale in Azure Cosmos DB for NoSQL".

4. Leggere la descrizione della funzionalità per confermare la registrazione nell'anteprima.

5. Selezionare "Abilita" per registrarsi all'anteprima.

Nota

La richiesta di registrazione verrà approvata automaticamente, ma potrebbero essere necessari alcuni minuti prima che diventi effettiva.

Informazioni sulla procedura necessaria per la ricerca vettoriale

La procedura seguente presuppone che sia in grado di configurare un account Cosmos DB NoSQL e di creare un database. La funzionalità di ricerca vettoriale non è attualmente supportata nei contenitori esistenti. È quindi necessario creare un nuovo contenitore e, durante il processo di creazione del contenitore, specificare i criteri di incorporamento vettoriale a livello di contenitore e i criteri di indicizzazione vettoriale.

Si prenda come esempio la creazione di un database per una libreria online in cui, per ogni libro, vengono archiviate le informazioni seguenti: Titolo, Autore, ISBN e Descrizione. Verranno inoltre definite due proprietà necessarie per poter contenere incorporamenti vettoriali. La prima è la proprietà "contentVector", contenente incorporamenti di testo generati dal contenuto di testo del libro (ad esempio, concatenando le proprietà "title" "author" "isbn" e "description" prima di creare l'incorporamento). La seconda è "coverImageVector", generata dalle immagini della copertina del libro.

1. Creare e archiviare incorporamenti vettoriali per i campi in cui si desidera eseguire la ricerca vettoriale.
2. Specificare i percorsi di incorporamento vettoriale nei criteri di incorporamento vettoriale.
3. Includere eventuali indici vettoriali desiderati nei criteri di indicizzazione per il contenitore.

Nelle sezioni successive di questo articolo, si considererà la struttura seguente per gli elementi archiviati nel contenitore:

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

Creazione di criteri di incorporamento vettoriale per il contenitore.

È ora necessario definire criteri vettoriali per il contenitore. Questi criteri forniscono le informazioni che verranno usate per istruire il motore di query di Azure Cosmos DB su come gestire le proprietà vettoriali nelle funzioni di sistema VectorDistance. In questo modo si forniscono anche le informazioni necessarie ai criteri di indicizzazione vettoriale, se si sceglie di specificarli. Nei criteri vettoriali contenuti sono disponibili le informazioni seguenti:

• "path": percorso della proprietà contenente i vettori
• "datatype": tipo degli elementi del vettore (tipo predefinito: Float32)
• "dimensions": lunghezza di ogni vettore presente nel percorso (dimensione predefinita: 1536)
• "distanceFunction": metrica usata per calcolare la distanza/somiglianza (metrica predefinita: Coseno)

Riprendendo l'esempio con i dettagli dei libri, i criteri vettoriali potrebbero avere un aspetto simile a questo codice JSON di esempio:

vector_embedding_policy = { 
    "vectorEmbeddings": [ 
        { 
            "path": "/coverImageVector", 
            "dataType": "float32", 
            "distanceFunction": "dotproduct", 
            "dimensions": 8 
        }, 
        { 
            "path": "/contentVector", 
            "dataType": "float32", 
            "distanceFunction": "cosine", 
            "dimensions": 10 
        } 
    ]    
} 

Creazione di indici vettoriali nei criteri di indicizzazione

Dopo aver deciso i percorsi di incorporamento vettoriali, gli indici vettoriali devono essere aggiunti ai criteri di indicizzazione. Per questo esempio, il criterio di indicizzazione sarà simile al seguente:

indexing_policy = { 
    "includedPaths": [ 
        { 
            "path": "/*" 
        } 
    ], 
    "excludedPaths": [ 
        { 
            "path": "/\"_etag\"/?",
            "path": "/coverImageVector/*",
            "path": "/contentVector/*"
            
        } 
    ], 
    "vectorIndexes": [ 
        {"path": "/coverImageVector", 
         "type": "quantizedFlat" 
        }, 
        {"path": "/contentVector", 
         "type": "quantizedFlat" 
        } 
    ] 
} 

Importante

Percorso vettoriale aggiunto alla sezione "excludedPaths" dei criteri di indicizzazione per garantire prestazioni ottimizzate per l'inserimento. Se non si aggiunge il percorso vettoriale a "excludedPaths", l’addebito e la latenza delle RU risulteranno più elevati.

Importante

Attualmente la ricerca vettoriale in Azure Cosmos DB for NoSQL è supportata solo nei nuovi contenitori. Al momento della creazione del contenitore è necessario impostare sia i criteri vettoriali del contenitore sia eventuali criteri di indicizzazione vettoriale, poiché non potranno più essere modificati. Entrambi i criteri saranno modificabili in un miglioramento futuro della funzionalità di anteprima.

Creare un contenitore con criteri vettoriali

Attualmente la funzionalità di ricerca vettoriale per Azure Cosmos DB for NoSQL è supportata solo nei nuovi contenitori, quindi è necessario applicare i criteri vettoriali al momento della creazione del contenitore e non è possibile modificarli in un secondo momento.

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 

Esecuzione di una query di ricerca di somiglianza vettoriale

Dopo aver creato un contenitore con i criteri vettoriali desiderati e aver inserito i dati vettoriali nel contenitore, è possibile eseguire una ricerca vettoriale usando la funzione di sistema Vector Distance in una query. Si supponga di voler cercare libri di ricette in base alla descrizione. È prima necessario ottenere gli incorporamenti per il testo della query. In questo caso, potrebbe essere necessario generare incorporamenti per il testo di query "food recipe" (ricetta). Dopo aver ottenuto l'incorporamento per la query di ricerca, è possibile usarlo nella funzione VectorDistance nella query di ricerca vettoriale e ottenere tutti gli elementi simili alla query, come illustrato di seguito:

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

Questa query recupera i titoli dei libri insieme ai punteggi di somiglianza rispetto alla query. Ecco un esempio in 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)) 

• Funzione di sistema VectorDistance
• Indicizzazione vettoriale
• Configurare Azure Cosmos DB for NoSQL per la ricerca vettoriale.