SearchKnowledge を使用したテキストベースの質問応答 - OpenSearch

テキスト Q&A は、ナレッジベースからコンテンツを取得し、クエリに回答します。セッション ID を使用して、マルチターン会話のコンテキストを維持します。また、異なる大規模言語モデル (LLM) を選択して回答を生成し、レスポンスをカスタマイズすることも可能です。

前提条件

OpenSearch - LLM Intelligent Q&A Edition への呼び出しを認証するための API キーを取得してください。詳細については、「API キーの管理」をご参照ください。
OpenSearch - LLM Intelligent Q&A Edition を呼び出すためのサービスエンドポイントを取得してください。詳細については、「サービスエンドポイントの取得」をご参照ください。

重要

この API はサーバーサイドでの利用 を想定して設計されており、ブラウザ、ミニプログラム、モバイルアプリなどのフロントエンド環境から直接呼び出さないでください。理由は 2 つあります。第一に、この API は認証に Authorization: Bearer <API key> ヘッダーを使用します。API キーは長期的な認証情報であるため、フロントエンドコードに埋め込むと盗難される危険があります。第二に、この API はオリジン間リソース共有 (CORS) をサポートしていないため、ブラウザは直接呼び出しをブロックします。API キーはサーバー上に保存し、サーバーから呼び出し、その結果をフロントエンドに返す必要があります。

API

リクエストメソッド	プロトコル	リクエストフォーマット
POST	HTTP	JSON

リクエスト URL

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

{host}：サービスエンドポイントです。インターネットまたは仮想プライベートクラウド (VPC) 経由でアクセスできます。詳細については、「エンドポイントの取得」をご参照ください。
{app_group_identity}：アプリケーション名です。OpenSearch LLM-Based Conversational Search Edition コンソールにサインインし、[Instance Management] ページでこの名前を確認できます。

リクエストパラメータ

ヘッダーパラメーター

パラメーター	タイプ	必須	説明	例
Content-Type	文字列	はい	リクエストボディのメディアタイプを指定します。値は "application/json" である必要があります。	application/json
Authorization	文字列	はい	プレフィックス "Bearer " を付けた API キーです。	Bearer OS-d1**2a
accept	文字列	いいえ	サーバー送信イベント (SSE) を使用してストリーミングレスポンスを受信するには、値を "text/event-stream" に設定します。	text/event-stream

ボディパラメータ

