PutVectors - Object Storage Service - Alibaba Cloud Dokümantasyon Merkezi

Kullanım notları

Tek bir vektör dizini en fazla 2 milyar satır vektör verisi depolayabilir.
PutVectors işlemi için saniyede 1.000 istek (QPS) sınırı vardır. Tek bir istekte en fazla 500 vektörden oluşan bir toplu iş yazılabilir ve tüm eşzamanlı isteklerdeki toplam vektör sayısı 2.500 ile sınırlıdır.

İzinler

Bir Alibaba Cloud hesabı varsayılan olarak tüm izinlere sahiptir. Ancak RAM kullanıcıları ve RAM rolleri varsayılan olarak herhangi bir izne sahip değildir. Alibaba Cloud hesap sahibi veya yönetici, bir RAM ilkesi veya paket ilkesi kullanarak işlem izinleri vermelidir.

API	Eylem	Açıklama
PutVectors	`oss:PutVectors`	Vektör verilerini yazar.

İstek sözdizimi

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

İstek üstbilgileri

Bu işlem yalnızca ortak istek üstbilgilerini kullanır. Daha fazla bilgi için bkz. Ortak HTTP üstbilgileri.

İstek parametreleri

Ad	Veri türü	Gerekli	Örnek	Açıklama
indexName	String	Evet	vectorindex1	Dizin adı.
vectors	Konteyner	Evet	-	Yazılacak vektör dizisi. Konteynerdeki öğe sayısı 1 ile 500 arasında olmalıdır.
key	String	Evet	doc-001	Vektörü benzersiz şekilde tanımlayan birincil anahtar. Kısıtlamalar: Bir anahtar zaten varsa vektör üzerine yazılır. Aynı toplu işte yinelenen anahtarlar bulunursa tüm girdiler için hata döndürülür. Anahtar uzunluğu 1 ile 1.024 karakter arasında olmalıdır. Anahtar UTF-8 biçiminde olmalıdır. Üst düğüm: vectors
data	Konteyner	Evet	-	Vektör içeriği. Kısıtlamalar: Vektör boyutu sayısı, vektör dizini için yapılandırılan boyut sayısıyla eşleşmelidir. Kosinüs uzaklık ölçüsü için sıfır vektörlere (tüm elemanları sıfır olan vektörler) izin verilmez. Vektör verileri yalnızca geçerli kayan noktalı sayılar içermelidir. NaN (Sayı Değil) veya Infinity gibi geçersiz değerlere izin verilmez. Üst düğüm: vectors
float32	Sayı dizisi	Evet	[0.1, 0.2, 0.3]	float32 türündeki vektör verileri. Vektör boyutu sayısı, dizin için tanımlanan boyut sayısıyla eşleşmelidir. Kosinüs uzaklık ölçüsü kullanıldığında sıfır vektörlere izin verilmez. Üst düğüm: data
metadata	Konteyner	Hayır	-	Meta veriler. Kısıtlamalar: Toplam boyut 200 KB'yi aşamaz. Filtrelenebilir meta veriler için kısıtlamalar: Anahtar-değer çifti sayısı: 0 ile 100 arasında. Filtrelenebilir kısmın boyutu: ≤ 2 KB Desteklenen veri türleri: string, number, boolean ve list. Üst düğüm: vectors

Yanıt üstbilgileri

Bu işlem yalnızca ortak yanıt üstbilgilerini kullanır. Daha fazla bilgi için bkz. Ortak HTTP üstbilgileri.

Örnekler

Standard Mode

İstek örneği

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

Yanıt örneği

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

Not

Fusion modu dizini için data alanı, Standard modunda kullanılan sabit float32 vektör alanı adı yerine, dizin oluşturulurken şemada tanımlanan vektör alanı adlarını kullanır ve birden çok vektör alanının yazılmasını destekler.

İstek örneği

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

Yanıt örneği

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şağıdaki SDK'lar PutVectors işlemini destekler:

ossutil komut satırı arayüzü

PutVectors işlemi için ossutil komutu hakkında bilgi almak için bkz. put-vectors.

Hata kodları

Hata kodu	HTTP durum kodu	Açıklama
VectorIndexParameterInvalid	400	İstekte sağlanan vektör dizini parametreleri geçersiz veya tek bir vektör dizin tablosu 50 milyondan fazla satır vektör verisi depoluyor.
MalformedJson	400	İstek gövdesindeki JSON biçimi geçersiz.
AccessDenied	403	Bu hatanın olası nedenleri: İsteğe kullanıcı kimlik doğrulama bilgileri dahil edilmemiş. İşlem için gerekli izinlere sahip değilsiniz.
NoSuchVectorIndex	404	Belirtilen vektör dizini mevcut değil.
QpsLimitExceeded	503	Saniye başına sorgu sayısı (QPS) sınırı aşıldı. HTTP durum kodu 5xx ise aynı toplu işteki verilerin yalnızca bir kısmı başarıyla yazılmış olabilir. Yazma işlemi atomikliği garanti etmez.