Condividi tramite

Indicizzare ed eseguire query sui vettori in Azure Cosmos DB per NoSQL in .NET

  • Articolo
  • Si applica a:
    ✅ NoSQL

Prima di usare l'indicizzazione vettoriale e la ricerca, è necessario abilitare la funzionalità. Questo articolo illustra i passaggi seguenti:

  1. Abilitazione della funzionalità Ricerca vettoriale in Azure Cosmos DB per 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

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

Abilitare la funzionalità

La ricerca vettoriale per Azure Cosmos DB per NoSQL richiede l'abilitazione della funzionalità completando i passaggi seguenti:

  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 per NoSQL".
  4. Leggere la descrizione della funzionalità per confermare che si vuole abilitarla.
  5. Selezionare "Abilita" per attivare la ricerca vettoriale in Azure Cosmos DB per NoSQL.

Suggerimento

In alternativa, usare l'interfaccia della riga di comando di Azure per aggiornare le funzionalità dell'account per supportare la ricerca vettoriale NoSQL.

az cosmosdb update \
     --resource-group <resource-group-name> \
     --name <account-name> \
     --capabilities EnableNoSQLVectorSearch

Nota

La richiesta di registrazione verrà approvata automaticamente; tuttavia, potrebbero essere necessari 15 minuti.

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

Creazione di un criterio 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. Questi criteri 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 qui di seguito:

  Database db = await client.CreateDatabaseIfNotExistsAsync("vector-benchmarking");
  List<Embedding> embeddings = new List<Embedding>()
  {
      new Embedding()
      {
          Path = "/coverImageVector",
          DataType = VectorDataType.Float32,
          DistanceFunction = DistanceFunction.Cosine,
          Dimensions = 8,
      },
      new Embedding()
      {
          Path = "/contentVector",
          DataType = VectorDataType.Float32,
          DistanceFunction = DistanceFunction.Cosine,
          Dimensions = 10,
      }
  };

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 simile a:

    Collection<Embedding> collection = new Collection<Embedding>(embeddings);
    ContainerProperties properties = new ContainerProperties(id: "vector-container", partitionKeyPath: "/id")
    {   
        VectorEmbeddingPolicy = new(collection),
        IndexingPolicy = new IndexingPolicy()
        {
            VectorIndexes = new()
            {
                new VectorIndexPath()
                {
                    Path = "/vector",
                    Type = VectorIndexType.QuantizedFlat,
                }
            }
        },
    };
    properties.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });    
    properties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/vector/*" });

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.

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

  float[] embedding = {1f,2f,3f,4f,5f,6f,7f,8f,9f,10f};
  var queryDef = new QueryDefinition(
      query: $"SELECT c.title, VectorDistance(c.contentVector,@embedding) AS SimilarityScore FROM c ORDER BY VectorDistance(c.contentVector,@embedding)"
      ).WithParameter("@embedding", embedding);
  using FeedIterator<Object> feed = container.GetItemQueryIterator<Object>(
      queryDefinition: queryDef
  );
  while (feed.HasMoreResults) 
  {
      FeedResponse<Object> response = await feed.ReadNextAsync();
      foreach ( Object item in response)
      {
          Console.WriteLine($"Found item:\t{item}");
      }
  }

Contenuto correlato