PutVectors を使用したベクトルインデックスへのベクトルデータの書き込み - OSS - Alibaba Cloud - Object Storage Service

注意事項

1 つのベクトルインデックスには、最大 20 億行のベクトルデータを格納できます。
PutVectors API の 1 秒あたりのクエリ数 (QPS) は 1,000 に制限されています。1 回のリクエストで最大 500 個のベクトルをバッチで書き込むことができ、同時リクエスト全体の合計ベクトル数は 2,500 に制限されています。

権限

Alibaba Cloud アカウントには、デフォルトですべての権限があります。ただし、RAM ユーザーと RAM ロールには、デフォルトでは権限がありません。Alibaba Cloud アカウントの所有者または管理者は、RAM ポリシーまたはバケットポリシーを使用して、操作権限を付与する必要があります。

API	アクション	説明
PutVectors	`oss:PutVectors`	ベクトルデータを書き込みます。

リクエストの構文

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

リクエストヘッダー

この API は、共通リクエストヘッダーのみを使用します。詳細については、「共通 HTTP ヘッダー」をご参照ください。

リクエストパラメータ

名前	データ型	必須	例	説明
indexName	String	はい	vectorindex1	インデックスの名前。
vectors	コンテナ	はい	-	書き込むベクトルの配列。コンテナ内の要素数は 1 から 500 の範囲内である必要があります。
key	String	はい	doc-001	ベクトルを一意に識別するプライマリキー。制約：キーが既に存在する場合、ベクトルは上書きされます。同一バッチ内に重複するキーが存在する場合、そのバッチ内のすべてのエントリがエラーになります。キーの長さは 1 文字以上 1,024 文字以下である必要があります。キーは UTF-8 形式である必要があります。親ノード: vectors
data	コンテナ	はい	-	ベクトルの内容。制約：ベクトル次元の数は、ベクトルインデックスに設定された次元数と一致する必要があります。コサイン距離を使用する場合、ゼロベクトル (すべての要素がゼロのベクトル) は許可されません。ベクトルデータには、有効な浮動小数点数のみを含める必要があります。非数 (NaN) や無限大などの無効な値は許可されません。親ノード: vectors
float32	数値の配列	はい	[0.1, 0.2, 0.3]	float32 型のベクトルデータ。ベクトル次元の数は、インデックスに定義された次元数と一致する必要があります。コサイン距離を使用する場合、ゼロベクトルは許可されません。親ノード: data
metadata	コンテナ	いいえ	-	メタデータ。制約：合計サイズは 200 KB を超えることはできません。フィルタリング可能なメタデータの制約：キーと値のペアの数：0 から 100。フィルタリング可能な部分のサイズ：≤ 2 KB サポートされるデータ型：文字列、数値、ブール値、リスト。親ノード: vectors

レスポンスヘッダー

この API は、共通レスポンスヘッダーのみを使用します。詳細については、「共通 HTTP ヘッダー」をご参照ください。

例

リクエストの例

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

レスポンスの例

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

次の SDK は、PutVectors API に対応しています:

ossutil コマンドラインインターフェイス

PutVectors API 用の ossutil コマンドについては、「put-vectors」をご参照ください。

エラーコード

エラーコード	HTTP ステータスコード	説明
VectorIndexParameterInvalid	400	リクエストで指定されたベクトルインデックスパラメータが無効であるか、1 つのベクトルインデックステーブルに 20 億行を超えるベクトルデータが格納されています。
MalformedJson	400	リクエスト本文の JSON 形式が無効です。
AccessDenied	403	このエラーの考えられる原因：リクエストにユーザー認証情報が含まれていません。この操作に必要な権限がありません。
NoSuchVectorIndex	404	指定されたベクトルインデックスは存在しません。
QpsLimitExceeded	503	1 秒あたりのクエリ数 (QPS) が制限を超えています。HTTP ステータスコードが 5xx の場合、同一バッチ内の一部のデータのみが正常に書き込まれる可能性があります。書き込み操作は原子性を保証しません。