Condividi tramite

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

  • Articolo

SI APPLICA A: NoSQL

La funzionalità di ricerca vettoriale di Azure Cosmos DB per NoSQL è disponibile in anteprima. Prima di usare questa funzionalità, è 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

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

Registrarsi 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 per 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.

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 è attualmente supportata solo nei nuovi contenitori, non in quelli esistenti. È necessario creare un nuovo contenitore e, durante il processo di creazione, 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", che contiene 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). Il secondo è "coverImageVector", generato 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.

Per le sezioni successive di questo articolo, si consideri questa struttura 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 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:

Descrizione
path Percorso della proprietà che contiene vettori
datatype Tipo degli elementi del vettore (impostazione predefinita Float32)
dimensions Lunghezza di ogni vettore nel percorso (impostazione predefinita 1536)
distanceFunction Metrica usata per calcolare distanza/somiglianza (impostazione predefinita Cosine)

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

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

Creare un indice vettoriale nei criteri di indicizzazione

Dopo aver deciso i percorsi di incorporamento vettoriali, è necessario aggiungere gli indici vettoriali ai criteri di indicizzazione. È necessario applicare i criteri vettoriali durante il periodo di creazione del contenitore e non può essere modificato in un secondo momento. Per questo esempio, i criteri di indicizzazione saranno simili a quanto segue:

const indexingPolicy: IndexingPolicy = {
  vectorIndexes: [
    { path: "/coverImageVector", type: "quantizedFlat" },
    { path: "/contentVector", type: "diskANN" },
  ],
    inlcludedPaths: [
      {
        path: "/*",
      },
    ],
    excludedPaths: [
      {
        path: "/coverImageVector/*",
      },
      {
        path: "/contentVector/*",
      },
    ]
};

Creare ora il contenitore come di consueto.

const containerName = "vector embedding container";
    // create container
    const { resource: containerdef } = await database.containers.createIfNotExists({
      id: containerName,
      vectorEmbeddingPolicy: vectorEmbeddingPolicy,
      indexingPolicy: indexingPolicy,
    });

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.

Eseguire 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 sulle ricette alimentari esaminando la descrizione. È prima necessario ottenere gli incorporamenti per il testo della query. In questo caso, potrebbe essere necessario generare incorporamenti per il testo della query, ovvero "ricetta alimentare". 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 JavaScript:

const { resources } = await container.items
  .query({
    query: "SELECT c.title, VectorDistance(c.contentVector, @embedding) AS SimilarityScore FROM c  ORDER BY VectorDistance(c.contentVector, @embedding)"
    parameters: [{ name: "@embedding", value: [1,2,3,4,5,6,7,8,9,10] }]
  })
  .fetchAll();
for (const item of resources) {
  console.log(`${itme.title}, ${item.SimilarityScore} is a capitol `);
}

Contenuto correlato