> ## 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. # 创建研究任务 > 为一个问题创建研究任务，返回的任务 `stage` 为 `queued`，随后在后台运行。规划、创建、轮询和读取结果的完整流程，详见 [运行研究任务](/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 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: post: tags: - Research Tasks summary: 创建研究任务 description: >- 为一个问题创建研究任务，返回的任务 `stage` 为 `queued`，随后在后台运行。规划、创建、轮询和读取结果的完整流程，详见 [运行研究任务](/zh/api-reference/guides/knowledge-base#run-a-research-task)。 operationId: createResearchTask parameters: - description: >- 知识库 ID：即知识库 **API 访问** 对话框中所示服务 API 端点的最后一段（`…/knowledge-fs/spaces/`），也是地址栏中 `/datasets/new/` 之后的那一段。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- 可选的幂等键，用于安全地重试创建。使用 8～255 个可打印 ASCII 字符，首尾不得有空白；格式不正确的键返回 `400`。 用同一个 API 密钥重复发送相同的键和请求体，会以 `202` 返回原任务及其当前状态，不会再创建新任务。键在工作空间内唯一：以不同的请求体、通过其他 API 密钥、在其他知识库中或为其他操作复用该键，会返回 `409`。 in: header name: Idempotency-Key required: false schema: maxLength: 255 minLength: 8 type: string requestBody: content: application/json: examples: request: summary: 请求示例 value: budgetUsd: 1.5 limits: maxRetrievalSteps: 8 maxScannedResources: 800 maxToolCalls: 12 timeoutMs: 120000 metadata: client_request_id: client-20260907-0001 ticket: SUP-1042 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）。在任务运行期间生效，创建时不检查。即使 [规划研究任务](/zh/api-reference/research-tasks/plan-research-task) 的估算超出该上限，任务也会被受理。每次调用模型之前，任务会用这次调用的最坏情况成本对照预算检查；如果这次调用可能超出预算，任务会被取消，不再发起调用。 单次调用的实际成本仍可能高于其最坏情况估算，因此 `cost.totalUsd` 最终可能超过 `budgetUsd`。如果任务在 `generating` 阶段之前因预算被取消，就不会有回答。最坏情况成本通常远高于规划结果中的估算，因此需要得到回答时，把上限设得远高于 `estimates.costUsd.max`；`topK` 较大时还要更高。 因预算停止的任务，`stage` 为 `canceled`。 minimum: 0 nullable: true type: number limits: additionalProperties: false description: >- 仅在创建时对照规划结果中的估算检查一次。估算超出任一限制的任务会被拒绝并返回 `422`。省略 `limits` 则跳过这些检查。如需在任务运行期间限制花费，使用 `budgetUsd`。 估算值等于限制值时视为通过。参照 [规划研究任务](/zh/api-reference/research-tasks/plan-research-task) 返回的 `estimates` 设定这些值。 nullable: true properties: maxRetrievalSteps: description: 对照 `estimates.retrievalSteps` 检查。 minimum: 1 nullable: true type: integer maxScannedResources: description: 对照 `estimates.scannedResources` 检查。 minimum: 1 nullable: true type: integer maxToolCalls: description: 对照 `estimates.toolCalls` 检查。 minimum: 1 nullable: true type: integer timeoutMs: description: 对照 `estimates.latencyMs.p95` 检查，单位为毫秒。 minimum: 1 nullable: true type: integer type: object metadata: description: >- 自由格式的对象，随任务保存，并以 `metadata` 返回。以 `__knowledgeFs` 开头的键为保留键，会被丢弃。 可在其中放入 `client_request_id` 等唯一值，创建响应丢失时，可据此识别并找到该任务。如需让重试直接返回原任务、不再创建新任务，发送 `Idempotency-Key`。 type: object 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: '202': content: application/json: examples: success: summary: 响应示例 value: budget_usd: 1.5 completed_at: null cost: budgetUsd: 1.5 entries: [] totalUsd: 0 created_at: 1788681600000 error: null failure: null id: e4d1b7a2-3c5f-4d8e-9a0b-1c2d3e4f5a6b knowledge_space_id: b2f1d3a4-5e6c-4a7b-8c9d-0e1f2a3b4c5d limits: max_retrieval_steps: 8 max_scanned_resources: 800 max_tool_calls: 12 timeout_ms: 120000 metadata: client_request_id: client-20260907-0001 ticket: SUP-1042 mode: research query: >- What changed in the 2025 refund policy, and which regions are affected? stage: queued top_k: 10 updated_at: 1788681600000 schema: $ref: '#/components/schemas/KnowledgeBaseResearchTask' description: >- 任务已受理。`stage` 为 `queued`，`mode` 为实际采用的深度，`cost.totalUsd` 为 `0`。用相同的 `Idempotency-Key` 和请求体重复请求，会返回原任务及其当前状态。 '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: - topK type: less_than_equal 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: 30692184-e927-4398-b8f9-a6e1eda1ea7b message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`：请求未通过校验。`violations` 列出每个出错的字段。 - `knowledge_fs_invalid_request`：请求体包含未知字段（包括 `knowledgeSpaceId`）、某个值超出其限制，或缺少非空白的 `query`。 - `knowledge_fs_invalid_request`：知识库的检索设置无法以实际采用的深度运行，例如启用了分数阈值但 `rerank.enabled: false`。在 Dify 中的 **设置** > **检索** 下检查重排序模型配置。`failure` 对象中的 `retryPolicy` 为 `never`，而非 `after_configuration`。 - `knowledge_fs_invalid_request`：`Idempotency-Key` 不是 8～255 个可打印 ASCII 字符，或首尾带有空白。 '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 知识库功能。 '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`：`Idempotency-Key` 已以不同的请求体、通过其他 API 密钥、在其他知识库中或为其他操作使用过。新任务需使用新的键。 '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)。 '422': content: application/json: examples: knowledge_fs_request_rejected: summary: knowledge_fs_request_rejected value: code: knowledge_fs_request_rejected failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 9c729446-ba49-4733-9cc1-dbe73542d014 message: The Agent Knowledge Base request is invalid. status: 422 violations: - estimatedValue: 14 limit: maxToolCalls limitValue: 12 description: >- - `knowledge_fs_request_rejected`：规划结果中的估算超出了你设置的一项或多项 `limits`。每个 `violations` 条目对应其中一项，包含 `limit`（该限制在请求中的名称）、`estimatedValue` 和 `limitValue`。估算值等于限制值时视为通过。如果按规划结果设定 `limits` 后仍持续返回 422，可省略 `limits`，改用 `budgetUsd` 约束任务。 '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`：未能及时收到响应，或无法读取响应。 任务可能已经开始。如果发送过 `Idempotency-Key`，用同一个键再次发送相同的请求，即可拿回原任务，不会再创建新任务。如果没有发送键，在重新创建之前，先用同一个 API 密钥调用 [获取研究任务列表](/zh/api-reference/research-tasks/list-research-tasks)。翻完所有页，在每个任务的 `metadata` 中查找你发送的唯一值。找到匹配的任务后，保存其 ID 并轮询。 '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: schemas: KnowledgeBaseResearchTask: properties: budget_usd: description: 请求中设置的花费上限，单位为 USD。未设置时为 `null`。 nullable: true type: number completed_at: description: 任务到达 `completed`、`failed` 或 `canceled` 的时间，Unix 纪元毫秒。任务运行期间为 `null`。 nullable: true type: number cost: description: 目前已记录的花费。 properties: budgetExceeded: description: 花费超出 `budgetUsd` 并因此取消任务时为 `true`，否则不返回此字段。 type: boolean budgetUsd: description: 请求中的 `budgetUsd`。未设置预算时不返回此字段。 type: number entries: description: 每次已记录的模型调用对应一项，最早的在前。 items: properties: costUsd: description: 该次调用的花费，单位为 USD。 type: number provider: description: 处理该次调用的模型供应商。 type: string recordedAt: description: 记录该花费的时间，Unix 纪元毫秒。 type: number step: description: >- 发起该调用的步骤：`pageindex.layer`、`pageindex.semantic`、`pageindex.whole-tree`、`research.judge`、`research.plan`、`graph.plan`、`query.answer` 或 `query.image-expand`。 type: string usage: description: >- 该次调用的 token 用量：`promptTokens`、`completionTokens`、`totalTokens`、`estimated`、`reserved`、`status`（`reserved`、`succeeded` 或 `failed`）和 `researchModelCallId`。仍在进行中的调用所预留的额度也算作一项，并计入 `totalUsd`。 type: object type: object type: array totalUsd: description: '`entries[].costUsd` 的总和，单位为 USD。记录第一次模型调用之前为 `0`。' type: number type: object created_at: description: 任务创建时间，Unix 纪元毫秒。 type: number error: description: >- 错误码，与 `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`。 nullable: true type: string failure: description: >- 错误详情。仅当 `stage` 为 `failed` 时有值，其他情况下为 `null`。此处没有值的成员为 `null`。`traceId` 为任务 ID。 当 `action` 为 `retry` 时，使用 [创建研究任务](/zh/api-reference/research-tasks/create-research-task) 创建新任务。 nullable: true properties: action: description: >- 建议的下一步操作（如有）：`configure_model`、`configure_parser`、`configure_source`、`contact_admin`、`reupload` 或 `retry`。不适用时为 `null`。 nullable: true type: string category: description: >- 失败类别：`authorization`、`canceled`、`configuration`、`conflict`、`dependency`、`internal`、`not_found`、`rate_limit`、`timeout` 或 `validation`。 type: string code: description: 研究任务的错误码，与此任务的 `error` 一致。 type: string message: description: 任务失败的公开消息。不会暴露提供商的错误详情。 type: string parameters: additionalProperties: true description: >- 描述失败细节的值，最多 8 个，键取自 `attempt`、`currentRowVersion`、`documentCount`、`expectedRowVersion`、`fileSizeBytes`、`limit`、`maxFileSizeBytes`、`maxItems`、`modelType`、`providerKind`、`retryAfterSeconds` 和 `status`。没有时为 `null`。 nullable: true type: object retryPolicy: description: >- 重试是否有用：`automatic`（服务会自动重试）、`manual`（需自行重试）、`after_configuration`（先在 Dify 中修正知识库配置）或 `never`（需修改请求）。 type: string stage: description: 始终为 `research`。 nullable: true type: string traceId: description: 研究任务 ID。联系管理员时提供此 ID。 nullable: true type: string type: object id: description: 研究任务 ID。在研究任务的各项操作中用作 `research_task_id`。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string limits: description: >- 请求中的限制项，键名为 snake_case。请求未携带 `limits` 时为 `null`，未发送的成员为 `null`。再次发送给 [创建研究任务](/zh/api-reference/research-tasks/create-research-task) 前，需将键名转换回 camelCase。 nullable: true properties: max_retrieval_steps: description: 请求中 `limits.maxRetrievalSteps` 的值。 nullable: true type: integer max_scanned_resources: description: 请求中 `limits.maxScannedResources` 的值。 nullable: true type: integer max_tool_calls: description: 请求中 `limits.maxToolCalls` 的值。 nullable: true type: integer timeout_ms: description: 请求中 `limits.timeoutMs` 的值。 nullable: true type: integer type: object metadata: description: 创建时发送的 `metadata` 对象，不含以 `__knowledgeFs` 开头的键。 type: object mode: description: 任务的检索深度：`fast`、`deep` 或 `research`。 nullable: true type: string query: description: 存储的研究问题。 type: string query_images: description: 原始查询中使用的图片。纯文本查询不返回此字段。 items: properties: byte_size: description: 在此 API 中始终为 `null`。 minimum: 0 nullable: true type: integer mime_type: description: 在此 API 中始终为 `null`。 nullable: true type: string name: description: 在此 API 中始终为 `null`。 nullable: true type: string preview_url: description: 在此 API 中始终为 `null`。 nullable: true type: string upload_file_id: description: 原始查询中所用图片文件的 ID。 type: string required: - upload_file_id type: object type: array stage: description: >- 任务在生命周期中所处的阶段。任务每次前进一个阶段： - `queued`：已受理，等待工作进程处理。 - `planning`：正在确定检索计划。 - `retrieving`：正在检索知识库，可能会写入检索检查点。 - `analyzing`：正在阅读和权衡检索到的分段。 - `generating`：正在撰写回答，最终结果在此阶段写入。 - `completed`：已完成。可用 [获取研究任务结果列表](/zh/api-reference/research-tasks/list-research-task-results) 读取结果。 - `failed`：因错误停止。详见 `error` 和 `failure`。 - `canceled`：因 [取消研究任务](/zh/api-reference/research-tasks/cancel-research-task) 或超出预算而停止。 - `paused`：任务已暂停。可向部署的运维人员确认失败详情（如有），或取消该任务。 `completed`、`failed` 和 `canceled` 为终态。 type: string top_k: description: 检索结果合并并重排序后最多保留的分段数：取请求中的 `topK`，未传时取知识库的 **Top K**。 nullable: true type: integer updated_at: description: 任务记录最后更新的时间（Unix 纪元毫秒），包括内部检查点和重试调度产生的更新。 type: number type: object 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.