Embeddings de la búsqueda de vectores con metadatos

En esta guía, se proporciona información sobre los metadatos opcionales para los embeddings de vectores. La Búsqueda de vectores te permite definir metadatos para cada incorporación.

Los metadatos son información arbitraria que no se puede filtrar y que Vector Search puede almacenar para cada incorporación. Esto puede proporcionar incorporaciones con contexto útil, como los siguientes:

  • Detalles del producto, como el nombre, el precio y la URL de una imagen

  • Son las descripciones, los fragmentos, las fechas y la autoría de las incorporaciones de texto.

  • Es la información del usuario para los embeddings de usuarios.

  • Son las coordenadas de las incorporaciones de lugares.

Funciones y beneficios clave

Estos son algunos de los beneficios de usar metadatos:

  • Contexto con resultados: La información se puede proporcionar directamente en los resultados de la búsqueda, lo que elimina la necesidad de realizar búsquedas separadas y reduce la latencia.

  • Estructura flexible: Los metadatos se proporcionan como un objeto JSON, lo que permite que se definan como datos complejos y anidados.

  • Non-Filterable: Los metadatos de la incorporación de vectores sirven para almacenar y recuperar información no filtrable que es distinta de restricts y numeric_restricts.

  • Actualizaciones eficientes: El campo update_mask te permite especificar que las APIs solo actualicen los metadatos para evitar volver a enviar los vectores de incorporación.

  • Información desacoplada: La información no filtrable se puede separar de los atributos filtrables, como restricts.

  • Desarrollo optimizado: Las respuestas de la búsqueda incluyen metadatos asociados con una incorporación de vectores, a la vez que reducen la complejidad necesaria para funciones como la visualización de resultados de la búsqueda enriquecidos y la realización del procesamiento posterior basado en el contexto.

Formato de los datos

Un campo embedding_metadata opcional contiene un objeto JSON que asocia de forma flexible información enriquecida y no filtrable con las incorporaciones en la Búsqueda vectorial. Esto puede optimizar las aplicaciones, ya que devuelve contexto con los resultados y permite actualizaciones eficientes solo de metadatos con update_mask para la API de upsertDatapoints.

Ejemplo de estructura de punto de datos:

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

Transfiere datos con embedding_metadata

Cuando agregues puntos de datos, puedes incluir embedding_metadata cuando ocurra una de las siguientes acciones:

  • Cómo subir un archivo (Cloud Storage):
    • Usa formatos JSON o AVRO. El formato CSV no es compatible con embedding_metadata.
  • Usa la API de upsertDatapoints:
    • Pasa objetos de puntos de datos (incluido embedding_metadata) en la carga útil de la solicitud a la API.

Cómo recuperar embedding_metadata durante las búsquedas

Cuando se realiza una búsqueda estándar de vecinos más cercanos con la API de findNeighbors, el campo embedding_metadata de cada vecino se incluye automáticamente en la respuesta si returnFullDatapoint se establece en 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}'

Actualizando embedding_metadata

Actualiza los metadatos con la API de upsertDatapoints y un update_mask con el valor embedding_metadata. El campo update_mask también puede incluir valores de máscara adicionales. Para conocer los usos de una máscara de campo, consulta Actualiza los metadatos de la incorporación.

El campo update_mask ayuda a garantizar que solo se actualice embedding_metadata, lo que evita el reenvío de los campos de restricción y de incorporación.

En el siguiente ejemplo, se muestra cómo definir y actualizar metadatos para crear un IndexDatapoint segmentado, especificar update_mask y llamar a 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"}'