ナレッジベース内のドキュメントを検索するための SearchKnowledge 操作の呼び出し - OpenSearch

ナレッジベースに基づいてテキストベースの会話型検索を実行します。複数ラウンドの会話がサポートされています。複数ラウンドの会話のコンテキストを保持するためにセッション ID を指定できます。さらに、回答を生成するために必要な LLM を選択し、生成される回答をカスタマイズできます。

前提条件

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

操作情報

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

リクエスト URL

{host}/v3/openapi/apps/{app_group_identity}/actions/knowledge-search

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

リクエストパラメーター

ヘッダーパラメーター

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

ボディパラメーター

パラメーター	タイプ	必須	説明	例
question	map	はい	入力の質問。	{ 詳細については、「ユーザー」をご参照ください。質問」、 "type": "TEXT", "session" : "" }
question.text	string	はい	入力の質問のテキストコンテンツ。	ユーザーの質問
question.session	string	いいえ	複数ラウンドの会話のセッション ID。この ID は、複数ラウンドの会話のコンテキストを識別するために使用されます。このパラメーターを指定しない、または空のままにした場合、複数ラウンドの会話機能は無効になります。このパラメーターを null 以外の値に設定すると、複数ラウンドの会話機能が有効になります。この場合、システムは同じセッション ID を持つ会話を複数ラウンドの会話のコンテキストとして保持します。	1725530408586
question.type	string	いいえ	入力の質問の形式。例: `TEXT`。	TEXT
options	map	いいえ	取得、モデル、プロンプトの構成などの追加構成。
options.chat	map	いいえ	LLM アクセスの構成。
options.chat.disable	boolean	いいえ	LLM アクセスを無効にするかどうかを指定します。有効な値: false (デフォルト): LLM アクセスを有効にし、LLM を使用して結果を要約および生成します。 true: LLM アクセスを無効にします。	false
options.chat.stream	boolean	いいえ	HTTP チャンク転送エンコーディングを有効にするかどうかを指定します。有効な値: true (デフォルト) false	true
options.chat.model	string	いいえ	使用する LLM。有効な値: シンガポールリージョン opensearch-llama2-13b opensearch-falcon-7b qwen-turbo qwen-plus qwen-max qwen2-72b-instruct	opensearch-llama2-13b
options.chat.enable_deep_search	boolean	いいえ	ディープサーチ機能を有効にするかどうかを指定します。有効な値: true: ディープサーチ機能を有効にします。この場合、データを合成して結果を返すために複数ラウンドの推論が必要になります。 1 回の会話で比較的多くの時間と計算リソースが消費されます。 false: ディープサーチ機能を無効にします。	false
options.chat.model_generation	integer	いいえ	使用するカスタムモデルのバージョン。デフォルトでは、最も古いバージョンが使用されます。	20
options.chat.prompt_template	string	いいえ	カスタムプロンプトテンプレートの名前。デフォルトでは、このパラメーターは空のままです。この場合、組み込みのプロンプトテンプレートが使用されます。	注意: 一部のプラグインは、インストール後に追加の設定が必要な場合があります。
options.chat.prompt_config	object	いいえ	カスタムプロンプトテンプレートの構成。次の形式でキーと値のペアを指定します。 `{ "String_key": "value", "Integer_key" : 1 }`	`{ "attitude": "normal", // 態度 "rule" : "detailed", // ルール "noanswer": "sorry", // 回答なし "language": "Chinese", // 言語 "role": false, // ロール "role_name": "AI assistant", // ロールの名前 }`
options.chat.prompt_config.attitude	string	いいえ	会話のトーン。このパラメーターは、組み込みのプロンプトテンプレートに含まれています。有効な値: normal (デフォルト) polite patience	通常
options.chat.prompt_config.rule	string	いいえ	会話の詳細レベル。有効な値: detailed (デフォルト) stepbystep	詳細
options.chat.prompt_config.noanswer	string	いいえ	システムが質問に対する回答を見つけられなかった場合に返される情報。有効な値: sorry (デフォルト) uncertain	申し訳ございません
options.chat.prompt_config.language	string	いいえ	回答の言語。有効な値: Chinese (デフォルト) English Thai Korean	中国語
options.chat.prompt_config.role	boolean	いいえ	質問に答えるカスタムロールを有効にするかどうかを指定します。有効にした場合は、カスタムロールを指定する必要があります。	false
options.chat.prompt_config.role_name	string	いいえ	カスタムロールの名前。例: AI アシスタント。	AI アシスタント
options.chat.prompt_config.out_format	string	いいえ	回答の形式。有効な値: text (デフォルト) table list markdown	テキスト
options.chat.generate_config.repetition_penalty	float	いいえ	モデルによって生成されるコンテンツの繰り返しレベル。値が大きいほど、繰り返しが少なくなります。 1.0 の値はペナルティがないことを示します。このパラメーターには有効な値が指定されていません。	1.01
options.chat.generate_config.top_k	integer	いいえ	トークンがサンプリングされる候補セットのサイズ。たとえば、このパラメーターを 50 に設定すると、確率が最も高い上位 50 個のトークンが候補セットとして使用されます。値が大きいほど、生成されるコンテンツのランダム性が高くなります。逆に、値が小さいほど、生成されるコンテンツの決定性が高くなります。デフォルト値: 0。これは、top_k パラメーターが無効になっていることを示します。この場合、top_p パラメーターのみが有効になります。	50
options.chat.generate_config.top_p	float	いいえ	生成プロセス中に使用される核サンプリング法の確率しきい値。たとえば、このパラメーターを 0.8 に設定すると、累積確率が少なくとも 0.8 になる最も確率の高いトークンの最小サブセットのみが候補セットとして保持されます。有効な値: (0, 1.0)。値が大きいほど、生成されるコンテンツのランダム性が高くなります。逆に、値が小さいほど、生成されるコンテンツの決定性が高くなります。	0.5
options.chat.generate_config.temperature	float	いいえ	生成されるコンテンツのランダム性と多様性のレベル。具体的には、温度値は、テキスト生成中に各候補語の確率分布がどの程度平滑化されるかを決定します。温度値が大きいほど、確率分布のピークが減少するため、確率の低い単語が選択され、より多様なコンテンツが生成されます。逆に、温度値が小さいほど、確率分布のピークが増加するため、確率の高い単語が選択され、より決定性の高いコンテンツが生成されます。有効な値: [0, 2)。 0 に設定しても意味がないため、このパラメーターを 0 に設定しないことをお勧めします。 python バージョン >= 1.10.1 java バージョン >= 2.5.1	0.7
options.chat.history_max	integer	いいえ	システムが結果を返す会話の最大ラウンド数。最大値: 20。デフォルト値: 1。	20
options.chat.link	boolean	いいえ	参照元の URL を返すかどうかを指定します。具体的には、このパラメーターは、参照元がモデルによって生成されたコンテンツに含まれるかどうかを指定します。有効な値: true false (デフォルト) このパラメーターを true に設定した場合のサンプルレスポンス: Elastic Compute Service (ECS) インスタンスのディスクのサイズ変更は、オンラインまたはオフライン[^1^] で行うことができます。オンラインサイズ変更方式を使用する場合、インスタンスを再起動せずにディスクのサイズを変更できます。オフラインサイズ変更方式を使用する場合は、インスタンスを再起動する必要があります[^1^]。ディスクのサイズを変更するには、次の手順を実行します。 ECS コンソールにログインし、サイズ変更するディスクを見つけ、[操作] 列の [サイズ変更] をクリックし、ビジネス要件に基づいてサイズ変更方式を選択します[^1^]。パーティションとファイルシステムのサイズ変更が必要な場合は、CLI またはコンソール[^2^] を使用して関連情報を取得できます。 ECS ディスクのサイズ変更後、容量を削減することはできません。適切な容量計画を実施することをお勧めします[^3^]。 `[^`数値`^]` は、返された結果の参照にある取得済みドキュメントの序数を示します。たとえば、`[^1^]` は参照内の最初のドキュメントを示します。	false
options.chat.rich_text_strategy	string	いいえ	リッチテキストの処理方法。このパラメーターが存在しない、または空のままにした場合、リッチテキストは有効にならず、デフォルトの処理方法が使用されます。 inside_response: 回答内のリッチテキストタグは、Markdown 形式の元のテキストに直接復元されます。表は、HTML 形式で Markdown ファイルに直接挿入されることに注意してください。 extend_response: 回答内の各リッチテキストタグの実際のコンテンツは、rich_text_ref によって返されます。画像は URL として返され、表は HTML 形式で返され、コードはテキスト形式で返されます。	inside_response
options.chat.agent	map	いいえ	Retrieval-Augmented Generation (RAG) ツール機能を有効にするかどうかを指定します。この機能が有効になっている場合、モデルは既存のコンテンツに基づいて RAG ツールを使用するかどうかを決定します。この機能は、次の LLM でサポートされています。 qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.tools	string のリスト	いいえ	使用する RAG ツールの名前。次のツールを使用できます。 knowledge_search: ナレッジベースの取得	["ナレッジ検索"]
options.retrieve	map	いいえ	取得、モデル、プロンプトの構成などの追加構成。
options.retrieve.web_search.enable	boolean	いいえ	インターネット検索機能を有効にするかどうかを指定します。有効な値: true: インターネット検索機能を有効にします。この場合、インターネット全体のデータに基づいて結果が返されます。 1 回の会話で比較的多くの時間と計算リソースが消費されます。 false: インターネット検索機能を無効にします。	false
doc	map	いいえ	取得構成。
options.retrieve.doc.disable	boolean	いいえ	ドキュメントの取得を無効にするかどうかを指定します。有効な値: false (デフォルト) true	false
options.retrieve.doc.filter	string	いいえ	ドキュメントの取得中に、特定のフィールドに基づいてナレッジベース内のドキュメントをフィルタリングするために使用されるフィルター。デフォルトでは、このパラメーターは空のままです。詳細については、「フィルター」をご参照ください。次のフィールドがサポートされています。 table: 表。 raw_pk: ドキュメントのプライマリキー。 category: ドキュメントのカテゴリ。 score: ドキュメントのスコア。 timestamp: ドキュメントのタイムスタンプ。例: "filter" : "raw_pk=\"123\"" // プライマリキーが 123 のドキュメントからデータを取得します。 "filter" : "category=\"value1\"" // カテゴリが value1 のドキュメントからデータを取得します。 "filter" : "category=\"value1\" OR category=\"value2\"" // カテゴリが value1 または value2 のドキュメントからデータを取得します。 "filter" : "score>1.0" // スコアが 1.0 より大きいドキュメントからデータを取得します。 "filter" : "timestamp>1356969600" // タイムスタンプが 1356969600 より大きいドキュメントからデータを取得します。	カテゴリ="value1"
options.retrieve.doc.sf	float	いいえ	ドキュメントの取得におけるベクトル関連性を判断するためのしきい値。スパースベクトルモデルが無効になっている場合、パラメーター値の範囲は 0 ～ 2.0 で、デフォルト値は 1.3 です。値が小さいほど、ドキュメントの関連性は高くなりますが、取得されるドキュメントは少なくなります。逆に、関連性の低いドキュメントが取得される可能性があります。スパースベクトルモデルが有効になっている場合、デフォルト値は 0.35 です。値が大きいほど、ドキュメントの関連性は高くなりますが、取得されるドキュメントは少なくなります。逆に、関連性の低いドキュメントが取得される可能性があります。	1.3
options.retrieve.doc.top_n	integer	いいえ	取得するドキュメントの数。有効な値: (0, 50]。デフォルト値: 5。	5
options.retrieve.doc.formula	string	いいえ	取得したドキュメントをソートする式。説明構文については、「高度ソート関数」をご参照ください。アルゴリズムの関連性と地理的な場所の関連性はサポートされていません。	-timestamp: 取得したドキュメントをドキュメントのタイムスタンプの降順でソートします。
options.retrieve.doc.rerank_size	integer	いいえ	再ランク機能が有効になっている場合に再ランクするドキュメントの数。有効な値: (0, 100]。デフォルト値: 30。	30
options.retrieve.doc.operator	string	いいえ	ドキュメントの取得中にテキストセグメンテーション後に取得された用語間の演算子。このパラメーターは、スパースベクトルモデルが無効になっている場合にのみ有効になります。 AND (デフォルト): すべての用語に一致するドキュメントが取得されます。デフォルト値: AND。 OR: 少なくとも 1 つの用語に一致するドキュメントが取得されます。	AND
options.retrieve.doc.dense_weight	float	いいえ	スパースベクトルモデルが有効になっている場合の、ドキュメント取得中の密ベクトルの重み。有効な値: (0.0, 1.0)。デフォルト値: 0.7。	0.7
options.retrieve.entry	map	いいえ	介入データ取得の構成。
options.retrieve.entry.disable	boolean	いいえ	介入データ取得を無効にするかどうかを指定します。有効な値: false (デフォルト) true	false
options.retrieve.entry.sf	float	いいえ	介入データ取得におけるベクトル関連性を判断するためのしきい値。有効な値: [0, 2.0]。デフォルト値: 0.3。値が小さいほど、ドキュメントの関連性は高くなりますが、取得されるドキュメントは少なくなります。逆に、関連性の低いドキュメントが取得される可能性があります。	0.3
options.retrieve.image	map	いいえ	画像検索の構成。
options.retrieve.image.disable	boolean	いいえ	画像検索を無効にするかどうかを指定します。有効な値: false (デフォルト) true	false
options.retrieve.image.sf	float	いいえ	ドキュメントの取得におけるベクトル関連性を判断するためのしきい値。スパースベクトルモデルが無効になっている場合、パラメーター値の範囲は 0 ～ 2.0 で、デフォルト値は 1.0 です。値が小さいほど、ドキュメントの関連性は高くなりますが、取得されるドキュメントは少なくなります。逆に、関連性の低いドキュメントが取得される可能性があります。スパースベクトルモデルが有効になっている場合、デフォルト値は 0.5 です。値が大きいほど、ドキュメントの関連性は高くなりますが、取得されるドキュメントは少なくなります。逆に、関連性の低いドキュメントが取得される可能性があります。	1.0
options.retrieve.image.dense_weight	float	いいえ	スパースベクトルモデルが有効になっている場合の、画像取得中の密ベクトルの重み。有効な値: (0.0, 1.0)。デフォルト値: 0.7。	0.7
options.retrieve.qp	map	いいえ	クエリ書き換えの構成。
options.retrieve.qp.query_extend	boolean	いいえ	クエリを拡張するかどうかを指定します。拡張クエリは、OpenSearch 内のドキュメントセグメントを取得するために使用されます。有効な値: false (デフォルト): クエリを拡張しません。 true: クエリを拡張します。 LLM との追加のインタラクションが実行されます。これにより、システムの応答が遅くなります。応答速度が重要なアプリケーションの場合は、クエリを拡張しないでください。	false
options.retrieve.qp.query_extend_num	integer	いいえ	クエリ拡張機能が有効になっている場合に拡張されるクエリの最大数。デフォルト値: 5。	5
options.retrieve.rerank	map	いいえ	ドキュメント取得の再ランク構成。
options.retrieve.rerank.enable	boolean	いいえ	関連性に基づいて取得した結果をモデルを使用して再ランクするかどうかを指定します。有効な値: true false options.retrieve.doc.formula パラメーターが指定されている場合のデフォルト値: false。 options.retrieve.doc.formula パラメーターが空のままになっている場合のデフォルト値: true。	true
options.retrieve.rerank.model	string	いいえ	再ランク用の LLM の名前。有効な値: ops-bge-reranker-larger (デフォルト): bge-reranker モデル。 ops-text-reranker-001: 自社開発の再ランクモデル。	ops-bge-reranker-larger
options.retrieve.return_hits	boolean	いいえ	ドキュメントの取得結果を返すかどうかを指定します。このパラメーターを true に設定すると、レスポンスで search_hits パラメーターが返されます。	false

