PutVectorIndex - Object Storage Service: Central de Documentação do Alibaba Cloud

Observações

Um único bucket de vetores pode conter no máximo 100 índices vetoriais.
O limite é de 5 requisições PutVectorIndex por segundo.

Permissões

Por padrão, as contas Alibaba Cloud têm todas as permissões, enquanto os usuários e as funções do Resource Access Management (RAM) não têm permissões. A conta Alibaba Cloud ou um administrador deve conceder permissões por meio de uma RAM policy ou de uma bucket policy.

API	Ação	Descrição
PutVectorIndex	`oss:PutVectorIndex`	Cria um índice vetorial.

Sintaxe da requisição

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

Cabeçalhos da requisição

Esta operação usa apenas cabeçalhos de requisição comuns. Para mais informações, consulte Common request headers.

Parâmetros da requisição

Nome	Tipo de dados	Obrigatório	Exemplo	Descrição
dataType	String	Sim	float32	O tipo de dados do vetor. Não é possível configurar este parâmetro. Valor padrão: float32.
dimension	Valor	Sim	512	As dimensões do vetor. Valores válidos: 1 a 4096. Valor padrão: 512.
distanceMetric	String	Sim	euclidean	A função de medida de distância. Valores válidos: euclidean: distância euclidiana (padrão) cosine: distância cosseno
indexName	String	Sim	vectorindex1	O nome personalizado do índice. O nome deve ser globalmente único no bucket de vetores e ter entre 1 e 63 caracteres. O nome pode conter apenas letras e dígitos e deve começar com uma letra.
metadata	Objeto	Não	-	O contêiner de configurações de metadados. Há suporte apenas a metadados não filtráveis.
nonFilterableMetadataKeys	Array de strings	Não	["field1", "field2"]	A configuração para metadados não filtráveis. Aplicam-se os seguintes limites: O número de chaves deve estar entre 1 e 100. O nome de cada chave primária de metadados deve ter entre 1 e 63 bytes. O nome pode conter letras maiúsculas, letras minúsculas, dígitos e sublinhados (_). Deve começar com uma letra maiúscula, uma letra minúscula ou um sublinhado (_). Nó pai: metadata

Cabeçalhos da resposta

Esta operação usa apenas cabeçalhos de resposta comuns. Para mais informações, consulte Common response headers.

Exemplos

Exemplo de requisição

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

Exemplo de resposta

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 API PutVectorIndex é compatível com os seguintes kits de desenvolvimento de software (SDKs):

Ferramenta de linha de comando ossutil

Para executar esta operação usando a ferramenta de linha de comando ossutil, consulte put-vector-index.

Códigos de erro

Código de erro	Código de status HTTP	Descrição
VectorIndexParameterInvalid	400	Os parâmetros do índice vetorial fornecidos na requisição são inválidos.
MalformedJson	400	O formato JSON no corpo da requisição é inválido.
VectorBucketIndexExceedLimit	400	O número de índices criados atingiu o limite máximo. É possível criar no máximo 100 índices vetoriais em um único bucket de vetores.
AccessDenied	403	Este erro ocorre pelos seguintes motivos: A requisição não inclui as informações de autenticação do usuário. Você não tem as permissões necessárias.
VectorBucketIndexAlreadyExist	409	O nome do índice especificado já existe. Não é possível criar um índice com o mesmo nome.