ListVectors - Object Storage Service - Centre de documentation Alibaba Cloud

Autorisations

Par défaut, un compte Alibaba Cloud dispose de toutes les autorisations nécessaires pour accéder à l'ensemble des ressources. Les utilisateurs RAM et les rôles RAM ne disposent d'aucune autorisation par défaut. Le propriétaire du compte Alibaba Cloud ou un administrateur doit leur accorder des autorisations en utilisant une politique RAM ou une politique de bucket.

API

Action

Description

ListVectors

oss:ListVectors

Répertorie les données vectorielles.

Syntaxe de la requête

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"
           }
       }]
    }
}

En-têtes de requête

Cette opération utilise uniquement des en-têtes de requête communs. Pour plus d'informations, consultez la section En-têtes HTTP communs.

Paramètres de requête

Paramètre	Type	Obligatoire	Exemple	Description
indexName	String	Oui	vectorindex1	Nom de l'index vectoriel.
maxResults	Integer	Non	500	Nombre maximal de résultats à renvoyer par requête. Valeur par défaut : 500. Valeur maximale : 1 000.
nextToken	String	Non	CAESCG15aC-xxxxx	Jeton de requête. Définissez ce paramètre sur la valeur de `nextToken` issue de la réponse précédente afin de récupérer la page de résultats suivante. Ne spécifiez pas ce paramètre lors de la première requête. La longueur du jeton peut varier de 1 à 2 048 octets.
returnData	Boolean	Non	false	Indique s'il faut renvoyer les données vectorielles. Valeurs possibles : true false (par défaut)
returnMetadata	Boolean	Non	false	Indique s'il faut renvoyer les métadonnées. Valeurs possibles : true false (par défaut)
segmentCount	Integer	Non	1	Spécifie le degré de parallélisme pour les opérations `ListVectors` parallèles. La valeur peut atteindre 16. Pour une exécution séquentielle, définissez ce paramètre sur 1.
segmentIndex	Integer	Non	0	Lors d'une opération `ListVectors` parallèle, la valeur de `segmentIndex` doit être inférieure à celle de `segmentCount`.
filter	Container	Non	N/A	Filtre les résultats de la requête en fonction des métadonnées. Les limites suivantes s'appliquent : La taille totale des métadonnées dans une expression de filtre ne peut pas dépasser 20 Ko. Le nombre d'éléments de métadonnées dans une expression de filtre ne peut pas dépasser 1 024. Les conditions de filtre peuvent être imbriquées jusqu'à 8 niveaux de profondeur. Le paramètre `filter` est pris en charge uniquement pour les index en mode Standard. Les index en mode Fusion ne prennent pas en charge le paramètre de requête `filter` par défaut.

Opérateurs de filtre

Opérateur

Type pris en charge

Description

$eq

String

Correspond à la valeur exacte. Lorsqu'il est utilisé avec des métadonnées de type tableau, cet opérateur renvoie true si la valeur d'entrée correspond à n'importe quel élément du tableau.

$ne

String

Différent de.

$gt

Number

Supérieur à.

$gte

Number

Supérieur ou égal à.

$lt

Number

Inférieur à.

$lte

Number

Inférieur ou égal à.

$in

Array of strings

Correspond à n'importe quelle valeur d'un tableau (similaire à l'opération SQL IN)

$nin

Array of strings

Ne correspond à aucune des valeurs du tableau (similaire à l'opération SQL NOT IN)

$exists

Boolean

Vérifie l'existence d'une clé de métadonnée.

$and

Array of filter objects

Effectue une opération logique AND sur un tableau contenant deux expressions de filtre ou plus.

$or

Array of filter objects

Effectue une opération logique OR sur un tableau contenant deux expressions de filtre ou plus.

$nor

Array of filter objects

Effectue une opération logique NOR sur un tableau contenant deux expressions de filtre ou plus.

En-têtes de réponse

Cette opération utilise uniquement des en-têtes de réponse communs. Pour plus d'informations, consultez la section En-têtes HTTP communs.

Éléments de réponse

Paramètre

Type

Exemple

Description

nextToken

String

CAESCG15aC2xxxxx

Jeton de requête pour la page de résultats suivante. Si cet élément est vide, tous les résultats ont été renvoyés.

vectors

Array of objects

N/A

Liste d'objets vectoriels.

key

String

doc-001

Clé primaire du vecteur.

Nœud parent : vectors

data

Object

N/A

Données vectorielles. Cet élément est renvoyé uniquement lorsque returnData est défini sur true.

Nœud parent : vectors

metadata

Object

N/A

Métadonnées du vecteur. Cet élément est renvoyé uniquement lorsque returnMetadata est défini sur true.

Nœud parent : vectors

Exemples

Mode Standard

Exemple de requête

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
}

Exemple de réponse

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"
         }
      }
   ]
}

Mode Fusion

Remarque

Pour un index en mode Fusion, data utilise les noms de champs vectoriels définis dans le schéma lors de la création de l'index, au lieu du nom de champ vectoriel fixe float32 utilisé en mode Standard, et peut renvoyer plusieurs champs vectoriels.

Exemple de requête

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
}

Exemple de réponse

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

L'opération ListVectors est disponible dans les SDK suivants :

CLI ossutil

Pour la commande ossutil correspondante, consultez la section list-vectors.

Codes d'erreur

Code d'erreur	Code d'état HTTP	Description
VectorIndexParameterInvalid	400	Le paramètre d'index vectoriel fourni dans la requête n'est pas valide.
MalformedJson	400	Le corps de la requête contient du JSON mal formé.
AccessDenied	403	Causes possibles : La requête ne contient pas d'informations d'authentification utilisateur. Vous ne disposez pas des autorisations requises pour l'opération.
NoSuchVectorIndex	404	L'index vectoriel spécifié n'existe pas.
QpsLimitExceeded	503	Le taux de requêtes a dépassé la limite QPS.