query-vectors - Object Storage Service: Central de Documentação do Alibaba Cloud

Permissões

Por padrão, uma conta Alibaba Cloud possui permissões completas. Já os usuários RAM e as funções RAM não possuem permissões, portanto, o proprietário ou administrador da conta deve conceder acesso a eles por meio de uma RAM policy ou de uma bucket policy.

API	Ação	Descrição
QueryVectors	`oss:QueryVectors`	Consulta dados vetoriais.

Formato do comando

ossutil vectors-api query-vectors --bucket value --index-name value --query-vector value --top-k value  [flags]

Parâmetros

Parâmetro	Tipo	Descrição
--bucket	string	O nome do bucket de vetores.
--index-name	string	O nome do índice de vetores.
--query-vector	string	O vetor de consulta no formato JSON. A dimensão do vetor de consulta deve ser igual à dimensão do índice de vetores.
--top-k	int	O número de vetores mais semelhantes a serem retornados. Valores válidos: 1 a 500.
--filter	string	Filtra os dados da consulta com metadados. Tamanho máximo de um único filtro: 20 KB Número máximo de instruções de filtro: 1.024
--return-distance	/	O comando retorna a distância de similaridade se este parâmetro estiver vazio ou caso o defina como `true`.
--return-metadata	/	O comando retorna os metadados se este parâmetro estiver vazio ou caso o defina como `true`.

Nota

O comando query-vectors corresponde à operação da API QueryVectors.
Para obter mais informações sobre as opções globais de linha de comando disponíveis, consulte Global command-line options.

Operadores de filtro

Operador	Tipo	Descrição
`$eq`	String, Number, Boolean	Correspondência exata (para um único valor). Quando usado em metadados do tipo array, o operador retorna `true` se o valor corresponder a qualquer elemento no array.
`$ne`	String, Number, Boolean	Corresponde a valores diferentes do valor especificado.
`$gt`	Number	Maior que.
`$gte`	Number	Maior ou igual a.
`$lt`	Number	Menor que.
`$lte`	Number	Menor ou igual a.
`$in`	Non-empty array of primitives	Corresponde a qualquer valor em um array (semelhante à operação `IN` do SQL).
`$nin`	Non-empty array of primitives	Não corresponde a nenhum dos valores no array (semelhante à operação `NOT IN` do SQL).
`$exists`	Boolean	Verifica a existência de uma chave de metadados.
`$and`	Non-empty array of filters	Executa uma operação lógica AND em um array de condições de filtro.
`$or`	Non-empty array of filters	Executa uma operação lógica OR em um array de condições de filtro.
`$nor`	Non-empty array of filters	Executa uma operação lógica NOR em um array de condições de filtro.

Exemplos de filtro

Confira a seguir exemplos comuns de expressões de filtro. Se o operador for omitido, o sistema usa $eq por padrão.

// Simple equality (uses $eq by default when the operator is omitted)
{"category": "finance"}

// Explicit equality / inequality
{"category": {"$eq": "finance"}}
{"category": {"$ne": "archived"}}

// Numeric comparison
{"created_year": {"$gt": 2023}}
{"created_year": {"$gte": 2024}}
{"created_year": {"$lt": 2026}}
{"created_year": {"$lte": 2025}}

// Array matching
{"language": {"$in": ["zh", "en"]}}
{"language": {"$nin": ["ja", "ko"]}}

// Existence check
{"author": {"$exists": true}}

// Logical combination
{"$and": [{"category": {"$eq": "finance"}}, {"created_year": {"$gte": 2024}}]}
{"$or": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}
{"$nor": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}

// Multiple conditions on the same field (range)
{"score": {"$gte": 0.6, "$lte": 0.95}}

Exemplo

O comando a seguir localiza os 10 vetores mais semelhantes a um vetor de consulta no índice de vetores 'index' do bucket de vetores 'examplebucket', filtrando aqueles cujo 'type' seja 'comedy' ou 'documentary'.

ossutil vectors-api query-vectors --bucket examplebucket --index-name index --filter "{\"$and\":[{\"type\":{\"$in\":[\"comedy\",\"documentary\"]}}]}" --query-vector "{\"float32\":[32]}" --top-k 10