Embeddings Vector Search avec métadonnées

Ce guide fournit des informations sur les métadonnées facultatives pour les embeddings vectoriels. Vector Search vous permet de définir des métadonnées pour chaque embedding.

Les métadonnées sont des informations arbitraires non filtrables que la recherche vectorielle peut stocker pour chaque embedding. Cela peut fournir des embeddings avec un contexte utile, par exemple :

  • Informations sur le produit, comme son nom, son prix et l'URL de son image

  • Descriptions, extraits, dates et auteurs pour les embeddings de texte.

  • Informations utilisateur pour les embeddings utilisateur.

  • Coordonnées des embeddings de lieux.

Principaux avantages et fonctionnalités

Voici quelques avantages de l'utilisation des métadonnées :

  • Contexte avec les résultats : des informations peuvent être fournies directement dans vos résultats de recherche, ce qui élimine la nécessité d'effectuer des recherches distinctes et réduit la latence.

  • Structure flexible : les métadonnées sont fournies sous forme d'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 permettent de stocker et de 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 mettent uniquement à jour les métadonnées pour éviter de renvoyer les vecteurs d'intégration.

  • 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 des 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 riches et non filtrables à des embeddings 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. Le format CSV n'est pas accepté pour embedding_metadata.
  • Utiliser l'API upsertDatapoints :
    • Transmettez des objets de points de données (y compris embedding_metadata) dans le corps de la requête API.

Récupérer embedding_metadata lors des requêtes

Lorsque vous effectuez une recherche standard des voisins les plus proches à 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}'

Mise à jour de 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 savoir comment utiliser un masque de champ, consultez Mettre à jour les métadonnées d'embedding.

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 d'intégration.

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"}'