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

La operación ListVectors enumera todos los datos vectoriales de un índice vectorial.

Permisos

De forma predeterminada, una cuenta de Alibaba Cloud tiene permisos completos para acceder a todos los recursos. Los usuarios y roles de RAM no cuentan con ningún permiso de manera predeterminada. El propietario de la cuenta de Alibaba Cloud o un administrador debe otorgarles permisos mediante una RAM policy o una bucket policy.

API	Acción	Descripción
ListVectors	`oss:ListVectors`	Enumera los datos vectoriales.

Sintaxis de la solicitud

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

{
   "indexName": "string",
   "maxResults": int,
   "nextToken": "string",
   "returnData": boolean,
   "returnMetadata": boolean,
   "segmentCount": int,
   "segmentIndex": int,
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    }
}

Encabezados de solicitud

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

Parámetros de la solicitud

Parámetro	Tipo	Obligatorio	Ejemplo	Descripción
indexName	String	Sí	vectorindex1	El nombre del índice vectorial.
maxResults	Integer	No	500	El número máximo de resultados que se devuelven por solicitud. Valor predeterminado: 500. Valor máximo: 1,000.
nextToken	String	No	CAESCG15aC-xxxxx	El token de consulta. Establezca este parámetro con el valor de `nextToken` de la respuesta anterior para recuperar la siguiente página de resultados. No especifique este parámetro en la primera solicitud. La longitud del token puede ser de 1 a 2,048 bytes.
returnData	Boolean	No	false	Indica si se devuelven los datos vectoriales. Valores válidos: true false (predeterminado)
returnMetadata	Boolean	No	false	Indica si se devuelven los metadatos. Valores válidos: true false (predeterminado)
segmentCount	Integer	No	1	Especifica el grado de paralelismo para las operaciones `ListVectors` en paralelo. El valor puede llegar hasta 16. Para una ejecución en serie, establezca este parámetro en 1.
segmentIndex	Integer	No	0	Cuando se ejecuta una operación `ListVectors` en paralelo, el valor de `segmentIndex` debe ser menor que el valor de `segmentCount`.
filter	Container	No	N/A	Filtra los resultados de la consulta según los metadatos. Se aplican los siguientes límites: El tamaño total de los metadatos en una expresión de filtro no puede superar los 20 KB. La cantidad de elementos de metadatos en una expresión de filtro no puede exceder 1,024. Las condiciones de filtro admiten hasta 8 niveles de anidamiento. El parámetro `filter` solo es compatible con índices en modo Standard. Los índices en modo Fusion no admiten el parámetro de consulta `filter` de forma predeterminada.

Operadores de filtro

Operador	Tipo compatible	Descripción
`$eq`	String	Coincide con el valor exacto. Cuando se usa con metadatos de tipo arreglo, este operador devuelve `true` si el valor de entrada coincide con algún elemento del arreglo.
`$ne`	String	Distinto de.
`$gt`	Number	Mayor que.
`$gte`	Number	Mayor o igual que.
`$lt`	Number	Menor que.
`$lte`	Number	Menor o igual que.
`$in`	Array of strings	Coincide con cualquier valor de un arreglo (similar a la operación `IN` de SQL).
`$nin`	Array of strings	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`	Array of filter objects	Aplica una operación lógica AND sobre un arreglo de dos o más expresiones de filtro.
`$or`	Array of filter objects	Aplica una operación lógica OR sobre un arreglo de dos o más expresiones de filtro.
`$nor`	Array of filter objects	Aplica una operación lógica NOR sobre un arreglo de dos o más expresiones de filtro.

Encabezados de respuesta

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

Elementos de la respuesta

Parámetro	Tipo	Ejemplo	Descripción
nextToken	String	CAESCG15aC2xxxxx	El token de consulta para la siguiente página de resultados. Si este elemento está vacío, ya se devolvieron todos los resultados.
vectors	Array of objects	N/A	Una lista de objetos vectoriales.
key	String	doc-001	La clave principal del vector. Nodo padre: `vectors`
data	Object	N/A	Los datos del vector. Este elemento se devuelve solo cuando `returnData` se establece en `true`. Nodo padre: `vectors`
metadata	Object	N/A	Los metadatos del vector. Este elemento se devuelve solo cuando `returnMetadata` se establece en `true`. Nodo padre: `vectors`

Ejemplos

Modo Standard

Ejemplo de solicitud

POST /?listVectors 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

{
   "indexName": "vectorindex1",
   "maxResults": 10,
   "returnData": true,
   "returnMetadata": true
}

Ejemplo de respuesta

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

{
   "nextToken": "CAESCG15aC2xxxxx",
   "vectors": [ 
      { 
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      { 
         "data": {
            "float32": [0.2, 0.3, 0.4, 0.5, 0.6]
         },
         "key": "doc-002",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations"
         }
      }
   ]
}

Modo Fusion

Nota

En un índice de modo Fusion, data utiliza los nombres de campo vectorial definidos en el esquema al crear el índice, en lugar del nombre de campo vectorial fijo float32 que se usa en el modo Standard. Además, puede devolver varios campos vectoriales.

Ejemplo de solicitud

POST /?listVectors 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

{
   "indexName": "vectorindex1",
   "maxResults": 10,
   "returnData": true,
   "returnMetadata": true
}

Ejemplo de respuesta

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

{
   "nextToken": "CAESCG15aC2xxxxx",
   "vectors": [ 
      { 
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      { 
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5],
            "vector_field_name_2": [0.2, 0.3, 0.4, 0.5, 0.6]
         },
         "key": "doc-002",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations"
         }
      }
   ]
}

SDK

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

CLI de ossutil

Para conocer el comando correspondiente de ossutil, consulte list-vectors.

Códigos de error

Código de error	Código de estado HTTP	Descripción
VectorIndexParameterInvalid	400	El parámetro del índice vectorial proporcionado en la solicitud no es válido.
MalformedJson	400	El cuerpo de la solicitud contiene JSON con formato incorrecto.
AccessDenied	403	Posibles causas: La solicitud no incluye la 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.