PutVectors - Object Storage Service - Centre de documentation Alibaba Cloud

Remarques sur l'utilisation

Un index vectoriel peut stocker au maximum 2 milliards de lignes de données vectorielles.
L'opération PutVectors est limitée à 1 000 QPS (requêtes par seconde). Une requête unique peut écrire un lot contenant jusqu'à 500 vecteurs. Le nombre total de vecteurs traités par toutes les requêtes simultanées est limité à 2 500.

Autorisations

Par défaut, un compte Alibaba Cloud dispose de toutes les autorisations. En revanche, les utilisateurs RAM et les rôles RAM n'ont aucune autorisation. Le propriétaire du compte Alibaba Cloud ou un administrateur doit accorder les autorisations d'opération à l'aide d'une politique RAM ou d'une politique de bucket.

API

Action

Description

PutVectors

oss:PutVectors

Écrit des données vectorielles.

Syntaxe de la requête

POST /?putVectors 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",
   "vectors": [ 
      { 
         "data": {
            "float32":[float]
         },
         "key": "string",
         "metadata": {
             "key1": ["value1", "value2"],
             "key2": "value2"
         }
      }
   ]
}

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

Nom	Type de données	Obligatoire	Exemple	Description
indexName	String	Oui	vectorindex1	Nom de l'index.
vectors	Container	Oui	-	Tableau de vecteurs à écrire. Le conteneur doit contenir entre 1 et 500 éléments.
key	String	Oui	doc-001	Clé primaire identifiant le vecteur de manière unique. Contraintes : Si une clé existe déjà, le vecteur est écrasé. Si des clés en double existent dans le même lot, le système renvoie une erreur pour toutes les entrées. La longueur de la clé doit être comprise entre 1 et 1 024 caractères. La clé doit être encodée en UTF-8. Nœud parent : vectors
data	Container	Oui	-	Contenu du vecteur. Contraintes : Le nombre de dimensions du vecteur doit correspondre au nombre de dimensions configuré pour l'index vectoriel. Pour la mesure de distance cosinus, les vecteurs nuls (vecteurs dont tous les éléments sont égaux à zéro) ne sont pas autorisés. Les données vectorielles doivent contenir uniquement des nombres à virgule flottante valides. Les valeurs non valides, telles que NaN (Not a Number) ou Infinity, ne sont pas autorisées. Nœud parent : vectors
float32	Array of numbers	Oui	[0.1, 0,2, 0,3]	Données vectorielles de type float32. Le nombre de dimensions du vecteur doit correspondre au nombre de dimensions défini pour l'index. Les vecteurs nuls ne sont pas autorisés lors de l'utilisation de la mesure de distance cosinus. Nœud parent : data
metadata	Container	Non	-	Métadonnées. Contraintes : La taille totale ne peut pas dépasser 200 Ko. Contraintes pour les métadonnées filtrables : Nombre de paires clé-valeur : 0 à 100. Taille de la partie filtrable : ≤ 2 Ko Types de données pris en charge : string, number, boolean et list. Nœud parent : vectors

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.

Exemples

Standard Mode

Exemple de requête

POST /?putVectors 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",
   "vectors": [
      {
         "key": "doc-001",
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      {
         "key": "doc-002",
         "data": {
            "float32": [0.6, 0.7, 0.8, 0.9, 1.0]
         },
         "metadata": {
             "category": ["technology", "database"],
             "title": "Advanced Database Indexing"
         }
      }
   ]
}

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

Fusion Mode

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. Ce mode prend en charge l'écriture de plusieurs champs vectoriels.

Exemple de requête

POST /?putVectors 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",
   "vectors": [
      {
         "key": "doc-001",
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      {
         "key": "doc-002",
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5],
            "vector_field_name_2": [0.6, 0.7, 0.8, 0.9, 1.0]
         },
         "metadata": {
             "category": ["technology", "database"],
             "title": "Advanced Database Indexing"
         }
      }
   ]
}

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

SDK

Les SDK suivants prennent en charge l'opération PutVectors :

Interface de ligne de commande ossutil

Pour obtenir des informations sur la commande ossutil relative à l'opération PutVectors, consultez la section put-vectors.

Codes d'erreur

Code d'erreur	Code d'état HTTP	Description
VectorIndexParameterInvalid	400	Les paramètres de l'index vectoriel fournis dans la requête ne sont pas valides, ou une table d'index vectoriel unique stocke plus de 50 millions de lignes de données vectorielles.
MalformedJson	400	Le format JSON dans le corps de la requête n'est pas valide.
AccessDenied	403	Causes possibles de cette erreur : Les informations d'authentification de l'utilisateur ne sont pas incluses dans la requête. Vous ne disposez pas des autorisations requises pour l'opération.
NoSuchVectorIndex	404	L'index vectoriel spécifié n'existe pas.
QpsLimitExceeded	503	Le nombre de requêtes par seconde (QPS) dépasse la limite. Si le code d'état HTTP est 5xx, seule une partie des données du même lot peut être écrite avec succès. L'opération d'écriture ne garantit pas l'atomicité.