Indicizzare ed eseguire query sui vettori in Azure Cosmos DB for NoSQL in Java

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 Java 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. Vengono 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] 
} 

Prima di tutto, creare l'oggetto CosmosContainerProperties.

CosmosContainerProperties collectionDefinition = new CosmosContainerProperties(UUID.randomUUID().toString(), "Partition_Key_Def");

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:

// Creating vector embedding policy
CosmosVectorEmbeddingPolicy cosmosVectorEmbeddingPolicy = new CosmosVectorEmbeddingPolicy();

CosmosVectorEmbedding embedding1 = new CosmosVectorEmbedding();
embedding1.setPath("/coverImageVector");
embedding1.setDataType(CosmosVectorDataType.FLOAT32);
embedding1.setDimensions(8L);
embedding1.setDistanceFunction(CosmosVectorDistanceFunction.COSINE);

CosmosVectorEmbedding embedding2 = new CosmosVectorEmbedding();
embedding2.setPath("/contentVector");
embedding2.setDataType(CosmosVectorDataType.FLOAT32);
embedding2.setDimensions(10L);
embedding2.setDistanceFunction(CosmosVectorDistanceFunction.DOT_PRODUCT);

cosmosVectorEmbeddingPolicy.setCosmosVectorEmbeddings(Arrays.asList(embedding1, embedding2, embedding3));

collectionDefinition.setVectorEmbeddingPolicy(cosmosVectorEmbeddingPolicy);

Creazione di indici vettoriali nei criteri di indicizzazione

Dopo aver deciso i percorsi di incorporamento vettoriali, è necessario aggiungere gli indici vettoriali ai criteri di indicizzazione. Attualmente la funzionalità di ricerca vettoriale per Azure Cosmos DB for NoSQL è supportata solo nei nuovi contenitori e, pertanto, è necessario applicare i criteri vettoriali al momento della creazione del contenitore e non è possibile modificarli in un secondo momento. Per questo esempio, i criteri di indicizzazione saranno simili a quanto segue:

IndexingPolicy indexingPolicy = new IndexingPolicy();
indexingPolicy.setIndexingMode(IndexingMode.CONSISTENT);
ExcludedPath excludedPath1 = new ExcludedPath("/coverImageVector/*");
ExcludedPath excludedPath2 = new ExcludedPath("/contentVector/*");
indexingPolicy.setExcludedPaths(ImmutableList.of(excludedPath1, excludedPath2));

IncludedPath includedPath1 = new IncludedPath("/*");
indexingPolicy.setIncludedPaths(Collections.singletonList(includedPath1));

// Creating vector indexes
CosmosVectorIndexSpec cosmosVectorIndexSpec1 = new CosmosVectorIndexSpec();
cosmosVectorIndexSpec1.setPath("/coverImageVector");
cosmosVectorIndexSpec1.setType(CosmosVectorIndexType.QUANTIZED_FLAT.toString());

CosmosVectorIndexSpec cosmosVectorIndexSpec2 = new CosmosVectorIndexSpec();
cosmosVectorIndexSpec2.setPath("/contentVector");
cosmosVectorIndexSpec2.setType(CosmosVectorIndexType.DISK_ANN.toString());

indexingPolicy.setVectorIndexes(Arrays.asList(cosmosVectorIndexSpec1, cosmosVectorIndexSpec2, cosmosVectorIndexSpec3));

collectionDefinition.setIndexingPolicy(indexingPolicy);

È necessario infine creare il contenitore con i criteri di indicizzazione del contenitore e i criteri di indicizzazione vettoriale.

database.createContainer(collectionDefinition).block();

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 tipi di criteri risulteranno modificabili in un miglioramento futuro della funzionalità di anteprima.

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 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 e i relativi punteggi di somiglianza rispetto alla query. Ecco un esempio in Java:

float[] embedding = new float[10];
for (int i = 0; i < 10; i++) {
    array[i] = i + 1;
}
ArrayList<SqlParameter> paramList = new ArrayList<SqlParameter>();
  paramList.add(new SqlParameter("@embedding", embedding));
  SqlQuerySpec querySpec = new SqlQuerySpec("SELECT c.title, VectorDistance(c.contentVector,@embedding) AS SimilarityScore  FROM c ORDER BY VectorDistance(c.contentVector,@embedding)", paramList);
  CosmosPagedIterable<Family> filteredFamilies = container.queryItems(querySpec, new CosmosQueryRequestOptions(), Family.class);

  if (filteredFamilies.iterator().hasNext()) {
      Family family = filteredFamilies.iterator().next();
      logger.info(String.format("First query result: Family with (/id, partition key) = (%s,%s)",family.getId(),family.getLastName()));
  }

Passaggi successivi

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