QueryVectors - Object Storage Service - Centro de documentación de Alibaba Cloud

Use la operación QueryVectors para ejecutar una búsqueda de similitud de vectores.

Nota

QueryVectors ejecuta una búsqueda de similitud de vectores en índices de modo Standard. Para los índices de modo Fusion, use la operación QueryVectorsFusion. Por compatibilidad con versiones anteriores, si el esquema de un índice de modo Fusion define únicamente un campo vectorial llamado float32, también puede seguir usando la operación QueryVectors para ejecutar la búsqueda.

Permisos

De forma predeterminada, una cuenta de Alibaba Cloud tiene permisos completos, mientras que un usuario o un rol de RAM no tiene ninguno. El propietario de la cuenta de Alibaba Cloud o un administrador debe otorgar permisos mediante un RAM policy o un bucket policy.

API	Acción	Descripción
QueryVectors	`oss:QueryVectors`	Consulta datos vectoriales.

Sintaxis de la solicitud

La tasa de recuperación de las llamadas a QueryVectors puede ser baja durante los primeros 30 segundos después de crear un índice vectorial. Los datos escritos mediante la operación PutVectors están disponibles para consulta en aproximadamente 2 o 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
}

Encabezados de solicitud

Esta operación usa únicamente los encabezados de solicitud comunes. Para obtener más información, consulte Common HTTP headers.

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
indexName	String	Sí	vectorindex1	El nombre del índice vectorial.
queryVector	Container	Sí	N/A	El vector de consulta. La dimensión debe coincidir con la del índice vectorial.
filter	Container	No	N/A	Filtra los datos con base en los metadatos. A continuación se describen los límites aplicables a los filtros de metadatos: El tamaño total de los metadatos en un solo filtro no puede superar los 20 KB. La cantidad de elementos de metadatos en un solo filtro no puede exceder 1,024. Las condiciones del filtro admiten hasta 8 niveles de anidamiento.
returnDistance	Boolean	No	false	Indica si se devuelve la distancia de similitud. Valores válidos: true false (valor predeterminado)
returnMetadata	Boolean	No	false	Indica si se devuelven los metadatos. Valores válidos: true false (valor predeterminado)
topK	Number	Sí	10	La cantidad de resultados más similares que se devuelven. El valor debe ser un número entero entre 1 y 500.

Operadores de filtro

Operador	Tipo	Descripción
`$eq`	String, Number, Boolean	Coincidencia exacta (para un solo valor). Cuando se aplica a metadatos de tipo arreglo, el operador devuelve `true` si el valor coincide con algún elemento del arreglo.
`$ne`	String, Number, Boolean	Coincide con los valores distintos al especificado.
`$gt`	Number	Mayor que.
`$gte`	Number	Mayor o igual que.
`$lt`	Number	Menor que.
`$lte`	Number	Menor o igual que.
`$in`	Arreglo no vacío de tipos primitivos	Coincide con cualquier valor de un arreglo (similar a la operación `IN` de SQL).
`$nin`	Arreglo no vacío de tipos primitivos	No coincide con ninguno de los valores del arreglo (similar a la operación `NOT IN` de SQL).
`$exists`	Boolean	Comprueba si existe una clave de metadatos.
`$and`	Arreglo no vacío de filtros	Aplica una operación lógica AND sobre un arreglo de condiciones de filtro.
`$or`	Arreglo no vacío de filtros	Aplica una operación lógica OR sobre un arreglo de condiciones de filtro.
`$nor`	Arreglo no vacío de filtros	Aplica una operación lógica NOR sobre un arreglo de condiciones de filtro.

Ejemplos de filtros

A continuación se muestran algunos ejemplos comunes de expresiones de filtro. Si se omite el operador, se usa $eq de forma predeterminada.

// 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}}

Encabezados de respuesta

Esta operación usa únicamente los encabezados de respuesta comunes. Para obtener más información, consulte Common HTTP headers.

Elementos de respuesta

Parámetro	Tipo	Ejemplo	Descripción
vectors	Arreglo de objetos	/	Una lista con los resultados de la búsqueda vectorial.
key	String	doc-001	La clave principal del vector. Nodo padre: vectors
distance	float32	0.25	La distancia de similitud entre el vector devuelto y el vector de consulta. Un valor menor indica mayor similitud. Este parámetro se devuelve únicamente cuando `returnDistance` se establece en `true`. Nodo padre: vectors
metadata	Object	/	Los metadatos completos del vector. Este parámetro se devuelve únicamente cuando `returnMetadata` se establece en `true`. Nodo padre: vectors

Ejemplos

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
}

Respuesta de ejemplo

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

La operación QueryVectors está disponible en los siguientes SDK:

ossutil CLI

Use el comando query-vectors de la herramienta de línea de comandos ossutil para ejecutar esta operación.

Códigos de error

Código de error	Código de estado HTTP	Descripción
VectorIndexParameterInvalid	400	La solicitud contiene parámetros de índice vectorial no válidos.
MalformedJson	400	El formato JSON del cuerpo de la solicitud no es válido.
AccessDenied	403	Entre las posibles causas de este error se incluyen las siguientes: La solicitud no incluye información de autenticación del usuario. No cuenta con los permisos obligatorios para la operación.
NoSuchVectorIndex	404	El índice vectorial especificado no existe.
QpsLimitExceeded	503	La tasa de solicitudes superó el límite de QPS. Las solicitudes se están limitando.