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

Notas de uso

Um único índice de vetor pode armazenar no máximo 2 bilhões de linhas de dados de vetor.
A operação PutVectors tem um limite de QPS de 1.000. Uma única solicitação pode gravar um lote de até 500 vetores, e o total de vetores em todas as solicitações simultâneas não pode exceder 2.500.

Permissões

Uma conta Alibaba Cloud possui todas as permissões por padrão. No entanto, usuários e funções do Resource Access Management (RAM) não têm permissões por padrão. O proprietário da conta Alibaba Cloud ou um administrador deve conceder permissões de operação usando uma política do RAM ou uma política de bucket.

API	Ação	Descrição
PutVectors	`oss:PutVectors`	Grava dados de vetor.

Sintaxe da solicitação

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

Cabeçalhos da solicitação

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

Parâmetros da solicitação

Nome	Tipo de dados	Obrigatório	Exemplo	Descrição
indexName	String	Sim	vectorindex1	O nome do índice.
vectors	Contêiner	Sim	-	O array de vetores para gravação. O contêiner deve conter entre 1 e 500 elementos.
key	String	Sim	doc-001	A chave primária que identifica o vetor de forma única. Restrições: Se uma chave já existir, o sistema sobrescreve o vetor. Se houver chaves duplicadas no mesmo lote, a operação retorna um erro para todas as entradas. A chave deve ter entre 1 e 1.024 caracteres. A chave deve estar no formato UTF-8. Nó pai: vectors
data	Contêiner	Sim	-	O conteúdo do vetor. Restrições: O número de dimensões do vetor deve corresponder ao número de dimensões configuradas para o índice de vetor. A métrica de distância cosseno não aceita vetores nulos (vetores com todos os elementos iguais a zero). Os dados do vetor devem conter apenas números de ponto flutuante válidos. Valores inválidos, como NaN (Not a Number) ou Infinity, são rejeitados. Nó pai: vectors
float32	Array de números	Sim	[0.1, 0.2, 0.3]	Dados do vetor do tipo float32. O número de dimensões do vetor deve corresponder ao número de dimensões definidas para o índice. A métrica de distância cosseno não aceita vetores nulos. Nó pai: data
metadata	Contêiner	Não	-	Os metadados. Restrições: O tamanho total não pode exceder 200 KB. Restrições para metadados filtráveis: Número de pares chave-valor: 0 a 100. Tamanho da parte filtrável: ≤ 2 KB Tipos de dados compatíveis: string, number, boolean e list. Nó pai: vectors

Cabeçalhos da resposta

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

Exemplos

Exemplo de solicitação

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

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

Os seguintes SDKs são compatíveis com a operação PutVectors:

Interface de linha de comando ossutil

Para mais informações sobre o comando ossutil para a operação PutVectors, consulte put-vectors.

Códigos de erro

Código de erro	Código de status HTTP	Descrição
VectorIndexParameterInvalid	400	Os parâmetros do índice de vetor fornecidos na solicitação são inválidos ou uma única tabela de índice de vetor armazena mais de 50 milhões de linhas de dados de vetor.
MalformedJson	400	O formato JSON no corpo da solicitação é inválido.
AccessDenied	403	Possíveis causas para este erro: A solicitação não inclui informações de autenticação do usuário. Você não tem as permissões necessárias para a operação.
NoSuchVectorIndex	404	O índice de vetor especificado não existe.
QpsLimitExceeded	503	O número de consultas por segundo (QPS) excede o limite. Se o código de status HTTP for 5xx, o sistema poderá gravar apenas parte dos dados no mesmo lote com sucesso. A operação de gravação não garante atomicidade.