SearchKnowledgeオペレーションを呼び出してドキュメントを検索する - OpenSearch

ナレッジベースに基づいて、テキストベースの会話型検索を実行します。

前提条件

ID認証用のAPIキーを取得します。OpenSearch LLMベース会話型検索版のAPIオペレーションを呼び出すときは、認証を受ける必要があります。詳細については、APIキーの管理を参照してください。LLMは、大規模言語モデルの略です。
エンドポイントを取得します。OpenSearch LLMベース会話型検索版のAPIオペレーションを呼び出すときは、エンドポイントを指定する必要があります。詳細については、エンドポイントの取得を参照してください。

操作情報

リクエストメソッド

POST

リクエストプロトコル

HTTP

リクエストURL

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

{host}: APIオペレーションの呼び出しに使用するエンドポイント。インターネットまたは仮想プライベートクラウド（VPC）経由でAPIオペレーションを呼び出すことができます。エンドポイントの取得方法の詳細については、エンドポイントの取得を参照してください。
{app_group_identity}: アクセスするアプリケーション。アプリケーション名を指定して、サービス中のアプリケーションにアクセスできます。OpenSearch LLMベース会話型検索版コンソールにログインし、インスタンス一覧で対応するインスタンスのアプリケーション名を確認できます。

リクエストデータ形式

JSON

リクエストパラメータ

ヘッダーパラメータ

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

ボディパラメータ

パラメータ	タイプ	必須	説明	例
question	map	はい	入力の質問。	{ "text":"ユーザーの質問" "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
options.chat.model_generation	integer	いいえ	使用するカスタムモデルのバージョン。デフォルトでは、最も古いバージョンがアクセスに使用されます。	20
options.chat.prompt_template	string	いいえ	カスタムプロンプトテンプレートの名前。デフォルトでは、このパラメータは空のままです。この場合、組み込みのプロンプトテンプレートが使用されます。	user_defined_prompt_name
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。有効な値: normal polite patience	normal
options.chat.prompt_config.rule	string	いいえ	会話の詳細レベル。デフォルト値: detailed。有効な値: detailed stepbystep	detailed
options.chat.prompt_config.noanswer	string	いいえ	システムが質問に対する回答を見つけられなかった場合に返される情報。デフォルト値: sorry。有効な値: sorry: 申し訳ありませんが、既知の情報に基づいてあなたの質問に答えることができません。 uncertain: わかりません。	sorry
options.chat.prompt_config.language	string	いいえ	回答の言語。デフォルト値: Chinese。有効な値: Chinese English Thai Korean	Chinese
options.chat.prompt_config.role	boolean	いいえ	質問に答えるためのカスタムロールを有効にするかどうかを指定します。	false
options.chat.prompt_config.role_name	string	いいえ	カスタムロールの名前。例: AI assistant。	AIアシスタント
options.chat.prompt_config.out_format	string	いいえ	回答の形式。デフォルト値: text。有効な値: text table list markdown	text
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.agent	map	いいえ	Retrieval-Augmented Generation (RAG)ツール機能を有効にするかどうかを指定します。この機能が有効になっている場合、モデルは既存のコンテンツに基づいてRAGツールを使用するかどうかを決定します。この機能は、次のLLMでサポートされています。 qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.tools	stringのリスト	いいえ	使用するRAGツールの名前。次のツールが使用可能です。 knowledge_search: ナレッジベース検索	["knowledge_search"]
options.retrieve	map	いいえ	検索設定。
options.retrieve.doc	map	いいえ	ドキュメント検索の設定。
options.retrieve.doc.disable	boolean	いいえ	ドキュメント検索を無効にするかどうかを指定します。 false（デフォルト） true	false
options.retrieve.doc.filter	string	いいえ	ドキュメント検索中に、特定のフィールドに基づいてナレッジベース内のドキュメントをフィルタリングするために使用されるフィルタ。デフォルトでは、このパラメータは空のままです。詳細については、「拡張パラメータ」トピックの「filter」セクションを参照してください。サポートされているフィールド: 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より大きいドキュメントからデータを取得します。	category=\"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（デフォルト）: すべての用語に一致するドキュメントが取得されます。 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。有効な値: 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: 自社開発のrerankerモデル。	ops-bge-reranker-larger
options.retrieve.return_hits	boolean	いいえ	ドキュメント検索結果を返すかどうかを指定します。このパラメータをtrueに設定すると、レスポンスにsearch_hitsパラメータが返されます。	false

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

{
    "question" : {
        "text" : "ユーザーの質問",
        "session" : "会話のセッション。複数ラウンド会話機能を有効にするには、このパラメータを指定します。",
        "type" : "TEXT"
    },
    "options": {
        "chat": {
            "disable" : false, // LLMアクセスを無効にするかどうかを指定します。デフォルト値: false。
            "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。
            },
            "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" : "エラーメッセージ。このパラメータは、エラーが発生した場合にのみ返されます。"
    }
  ]
}