Skip to main content
POST
リサーチタスクを作成

Authorizations

Authorization
string
header
required

すべてのリクエストは API キーで認証します:Authorization: Bearer {API_KEY}。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します(Dify API クイックスタート)。

キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP 401(unauthorized)で失敗します。

Headers

Idempotency-Key
string

作成を安全に再試行できるようにする任意のキーです。前後に空白を含まない、8〜255 文字の印字可能な ASCII 文字を使用してください。キーの形式が正しくない場合は 400 が返ります。

同じ API キーで同じ冪等キーと同じボディを再送信すると、新しいタスクは作成されず、元のタスクが現在の状態のまま 202 で返されます。キーはワークスペース内で一意です。異なるボディ、別の API キー、別のナレッジベース、または別の操作で同じキーを再利用すると 409 が返ります。

Required string length: 8 - 255

Path Parameters

knowledge_base_id
string<uuid>
required

ナレッジベース ID です。ナレッジベースの API アクセス ダイアログに表示されるサービス API エンドポイントの最後のセグメント(…/knowledge-fs/spaces/<knowledge base ID>)です。アドレスバーでは /datasets/new/ の後のセグメントです。

Body

application/json

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

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

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

query
string
required

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

Maximum string length: 16000
Pattern: \S
budgetUsd
number | null

支出の上限(USD)です。作成時ではなく、タスクの実行中に適用されます。リサーチタスクを計画 の見積もりがこの上限を超えていても、タスクは受け付けられます。タスクはモデルを呼び出す前に毎回、その呼び出しで最悪の場合にかかるコストを予算と照合します。予算を超える可能性がある場合は、呼び出しを行わずにキャンセルされます。

それでも、呼び出しのコストが最悪の場合の見積もりを上回ることはあるため、最終的に cost.totalUsd が budgetUsd を超える場合があります。generating 段階より前に予算によってキャンセルされると、タスクには回答が残りません。最悪の場合のコストは計画の見積もりを大きく上回ることが多いため、回答が必要な場合は、estimates.costUsd.max を大きく上回る上限を設定してください。topK が大きい場合は、さらに高くします。

予算によって停止したタスクは、stage が canceled になります。

Required range: x >= 0
limits
object | null

作成時に 1 回だけ、計画の見積もりと照合されます。見積もりがいずれかの上限を超えるタスクは 422 で拒否されます。limits を省略すると、このチェックは行われません。タスク実行中の支出を制限するには budgetUsd を使用してください。

見積もりが上限と等しい場合は通過します。これらの値は、リサーチタスクを計画 の estimates をもとに決めてください。

metadata
object

タスクとともに保存され、metadata として返される自由形式のオブジェクトです。__knowledgeFs で始まるキーは予約されており、破棄されます。

作成のレスポンスが失われた場合にタスクを識別できるよう、client_request_id などの一意の値を含めてください。これはタスクを探す手がかりになります。再試行時に新しいタスクを作成せず、元のタスクを返すようにするには、Idempotency-Key を送信してください。

mode
enum<string> | null

検索の深度です。fast、deep、research のいずれかを指定します(検索の深度 を参照)。省略すると、ナレッジベースのデフォルトの深度が使われます。これは ナレッジベース設定を取得 の retrieval.default_mode です。

Available options:
fast,
deep,
research,
null
topK
integer | null

検索結果をマージしてリランクした後に残すチャンクの最大数です。明示的に指定する場合は 1〜50 の値にしてください。省略すると、ナレッジベースで公開されている トップ K 設定(最大 100)が使われます。値を大きくするとモデルに渡るコンテキストが増えますが、ノイズも増えます。値を小さくすると焦点は絞られますが、関連するチャンクを取りこぼすことがあります。

Required range: 1 <= x <= 50

Response

タスクが受け付けられました。stage は queued、mode は決定された深度、cost.totalUsd は 0 です。同じ Idempotency-Key とボディで再送信すると、元のタスクが現在の状態で返されます。

budget_usd
number | null

リクエストで指定された支出上限(USD)です。設定されていない場合は null です。

completed_at
number | null

タスクが completed、failed、canceled のいずれかに達した日時(エポックミリ秒)です。タスクの実行中は null です。

cost
object

これまでに記録された支出です。

created_at
number

タスクの作成日時(エポックミリ秒)です。

error
string | null

失敗コードで、failure.code と同じ値です。stage が failed の場合にのみ設定され、それ以外の場合は、キャンセルされたタスクも含めて null です。

失敗したリサーチタスクでは、failure.code は RESEARCH_TASK_CAPABILITY_REVOKED、RESEARCH_TASK_DISPATCH_DEAD、RESEARCH_TASK_EXECUTION_ATTEMPTS_EXHAUSTED、RESEARCH_TASK_FAILED、RESEARCH_TASK_PERMISSION_SNAPSHOT_INVALID、RESEARCH_TASK_RUNTIME_SNAPSHOT_INVALID のいずれかです。

failure
object | null

エラー詳細です。stage が failed の場合にのみ設定され、それ以外の場合は null です。ここでは、値のないメンバーは null になります。traceId はタスク ID です。

action が retry の場合は、リサーチタスクを作成 で新しいタスクを作成してください。

id
string

リサーチタスク ID です。タスクに対する各操作で research_task_id として使用します。

knowledge_space_id
string

ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。

limits
object | null

リクエストで指定された制限で、キーはスネークケースです。リクエストに limits が含まれていなかった場合は null です。送信されなかったメンバーは null になります。リサーチタスクを作成 に再度送信する前に、キーをキャメルケースに戻してください。

metadata
object

作成時に送信された metadata オブジェクトです。__knowledgeFs で始まるキーは除かれます。

mode
string | null

タスクの検索の深度で、fast、deep、research のいずれかです。

query
string

保存されたとおりのリサーチの質問です。

query_images
object[]

元のクエリで使用された画像です。テキストのみのクエリでは省略されます。

stage
string

ライフサイクル上でのタスクの現在位置です。タスクは 1 段階ずつ進みます:

  • queued:受け付け済みで、ワーカーを待っています。
  • planning:検索計画を決定しています。
  • retrieving:ナレッジベースを検索しています。検索のチェックポイントが書き込まれることがあります。
  • analyzing:検索されたチャンクを読み、評価しています。
  • generating:回答を作成しています。最終結果はこの段階で書き込まれます。
  • completed:完了しました。結果は リサーチタスクの結果一覧を取得 で取得します。
  • failed:エラーで停止しました。error と failure を参照してください。
  • canceled:リサーチタスクをキャンセル または予算によって停止しました。
  • paused:タスクは一時停止中です。失敗の詳細をデプロイ環境の運用担当者に確認するか、タスクをキャンセルしてください。

completed、failed、canceled は最終状態です。

top_k
integer | null

検索結果をマージしてリランクした後に残すチャンクの最大数です。リクエストの topK、または省略時はナレッジベースの トップ K の値です。

updated_at
number

タスクレコードの最終更新日時(エポックミリ秒)です。内部のチェックポイントや再試行のスケジュール設定による更新も含みます。