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

Permissões

Por padrão, uma conta Alibaba Cloud tem permissões totais, enquanto um usuário RAM ou função RAM não tem nenhuma. O proprietário da conta Alibaba Cloud ou um administrador deve conceder as permissões por meio de uma RAM policy ou de uma bucket policy.

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

Sintaxe da solicitação

A taxa de recall das chamadas QueryVectors pode ser baixa por até 30 segundos após a criação de um índice de vetor. Os dados gravados pela operação PutVectors ficam disponíveis para consulta em aproximadamente 2 a 3 segundos.

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "string",
   "queryVector": {
       "float32":[float]
    },
   "returnDistance": boolean,
   "returnMetadata": boolean,
   "topK": int
}

Cabeçalhos da solicitação

Esta operação usa apenas cabeçalhos de solicitação comuns. Para mais informações, consulte Common HTTP headers.

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
indexName	String	Sim	vectorindex1	Nome do índice de vetor.
queryVector	Container	Sim	N/A	Vetor de consulta. A dimensão deve corresponder à do índice de vetor.
filter	Container	Não	N/A	Filtra dados com base em metadados. As seguintes restrições se aplicam aos filtros de metadados: O tamanho total dos metadados em um único filtro não pode exceder 20 KB. A quantidade de itens de metadados em um único filtro não pode ultrapassar 1.024. As condições de filtro permitem aninhamento de até 8 níveis.
returnDistance	Boolean	Não	false	Defina se a distância de similaridade deve ser retornada. Valores válidos: true false (padrão)
returnMetadata	Boolean	Não	false	Defina se os metadados devem ser retornados. Valores válidos: true false (padrão)
topK	Number	Sim	10	Número de resultados mais similares a retornar. O valor deve ser um inteiro entre 1 e 500.

Operadores de filtro

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

Exemplos de filtro

Veja a seguir exemplos comuns de expressões de filtro. Se o operador for omitido, $eq será usado 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}}

Cabeçalhos da resposta

Esta operação usa apenas cabeçalhos de resposta comuns. Para mais informações, consulte Common HTTP headers.

Elementos da resposta

Parâmetro	Tipo	Exemplo	Descrição
vectors	Array de objetos	/	Lista dos resultados da busca vetorial.
key	String	doc-001	Chave primária do vetor. Nó pai: vectors
distance	float32	0,25	Distância de similaridade entre o vetor retornado e o vetor de consulta. Um valor menor indica maior similaridade. Este parâmetro é retornado apenas quando `returnDistance` está definido como `true`. Nó pai: vectors
metadata	Object	/	Metadados completos do vetor. Este parâmetro é retornado apenas quando `returnMetadata` está definido como `true`. Nó pai: vectors

Exemplos

POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "filter": {
       "$and": [{
           "category": {
               "$in": ["technology", "science"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "vectorindex1",
   "queryVector": {
       "float32": [0.15, 0.25, 0.35, 0.45, 0.55]
    },
   "returnDistance": true,
   "returnMetadata": true,
   "topK": 5
}

Resposta de exemplo

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "vectors": [ 
      { 
         "distance": 0.12,
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search",
             "year": "2020"
         }
      },
      { 
         "distance": 0.25,
         "key": "doc-003",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations",
             "year": "2020"
         }
      }
   ]
}

SDK

A operação QueryVectors está disponível nos seguintes SDKs:

ossutil CLI

Use o comando query-vectors na ferramenta de linha de comando ossutil para executar esta operação.

Códigos de erro

Código de erro	Código de status HTTP	Descrição
VectorIndexParameterInvalid	400	A solicitação contém parâmetros de índice de vetor inválidos.
MalformedJson	400	O formato JSON do corpo da solicitação é inválido.
AccessDenied	403	Possíveis causas deste erro: A solicitação não inclui informações de autenticação do usuário. Você não tem as permissões necessárias para a operação.
NoSuchVectorIndex	404	O índice de vetor especificado não existe.
QpsLimitExceeded	503	A taxa de solicitações excedeu o limite de QPS. As solicitações estão sendo limitadas.