Condividi tramite

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

  • Si applica a: ✅ NoSQL

Questo articolo illustra come creare dati vettoriali, indicizzare i dati e quindi eseguire query sui dati in un contenitore.

Prima di usare l'indicizzazione e la ricerca di vettori, è necessario abilitare la ricerca vettoriale in Azure Cosmos DB per NoSQL. Dopo aver configurato il contenitore di Azure Cosmos DB per la ricerca vettoriale, si creano criteri di incorporamento vettoriali. Successivamente, si aggiungono indici vettoriali ai criteri di indicizzazione dei contenitori. Creare quindi un contenitore con indici vettoriali e criteri di incorporamento vettoriali. Infine, si esegue una ricerca vettoriale sui dati archiviati.

Prerequisiti

Abilitare la funzionalità

Per abilitare la ricerca vettoriale per Azure Cosmos DB per NoSQL, seguire questa procedura:

  1. Vai alla pagina della risorsa Azure Cosmos DB per NoSQL.
  2. Nel riquadro sinistro, in Impostazioni, selezionare Funzionalità.
  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 di Azure Cosmos DB per NoSQL.

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

La richiesta di registrazione viene approvata automaticamente, ma potrebbero essere necessari 15 minuti.

I passaggi seguenti presuppongono che si sappia come configurare un account Azure Cosmos DB per NoSQL e creare un database. La funzionalità di ricerca vettoriale non è attualmente supportata nei contenitori esistenti. È necessario creare un nuovo contenitore. Quando si crea il contenitore, si specificano i criteri di incorporamento del vettore a livello di contenitore e i criteri di indicizzazione vettoriale.

Di seguito è riportato un esempio di come creare un database per un booktore basato su Internet. Si desidera archiviare le informazioni su titolo, autore, ISBN e descrizione per ogni libro. È anche necessario definire le due proprietà seguenti per contenere incorporamenti vettoriali:

  • La contentVector proprietà contiene incorporamenti di testo generati dal contenuto di testo del libro. Ad esempio, si concatenano le proprietà title, author, isbn e description prima di creare l'integrazione.
  • La coverImageVector proprietà viene generata dalle immagini della copertina del libro.

Per eseguire una ricerca vettoriale, è necessario:

  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 gli indici vettoriali desiderati nei criteri di indicizzazione per il contenitore.

Per le sezioni successive di questo articolo, considerare 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] 
}

Creare un criterio di incorporamento vettoriale per il contenitore

Ora è necessario definire una politica del vettore di container. 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. Questo criterio fornisce anche le informazioni necessarie per i criteri di indicizzazione vettoriali, se si sceglie di specificarne uno.

Le informazioni seguenti sono incluse nella politica del vettore del contenitore.

Parametro Description
path Percorso della proprietà che contiene vettori.
datatype Tipo degli elementi del vettore. Il valore predefinito è Float32.)
dimensions Lunghezza di ogni vettore nel percorso. Il valore predefinito è 1536.)
distanceFunction Metrica usata per calcolare distanza/somiglianza. Il valore predefinito è Cosine.)

Per l'esempio con i dettagli del libro, i criteri vettoriali potrebbero essere simili all'esempio seguente:

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

Creare un indice vettoriale nei criteri di indicizzazione

Dopo aver deciso i percorsi di incorporamento dei vettori, è necessario aggiungere indici vettoriali ai criteri di indicizzazione. Attualmente, la funzionalità di ricerca vettoriale per Azure Cosmos DB per NoSQL è supportata solo nei nuovi contenitori. Quando si crea il contenitore, si applicano i criteri vettoriali. Non è possibile modificare i criteri in un secondo momento. Il criterio di indicizzazione è simile all'esempio seguente:

    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

Il percorso vettoriale viene aggiunto alla excludedPaths sezione dei criteri di indicizzazione per garantire prestazioni ottimizzate per l'inserimento. Non aggiungere il percorso vettoriale a excludedPaths risulta in un costo unitario di richiesta maggiore e una latenza più elevata per gli inserimenti vettoriali.

Eseguire una query di ricerca di somiglianza vettoriale

Dopo aver creato un contenitore con i criteri vettoriali desiderati e inserire dati vettoriali nel contenitore, usare la funzione di sistema VectorDistance in una query per eseguire una ricerca vettoriale.

Si supponga di voler cercare libri sulle ricette alimentari esaminando la descrizione. Prima di tutto, è necessario ottenere gli embedding per il testo della query. In questo caso, potrebbe essere necessario generare incorporamenti per il testo food recipedella query . Dopo aver ottenuto l'embedding per la tua query di ricerca, puoi usarlo nella funzione VectorDistance nella query di ricerca vettoriale per ottenere tutti gli elementi simili alla tua query.

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

Contenuti correlati

  • Last updated on