Embeddings Vector Search avec métadonnées

Ce guide fournit des informations sur les métadonnées facultatives pour les représentations vectorielles continues. Vector Search vous permet de définir des métadonnées pour chaque représentation vectorielle continue.

Les métadonnées sont des informations arbitraires non filtrables que Vector Search peut stocker pour chaque représentation vectorielle continue. Elles peuvent fournir aux représentations vectorielles continues un contexte utile, par exemple :

  • des informations sur le produit, telles que son nom, son prix et l'URL d'une image ;

  • des descriptions, des extraits, des dates et des informations sur l'auteur pour les représentations vectorielles continues de texte ;

  • des informations sur l'utilisateur pour les représentations vectorielles continues d'utilisateur ;

  • des coordonnées pour les représentations vectorielles continues de lieu.

Principaux avantages et fonctionnalités

Voici les avantages et les fonctionnalités liés à l'utilisation de métadonnées :

  • Contexte avec les résultats : les informations peuvent être fournies directement dans vos résultats de recherche, ce qui élimine le besoin de recherches distinctes et réduit la latence.

  • Structure flexible : les métadonnées sont fournies sous la forme d'un objet JSON, ce qui permet de les définir comme des données complexes et imbriquées.

  • Non filtrable : les métadonnées d'embedding vectoriel servent à stocker et à récupérer des informations non filtrables qui sont distinctes de restricts et numeric_restricts.

  • Mises à jour efficaces : le champ update_mask vous permet de spécifier que les API ne mettent à jour que les métadonnées pour éviter de renvoyer des vecteurs de représentation vectorielle continue.

  • Informations dissociées : les informations non filtrables peuvent être séparées des attributs filtrables tels que restricts.

  • Développement simplifié : les réponses de recherche incluent les métadonnées associées à un embedding vectoriel, tout en réduisant la complexité nécessaire pour des fonctionnalités telles que l'affichage de résultats de recherche enrichis et l'exécution d'un post-traitement basé sur le contexte.

Format des données

Un champ embedding_metadata facultatif contient un objet JSON qui associe de manière flexible des informations enrichies et non filtrables aux représentations vectorielles continues dans Vector Search. Cela peut simplifier les applications en renvoyant le contexte avec les résultats et permet des mises à jour efficaces des métadonnées uniquement à l'aide de update_mask pour l'API upsertDatapoints.

Exemple de structure de point de données :

    {
        "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

Ingérer des données avec embedding_metadata

Lorsque vous ajoutez des points de données, vous pouvez inclure embedding_metadata lorsque l'une des actions suivantes se produit :

  • Importer un fichier (Cloud Storage) :
    • Utilisez les formats JSON ou AVRO formats. Le format CSV n'est pas compatible avec embedding_metadata.
  • Utiliser l'API upsertDatapoints :
    • Transmettez des objets de point de données (y compris embedding_metadata) dans la charge utile de la requête API.

Récupérer embedding_metadata lors des requêtes

Lorsque vous effectuez une recherche standard du plus proche voisin à l'aide de l'API findNeighbors, le champ embedding_metadata de chaque voisin est automatiquement inclus dans la réponse si returnFullDatapoint est défini sur 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}'

Mettre à jour embedding_metadata

Mettez à jour les métadonnées à l'aide de l'API upsertDatapoints et d'un update_mask avec la valeur embedding_metadata. Le champ update_mask peut également inclure des valeurs de masque supplémentaires. Pour connaître les utilisations d'un masque de champ, consultez Mettre à jour les métadonnées de représentation vectorielle continue.

Le champ update_mask permet de s'assurer que seul embedding_metadata est mis à jour, ce qui évite de renvoyer les champs de restriction et de représentation vectorielle continue.

L'exemple suivant montre comment définir et mettre à jour des métadonnées pour créer un IndexDatapoint ciblé, en spécifiant update_mask et en appelant 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"}'