> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # リサーチタスクを計画 > リサーチタスクを作成せずに見積もります。決定された検索の深度と、コスト、レイテンシ、作業量の見積もりを返し、見積もりが提示された予算に収まるかどうかも示します。 計画、作成、ポーリング、結果の読み取りの流れについては、[リサーチタスクの実行](/ja/api-reference/guides/knowledge-base#run-a-research-task) を参照してください。 ## OpenAPI ````yaml /ja/api-reference/openapi_service.json post /knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan openapi: 3.0.1 info: description: >- Dify アプリケーションとナレッジベースのための REST API です。アプリケーション系エンドポイントはアプリの API キーで、ナレッジ系エンドポイントはナレッジベースの API キーで認証します。 title: Dify サービス API version: 1.0.0 servers: - description: Dify サービス API のベース URL です。セルフホスト環境では、独自の API ベース URL に置き換えてください。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API ベース URL のホストとパス（`https://` を除く）。 security: - ApiKeyAuth: [] tags: - description: チャットメッセージとインタラクションに関連する操作です。 name: チャットメッセージ - description: ファイルのアップロードとプレビューの操作です。 name: ファイル操作 - description: エンドユーザー情報に関連する操作です。 name: エンドユーザー - description: ユーザーフィードバックの操作です。 name: メッセージフィードバック - description: 会話管理に関連する操作です。 name: 会話管理 - description: テキスト読み上げと音声認識の操作です。 name: 音声・テキスト変換 - description: アプリケーション設定と情報を取得する操作です。 name: アプリケーション設定 - description: ダイレクト返信用のアノテーション管理に関連する操作です。 name: アノテーション管理 - description: 人間の入力を要する一時停止中のワークフローの再開操作です。 name: 人間の入力 - description: ワークフローの実行と管理のための操作です。 name: ワークフロー実行 - description: テキスト生成に関連する操作です。 name: 完了メッセージ - description: ナレッジベースの作成、設定、取得を含むナレッジベース管理の操作です。 name: ナレッジベース - description: ナレッジベース内のドキュメントの作成、更新、管理のための操作です。 name: ドキュメント - description: ドキュメントチャンクと子チャンクの管理のための操作です。 name: チャンク - description: ナレッジベースのメタデータフィールドとドキュメントメタデータ値の管理のための操作です。 name: メタデータ - description: ナレッジベースタグとタグバインディングの管理のための操作です。 name: タグ管理 - description: 利用可能なモデルを取得するための操作です。 name: モデル - description: データソースプラグインとパイプライン実行を含むナレッジパイプラインの管理と実行のための操作です。 name: ナレッジパイプライン - description: ナレッジベースに質問し、回答をストリーミングで受け取ります。 name: クエリ - description: クエリが何を検索したか、またその理由を確認します。 name: クエリ記録 - description: リサーチの質問をバックグラウンドで実行し、その結果を取得します。 name: リサーチタスク - description: ナレッジベースのドキュメントと、そのファイル、リビジョン、チャンクを読み取り、ドキュメントにメタデータのラベルを付けます。 name: ドキュメントとチャンク - description: インデックス処理の追跡、キャンセル、再試行と、ナレッジベースのバックグラウンドタスクの一覧表示を行います。 name: インデックスタスク - description: ドキュメントファイル、ファイルのバッチ、またはソースの削除を、完了するまで追跡します。 name: 削除ジョブ - description: ナレッジベースにデータを供給するソース、その同期スケジュール、接続を管理します。 name: ソース - description: ソースの即時同期、ウェブサイトのページまたはプロバイダーのアイテムのインポート、実行の追跡、キャンセル、再試行を行います。 name: ソースの同期とインポート - description: ナレッジベースのモデルと検索設定の読み取りと変更、および変更によって始まる移行の追跡を行います。 name: 設定 paths: /knowledge-fs/spaces/{knowledge_base_id}/research-tasks/plan: post: tags: - Research Tasks summary: リサーチタスクを計画 description: >- リサーチタスクを作成せずに見積もります。決定された検索の深度と、コスト、レイテンシ、作業量の見積もりを返し、見積もりが提示された予算に収まるかどうかも示します。 計画、作成、ポーリング、結果の読み取りの流れについては、[リサーチタスクの実行](/ja/api-reference/guides/knowledge-base#run-a-research-task) を参照してください。 operationId: planResearchTask parameters: - description: >- ナレッジベース ID です。ナレッジベースの **API アクセス** ダイアログに表示されるサービス API エンドポイントの最後のセグメント（`…/knowledge-fs/spaces/`）です。アドレスバーでは `/datasets/new/` の後のセグメントです。 in: path name: knowledge_base_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: リクエスト例 value: budgetUsd: 0.05 mode: research query: >- What changed in the 2025 refund policy, and which regions are affected? topK: 10 schema: additionalProperties: false description: 空白のみではない `query` を指定してください。 properties: budgetUsd: description: >- コストの見積もりと比較する支出の上限（USD）です。レスポンスの `budget.exceeds_budget` と `budget.remaining_budget_usd` に反映されます。 minimum: 0 nullable: true type: number mode: description: >- 検索の深度です。`fast`、`deep`、`research` のいずれかを指定します（[検索の深度](/ja/cloud/use-dify/knowledge-base/retrieval-settings#retrieval-depth) を参照）。省略すると、ナレッジベースのデフォルトの深度が使われます。これは [ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) の `retrieval.default_mode` です。 enum: - fast - deep - research - null nullable: true type: string query: description: 質問です。空白のみではないクエリを指定してください。また、UTF-8 で 16,384 バイトまでに制限されます。 maxLength: 16000 nullable: false pattern: \S type: string topK: description: >- 検索結果をマージしてリランクした後に残すチャンクの最大数です。明示的に指定する場合は 1〜50 の値にしてください。省略すると、ナレッジベースで公開されている **トップ K** 設定（最大 100）が使われます。値を大きくするとモデルに渡るコンテキストが増えますが、ノイズも増えます。値を小さくすると焦点は絞られますが、関連するチャンクを取りこぼすことがあります。 maximum: 50 minimum: 1 nullable: true type: integer required: - query type: object description: >- nullable と記されたオプションフィールドでは、`null` は省略と同じ扱いになります。 正規化後のリクエストは、UTF-8 で 65,536 バイト以内に収める必要があります。[リクエストサイズの制限](/ja/api-reference/guides/knowledge-base#request-size-limits) を参照してください。 required: true responses: '200': content: application/json: examples: success: summary: レスポンス例 value: budget: budget_usd: 0.05 exceeds_budget: false remaining_budget_usd: 0.018238 estimates: cacheHitProbability: 0.25 costUsd: currency: USD estimated: 0.031762 max: 0.042879 min: 0.020645 inputTokens: 3070 latencyMs: p50: 2800 p95: 5040 outputTokens: 1776 retrievalSteps: 3 scannedResources: 620 toolCalls: 6 totalTokens: 4846 workBounds: modelCalls: estimated: 3 max: 4 min: 2 openedResources: estimated: 20 max: 40 min: 0 retrievalSteps: estimated: 3 max: 5 min: 1 knowledge_space_id: b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d query: >- What changed in the 2025 refund policy, and which regions are affected? retrieval_plan: dense_top_k: 100 fts_top_k: 100 fusion_limit: 50 query_language: latin requested_mode: research rerank_candidate_limit: 50 resolved_mode: research strategy_version: retrieval-planner-v2 top_k: 10 steps: - estimatedCostUsd: 0.003126 estimatedInputTokens: 274 estimatedLatencyMs: 350 estimatedOutputTokens: 192 estimatedToolCalls: 1 name: plan - estimatedCostUsd: 0.00124 estimatedInputTokens: 0 estimatedLatencyMs: 600 estimatedOutputTokens: 0 estimatedToolCalls: 3 name: retrieve - estimatedCostUsd: 0.007542 estimatedInputTokens: 978 estimatedLatencyMs: 650 estimatedOutputTokens: 384 estimatedToolCalls: 1 name: analyze - estimatedCostUsd: 0.019854 estimatedInputTokens: 1818 estimatedLatencyMs: 1200 estimatedOutputTokens: 1200 estimatedToolCalls: 1 name: generate strategy_version: research-dry-run-planner-v1 schema: properties: budget: description: リクエストの `budgetUsd` に対するコスト見積もりの判定結果です。 properties: budget_usd: description: リクエストの `budgetUsd` です。送信されなかった場合は `null` です。 nullable: true type: number exceeds_budget: description: >- `estimates.costUsd.estimated` が `budgetUsd` を上回る場合は `true` です。予算がない場合は常に `false` です。この値は参考情報にすぎません。[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) は、この場合もタスクを受け付け、次のモデル呼び出しで予算を超える可能性が生じた時点でキャンセルします。 type: boolean remaining_budget_usd: description: >- `budgetUsd` から見積もりコストを引いた値です。予算を超える場合は負の値になります。予算がない場合は `null` です。 nullable: true type: number type: object estimates: description: >- タスクの作業量、コスト、レイテンシの見積もりです。[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) に送信する予定の `limits` と比較してください。 properties: cacheHitProbability: description: キャッシュから返される検索の割合の見積もりで、`0` から `1` までの値です。 type: number costUsd: description: タスクの見積もりコストです。 properties: currency: description: 常に `USD` です。 type: string estimated: description: 点推定値（USD）です。 type: number max: description: 上限値（USD）です。 type: number min: description: 下限値（USD）です。 type: number type: object inputTokens: description: 全ステップでのモデル入力トークン数の見積もりです。 type: integer latencyMs: description: >- 開始から完了までの所要時間の見積もり（ミリ秒）です。[リサーチタスクを取得](/ja/api-reference/research-tasks/get-research-task) の最初のポーリングのタイミングは、`p50` をもとに決めてください。 properties: p50: description: 中央値の見積もりです。 type: integer p95: description: 95 パーセンタイルの見積もりです。この値が `limits.timeoutMs` と照合されます。 type: integer type: object outputTokens: description: 全ステップでのモデル出力トークン数の見積もりです。 type: integer retrievalSteps: description: 検索ラウンド数の見積もりです。`limits.maxRetrievalSteps` と照合されます。 type: integer scannedResources: description: >- 読み取るドキュメントとセクションの数の見積もりです。`limits.maxScannedResources` と照合されます。 type: integer toolCalls: description: ツール呼び出し回数の見積もりです。`limits.maxToolCalls` と照合されます。 type: integer totalTokens: description: '`inputTokens` と `outputTokens` の合計です。' type: integer workBounds: description: >- 点推定値の根拠となる範囲です。[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) がチェックするのは、これらの範囲ではなく点推定値です。 properties: modelCalls: description: モデル呼び出し回数の見積もり値、最小値、最大値です。 properties: estimated: description: 点推定値です。 type: integer max: description: 上限値です。 type: integer min: description: 下限値です。 type: integer type: object openedResources: description: 開くドキュメントとセクションの数の見積もり値、最小値、最大値です。 properties: estimated: description: 点推定値です。 type: integer max: description: 上限値です。 type: integer min: description: 下限値です。 type: integer type: object retrievalSteps: description: 検索ラウンド数の見積もり値、最小値、最大値です。 properties: estimated: description: 点推定値です。 type: integer max: description: 上限値です。 type: integer min: description: 下限値です。 type: integer type: object type: object type: object knowledge_space_id: description: ナレッジベースの内部 ID です。パスのナレッジベース ID とは異なります。 type: string query: description: 前後の空白を取り除いた質問です。 type: string retrieval_plan: description: 検索をどのように実行するかを示します。 properties: dense_top_k: description: ベクトル検索から取得する候補数です。 type: integer fts_top_k: description: キーワード検索から取得する候補数です。 type: integer fusion_limit: description: ベクトル検索とキーワード検索の結果をマージした後に残す候補数です。 type: integer query_language: description: >- 検出された質問の言語で、`cjk`、`latin`、`mixed-cjk-latin`、`other` のいずれかです。 type: string requested_mode: description: >- リクエストの `mode` です。省略した場合はナレッジベースのデフォルトの深度です。`fast`、`deep`、`research` のいずれかです。 type: string rerank_candidate_limit: description: リランクモデルに渡す候補数です。 type: integer resolved_mode: description: >- 実行される深度で、`fast`、`deep`、`research` のいずれかです。[リサーチタスクを作成](/ja/api-reference/research-tasks/create-research-task) にも同じ `mode` を送信してください。そこで異なる深度を指定すると、`limits` は別の見積もりと照合されます。 type: string strategy_version: description: この計画を作成した検索戦略のバージョンです。 type: string top_k: description: 検索結果をマージしてリランクした後に残すチャンクの最大数です。 type: integer type: object steps: description: ステップごとの見積もりです。実行順に並びます。 items: properties: estimatedCostUsd: description: ステップの見積もりコスト（USD）です。 type: number estimatedInputTokens: description: モデル入力トークン数の見積もりです。 type: integer estimatedLatencyMs: description: 所要時間の見積もり（ミリ秒）です。 type: integer estimatedOutputTokens: description: モデル出力トークン数の見積もりです。 type: integer estimatedToolCalls: description: ツール呼び出し回数の見積もりです。 type: integer name: description: >- ステップ名です。`plan`、`retrieve`、`analyze`、`generate` は常にこの順で含まれます。検索戦略がドキュメントのアウトラインを読む場合は、`plan` の後に `inspect` が続きます。 type: string type: object type: array strategy_version: description: 見積もりロジックのバージョンです。 type: string type: object description: 計画とその見積もりです。 '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request (validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - limits type: extra_forbidden knowledge_fs_invalid_request_2: summary: knowledge_fs_invalid_request (rejected upstream) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: d44c6dd1-da9c-46e7-81e1-5f09707c4352 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`：リクエストが検証に失敗しました。`violations` には、問題のあるフィールドがそれぞれ示されます。 - `knowledge_fs_invalid_request`：ボディに不明なフィールド（`knowledgeSpaceId`、`limits`、`metadata` を含む）や範囲外の値が含まれているか、空白のみではない `query` がありません。 - `knowledge_fs_invalid_request`：ナレッジベースの検索設定では、決定された深度を実行できません。たとえば、スコアしきい値が有効で `rerank.enabled: false` の場合です。Dify の **設定** > **検索** で、リランクモデルの設定を確認してください。`failure` オブジェクトの `retryPolicy` は、`after_configuration` ではなく `never` です。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：`Authorization` ヘッダーがないか、キーが不明であるか、ナレッジベースの API キーではありません。 - `knowledge_fs_invalid_credential`：キーは有効ですが、キーのワークスペースにこの ID のナレッジベースが存在しないか、キーがワークスペースに紐付いていません。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`：キーのアクセス範囲がほかのナレッジベースに限定されているか、このナレッジベースで **API アクセス** がオフになっています。または、ナレッジベースがアクティブではありません。 - `forbidden`：Dify Cloud で、ワークスペースがサブスクリプションで定められたナレッジベースのリクエストレート制限に達しました。読み取りを含め、すべての呼び出しがカウントされます。 '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: |- - `knowledge_fs_resource_not_found`：ナレッジベース ID が認識されません。 - `not_found`：このデプロイ環境では Agent ナレッジベース機能が無効になっています。 '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large (request budget) value: code: knowledge_fs_request_too_large message: Agent Knowledge Base request is too large. status: 413 description: >- - `knowledge_fs_request_too_large`：Dify がデフォルト値を追加した後のリクエストが、UTF-8 で 65,536 バイトを超えています。[リクエストサイズの制限](/ja/api-reference/guides/knowledge-base#request-size-limits) を参照してください。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_2: summary: knowledge_fs_upstream_unavailable (without error details) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`：時間内に応答が返らなかったか、応答を読み取れませんでした。しばらく待ってから再試行してください。 '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`：このワークスペースで Agent ナレッジベース機能が設定されていないか、このデプロイ環境ではこの操作を利用できません。または、リクエストの認可中に、このナレッジベースに対するキーのアクセス権が変更されました。 - `knowledge_fs_operation_unavailable`：現在このリクエストを処理できません。`failure.retryPolicy` に従ってください。 - `knowledge_fs_operation_unavailable`：ナレッジベースはまだクエリを受け付ける準備ができていません。アクティブな埋め込みモデルがないか、設定が公開されていません。再試行する前に、[ナレッジベース設定を取得](/ja/api-reference/settings/get-knowledge-base-settings) の `capabilities.query` を確認してください。 - `knowledge_fs_operation_unavailable`：このナレッジベースは従来型ナレッジベースからアップグレードされたものです。従来型ナレッジベースで無効化またはアーカイブされていたドキュメントを、まだ無効化している途中です。後で再試行してください。 components: securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- すべてのリクエストは API キーで認証します：`Authorization: Bearer {API_KEY}`。アプリのエンドポイントにはアプリの API キーを、ナレッジのエンドポイントにはナレッジベースの API キーを使用します（[Dify API クイックスタート](/ja/api-reference/guides/get-started)）。 キーはサーバーサイドで保管し、クライアントコードには決して埋め込まないでください。キーが欠落または無効なリクエストは HTTP `401`（`unauthorized`）で失敗します。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.