Embeddings de la búsqueda de vectores con metadatos

En esta guía, se proporciona información sobre los metadatos opcionales para las incorporaciones 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 la búsqueda de vectores puede almacenar para cada incorporación. Esto puede proporcionar incorporaciones con contexto útil, como el siguiente:

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

  • Descripciones, fragmentos, fechas y autoría para las incorporaciones de texto

  • Información del usuario para las incorporaciones de usuarios

  • Coordenadas para las incorporaciones de lugares

Funciones y beneficios clave

Las funciones y los beneficios de usar metadatos incluyen lo siguiente:

  • 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.

  • No se pueden filtrar: Los metadatos de incorporación de vectores son para almacenar y recuperar información que no se puede filtrar y 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 vectores de incorporación.

  • Información desacoplada: La información que no se puede filtrar se puede separar de los atributos que se pueden filtrar, como restricts.

  • Desarrollo optimizado: Las respuestas de búsqueda incluyen metadatos asociados con una incorporación de vectores, lo que reduce la complejidad necesaria para funciones como mostrar resultados de búsqueda enriquecidos y realizar el 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 que no se puede filtrar con las incorporaciones en la búsqueda de vectores. Esto puede optimizar las aplicaciones, ya que muestra el contexto con los resultados y permite actualizaciones eficientes solo de metadatos con update_mask para la API de upsertDatapoints.

Ejemplo de estructura 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

Cómo transferir datos con embedding_metadata

Cuando agregues datos, puedes incluir embedding_metadata cuando se produzca una de las siguientes acciones:

  • Subir un archivo (Cloud Storage):
    • Usa los formatos JSON o AVRO formats. CSV no es compatible con embedding_metadata.
  • Usar la API de upsertDatapoints:
    • Pasa objetos de datos (incluido embedding_metadata) en la carga útil de la solicitud a la API.

Cómo recuperar embedding_metadata durante las consultas

Cuando realizas una búsqueda estándar de vecinos más cercanos con la API de findNeighbors, el campo embedding_metadata para 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}'

Cómo actualizar embedding_metadata

Actualiza los metadatos con la API de upsertDatapoints y una 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 incorporación.

El campo update_mask ayuda a garantizar que solo se actualice embedding_metadata, lo que evita volver a enviar 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"}'