Incorporações da Vector Search com metadados

Este guia fornece informações sobre os metadados opcionais para incorporações vetoriais. A pesquisa vetorial permite-lhe definir metadados para cada incorporação.

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

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

  • Descrições, fragmentos, datas e autoria para incorporações de texto.

  • Informações do utilizador para incorporações de utilizadores.

  • Coordenadas para incorporações de locais.

Principais funcionalidades e vantagens

As funcionalidades e as vantagens da utilização de metadados incluem:

  • 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 os metadados sejam definidos como dados complexos e aninhados.

  • Não filtrável: os metadados de incorporação de vetores destinam-se a armazenar e obter informações não filtráveis que são distintas de restricts e numeric_restricts.

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

  • Informações desagrupadas: 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 vetorial, ao mesmo tempo que reduzem a complexidade necessária para funcionalidades como a apresentação de resultados da pesquisa avançados e a realização de pós-processamento baseado no contexto.

Formato de dados

Um campo embedding_metadata opcional contém um objeto JSON que associa de forma flexível informações detalhadas e não filtráveis a incorporações na pesquisa vetorial. Isto pode simplificar as aplicações ao devolver o contexto com os resultados e permite atualizações eficientes apenas de metadados através de 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

Carregue dados com o embedding_metadata

Quando adiciona pontos de dados, pode incluir embedding_metadata quando ocorre uma das seguintes ações:

  • Carregar um ficheiro (Cloud Storage):
    • Use formatos JSON ou AVRO. O CSV não é suportado para embedding_metadata.
  • Usar a API upsertDatapoints:
    • Transmita objetos de pontos de dados (incluindo embedding_metadata) no payload do pedido da API.

A obter embedding_metadata durante as consultas

Quando realiza uma pesquisa padrão de vizinhos mais próximos através da API findNeighbors, o campo embedding_metadata para 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}'

A atualizar embedding_metadata

Atualize os metadados através da API upsertDatapoints e de um update_mask com o valor embedding_metadata. O campo update_mask também pode incluir valores de máscara adicionais. Para utilizações de uma máscara de campo, consulte o artigo Atualize os metadados de incorporação.

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

O exemplo seguinte demonstra como definir e atualizar metadados para criar um IndexDatapoint segmentado, especificar update_mask e chamar 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"}'