Incorporamenti di ricerca vettoriale con metadati

Questa guida fornisce informazioni sui metadati facoltativi per gli embedding vettoriali. La ricerca vettoriale consente di definire i metadati per ogni embedding.

I metadati sono informazioni arbitrarie e non filtrabili che la ricerca vettoriale può memorizzare per ogni embedding. In questo modo, gli embedding possono avere un contesto utile, ad esempio:

  • Dettagli del prodotto, come nome, prezzo e URL di un'immagine.

  • Descrizioni, snippet, date e autori per gli embedding di testo.

  • Informazioni utente per gli embedding utente.

  • Coordinate per gli embedding di luoghi.

Funzionalità e vantaggi principali

Le funzionalità e i vantaggi dell'utilizzo dei metadati includono:

  • Contesto con i risultati: le informazioni possono essere fornite direttamente nei risultati di ricerca, il che elimina la necessità di ricerche separate e riduce la latenza.

  • Struttura flessibile: i metadati vengono forniti come oggetto JSON, il che consente di definirli come dati complessi e nidificati.

  • Non filtrabili: i metadati degli embedding vettoriali vengono utilizzati per memorizzare e recuperare informazioni non filtrabili distinte da restricts e numeric_restricts.

  • Aggiornamenti efficienti: il campo update_mask consente di specificare che le API solo aggiornano i metadati per evitare di inviare di nuovo i vettori di embedding.

  • Informazioni disaccoppiate: le informazioni non filtrabili possono essere separate dagli attributi filtrabili come restricts.

  • Sviluppo semplificato: le risposte di ricerca includono i metadati associati a un embedding vettoriale, riducendo al contempo la complessità necessaria per funzionalità come la visualizzazione di risultati di ricerca avanzati e l'esecuzione di post-elaborazione basata sul contesto.

Formato dei dati

Un campo embedding_metadata facoltativo contiene un oggetto JSON che associa in modo flessibile informazioni avanzate e non filtrabili agli embedding nella ricerca vettoriale. In questo modo, le applicazioni possono essere semplificate restituendo il contesto con i risultati e consentendo aggiornamenti efficienti solo dei metadati utilizzando update_mask per l'API upsertDatapoints.

Esempio di struttura del punto dati:

    {
        "id": "movie_001",
        "embedding": [0.1, 0.2, ..., 0.3],
        "sparse_embedding": {
            "values": [-0.4, 0.2, -1.3],
            "dimensions": [10, 20, 30]
        },
        "numeric_restricts": [{'namespace': 'year', 'value_int': 2022}],
        "restricts": [{'namespace': 'genre', 'allow': ['action', 'comedy']}],

        # --- New embedding_metadata field ---
        "embedding_metadata": {
            "title": "Ballet Train",
            "runtime": {
                "hours": 2,
                "minutes": 6
            },
            "review_info": {
                "review": "This movie is fun and...",
                "rotten_potatoes_rating": 76
            }
        }
        # ------------------------------------
    },
    # ... other data points

Importare dati con embedding_metadata

Quando aggiungi punti dati, puoi includere embedding_metadata quando si verifica una delle seguenti azioni:

  • Caricamento di un file (Cloud Storage):
    • Utilizza i formati JSON o AVRO formats. Il formato CSV non è supportato per embedding_metadata.
  • Utilizzo dell'API upsertDatapoints:
    • Trasmetti gli oggetti punto dati (incluso embedding_metadata) nel payload della richiesta API.

Recuperare embedding_metadata durante le query

Quando esegui una ricerca standard dei vicini più prossimi utilizzando l'API findNeighbors, il campo embedding_metadata per ogni vicino viene incluso automaticamente nella risposta se returnFullDatapoint è impostato su True.

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors" \
-d '{deployedIndexId:"${DEPLOYED_INDEX_ID}", "queries":[{datapoint:{"featureVector":"<FEATURE_VECTOR>"}}], returnFullDatapoint:true}'

Aggiornare embedding_metadata

Aggiorna i metadati utilizzando l'API upsertDatapoints e un update_mask utilizzando il valore embedding_metadata. Il campo update_mask può includere anche valori di maschera aggiuntivi. Per gli utilizzi di una maschera di campo, vedi Aggiornare i metadati degli embedding.

Il campo update_mask consente di garantire che venga aggiornato solo embedding_metadata, evitando di inviare di nuovo i campi di restrizione e embedding.

L'esempio seguente mostra come definire e aggiornare i metadati per creare un IndexDatapoint mirato, specificare update_mask e chiamare upsertDatapoints.

curl

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints:[
    {
        datapoint_id: "'${DATAPOINT_ID_1}'",
        feature_vector: [...],
        embedding_metadata:{"title": "updated title", "rating": 4.5, "tags": ["updated", "reviewed"]
    }, update_mask: "embedding_metadata"}'