Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
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']}],#---Newembedding_metadatafield---"embedding_metadata":{"title":"Ballet Train","runtime":{"hours":2,"minutes":6},"review_info":{"review":"This movie is fun and...","rotten_potatoes_rating":76}}#------------------------------------},#...otherdatapoints
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 formatosJSON 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 de 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.
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.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 UTC."],[],[],null,["# Vector Search embeddings with metadata\n\n| **Preview**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nThis guide provides information about optional metadata for vector embeddings.\nVector Search lets you define metadata for each embedding.\n\nMetadata is non-filterable, arbitrary information that Vector Search\ncan store for each embedding. This can provide embeddings with useful context\nsuch as:\n\n- Product details, such as name, price, and an image URL.\n\n- Descriptions, snippets, dates, and authorship for text embeddings.\n\n- User information for user embeddings.\n\n- Coordinates for place embeddings.\n\nKey features and benefits\n-------------------------\n\nFeatures and benefits of using metadata include:\n\n- **Context with results**: Information can be provided directly in\n your search results, which eliminates the need for separate lookups\n and reduces latency.\n\n- **Flexible structure** : Metadata is provided as a **JSON object**,\n which allows the metadata to be defined as complex, nested data.\n\n- **Non-Filterable** : Vector embedding metadata is for storing and retrieving\n non-filterable information that's distinct from `restricts` and\n `numeric_restricts`.\n\n- **Efficient updates** : The `update_mask` field lets you specify that APIs\n *only* update metadata to avoid resubmitting embedding vectors.\n\n- **Decoupled Information** : Non-filterable information can be separated from\n filterable attributes like `restricts`.\n\n- **Streamlined development**: Search responses include metadata associated\n with a vector embedding, while reducing the complexity needed for features\n such as displaying rich search results and performing context-based\n post-processing.\n\nData format\n-----------\n\nAn optional `embedding_metadata` field holds a JSON object that\nflexibly associates rich, non-filterable information with embeddings in\nVector Search. This can streamline applications by returning context\nwith results and allows efficient metadata-only updates using `update_mask`\nfor the `upsertDatapoints` API.\n| **Note:** Use `restricts` and `numeric_restricts` for filtering data.\n\nExample data point structure: \n\n {\n \"id\": \"movie_001\",\n \"embedding\": [0.1, 0.2, ..., 0.3],\n \"sparse_embedding\": {\n \"values\": [-0.4, 0.2, -1.3],\n \"dimensions\": [10, 20, 30]\n },\n \"numeric_restricts\": [{'namespace': 'year', 'value_int': 2022}],\n \"restricts\": [{'namespace': 'genre', 'allow': ['action', 'comedy']}],\n\n # --- New embedding_metadata field ---\n \"embedding_metadata\": {\n \"title\": \"Ballet Train\",\n \"runtime\": {\n \"hours\": 2,\n \"minutes\": 6\n },\n \"review_info\": {\n \"review\": \"This movie is fun and...\",\n \"rotten_potatoes_rating\": 76\n }\n }\n # ------------------------------------\n },\n # ... other data points\n\nIngesting data with `embedding_metadata`\n----------------------------------------\n\nWhen adding data points, you can include `embedding_metadata` when one of the\nfollowing actions occurs:\n\n- Uploading a file (Cloud Storage):\n - Use **JSON** or **AVRO** [formats](/vertex-ai/docs/vector-search/setup/format-structure). **CSV isn't supported** for `embedding_metadata`.\n- Using the `upsertDatapoints` API:\n - Pass data point objects (including `embedding_metadata`) in the API request payload.\n\n| **Note:** `embedding_metadata` has a size limit of 2 KB for each datapoint.\n\nRetrieving `embedding_metadata` during queries\n----------------------------------------------\n\nWhen performing a standard nearest-neighbor search using the\n`findNeighbors` API, the `embedding_metadata` field for each neighbor is\n**automatically included** in the response if `returnFullDatapoint`\nis set to `True`. \n\n### curl\n\n curl -X POST -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n \"https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors\" \\\n -d '{deployedIndexId:\"${DEPLOYED_INDEX_ID}\", \"queries\":[{datapoint:{\"featureVector\":\"\u003cFEATURE_VECTOR\u003e\"}}], returnFullDatapoint:true}'\n\nUpdating `embedding_metadata`\n-----------------------------\n\nUpdate metadata using the `upsertDatapoints` API and an `update_mask`\nusing the value `embedding_metadata`. The `update_mask` field might also\ninclude additional mask values. For uses of a field mask, see\n[Update embedding metadata](/vertex-ai/docs/vector-search/update-rebuild-index#upsert-metadata).\n\nThe `update_mask` field helps to ensure that only `embedding_metadata` is updated,\navoiding resubmission of restrict and embedding fields.\n| **Note:** This can also include existing `FieldMask` values, such as [all_restricts](/vertex-ai/docs/vector-search/update-rebuild-index#upsert-metadata), along with `embedding_metadata` in the request.\n\nThe following example demonstrates how to define and update metadata to create a\ntargeted `IndexDatapoint`, specifying `update_mask`, and calling\n`upsertDatapoints`. \n\n### curl\n\n 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 \\\n -d '{\n datapoints:[\n {\n datapoint_id: \"'${DATAPOINT_ID_1}'\",\n feature_vector: [...],\n embedding_metadata:{\"title\": \"updated title\", \"rating\": 4.5, \"tags\": [\"updated\", \"reviewed\"]\n }, update_mask: \"embedding_metadata\"}'"]]
