複数のドキュメントを一度にプッシュする - OpenSearch - Alibaba Cloud ドキュメントセンター

OpenSearch LLM ベースの対話型検索エディションでは、API を呼び出して複数のドキュメントを一度にプッシュできます。

前提条件

ID 認証用の API キーを取得済みであること。 OpenSearch LLM ベースの対話型検索エディションの API 操作を呼び出すときは、認証されている必要があります。詳細については、「API キーを管理する」をご参照ください。 LLM は大規模言語モデルの略です。
エンドポイントを取得済みであること。 OpenSearch LLM ベースの対話型検索エディションの API 操作を呼び出すときは、エンドポイントを指定する必要があります。詳細については、「エンドポイントを取得する」をご参照ください。

操作情報

リクエストメソッド	リクエストプロトコル	リクエストデータ形式
POST	HTTP	JSON

リクエスト URL

{host}/v3/openapi/apps/[app_group_identity]/actions/knowledge-bulk

{host}: API 操作の呼び出しに使用するエンドポイント。インターネットまたは VPC (仮想プライベートクラウド) 経由で API 操作を呼び出すことができます。エンドポイントの取得方法の詳細については、「エンドポイントを取得する」をご参照ください。
{app_group_identity}: アクセスするアプリケーションの名前。 OpenSearch LLM ベースの対話型検索エディションコンソールにログインし、[インスタンス管理] ページで対応するインスタンスのアプリケーション名を確認できます。

リクエストパラメーター

ヘッダーパラメーター

パラメーター	タイプ	必須	説明	例
Content-Type	文字列	はい	リクエストのデータ形式。 JSON 形式のみがサポートされています。値を application/json に設定します。	application/json
Authorization	文字列	はい	リクエスト認証に使用する API キー。値は Bearer で始まる必要があります。	Bearer OS-d1**2a

本文パラメーター

パラメーター	タイプ	必須	説明	例
cmd	文字列	はい	ドキュメントに対して実行される操作。	ADD/DELETE
fields	マップ	はい	フィールドのコレクション。
fields.id	文字列	はい	プライマリキーの ID。	13579
fields.title	文字列	いいえ	ドキュメントのタイトル。	Something interesting
fields.url	文字列	いいえ	ドキュメントの URL。	https://www.aliyun.com
fields.content	文字列	はい	ドキュメントの内容。	No, is not.

リクエスト本文の例

1. プライマリテーブルにドキュメントをアップロードする

['{
    "cmd": "ADD",
    "fields": {
      "id": "13579",
      "title": "Something interesting",
      "url": "https://www.aliyun.com",
      "content": "No, is not."
      }
}']

PDF、DOC、TXT、HTML などの非構造化ドキュメントをアップロードする

['{
    "cmd" : "URL/BASE64",
    "fields": {
      "id": "Optional. The document ID.",
      "type": "Optional. The file type such as PDF, DOC, TXT, or HTML.",
      "title": "Optional. The file name.",
      "content": "URL/Base64-encoded data.",
      "url": "Optional. The file URL."
    }
 }']

説明

url パラメーターは、OSS クライアントで generatePresignedUrl メソッドを呼び出すことによって Object Storage Service (OSS) オブジェクトに対して生成された URL のみサポートします。

2. カスタムテーブルにドキュメントをアップロードする

['{
    "cmd" : "ADD",
    "fields": {					// フィールド。カスタムテーブルのスキーマに基づいてフィールドを指定します。
      "key1": "value1",
      "key2": "value2",
      "key3": "value3"
    },
    "table_name": "The name of the custom table."	// テーブル名。このパラメーターを空のままにすると、操作はメインテーブルで実行されます。
  }']

3. テーブルを削除する

['{
    "cmd" : "DELETE",
    "fields": {
      "id": "13579333"
    }
}']

