Skip to main content
POST

Authorizations

​
Authorization
string
header
required

クエリトークンを作成 が返すクエリトークンで、Authorization: Bearer {token} として送信します。返された expires_at の時刻（発行から最大 60 秒後）より前に使用してください。このトークンで認可されるのは、そのナレッジベースに対する「クエリを実行」だけです。

同じリクエストで、「クエリトークンを作成」が返した trace_id を X-Trace-ID として送信してください。

Headers

​
X-Trace-ID
string
required

クエリトークンを作成 のレスポンスに含まれる trace_id です。トークンの trace_id クレームと同じ値です。トークンと一致しない値は 403 で拒否されます。ナレッジベースへのクエリ を参照してください。

Body

application/json

クエリトークンを作成 の request オブジェクトを変更せずに送信してください。不明なフィールドが含まれていると 400 が返ります。

nullable と記されたオプションフィールドでは、null は省略と同じ扱いになります。

正規化後のリクエストは、UTF-8 で 65,536 バイト以内に収める必要があります。超えると 413 が返ります。リクエストサイズの制限 を参照してください。

空白のみではない query を指定してください。

​
knowledgeSpaceId
string<uuid>
required

ナレッジベースの内部 ID です。クエリトークンを作成 の request オブジェクトからコピーします。トークンと一致している必要があり、一致しない場合は 403 で拒否されます。

Minimum string length: 1
​
query
string
required

質問です。空白のみではないクエリを指定してください。また、UTF-8 で 16,384 バイトまでに制限されます。

Maximum string length: 16000
Pattern: \S
​
activeDocumentIds
string<uuid>[]

返された request オブジェクトからコピーした値です。これらの ID は、検索されたコンテンツの絞り込みにも順位付けにも使われません。

Maximum array length: 100
​
activeEntityIds
string[]

返された request オブジェクトからコピーした値です。これらの ID は、検索されたコンテンツの絞り込みにも順位付けにも使われません。

Maximum array length: 100
Required string length: 1 - 200
​
mode
enum<string> | null

検索の深度です。クエリトークンを作成 の request オブジェクトからコピーします。null も指定でき、その場合はナレッジベースのデフォルトの深度を意味します。

Available options:
fast,
deep,
research,
null
​
sessionId
string<uuid> | null

セッション ID です。クエリトークンを作成 の request オブジェクトからコピーします。

Response

ストリームが開きました。リクエストの Accept にかかわらず、イベントは text/event-stream として続きます。ストリームが開く前の失敗は、HTTP エラーとして処理してください。開いた後は、HTTP ステータスが 200 であっても answer.error イベントを失敗として処理してください。

各フレームには、イベント名を示す event: 行と、JSON オブジェクトを 1 つ含む data: 行があります。イベントの振り分けには event: 行を使ってください。JSON には event フィールドが含まれません。

クライアントの読み取りタイムアウトは、使用する検索モードのうち最も遅いものに合わせて設定してください。API 側には読み取りタイムアウトがなく、キープアライブのイベントも送信しません。クライアントがタイムアウトしても処理を続ける必要がある場合は、リサーチタスクを作成 を使用してください。

ストリーミングの流れについては、ナレッジベースへのクエリ を参照してください。

イベント

  • answer.delta：回答の断片を 1 つ届けます。
    • delta：追加するテキストです。
    • traceId：クエリ記録 ID です。
  • answer.done：回答が完了し、クエリ記録が保存されたことを示します。

    • finishReason：チャンクが見つかった場合は retrieval-evidence、何も一致しなかった場合は no-retrieval-evidence です。

    • metadata：キーが固定されていないマップです。fast、deep、research のいずれの深度でも mode と evidenceBundle を含み、retrieval-evidence の場合は citations を含みます。そのほか、実行で生成されたキーも含まれます。evidenceBundle.items には、検索されたチャンクがテキストとスコアとともに格納されます。

      後から確認するには、クエリのチャンク一覧を取得 を呼び出します。チャンクをページ単位で返し、実行後にドキュメントが削除されたチャンクにはその旨を示します。

    • traceId：クエリ記録 ID です。

  • answer.error：ストリームの開始後にクエリが失敗したことを示します。
    • code：失敗の種類で、次のいずれかです。
      • RETRIEVAL_EXECUTION_LEASE_LOST：ナレッジベースの削除が始まったか、実行が期限切れになりました。クエリを再実行してください。
      • KNOWLEDGE_FS_UNAVAILABLE：回答の生成中またはクエリ記録の保存中に発生した、その他の失敗です。
    • error：メッセージです。
    • failure：エラー詳細です。category、code、message、retryPolicy、stage、traceId、および任意で action を含みます。
      • stage：常に query_generation です。
    • traceId：クエリ記録 ID です。

citations

回答を裏付ける、検索されたチャンクごとに 1 つのエントリがあります。

  • nodeId：チャンク ID です。
  • label：node:<nodeId> です。
  • documentAssetId：チャンクの取得元のドキュメントファイルです。
  • sectionPath：アウトライン上のパスです。
  • pageNumber：ソースがページ情報を提供する場合のページ番号で、1 から始まります。それ以外の場合は省略されます。
  • projectionIds：この一致に寄与した検索インデックスの ID です。元のファイルの特定には documentAssetId を使用してください。
  • sources：チャンクを見つけた検索の種類（dense、fts、pageindex、visual）です。

画像の引用には multimodalCandidate.assetRef.analysisUnavailable.reason が含まれることがあります。これが含まれる場合、リソースの制限または画像処理の失敗により、画像の解析はスキップされています。その場合でも、関連するテキストは結果に寄与できます。

evidenceBundle.items[].citations[] には startOffset と endOffset が含まれることもあります。これらは解析済みドキュメントテキスト内の 0 始まりの UTF-8 バイトオフセットで、開始位置を含み、終了位置を含みません。引用の表示には返されたチャンクテキストを使用し、元のファイルをこのオフセットで切り出さないでください。

結果別の終了シーケンス

  • 成功：0 個以上の answer.delta の後に answer.done が 1 つ届き、ストリームが閉じます。
  • 失敗：answer.done の代わりに answer.error が届き、ストリームが閉じます。その前に一部の断片がすでに配信されている場合があり、HTTP ステータスは 200 のままです。これを最終結果として扱い、やり直す場合は新しいクエリを開始してください。
  • クライアントの切断：実行はキャンセルされ、ストリームが終了します。

回答の内容：fast と deep では、検索されたチャンクのダイジェストが 1 つの answer.delta で届きます（Retrieval evidence answer: に続けて、番号付きのセクションパスとそのテキスト）。research では、統合された回答が 1 つ以上の断片としてストリーミングで返されます。何も一致しなかった場合、断片は I could not find evidence for that query in the indexed retrieval projections. の 1 つだけで、finishReason は no-retrieval-evidence になります。

回答はどの深度でも 2,000 文字が上限です。回答がこの長さに達していても、切り詰められたかどうかは判断できません。

成功した実行の例：

ストリームの開始後に失敗した例：