PutVectors - Gravar dados vetoriais em índice do OSS - Object Storage Service: Central de Documentação do Alibaba Cloud

Notas de uso

Um único índice vetorial pode armazenar no máximo 2 bilhões de linhas de dados vetoriais.
Cada solicitação grava até 500 vetores. QPS máximo: 5.

Permissões

As contas do Alibaba Cloud têm permissões completas por padrão. Usuários e funções do RAM exigem autorização explícita por meio de uma política do RAM ou de uma política de bucket.

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

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 utiliza apenas cabeçalhos comuns de solicitação.

Parâmetros da solicitação

Nome	Tipo de dados	Obrigatório	Exemplo	Descrição
indexName	string	Sim	vectorindex1	O nome do índice.
vectors	container	Sim	-	O array de vetores. Contém de 1 a 500 elementos.
key	string	Sim	doc-001	O identificador exclusivo do vetor. Limites: Chaves existentes são sobrescritas. Chaves duplicadas no mesmo lote retornam um erro para todo o lote. Comprimento: de 1 a 1.024 caracteres. Codificação: UTF-8. Nó pai: vectors
data	container	Sim	-	O conteúdo do vetor. Limites: As dimensões devem corresponder à configuração do índice vetorial. Vetores nulos não são permitidos com a medida de distância cosseno. Os valores devem ser números de ponto flutuante válidos. NaN e Infinity não são permitidos. Nó pai: vectors
float32	array de números	Sim	[0.1, 0.2, 0.3]	Os dados vetoriais float32. As dimensões devem corresponder à definição do índice. Vetores nulos não são permitidos com distância cosseno. Nó pai: data
metadata	container	Não	-	Os metadados. Limites: Tamanho total: ≤ 40 KB Limites para metadados filtráveis: O comprimento deve estar no intervalo de 0 a 10. Tamanho da parte filtrável: ≤ 2 KB Tipos compatíveis: string ou array de strings Nó pai: vectors

Cabeçalhos de resposta

Esta operação utiliza apenas cabeçalhos comuns de resposta.

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

SDKs disponíveis:

Interface de linha de comando ossutil

O comando ossutil correspondente é put-vectors.

Códigos de erro

Código de erro	Código de status HTTP	Descrição
VectorIndexParameterInvalid	400	Parâmetros de índice vetorial inválidos ou a tabela de índice excede 50 milhões de linhas.
MalformedJson	400	JSON inválido no corpo da solicitação.
AccessDenied	403	Possíveis causas: A solicitação não contém informações de autenticação. As permissões necessárias estão ausentes.
NoSuchVectorIndex	404	O índice vetorial especificado não existe.
QpsLimitExceeded	503	Limite de QPS excedido. Com erros 5xx, o lote pode ser parcialmente gravado, pois a operação não é atômica.