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

Use a operação QueryVectors para buscar vetores por similaridade.

Nota

A operação QueryVectors busca vetores por similaridade em índices do modo Standard. Para índices do modo Fusion, use a operação QueryVectorsFusion. Para compatibilidade com versões anteriores, se o esquema de um índice do modo Fusion definir apenas um único campo de vetor chamado float32, você também pode continuar usando a operação QueryVectors para fazer a busca.

Permissões

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

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

Sintaxe da requisição

A taxa de recall das chamadas de 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 requisição

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

Parâmetros da requisição

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

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 do array.
`$ne`	String, Number, Boolean	Corresponde a valores que não são iguais ao 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 se uma chave de metadados existe.
`$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 filtros

Veja a seguir exemplos comuns de expressões de filtro. Quando o operador é omitido, a operação 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}}

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 of objects	/	Uma lista dos resultados da busca vetorial.
key	String	doc-001	A chave primária do vetor. Nó pai: vectors
distance	float32	0,25	A distância de similaridade entre o vetor retornado e o vetor de consulta. Um valor menor indica uma similaridade maior. Este parâmetro é retornado apenas quando `returnDistance` está definido como `true`. Nó pai: vectors
metadata	Object	/	Os 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 requisição contém parâmetros inválidos para o índice de vetor.
MalformedJson	400	O formato JSON do corpo da requisição é inválido.
AccessDenied	403	Este erro pode ocorrer pelos seguintes motivos: A requisiçã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 requisições excedeu o limite de QPS. O sistema está limitando as suas requisições.