サンプルリクエストボディ

{
    "question" : {
        "text" : "ユーザーの質問",
        "session" : "会話のセッション。複数ラウンドの会話機能を有効にするには、このパラメーターを指定できます。",
        "type" : "TEXT"
    },
    "options": {
        "chat": {
            "disable" : false, // LLM アクセスを無効にし、ドキュメントの取得結果を直接返すかどうかを指定します。デフォルト値: false。これは、LLM アクセスが有効になっていることを示します。
            "stream" : false, // HTTP チャンク転送エンコーディングを有効にするかどうかを指定します。デフォルト値: false。
            "model" : "Qwen", // 使用する LLM。
            "prompt_template" : "user_defined_prompt_name", // カスタムプロンプトテンプレートの名前。
            "prompt_config" : { // オプション。カスタムプロンプトテンプレートの構成。
                "key" : "value" // キーと値のペアを指定します。
            },
            "generate_config" : {
                "repetition_penalty": 1.01,
                "top_k": 50,
                "top_p": 0.5,
                "temperature": 0.7
            },
            "history_max": 20, // システムが結果を返す会話の最大ラウンド数。
            "link": false, // 参照元の URL を返すかどうかを指定します。
            "agent":{
                "tools":["knowledge_search"]
            }
        },
        "retrieve": {
            "doc": {
                "disable": false, // ドキュメントの取得を無効にするかどうかを指定します。デフォルト値: false。
                "filter": "category=\"type\"", // ドキュメントの取得中に、カテゴリフィールドに基づいてドキュメントをフィルタリングするために使用されるフィルター。デフォルトでは、このパラメーターは空のままです。
                "sf": 1.3,    // ドキュメントの取得におけるベクトル関連性を判断するためのしきい値。デフォルト値: 1.3。値が大きいほど、取得されるドキュメントの関連性は低くなります。
                "top_n": 5,    // 取得するドキュメントの数。有効な値: (0, 50]。デフォルト値: 5。
                "formula" : "", // ドキュメント取得の式。デフォルトでは、ドキュメントはベクトル類似性に基づいて取得されます。
                "rerank_size" : 5, // 高度ソートするドキュメントの数。デフォルトでは、このパラメーターを指定する必要はありません。システムは、高度ソートするドキュメントの数を自動的に決定します。
                "operator": "OR" // テキストトークン間の演算子。デフォルト値: AND。
            },
            "web_search":{
                      "enable": false // インターネット検索機能を有効にするかどうかを指定します。デフォルト値: false。
            },
            "entry": {
                "disable": false, // 介入データ取得を無効にするかどうかを指定します。デフォルト値: false。
                "sf": 0.3 // 介入データ取得におけるベクトル関連性を判断するためのしきい値。デフォルト値: 0.3。
            },
            "image": {
                "disable": false,  // 画像検索を無効にするかどうかを指定します。デフォルト値: false。
                "sf": 1.0          // 画像検索におけるベクトル関連性を判断するためのしきい値。デフォルト値: 1.0。
            },
            "qp": {
                "query_extend": false, // クエリを拡張するかどうかを指定します。
                "query_extend_num": 5 // 拡張されるクエリの最大数。デフォルト値: 5。
            },
            "rerank" : {
                "enable": true, // LLM を使用して取得した結果を再ランクするかどうかを指定します。デフォルト値: true。
                "model":"model_name" // LLM の名前。
            },
            "return_hits": false   // ドキュメントの取得結果を返すかどうかを指定します。このパラメーターを true に設定すると、レスポンスで search_hits パラメーターが返されます。
        }
    }
}

