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

Llame a la operación PutVectors para escribir datos vectoriales en un índice.

Notas de uso

Un solo índice vectorial puede almacenar un máximo de 2 mil millones de filas de datos vectoriales.
La operación PutVectors tiene un límite de QPS de 1,000. Una sola solicitud puede escribir un lote de hasta 500 vectores. El número total de vectores en todas las solicitudes simultáneas está limitado a 2,500.

Permisos

Una cuenta de Alibaba Cloud tiene todos los permisos de forma predeterminada. Sin embargo, los usuarios y roles de Resource Access Management (RAM) no cuentan con permisos de forma predeterminada. El propietario de la cuenta de Alibaba Cloud o un administrador debe otorgar los permisos de operación mediante una RAM policy o un bucket policy.

API	Acción	Descripción
PutVectors	`oss:PutVectors`	Escribe datos vectoriales.

Sintaxis de la solicitud

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

Encabezados de solicitud

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

Parámetros de solicitud

Nombre	Tipo de dato	Obligatorio	Ejemplo	Descripción
indexName	String	Sí	vectorindex1	El nombre del índice.
vectors	Container	Sí	-	El arreglo de vectores que se va a escribir. La cantidad de elementos en el contenedor debe estar entre 1 y 500.
key	String	Sí	doc-001	La clave principal que identifica de forma única al vector. Restricciones: Si la clave ya existe, el vector se sobrescribe. Si hay claves duplicadas en el mismo lote, se devuelve un error para todas las entradas. La clave debe tener entre 1 y 1,024 caracteres de longitud. La clave debe estar en formato UTF-8. Nodo padre: vectors
data	Container	Sí	-	El contenido del vector. Restricciones: La cantidad de dimensiones del vector debe coincidir con las dimensiones configuradas para el índice vectorial. No se permiten vectores cero (vectores en los que todos los elementos son cero) cuando se usa la medida de distancia coseno. Los datos vectoriales deben contener únicamente números de punto flotante válidos. No se admiten valores como NaN (Not a Number) o Infinity. Nodo padre: vectors
float32	Array of numbers	Sí	[0.1, 0.2, 0.3]	Los datos vectoriales de tipo float32. La cantidad de dimensiones del vector debe coincidir con las definidas para el índice. No se permiten vectores cero cuando se utiliza la medida de distancia coseno. Nodo padre: data
metadata	Container	No	-	Los metadatos. Restricciones: El tamaño total no puede superar los 200 KB. Restricciones para los metadatos filtrables: Cantidad de pares clave-valor: de 0 a 100. Tamaño de la parte filtrable: ≤ 2 KB Tipos de datos compatibles: string, number, boolean y list. Nodo padre: vectors

Encabezados de respuesta

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

Ejemplos

Standard Mode

Ejemplo de solicitud

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

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

Fusion Mode

Nota

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

Ejemplo de solicitud

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

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

SDK

A continuación se muestran los SDK compatibles con la operación PutVectors:

Interfaz de línea de comandos ossutil

Para consultar información sobre el comando de ossutil correspondiente a la operación PutVectors, consulte put-vectors.

Códigos de error

Código de error	Código de estado HTTP	Descripción
VectorIndexParameterInvalid	400	Los parámetros del índice vectorial proporcionados en la solicitud no son válidos, o bien una sola tabla de índice vectorial almacena más de 50 millones de filas de datos vectoriales.
MalformedJson	400	El formato JSON del cuerpo de la solicitud no es válido.
AccessDenied	403	Posibles causas de este error: La solicitud no incluye la información de autenticación del usuario. No cuenta con los permisos obligatorios para ejecutar la operación.
NoSuchVectorIndex	404	El índice vectorial especificado no existe.
QpsLimitExceeded	503	La cantidad de consultas por segundo (QPS) supera el límite permitido. Si el código de estado HTTP es 5xx, es posible que solo se escriban correctamente algunos datos del mismo lote. La operación de escritura no garantiza atomicidad.