cmd: 必須。ドキュメントに対して実行される操作。有効な値: ADD および DELETE。一度に複数のドキュメントに対して操作を実行するリクエストを送信することをお勧めします。これにより、ネットワーク経由のインタラクション効率と処理効率が向上します。 ADD の値は、ドキュメントが作成されることを指定します。指定されたプライマリキー値を持つドキュメントが既に存在する場合、新しいドキュメントが作成される前に元のドキュメントが削除されます。 DELETE の値は、ドキュメントが削除されることを指定します。指定されたプライマリキー値を持つドキュメントが存在しない場合、操作は成功したと見なされます。
fields: 必須。ドキュメント内で操作が実行されるフィールド。プライマリキーフィールドを指定する必要があります。 OpenSearch は、プライマリキー値に基づいてドキュメントを識別します。ドキュメントを削除する場合、ドキュメントのプライマリキーフィールドのみを指定する必要があります。
上記のサンプルコードでは、最外層は一度に複数のドキュメントを管理するために使用される JSON 配列です。

レスポンスパラメーター

パラメーター	タイプ	説明
errors	リスト	エラーメッセージ。
status	文字列	リクエストの実行結果。有効な値: OK および FAIL。 OK の値は、リクエストが成功したことを示します。 FAIL の値は、リクエストが失敗したことを示します。この場合、エラーコードに基づいてエラーをトラブルシューティングします。
request_id	文字列	リクエスト ID。
result	ブール値	リクエストの結果。リクエストが成功した場合、true の値が返されます。リクエストが失敗した場合、このパラメーターは返されません。
total	整数	アップロードされたドキュメントの総数。
success	整数	正常にアップロードされたドキュメントの総数。
failure	整数	アップロードに失敗したドキュメントの総数。
failed_ids	配列	アップロードに失敗したドキュメントの ID。

レスポンス本文の例

{
  "request_id" : "abc123-ABC",
  "result" : {
    "total": 100,
    "success": 50,
    "failure": 50,
    "failed_ids": [
      "id1",
      "id2",
      "id3",
      "..."
    ]
  }
  "errors" : [
    {
      "code" : "エラーが発生した場合に返されるエラーコード。",
      "message" : "エラーが発生した場合に返されるエラーメッセージ。"
    }
  ]
}

注意事項

API を呼び出すか、OpenSearch SDK を使用してデータをプッシュする場合、アプリケーションのフィールド名は大文字と小文字を区別しません。
API を呼び出すか、OpenSearch SDK を使用してデータをプッシュできる回数とサイズには制限があります。アプリケーションごとに異なる制限が課せられます。詳細については、「制限」をご参照ください。
データのアップロード後、戻り値を確認してください。エラーコード、特に 3007 が返された場合は、エラーコードに基づいてエラーをトラブルシューティングし、再試行してください。そうしないと、データが失われる可能性があります。 OpenSearch はデータを非同期的に処理します。戻り値 OK は、OpenSearch がデータを受信したことを示します。これは、データが正しく処理されたことを示すものではありません。データ処理中にエラーが発生した場合、関連するエラーメッセージが OpenSearch コンソールに表示されます。できるだけ早くエラーメッセージを確認してください。
HTTP POST リクエストを送信するときにアップロードできるデータのサイズには制限があります。エンコード前のデータサイズが 2 MB を超えると、OpenSearch はリクエストを拒否し、エラーを返します。
データをプッシュするための HTTP POST リクエストの本文に中国語の文字が含まれている場合、本文を UTF-8 でエンコードする必要があります。さらに、Content-MD5 ヘッダーの値も、MD5 値を計算する前に UTF-8 でエンコードする必要があります。そうしないと、エラーが返され、リクエストは失敗します。
エラーコード 4016 が返された場合、API の呼び出しに使用している RAM ユーザーに必要な権限がありません。この場合は、[AliyunOpenSearchFullAccess] ポリシーを RAM ユーザーにアタッチする必要があります。詳細については、「RAM ユーザーに権限を付与する」をご参照ください。