レスポンスパラメーター

パラメーター	タイプ	説明
request_id	string	リクエスト ID。
status	string	リクエストが成功したかどうかを示します。有効な値: OK FAIL
latency	float	サーバーがリクエストの処理に費やした時間。単位: ミリ秒。
id	integer	プライマリキーの ID。
title	string	ドキュメントのタイトル。
category	string	カテゴリの名前。
url	string	ドキュメントの URL。
answer	string	返された結果。
type	string	返された結果の形式。
scores	array	ドキュメントの関連性に基づくスコア。
code	string	返されたエラーコード。
message	string	返されたエラーメッセージ。

サンプルレスポンスボディ

{
  "request_id": "6859E98D-D885-4AEF-B61C-9683A0184744",
  "status": "OK",
  "latency": 6684.410397,
  "result" : {
    "data" : [
      {
        "answer" : "回答テキスト",
        "type" : "TEXT",
        "reference" : [
          {"url" : "http://....","title":"ドキュメントタイトル"}
    		]
      },
      {
        "reference": [
          {"id": "16","title": "テストタイトル","category": "テストカテゴリ","url": "テスト URL"}
        ],
        "answer": "https://ecmb.bdimg.com/tam-ogel/-xxxx.jpg",
        "type": "IMAGE"
      }
    ],
    "search_hits" : [  // このパラメーターは、リクエストの options.retrieve.return_hits パラメーターが true に設定されている場合にのみ返されます。
      {
        "fields" : {
          "content" : "....",
          "key1" : "value1"
        },
        "scores" : ["10000.1234"],
        "type" : "doc"
      },
      {
        "fields"{
          "answer" : "...",
          "key1" : "value1"
        },
        "scores" : ["10000.1234"],
        "type" : "entry"
      }
    ]
  },
  "errors" : [
    {
      "code" : "エラーが発生した場合に返されるエラーコード。",
      "message" : "エラーが発生した場合に返されるエラーメッセージ。"
    }
  ]
}

前提条件

操作情報

リクエスト URL

リクエストパラメーター

ヘッダーパラメーター

ボディパラメーター

シンガポールリージョン

サンプルリクエストボディ

レスポンスパラメーター

サンプルレスポンスボディ