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

La API PutVectorIndex crea un índice vectorial en un bucket de vectores.

Notas

Un bucket de vectores puede contener hasta 100 índices vectoriales.
Se admiten hasta 5 solicitudes PutVectorIndex por segundo.

Permisos

De forma predeterminada, las cuentas de Alibaba Cloud tienen todos los permisos, mientras que los usuarios y roles de Resource Access Management (RAM) no tienen ninguno. La cuenta de Alibaba Cloud o un administrador debe otorgar permisos mediante una RAM policy o un bucket policy.

API	Acción	Descripción
PutVectorIndex	`oss:PutVectorIndex`	Crea un índice vectorial.

Sintaxis de la solicitud

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

{
   "dataType": "string",
   "dimension": int,
   "distanceMetric": "string",
   "indexName": "string",
   "metadata": { 
      "nonFilterableMetadataKeys": [string, string]
   }
}

Encabezados de la solicitud

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

Parámetros de la solicitud

Nombre	Tipo de datos	Obligatorio	Ejemplo	Descripción
dataType	String	Sí	float32	Tipo de datos vectoriales. Este parámetro no es configurable. Valor predeterminado: float32.
dimension	Valor	Sí	512	Dimensiones del vector. Valores válidos: de 1 a 4096. Valor predeterminado: 512.
distanceMetric	String	Sí	euclidean	Función de medición de distancia. Valores válidos: euclidean: Distancia euclidiana (predeterminado) cosine: Distancia coseno
indexName	String	Sí	vectorindex1	Nombre personalizado del índice. El nombre debe ser único en el bucket de vectores y tener entre 1 y 63 caracteres. El nombre solo puede contener letras y dígitos, y debe comenzar con una letra.
metadata	Object	No	-	Contenedor de configuraciones de metadatos. Solo se admiten metadatos no filtrables.
nonFilterableMetadataKeys	Array of strings	No	["field1", "field2"]	Configuración para metadatos no filtrables. Se aplican los siguientes límites: El número de claves debe estar entre 1 y 100. El nombre de cada clave principal de metadatos debe tener entre 1 y 63 bytes. Puede contener letras mayúsculas, minúsculas, dígitos y guiones bajos (_), y debe comenzar con una letra o un guion bajo (_). Nodo padre: metadata

Encabezados de la respuesta

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

Ejemplos

Solicitud de ejemplo

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

{
   "dataType": "float32",
   "dimension": 1024,
   "distanceMetric": "euclidean",
   "indexName": "vectorindex1",
   "metadata": { 
      "nonFilterableMetadataKeys": ["category", "timestamp"]
   }
}

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

SDK

La API PutVectorIndex es compatible con los siguientes kits de desarrollo de software (SDK):

Herramienta de línea de comandos ossutil

Para invocar esta operación mediante la herramienta de línea de comandos ossutil, consulte put-vector-index.

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.
MalformedJson	400	El formato JSON en el cuerpo de la solicitud no es válido.
VectorBucketIndexExceedLimit	400	Se alcanzó el límite de índices creados. Un bucket de vectores admite un máximo de 100 índices vectoriales.
AccessDenied	403	Este error se devuelve por las siguientes razones posibles: La solicitud no incluye información de autenticación del usuario. No cuenta con los permisos obligatorios.
VectorBucketIndexAlreadyExist	409	El nombre de índice especificado ya existe. No puede crear un índice con el mismo nombre.