> ## 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. # 规划研究任务 > 估算研究任务，但不创建任务。返回实际采用的检索深度，以及成本、延迟和工作量的估算，包括是否在拟定的预算之内。 规划、创建、轮询和读取结果的完整流程，详见 [运行研究任务](/zh/api-reference/guides/knowledge-base#run-a-research-task)。 ## OpenAPI ````yaml /zh/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: >- 估算研究任务，但不创建任务。返回实际采用的检索深度，以及成本、延迟和工作量的估算，包括是否在拟定的预算之内。 规划、创建、轮询和读取结果的完整流程，详见 [运行研究任务](/zh/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`（参见 [检索深度](/zh/cloud/use-dify/knowledge-base/retrieval-settings#retrieval-depth)）。省略时使用知识库的默认深度，即 [获取知识库设置](/zh/api-reference/settings/get-knowledge-base-settings) 中的 `retrieval.default_mode`。 enum: - fast - deep - research - null nullable: true type: string query: description: 要查询的问题。不能为空白，且不超过 16,384 个 UTF-8 字节。 maxLength: 16000 nullable: false pattern: \S type: string topK: description: >- 检索结果合并并重排序后最多保留的分段数。显式传入的值必须在 1～50 之间。省略时使用知识库已发布的 **Top K** 设置，该设置最高可达 100。值越大，模型获得的上下文越多，干扰也越多；值越小，结果越集中，但可能漏掉相关分段。 maximum: 50 minimum: 1 nullable: true type: integer required: - query type: object description: >- 标记为 nullable 的可选字段，传 `null` 等同于省略。 规范化后的请求不得超过 65,536 个 UTF-8 字节。参见 [请求大小限制](/zh/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`。仅供参考：[创建研究任务](/zh/api-reference/research-tasks/create-research-task) 仍会受理该任务，并在下一次模型调用可能超出预算时取消它。 type: boolean remaining_budget_usd: description: '`budgetUsd` 减去估算成本。超出预算时为负数。未设置预算时为 `null`。' nullable: true type: number type: object estimates: description: >- 任务的工作量、成本和延迟估算。可与你打算发送给 [创建研究任务](/zh/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: 所有步骤预计消耗的模型输入 token 数。 type: integer latencyMs: description: >- 预计的端到端耗时，单位为毫秒。可根据 `p50` 安排首次轮询 [获取研究任务](/zh/api-reference/research-tasks/get-research-task) 的时间。 properties: p50: description: 中位数估算。 type: integer p95: description: 第 95 百分位估算。`limits.timeoutMs` 对照的就是这个值。 type: integer type: object outputTokens: description: 所有步骤预计产生的模型输出 token 数。 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: >- 点估计值背后的范围。[创建研究任务](/zh/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`。调用 [创建研究任务](/zh/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: 预计的模型输入 token 数。 type: integer estimatedLatencyMs: description: 预计耗时，单位为毫秒。 type: integer estimatedOutputTokens: description: 预计的模型输出 token 数。 type: integer estimatedToolCalls: description: 预计的工具调用次数。 type: integer name: description: >- 步骤名称。`plan`、`retrieve`、`analyze` 和 `generate` 始终出现，并按此顺序排列。检索策略需要读取文档大纲时，`inspect` 紧跟在 `plan` 之后。 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` 为 `never`，而非 `after_configuration`。 '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 补上默认值后，请求超过 65,536 个 UTF-8 字节。参见 [请求大小限制](/zh/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`：知识库尚不能处理查询：没有生效的嵌入模型，或其设置尚未发布。重试前先检查 [获取知识库设置](/zh/api-reference/settings/get-knowledge-base-settings) 中的 `capabilities.query`。 - `knowledge_fs_operation_unavailable`：该知识库由经典知识库升级而来，仍在禁用原先已禁用或已归档的文档。稍后重试。 components: securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.