Embeddings de pesquisa vetorial com metadados

Este guia fornece informações sobre metadados opcionais para embeddings vetoriais. Com a pesquisa de vetor, é possível definir metadados para cada embedding.

Os metadados são informações arbitrárias e não filtráveis que a pesquisa vetorial pode armazenar para cada incorporação. Isso pode fornecer embeddings com contexto útil, como:

  • Detalhes do produto, como nome, preço e URL de uma imagem.

  • Descrições, snippets, datas e autoria para embeddings de texto.

  • Informações do usuário para embeddings de usuário.

  • Coordenadas para embeddings de lugar.

Principais recursos e benefícios

Recursos e benefícios do uso de metadados:

  • Contexto com resultados: as informações podem ser fornecidas diretamente nos resultados da pesquisa, o que elimina a necessidade de pesquisas separadas e reduz a latência.

  • Estrutura flexível: os metadados são fornecidos como um objeto JSON, o que permite que eles sejam definidos como dados complexos e aninhados.

  • Não filtrável: os metadados de incorporação de vetor são para armazenar e recuperar informações não filtráveis que são distintas de restricts e numeric_restricts.

  • Atualizações eficientes: o campo update_mask permite especificar que as APIs apenas atualizam metadados para evitar o reenvio de vetores de incorporação.

  • Informações dissociadas: as informações não filtráveis podem ser separadas de atributos filtráveis, como restricts.

  • Desenvolvimento simplificado: as respostas da pesquisa incluem metadados associados a uma incorporação de vetor, reduzindo a complexidade necessária para recursos como exibir resultados de pesquisa avançada e realizar pós-processamento baseado em contexto.

Formato de dados

Um campo embedding_metadata opcional contém um objeto JSON que associa de forma flexível informações avançadas e não filtráveis a incorporações na pesquisa vetorial. Isso pode simplificar os aplicativos retornando o contexto com os resultados e permite atualizações eficientes somente de metadados usando update_mask para a API upsertDatapoints.

Exemplo de estrutura de ponto de dados:

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

Ingestão de dados com embedding_metadata

Ao adicionar pontos de dados, você pode incluir embedding_metadata quando uma das seguintes ações ocorrer:

  • Fazer upload de um arquivo (Cloud Storage):
    • Use formatos JSON ou AVRO. O formato CSV não é compatível com embedding_metadata.
  • Usando a API upsertDatapoints:
    • Transmita objetos de ponto de dados (incluindo embedding_metadata) no payload da solicitação da API.

Como recuperar embedding_metadata durante consultas

Ao realizar uma pesquisa padrão de vizinho mais próximo usando a API findNeighbors, o campo embedding_metadata de cada vizinho é incluído automaticamente na resposta se returnFullDatapoint estiver definido como 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}'

Atualizando embedding_metadata

Atualize os metadados usando a API upsertDatapoints e um update_mask com o valor embedding_metadata. O campo update_mask também pode incluir outros valores de máscara. Para usos de uma máscara de campo, consulte Atualizar metadados de incorporação.

O campo update_mask ajuda a garantir que apenas embedding_metadata seja atualizado, evitando o reenvio de campos de restrição e incorporação.

O exemplo a seguir demonstra como definir e atualizar metadados para criar uma IndexDatapoint segmentada, especificando update_mask e chamando 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"}'