パラメーター	型	必須	説明	値の例
question	マップ	はい	入力された質問です。	{ "text": "ユーザーの質問", "type": "TEXT", "session": "" }
question.text	文字列	はい	ユーザーの質問のテキスト内容です。	ユーザーの質問
question.session	文字列	いいえ	複数ターンの会話のコンテキストを識別するセッション ID です。有効な値は次のとおりです。このパラメーターが設定されていないか、空のままの場合、複数ターンの会話は無効になります。空でない値を指定すると、複数ターンの会話が有効になります。システムはコンテキストのために同じセッション ID を持つ会話を保持します。システムは会話履歴を最大 7 日間保持します。`history_max` パラメーターを使用して、保持する会話のターン数 (最大 20) を指定します。	1725530408586
question.type	文字列	いいえ	入力された質問のタイプです。これを `TEXT` に設定します。	TEXT
options	マップ	いいえ	検索、モデル選択、プロンプトなどの設定を制御するためのオプションです。
options.chat	マップ	いいえ	大規模言語モデル (LLM) にアクセスするためのパラメーターです。
options.chat.disable	ブール型	いいえ	LLM へのアクセスを無効にするかどうかを指定します。 `false`：LLM にアクセスして結果を要約・生成します。これがデフォルト値です。 `true`：LLM にアクセスしません。	false
options.chat.stream	ブール型	いいえ	ストリーミング応答を有効にするかどうかを指定します。 `true`：ストリーミング応答を有効にします。これがデフォルト値です。 `false`：ストリーミング応答を無効にします。	true
options.chat.model	文字列	いいえ	使用する大規模言語モデル (LLM) です。有効な値は次のとおりです。アジアパシフィック SE 1 (シンガポール) opensearch-llama2-13b opensearch-falcon-7b qwen-turbo qwen-plus qwen-max qwen2-72b-instruct	opensearch-llama2-13b
options.chat.enable_deep_search	ブール型	いいえ	ディープサーチを有効にするかどうかを指定します。 `true`：ディープサーチを有効にします。この機能はマルチターン推論を用いて最終応答のためのデータを統合するため、ターンあたりの所要時間とコンピューティングリソースが増加する可能性があります。 `false`：ディープサーチを無効にします。	false
options.chat.model_generation	整数	いいえ	カスタム製品モデルに使用するモデルバージョンを指定します。このパラメーターを指定しない場合、システムはデフォルトでは最も古いバージョンを使用します。	20
options.chat.prompt_template	文字列	いいえ	カスタムプロンプトテンプレートの名前です。このパラメーターが空の場合、システムはデフォルトでは組み込みのプロンプトテンプレートを使用します。	user_defined_prompt_name
options.chat.prompt_config	オブジェクト	いいえ	カスタムプロンプトを設定するためのキーと値のペアです。パラメーターは次の形式である必要があります： `{ "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	文字列	いいえ	応答のトーンを制御する、組み込みプロンプトテンプレートのパラメーターです。デフォルト値は `normal` です。 `normal`：ニュートラルなトーン。 `polite`：フレンドリーで丁寧なトーン。 `patience`：巧みで忍耐強いトーン。	normal
options.chat.prompt_config.rule	文字列	いいえ	応答の詳細レベルを制御します。デフォルト値は `detailed` です。 `detailed`：詳細かつプロフェッショナル。 `stepbystep`：詳細かつステップバイステップ。	detailed
options.chat.prompt_config.noanswer	文字列	いいえ	システムが質問に答えられない場合に返す応答です。デフォルト値は `sorry` です。 `sorry`："Sorry, I cannot answer this question based on the available information." `uncertain`："I don't know."	sorry
options.chat.prompt_config.language	文字列	いいえ	応答に使用する言語です。デフォルト値は `Chinese` です。 `Chinese`：中国語。 `English`：英語。 `Thai`：タイ語。 `Korean`：韓国語。	Chinese
options.chat.prompt_config.role	ブール型	いいえ	応答にカスタムペルソナを有効にするかどうかを指定します。これを `true` に設定すると、システムは `role_name` で定義されたペルソナに基づいて応答を生成します。	false
options.chat.prompt_config.role_name	文字列	いいえ	カスタムペルソナの名前です。例：AI アシスタント。	AI アシスタント
options.chat.prompt_config.out_format	文字列	いいえ	出力コンテンツの形式です。デフォルト値は `text` です。 `text`：テキスト。 `table`：テーブル。 `list`：リスト。 `markdown`：Markdown。	text
options.chat.generate_config.repetition_penalty	浮動小数点数	いいえ	生成されるトークンシーケンスにおける繰り返しのペナルティを制御します。値が大きいほど、繰り返しの可能性が低くなります。値が `1.0` の場合はペナルティがないことを意味します。厳密な値の範囲はありません。	1.01
options.chat.generate_config.top_k	整数	いいえ	サンプリングで考慮する、最も確率の高いトークンの数です。たとえば、値が `50` の場合、モデルはスコアが最も高い 50 個のトークンからのみサンプリングします。値が大きいほどランダム性が増し、値が小さいほど決定性が増します。デフォルト値は `0` で、top-k 戦略を無効にして、代わりに top-p 戦略を使用します。	50
options.chat.generate_config.top_p	浮動小数点数	いいえ	Nucleus サンプリングの累積確率のしきい値です。たとえば、値が `0.8` の場合、モデルは累積確率が 0.8 以上になる最小のトークンセットから選択します。有効な値の範囲は (0, 1.0) です。値が大きいほどランダム性が増し、値が小さいほど決定性が増します。	0.5
options.chat.generate_config.temperature	浮動小数点数	いいえ	生成されるテキストのランダム性と多様性を制御します。temperature が高いほど、候補トークンの確率分布が平坦化され、モデルがより可能性の低いトークンを選択できるようになり、出力の多様性が増します。値が低いほど分布が鋭くなり、モデルが確率の高いトークンを選択する可能性が高くなり、出力の決定性が増します。値の範囲：[0, 2)。このパラメーターを 0 に設定しないでください。 python バージョン >= 1.10.1 java バージョン >= 2.5.1	0.7
options.chat.history_max	整数	いいえ	複数ターンの会話の履歴で保持する最大ターン数です。最大値は 20 です。デフォルト値は 1 です。	20
options.chat.link	ブール型	いいえ	応答に引用元を含めるかどうかを指定します。有効な値は次のとおりです。 `true`：応答に引用元が含まれます。 `false`：応答に引用元は含まれません。これがデフォルト値です。以下は引用を含む応答の例です： ECS ディスクの容量は、オンラインまたはオフラインで拡張できます[^1^]。オンライン拡張ではインスタンスを再起動する必要はありませんが、オフライン拡張では再起動が必要です[^1^]。拡張を実行するには、ECS コンソールに移動し、ディスクを選択して、[操作] 列から [ディスクの拡張] を選択します。次に、必要に応じて拡張方法を選択します[^1^]。パーティションとファイルシステムを拡張する必要がある場合は、コンソールから行うことができます[^2^]。ディスク容量を拡張した後は縮小できないため、ストレージスペースを適切に計画してください[^3^]。 `[^` と `^]` で囲まれた数字は、API 応答の `reference` オブジェクト内のドキュメントに対応します。たとえば、`[^1^]` は `reference` オブジェクトの最初のドキュメントを参照します。	false
options.chat.rich_text_strategy	文字列	いいえ	リッチテキスト LLM からの出力に対する後処理戦略です。このパラメーターが空または指定されていない場合、リッチテキスト処理はデフォルトでは無効になります。 `inside_response`：リッチテキストタグを応答コンテンツ内に直接 Markdown 形式でレンダリングします。テーブルは Markdown 内に HTML として挿入されます。 `extend_response`：応答にリッチテキストタグが含まれている場合、各タグのコンテンツは rich_text_ref オブジェクトで個別に返されます。たとえば、画像コンテンツは URL として、テーブルコンテンツは HTML として、コードコンテンツはプレーンテキストとして返されます。	inside_response
options.chat.agent	マップ	いいえ	RAG エージェントのツール使用機能のオプションを指定します。有効にすると、モデルは利用可能なコンテンツに基づいてツールを実行するかどうかを決定します。現在この機能をサポートしている LLM は次のとおりです。 qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.think_process	ブール型	いいえ	エージェントの思考プロセスを返すかどうかを指定します。	true
options.chat.agent.max_think_round	整数	いいえ	エージェントの思考ラウンドの最大数です。値は 20 を超えることはできません。	10
options.chat.agent.language	文字列	いいえ	思考プロセスと最終回答の言語です。 `AUTO`：ユーザーのクエリに基づいて中国語と英語のどちらを使用するかを自動的に決定します。 `CN`：中国語。 `EN`：英語。	AUTO
options.chat.agent.tools	文字列のリスト	いいえ	エージェントが使用できる RAG ツールです。利用可能なツールは次のとおりです。 `knowledge_search`：ナレッジベースから取得を実行します。	["knowledge_search"]
options.retrieve	マップ	いいえ	取得プロセスを制御するパラメーターです。
options.retrieve.web_search.enable	ブール型	いいえ	Web 検索を有効にするかどうかを指定します。 `true`：Web 検索を有効にします。システムは Web 検索からのデータに基づいて応答を生成するため、時間とリソースの消費量が増加する可能性があります。 `false`：Web 検索を無効にします。これがデフォルト値です。	false
doc	マップ	いいえ	ドキュメント取得に関連するパラメーターです。
options.retrieve.doc.disable	ブール型	いいえ	ナレッジベースからの取得を無効にするかどうかを指定します。 `false`：取得を有効にします。これがデフォルト値です。 `true`：取得を無効にします。	false
options.retrieve.doc.filter	文字列	いいえ	ナレッジベースから取得するデータを選択するためのフィルター式です。指定しない場合、フィルターは適用されません。構文の例については、フィルターパラメーターをご参照ください。サポートされるフィールド： `table`：ドキュメントが格納されているテーブル。 `raw_pk`：ドキュメントのプライマリキー。 `category`：ドキュメントのカテゴリ。 `score`：ドキュメントのスコア。 `timestamp`：ドキュメントのタイムスタンプ。フォーマット例： "filter": "raw_pk=\"123\"" # ID 123 のドキュメントからのみデータを取得します。 "filter": "category=\"value1\"" # "value1" カテゴリのドキュメントからのみデータを取得します。 "filter": "category=\"value1\" OR category=\"value2\"" # "value1" と "value2" カテゴリのドキュメントからデータを取得します。 "filter": "score>1.0" # スコアが 1.0 より大きいドキュメントからのみデータを取得します。 "filter": "timestamp>1356969600" # タイムスタンプが 2013-01-01 より後のドキュメントからのみデータを取得します。	category=\"value1\"
options.retrieve.doc.sf	浮動小数点数	いいえ	ベクトル検索のスコアしきい値です。スパースベクトルが無効な場合：値の範囲は `[0, 2.0]` で、デフォルト値は `1.3` です。値が小さいほど関連性は高くなりますが、結果は少なくなります。値が大きいほど、関連性の低い結果が取得される可能性があります。スパースベクトルが有効な場合：デフォルト値は `0.35` です。値が大きいほど関連性は高くなりますが、結果は少なくなります。値が小さいほど、関連性の低い結果が取得される可能性があります。	0.35
options.retrieve.doc.top_n	整数	いいえ	取得するドキュメント数です。値は (0, 50] の範囲で指定する必要があります。デフォルト値は 5 です。	5
options.retrieve.doc.formula	文字列	いいえ	取得したドキュメントのカスタムランキング式です。説明構文の詳細については、ビジネス並べ替え関数をご参照ください。アルゴリズム関連性および地理的関連性機能はサポートされていません。	-timestamp：timestamp フィールドでドキュメントを降順にソートします。
options.retrieve.doc.rerank_size	整数	いいえ	再ランキング機能が有効な場合に再ランキングするドキュメント数です。値は (0, 100] の範囲で指定する必要があります。デフォルト値は 30 です。	30
options.retrieve.doc.operator	文字列	いいえ	ナレッジベース取得のために `question.text` をトークン化した結果の用語間の関係です。このパラメーターは、スパースベクトルを無効にした場合にのみ有効です。 `AND`：取得されるドキュメントには、すべての用語が含まれている必要があります。これがデフォルト値です。 `OR`：取得されるドキュメントには、少なくとも 1 つの用語が含まれている必要があります。	AND
options.retrieve.doc.dense_weight	浮動小数点数	いいえ	スパースベクトルが有効な場合、このパラメーターはドキュメント取得中の密ベクトルの重みを制御します。値は (0.0, 1.0) の範囲で指定する必要があります。デフォルト値は 0.7 です。	0.7
options.retrieve.entry	マップ	いいえ	手動介入データから結果を取得するためのパラメーターです。
options.retrieve.entry.disable	ブール型	いいえ	手動介入データからの取得を無効にするかどうかを指定します。 `false`：取得を有効にします。これがデフォルト値です。 `true`：取得を無効にします。	false
options.retrieve.entry.sf	浮動小数点数	いいえ	手動介入データを取得するためのベクトルスコアのしきい値です。値の範囲は `[0, 2.0]` で、デフォルト値は `0.3` です。値が小さいほど、取得される結果は少なくなりますが関連性は高くなります。一方、値が大きいほど、関連性の低い結果が取得される可能性があります。	0.3
options.retrieve.image	マップ	いいえ	ナレッジベースから画像取得結果を取得するためのパラメーターです。
options.retrieve.image.disable	ブール型	いいえ	画像取得を無効にするかどうかを指定します。デフォルト値は `false` です。 `false`：画像取得を有効にします。これがデフォルト値です。 `true`：画像取得を無効にします。	false
options.retrieve.image.sf	浮動小数点数	いいえ	画像ベクトル取得のスコアしきい値です。スパースベクトルが無効な場合：値の範囲は `[0, 2.0]` で、デフォルト値は `1.0` です。値が小さいほど関連性は高くなりますが、結果は少なくなります。値が大きいほど、関連性の低い結果が取得される可能性があります。スパースベクトルが有効な場合：デフォルト値は `0.5` です。値が大きいほど関連性は高くなりますが、結果は少なくなります。値が小さいほど、関連性の低い結果が取得される可能性があります。	1.0
options.retrieve.image.dense_weight	浮動小数点数	いいえ	スパースベクトルが有効な場合、このパラメーターは画像取得中の密ベクトルの重みを制御します。値は (0.0, 1.0) の範囲で指定する必要があります。デフォルト値は 0.7 です。	0.7
options.retrieve.qp	マップ	いいえ	クエリ書き換えのオプションです。
options.retrieve.qp.query_extend	ブール型	いいえ	ユーザーのクエリを拡張するかどうかを指定します。検索エンジンは拡張されたクエリを使用してドキュメントチャンクを取得します。 `false`：クエリを拡張しません。これがデフォルト値です。 `true`：クエリを拡張します。このオプションは LLM への追加の呼び出しを必要とするため、応答レイテンシが増加します。低レイテンシが求められるアプリケーションでは、このオプションを有効にしないでください。	false
options.retrieve.qp.query_extend_num	整数	いいえ	クエリ拡張が有効な場合、このパラメーターは生成する追加クエリの最大数を指定します。デフォルト値は 5 です。	5
options.retrieve.rerank	マップ	いいえ	取得したドキュメントの再ランキングのオプションです。
options.retrieve.rerank.enable	ブール型	いいえ	モデルを使用して検索結果を関連性に基づいて再ランキングするかどうかを指定します。有効な値は次のとおりです。 `true`：モデルを使用して結果を再ランキングします。 `false`：結果を再ランキングしません。 `options.retrieve.doc.formula` が指定されている場合、デフォルト値は `false` です。それ以外の場合は `true` です。	true
options.retrieve.rerank.model	文字列	いいえ	再ランキングに使用する大規模モデルの名前です。 `ops-bge-reranker-larger`：bge-reranker モデル。これがデフォルトです。 `ops-text-reranker-001`：独自の再ランキングモデル。	ops-bge-reranker-larger
options.retrieve.return_hits	ブール型	いいえ	ドキュメント取得の結果を返すかどうかを指定します。これは応答の `search_hits` オブジェクトに対応します。	false

リクエストボディ

{
  "question": {
    "text": "What is Alibaba Cloud OpenSearch?",
    "session": "session_001",
    "type": "TEXT"
  },
  "options": {
    "chat": {
      "disable": false,
      "stream": false,
      "model": "Qwen",
      "history_max": 20,
      "link": false,
      "agent": {
        "tools": ["knowledge_search"]
      }
    },
    "retrieve": {
      "doc": {
        "disable": false,
        "filter": "category=\"type\"",
        "sf": 0.35,
        "top_n": 5,
        "operator": "OR"
      },
      "web_search": { "enable": false },
      "entry": { "disable": false, "sf": 0.3 },
      "image": { "disable": false, "sf": 1.0 },
      "rerank": {
        "enable": true,
        "model": "ops-bge-reranker-larger"
      },
      "return_hits": false
    }
  }
}

主要なパラメーター：

question.session は、複数ターンにわたる会話のコンテキストを有効にします。
LLM をスキップして検索結果を返すには、options.chat.disable を true に設定します。
options.retrieve.doc.top_n は、取得したドキュメントの数を指定します。デフォルト値は 5 です。
options.retrieve.return_hits を true に設定すると、search_hits の詳細な内容が返されます。

応答パラメーター

パラメーター	タイプ	説明
request_id	文字列	一意のリクエスト ID です。サポートリクエストにはこの値を含めてください。
status	文字列	リクエストの処理ステータスです。 `OK`：リクエストは成功しました。 `FAIL`：リクエストは失敗しました。
latency	float	ミリ秒単位のレイテンシーです。リクエストが成功した場合にのみ返されます。
id	integer	プライマリキーです。
title	文字列	ドキュメントのタイトルです。
category	文字列	カテゴリ名です。
url	文字列	ドキュメントの URL です。
answer	文字列	生成された回答です。
type	文字列	結果のタイプです。
scores	配列	ドキュメントの関連性スコアです。
event	文字列	ストリーミングイベントのタイプです。思考ラウンドには、`THINK`、`ACTION`、`ANSWER` のイベントが含まれますが、`THINK` はオプションです。これらのイベントは、モデルの思考プロセス (`THINK`)、実行されたアクション (`ACTION`)、および現在のラウンドの結論 (`ANSWER`) を示します。`SUMMARY` は最終的なサマリーを提供し、1 回のみ返されます。
event_status	文字列	イベントが完了しているかどうかを示します。 `PROCESSING`：イベントは進行中です。 `FINISHED`：イベントは完了しました。
code	文字列	エラーコードです。エラーが発生した場合にのみ返されます。
message	文字列	エラーメッセージです。エラーが発生した場合にのみ返されます。

応答本文のサンプル

成功時の応答

{
  "request_id": "6859E98D-D885-4AEF-B61C-9683A0184744",
  "status": "OK",
  "latency": 6684.41,
  "result": {
    "data": [
      {
        "answer": "Alibaba Cloud OpenSearch is a managed service for searching structured data...",
        "type": "TEXT",
        "reference": [
          {"url": "https://www.alibabacloud.com/help/document_detail/463469.html", "title": "OpenSearch Product Introduction"}
        ]
      }
    ],
    "search_hits": [
      {
        "fields": {"content": "Content of OpenSearch-related documents...", "title": "OpenSearch Introduction"},
        "scores": ["0.9778"],
        "type": "DOC"
      }
    ]
  }
}

エラー応答

{
  "request_id": "e579a090bf99dc787d29d878b40c8367",
  "status": "FAIL",
  "errors": [
    {"code": 3005, "message": "topN[51] is not in (0, 50]"}
  ]
}