langgenius/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-07-23 04:45:29 -04:00
Code Issues 10 Packages Projects Releases Wiki Activity
Files
6258bbfb0f653f3caaa06fae84207c82041b0ac8
dify-docs/zh/api-reference/openapi_knowledge.json
T
Riskey 32e1b169da feat: consolidate and restructure the API reference (Phase 1) (#846) 
* docs: correct HITL API integration flow and sync translations

- Fix the claim that the resume endpoint differs per app type (same
  endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
  (chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
  returns 404); add include_state_snapshot and continue_on_pause
  guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page

* fix: correct API references against verified backend behavior

Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.

- Add curl samples for GET endpoints with required query params
  (Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
  string; DELETE /conversations requires a JSON body; audio-to-text
  accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
  created_by_account filters by email; triggered_from values are
  app-run/webhook/schedule/plugin; stop endpoints' user semantics
  differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
  403, file preview endpoint in the workflow spec, invented
  score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
  response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
  values, no response-field enums)

* fix: complete API reference audit for knowledge and completion specs

* feat: add API spec consolidation pipeline

Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.

* feat: consolidate API reference into one spec per language

Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.

* fix: remove dead conversation_completed error from chat specs

ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.

* feat: add membership matrix and restructure nav config

* feat: rename resource tags and update all references

* feat: stamp per-operation availability lines

* feat: wire three-group API navigation

* feat: add app-type page coverage lint

* docs: rewrite chatflow overview as app-type API guide

* docs: polish chatflow overview zh and ja wording

* docs: rewrite workflow overview as app-type API guide

* docs: align workflow overview details across languages

* docs: expand new agent overview into app-type API guide

* docs: use task-oriented heading on new agent overview

* docs: rewrite chatbot and agent overview as app-type API guide

* docs: rewrite text generator overview as app-type API guide

* docs: match end user link text to merged spec summary

* docs: rewrite knowledge overview as app-type API guide

* docs: move knowledge api guide into api reference

* docs: localize ui labels on knowledge overview

* docs: refresh pipeline readme for restructure modes

* docs: name app-type pages in the guides sidebar

* feat: rename zh completion messages tag to match resource framing

* docs: prototype endpoints-first layout on chatflow overview

* docs: correct detail accuracy on chatflow overview

* docs: move human input flow guide into api reference

Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.

* fix: update spec links to the moved human input guide

* fix: let spec lint accept mdx guide pages under api-reference

* docs: align chatflow zh and ja overviews to endpoints-first layout

* docs: polish chatflow zh and ja mode terms and hitl wording

* docs: align workflow overviews to endpoints-first layout

* docs: document form expiry path in human input flow guide

* docs: align new agent overviews to endpoints-first layout

* docs: align chatbot and agent overviews to endpoints-first layout

* docs: align text generator overviews to endpoints-first layout

* docs: align knowledge overviews to endpoints-first layout

* docs: correct built-in metadata examples and agent heading

* docs: flatten app-type pages directly under guides

* docs: make guide pages self-contained and trim reference detail

* docs: add get started guide and retire developing-with-apis

* docs: update new agent api behavior for latest main

New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.

* docs: audit fixes for get started and human input flow guides

* docs: fix em dash spacing and ja sentence length in get started

* docs: move message_end note to the send endpoint line

* docs: update writing guides and API skill for app-type naming

- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.

* feat: add operation sidebar titles and simplify API redirects

- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).

* docs: correct app-type naming and translations across API specs

- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.

* docs: add streaming, errors, and end-user identity API guides

- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.

* docs: reconcile API guides and apply app-type naming

- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.

* feat: wire API nav and redirects for consolidated guides

- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.

* fix: normalize zh model-provider term to 模型供应商

Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.

* docs: use Info callouts for guide forward-link notes

Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.

* refactor: remove one-time analyze mode and verification compose

- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.

* fix: correct Chatflow naming and reasoning wording in SSE overrides

- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".

* docs: refine API guide wording and simplify the human-input example

* docs: standardize Workflow and Chatflow app-type capitalization

Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.

* fix: use 供应商 for model provider in the zh Knowledge spec

* fix: rename the Knowledge API nav group to "Knowledge APIs"

* fix: un-deprecate Update Document by Text in the Knowledge spec

* translate: un-deprecate Update Document by Text in zh/ja specs

Mirror the en fix (6802d5eb) into the zh and ja Knowledge specs, source and merged: drop the deprecated flag and the leading Deprecated notice from the update-by-text operation. It is the canonical text-update route; only Update Document by File stays deprecated.
2026-07-09 16:40:54 +08:00

8589 lines
315 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"openapi": "3.0.1",
"info": {
"title": "知识库 API",
"description": "用于管理知识库、文档、分段、元数据和标签的 API，包括创建、检索和配置操作。**注意：**单个知识库 API 密钥有权操作同一账户下所有可见的知识库。请注意数据安全。",
"version": "1.0.0"
},
"servers": [
{
"url": "https://{api_base_url}",
"description": "Knowledge API 的基础 URL。自部署时，替换为你的 API 基础 URL。",
"variables": {
"api_base_url": {
"default": "api.dify.ai/v1",
"description": "API 基础 URL 的主机与路径，不含 `https://` 前缀。"
}
}
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"tags": [
{
"name": "知识库",
"description": "用于管理知识库的操作，包括创建、配置和检索。"
},
{
"name": "文档",
"description": "用于在知识库中创建、更新和管理文档的操作。"
},
{
"name": "分段",
"description": "用于管理分段和子分段的操作。"
},
{
"name": "元数据",
"description": "用于管理知识库元数据字段和文档元数据值的操作。"
},
{
"name": "标签",
"description": "用于管理知识库标签和标签绑定的操作。"
},
{
"name": "模型",
"description": "用于获取可用模型的操作。"
},
{
"name": "知识流水线",
"description": "用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。"
}
],
"paths": {
"/datasets": {
"post": {
"tags": [
"知识库"
],
"summary": "创建空知识库",
"description": "创建新的空知识库。创建后，使用 [从文本创建文档](/api-reference/文档/从文本创建文档) 或 [从文件创建文档](/api-reference/文档/从文件创建文档) 添加文档。",
"operationId": "createDataset",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"description": "知识库名称。"
},
"description": {
"type": "string",
"maxLength": 400,
"default": "",
"description": "知识库描述。"
},
"indexing_technique": {
"type": "string",
"enum": [
"high_quality",
"economy"
],
"nullable": true,
"description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
},
"permission": {
"type": "string",
"enum": [
"only_me",
"all_team_members",
"partial_members"
],
"default": "only_me",
"description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。"
},
"provider": {
"type": "string",
"enum": [
"vendor",
"external"
],
"default": "vendor",
"description": "`vendor` 为内部知识库，`external` 为外部知识库。"
},
"embedding_model": {
"type": "string",
"description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。"
},
"embedding_model_provider": {
"type": "string",
"description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
},
"external_knowledge_api_id": {
"type": "string",
"description": "外部知识库 API 连接的 ID。"
},
"external_knowledge_id": {
"type": "string",
"description": "外部知识库的 ID。"
},
"summary_index_setting": {
"type": "object",
"nullable": true,
"description": "摘要索引配置。",
"properties": {
"enable": {
"type": "boolean",
"description": "是否启用摘要索引。"
},
"model_name": {
"type": "string",
"description": "用于生成摘要的模型名称。"
},
"model_provider_name": {
"type": "string",
"description": "摘要生成模型的供应商。"
},
"summary_prompt": {
"type": "string",
"description": "用于摘要生成的自定义提示词模板。"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "知识库创建成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Dataset"
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "产品 API 技术文档",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"409": {
"description": "`dataset_name_duplicate` : 知识库名称已存在，请修改名称。",
"content": {
"application/json": {
"examples": {
"dataset_name_duplicate": {
"summary": "dataset_name_duplicate",
"value": {
"status": 409,
"code": "dataset_name_duplicate",
"message": "The dataset name already exists. Please modify your dataset name."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"知识库"
],
"summary": "获取知识库列表",
"description": "返回知识库的分页列表。支持按关键词和标签筛选。",
"operationId": "listDatasets",
"parameters": [
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1
},
"description": "要获取的页码。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "每页条目数。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "按名称筛选的搜索关键词。"
},
{
"name": "include_all",
"in": "query",
"schema": {
"type": "boolean",
"default": false
},
"description": "是否包含所有知识库，无论权限如何。"
},
{
"name": "tag_ids",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "用于筛选的标签 ID。"
}
],
"responses": {
"200": {
"description": "知识库列表。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "知识库对象数组。",
"items": {
"$ref": "#/components/schemas/Dataset"
}
},
"has_more": {
"type": "boolean",
"description": "下一页是否还有更多项目。"
},
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"total": {
"type": "integer",
"description": "匹配条目的总数。"
},
"page": {
"type": "integer",
"description": "当前页码。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "产品 API 技术文档",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin"
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}": {
"get": {
"tags": [
"知识库"
],
"summary": "获取知识库详情",
"description": "获取指定知识库的详细信息，包括嵌入模型、检索配置和文档统计信息。",
"operationId": "getDatasetDetail",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"responses": {
"200": {
"description": "知识库详情。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Dataset"
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "产品 API 技术文档",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"patch": {
"tags": [
"知识库"
],
"summary": "更新知识库",
"description": "更新现有知识库的名称、描述、权限或检索设置。仅更新请求体中提供的字段。",
"operationId": "updateDataset",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40,
"description": "知识库名称。"
},
"description": {
"type": "string",
"maxLength": 400,
"description": "知识库描述。"
},
"indexing_technique": {
"type": "string",
"enum": [
"high_quality",
"economy"
],
"nullable": true,
"description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
},
"permission": {
"type": "string",
"enum": [
"only_me",
"all_team_members",
"partial_members"
],
"description": "控制谁可以访问此知识库。`only_me` 仅限创建者，`all_team_members` 授权整个工作区访问，`partial_members` 授权指定成员访问。"
},
"embedding_model": {
"type": "string",
"description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。"
},
"embedding_model_provider": {
"type": "string",
"description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
},
"partial_member_list": {
"type": "array",
"description": "当 `permission` 为 `partial_members` 时有访问权限的团队成员列表。",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "要授予访问权限的团队成员 ID。"
}
}
}
},
"external_retrieval_model": {
"type": "object",
"description": "外部知识库的检索设置。",
"properties": {
"top_k": {
"type": "integer",
"description": "返回的最大结果数。"
},
"score_threshold": {
"type": "number",
"description": "用于过滤结果的最低相关性分数阈值。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "是否启用分数阈值过滤。"
}
}
},
"external_knowledge_id": {
"type": "string",
"description": "外部知识库的 ID。"
},
"external_knowledge_api_id": {
"type": "string",
"description": "外部知识库 API 连接的 ID。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "知识库更新成功。",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Dataset"
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"name": "Product Documentation",
"description": "产品 API 技术文档",
"provider": "vendor",
"permission": "only_me",
"data_source_type": null,
"indexing_technique": "high_quality",
"app_count": 0,
"document_count": 0,
"word_count": 0,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"author_name": "admin",
"created_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"updated_at": 1741267200,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "openai",
"embedding_available": true,
"retrieval_model_dict": {
"search_method": "semantic_search",
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"weights": null,
"top_k": 3,
"score_threshold_enabled": false,
"score_threshold": null
},
"tags": [],
"doc_form": "text_model",
"external_knowledge_info": null,
"external_retrieval_model": null,
"doc_metadata": [],
"built_in_field_enabled": true,
"pipeline_id": null,
"runtime_mode": null,
"chunk_structure": null,
"icon_info": null,
"summary_index_setting": null,
"is_published": false,
"total_documents": 0,
"total_available_documents": 0,
"enable_api": true,
"is_multimodal": false,
"maintainer": "admin",
"partial_member_list": []
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"知识库"
],
"summary": "删除知识库",
"description": "永久删除知识库及其所有文档。",
"operationId": "deleteDataset",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/document/create-by-text": {
"post": {
"tags": [
"文档"
],
"summary": "从文本创建文档",
"description": "通过纯文本内容创建文档。文档将异步处理，使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。",
"operationId": "createDocumentFromText",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"text"
],
"properties": {
"name": {
"type": "string",
"description": "文档名称。"
},
"text": {
"type": "string",
"description": "文档文本内容。"
},
"indexing_technique": {
"type": "string",
"enum": [
"high_quality",
"economy"
],
"description": "向知识库添加首个文档时必填。后续文档如果省略此字段，将继承知识库的索引方式。`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
},
"doc_form": {
"type": "string",
"enum": [
"text_model",
"hierarchical_model",
"qa_model"
],
"default": "text_model",
"description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。"
},
"doc_language": {
"type": "string",
"default": "English",
"description": "用于处理优化的文档语言。"
},
"process_rule": {
"type": "object",
"description": "分块处理规则。",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"automatic",
"custom",
"hierarchical"
],
"description": "处理模式。`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。"
},
"rules": {
"type": "object",
"properties": {
"pre_processing_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"remove_stopwords",
"remove_extra_spaces",
"remove_urls_emails"
],
"description": "规则标识符。"
},
"enabled": {
"type": "boolean",
"description": "该预处理规则是否启用。"
}
}
}
},
"segmentation": {
"type": "object",
"properties": {
"separator": {
"type": "string",
"default": "\n",
"description": "用于拆分文本的自定义分隔符。"
},
"max_tokens": {
"type": "integer",
"description": "每个分段的最大令牌数。"
},
"chunk_overlap": {
"type": "integer",
"default": 0,
"description": "分段之间的令牌重叠数。"
}
}
}
}
}
}
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
},
"embedding_model": {
"type": "string",
"description": "嵌入模型名称。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `model` 字段值。"
},
"embedding_model_provider": {
"type": "string",
"description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
},
"original_document_id": {
"type": "string",
"description": "用于版本控制的原始文档 ID。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "文档创建成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "用于跟踪索引进度的批次 ID。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 0,
"indexing_status": "indexing",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "indexing",
"word_count": 0,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 未找到有效的模型供应商凭据。前往 Settings -> Model Provider 补全供应商凭据。\n- `invalid_param` : 添加首个文档时必须提供 `indexing_technique`，或 `doc_form` 无效。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_indexing": {
"summary": "invalid_param (indexing_technique)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "indexing_technique is required."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 文档数量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (documents limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The number of documents has reached the limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/document/create-by-file": {
"post": {
"tags": [
"文档"
],
"summary": "从文件创建文档",
"description": "通过上传文件创建文档。支持常见文档格式（PDF、TXT、DOCX 等）。处理过程为异步，使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。",
"operationId": "createDocumentFromFile",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "要上传的文件。"
},
"data": {
"type": "string",
"description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/api-reference/文档/从文本创建文档) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。",
"example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "文档创建成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "用于跟踪索引进度的批次 ID。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 0,
"indexing_status": "indexing",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "indexing",
"word_count": 0,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `no_file_uploaded` : 请上传文件。\n- `too_many_files` : 仅允许上传一个文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。前往 Settings -> Model Provider 补全供应商凭据。\n- `invalid_param` : 不支持外部知识库，缺少 `indexing_technique`，或缺少 `process_rule`。",
"content": {
"application/json": {
"examples": {
"no_file_uploaded": {
"summary": "no_file_uploaded",
"value": {
"status": 400,
"code": "no_file_uploaded",
"message": "Please upload your file."
}
},
"too_many_files": {
"summary": "too_many_files",
"value": {
"status": 400,
"code": "too_many_files",
"message": "Only one file is allowed."
}
},
"filename_not_exists_error": {
"summary": "filename_not_exists_error",
"value": {
"status": 400,
"code": "filename_not_exists_error",
"message": "The specified filename does not exist."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_external": {
"summary": "invalid_param (external)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "External datasets are not supported."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 文档数量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (documents limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The number of documents has reached the limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents": {
"get": {
"tags": [
"文档"
],
"summary": "获取知识库的文档列表",
"description": "返回知识库中的文档分页列表。支持按关键词和索引状态进行筛选。",
"operationId": "listDocuments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1
},
"description": "要获取的页码。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "每页的项目数量。服务器上限为 `100`。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "按文档名称筛选的搜索关键词。"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"queuing",
"indexing",
"paused",
"error",
"available",
"disabled",
"archived"
]
},
"description": "按显示状态筛选。"
}
],
"responses": {
"200": {
"description": "文档列表。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "文档对象数组。",
"items": {
"$ref": "#/components/schemas/Document"
}
},
"has_more": {
"type": "boolean",
"description": "下一页是否还有更多项目。"
},
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"total": {
"type": "integer",
"description": "匹配条目的总数。"
},
"page": {
"type": "integer",
"description": "当前页码。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 知识库未找到。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}": {
"get": {
"tags": [
"文档"
],
"summary": "获取文档详情",
"description": "获取指定文档的详细信息，包括索引状态、元数据和处理统计信息。",
"operationId": "getDocumentDetail",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "metadata",
"in": "query",
"schema": {
"type": "string",
"enum": [
"all",
"only",
"without"
],
"default": "all"
},
"description": "`all` 返回所有字段（包括元数据）。`only` 仅返回 `id`、`doc_type` 和 `doc_metadata`。`without` 返回除 `doc_metadata` 外的所有字段。"
}
],
"responses": {
"200": {
"description": "文档详情。响应结构根据 `metadata` 查询参数的不同而变化。当 `metadata` 为 `only` 时，仅返回 `id`、`doc_type` 和 `doc_metadata`。当 `metadata` 为 `without` 时，省略 `doc_type` 和 `doc_metadata`。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "文档标识符。"
},
"position": {
"type": "integer",
"description": "在知识库中的位置索引。"
},
"data_source_type": {
"type": "string",
"description": "文档的上传方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。"
},
"data_source_info": {
"type": "object",
"description": "数据源详情。文件上传时，此详情接口在 `upload_file` 下返回完整的文件对象，而列表接口仅返回 `upload_file_id`。",
"properties": {
"upload_file": {
"type": "object",
"description": "上传文件的详情。当 `data_source_type` 为 `upload_file` 时返回。",
"properties": {
"id": {
"type": "string",
"description": "文件标识符。"
},
"name": {
"type": "string",
"description": "原始文件名。"
},
"size": {
"type": "integer",
"description": "文件大小（字节）。"
},
"extension": {
"type": "string",
"description": "文件扩展名。"
},
"mime_type": {
"type": "string",
"description": "文件的 MIME 类型。"
},
"created_by": {
"type": "string",
"description": "上传该文件的用户 ID。"
},
"created_at": {
"type": "integer",
"description": "文件上传的 Unix 时间戳。"
}
}
}
}
},
"dataset_process_rule_id": {
"type": "string",
"description": "应用于该文档的处理规则 ID。"
},
"dataset_process_rule": {
"type": "object",
"description": "知识库级别的处理规则配置。"
},
"document_process_rule": {
"type": "object",
"description": "文档级别的处理规则配置。"
},
"name": {
"type": "string",
"description": "文档名称。"
},
"created_from": {
"type": "string",
"description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。"
},
"created_by": {
"type": "string",
"description": "创建该文档的用户 ID。"
},
"created_at": {
"type": "number",
"description": "文档创建的 Unix 时间戳。"
},
"tokens": {
"type": "integer",
"description": "文档中的令牌数。"
},
"indexing_status": {
"type": "string",
"description": "当前索引状态，例如 `waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed`、`error`、`paused`。"
},
"error": {
"type": "string",
"nullable": true,
"description": "索引失败时的错误消息，否则为 `null`。"
},
"enabled": {
"type": "boolean",
"description": "该文档是否启用检索。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "文档被禁用的 Unix 时间戳，启用时为 `null`。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "禁用该文档的用户 ID，启用时为 `null`。"
},
"archived": {
"type": "boolean",
"description": "文档是否已归档。"
},
"display_status": {
"type": "string",
"description": "适合 UI 显示的索引状态。"
},
"hit_count": {
"type": "integer",
"description": "该文档被检索的次数。"
},
"doc_form": {
"type": "string",
"description": "文档分块模式。`text_model` 表示标准文本，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对。"
},
"doc_language": {
"type": "string",
"description": "文档内容的语言。"
},
"doc_type": {
"type": "string",
"nullable": true,
"description": "文档类型分类，未设置时为 `null`。"
},
"doc_metadata": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "元数据字段标识符。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
},
"type": {
"type": "string",
"description": "元数据字段类型。"
},
"value": {
"type": "string",
"description": "此文档的元数据字段值。"
}
}
},
"description": "此文档的自定义元数据键值对。"
},
"completed_at": {
"type": "number",
"nullable": true,
"description": "处理完成的 Unix 时间戳，尚未完成时为 `null`。"
},
"updated_at": {
"type": "number",
"nullable": true,
"description": "最后更新的 Unix 时间戳，从未更新时为 `null`。"
},
"indexing_latency": {
"type": "number",
"nullable": true,
"description": "索引耗时（秒），未完成时为 `null`。"
},
"segment_count": {
"type": "integer",
"description": "文档中的分段数。"
},
"average_segment_length": {
"type": "number",
"description": "分段的平均字符长度。"
},
"summary_index_status": {
"type": "string",
"nullable": true,
"description": "摘要索引的状态，未启用摘要索引时为 `null`。"
},
"need_summary": {
"type": "boolean",
"description": "该文档是否需要生成摘要。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"dataset_process_rule": {
"id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"mode": "custom"
},
"document_process_rule": {
"mode": "custom",
"rules": {
"pre_processing_rules": [],
"segmentation": {
"separator": "###",
"max_tokens": 500,
"chunk_overlap": 50
}
}
},
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"hit_count": 0,
"doc_form": "text_model",
"doc_language": "English",
"doc_type": null,
"doc_metadata": [],
"completed_at": 1741267260,
"updated_at": 1741267260,
"indexing_latency": 60.0,
"segment_count": 5,
"average_segment_length": 70.0,
"summary_index_status": null,
"need_summary": false
}
}
}
}
}
},
"400": {
"description": "`invalid_metadata` : `metadata` 查询参数的值无效（必须为 `all`、`only` 或 `without`）。",
"content": {
"application/json": {
"examples": {
"invalid_metadata": {
"summary": "invalid_metadata",
"value": {
"status": 400,
"code": "invalid_metadata",
"message": "Invalid metadata value: only"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 无权限。\n- `forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (no permission)",
"value": {
"status": 403,
"code": "forbidden",
"message": "No permission."
}
},
"forbidden_2": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到文档。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"文档"
],
"summary": "删除文档",
"description": "从知识库中永久删除文档及其所有分段。",
"operationId": "deleteDocument",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `archived_document_immutable` : 已归档的文档不可编辑。\n- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"archived_document_immutable": {
"summary": "archived_document_immutable",
"value": {
"status": 403,
"code": "archived_document_immutable",
"message": "The archived document is not editable."
}
},
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 文档不存在。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document Not Exists."
}
}
}
}
}
}
}
},
"patch": {
"tags": [
"文档"
],
"summary": "更新文档",
"description": "通过上传新文件更新现有文档。这是基于文件更新文档的规范端点。将重新触发索引，使用返回的 `batch` ID 配合 [获取文档嵌入状态（进度）](/api-reference/文档/获取文档嵌入状态（进度）) 跟踪进度。",
"operationId": "updateDocument",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "要上传的文件。"
},
"data": {
"type": "string",
"description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/api-reference/文档/从文本创建文档) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。",
"example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "文档更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "用于跟踪索引进度的批次 ID。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 未找到有效的模型供应商凭据。前往 Settings -> Model Provider 补全供应商凭据。\n- `invalid_param` : 文档不可用，无法更新（仅可更新处于可用状态的文档）。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_not_available": {
"summary": "invalid_param (not available)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document is not available"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
},
"413": {
"description": "`file_too_large` : 文件大小超出限制。",
"content": {
"application/json": {
"examples": {
"file_too_large": {
"summary": "file_too_large",
"value": {
"status": 413,
"code": "file_too_large",
"message": "File size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_file_type` : 不支持的文件类型。",
"content": {
"application/json": {
"examples": {
"unsupported_file_type": {
"summary": "unsupported_file_type",
"value": {
"status": 415,
"code": "unsupported_file_type",
"message": "File type not allowed."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/download": {
"get": {
"tags": [
"文档"
],
"summary": "下载文档",
"description": "获取文档原始上传文件的签名下载 URL。",
"operationId": "downloadDocumentZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
}
],
"responses": {
"200": {
"description": "下载 URL 生成成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "用于下载原始上传文件的签名 URL。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"url": "https://storage.example.com/datasets/documents/abc123/original-file.pdf?token=xyz789&expires=1741353600"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 无权限。\n- `forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (no permission)",
"value": {
"status": 403,
"code": "forbidden",
"message": "No permission."
}
},
"forbidden_2": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到文档。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{batch}/indexing-status": {
"get": {
"tags": [
"文档"
],
"summary": "获取文档嵌入状态（进度）",
"description": "检查批量文档的索引进度。返回每个文档的当前处理阶段和分段完成计数。请轮询此接口直到 `indexing_status` 变为 `completed` 或 `error`。状态按以下顺序推进：`waiting` → `parsing` → `cleaning` → `splitting` → `indexing` → `completed`。",
"operationId": "getDocumentIndexingStatus",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "batch",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "创建文档时返回的批次 ID。"
}
],
"responses": {
"200": {
"description": "批次中文档的索引状态。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "文档标识符。"
},
"indexing_status": {
"type": "string",
"description": "当前索引状态：`waiting`、`parsing`、`cleaning`、`splitting`、`indexing`、`completed` 或 `error`。"
},
"processing_started_at": {
"type": "number",
"description": "处理开始的 Unix 时间戳。"
},
"parsing_completed_at": {
"type": "number",
"description": "解析完成的 Unix 时间戳。"
},
"cleaning_completed_at": {
"type": "number",
"description": "清洗完成的 Unix 时间戳。"
},
"splitting_completed_at": {
"type": "number",
"description": "拆分完成的 Unix 时间戳。"
},
"completed_at": {
"type": "number",
"description": "索引完成的 Unix 时间戳。"
},
"paused_at": {
"type": "number",
"nullable": true,
"description": "索引暂停的时间戳。未暂停时为 `null`。"
},
"error": {
"type": "string",
"nullable": true,
"description": "索引失败时的错误信息。无错误时为 `null`。"
},
"stopped_at": {
"type": "number",
"nullable": true,
"description": "索引停止的时间戳。未停止时为 `null`。"
},
"completed_segments": {
"type": "integer",
"description": "已索引的分段数。"
},
"total_segments": {
"type": "integer",
"description": "待索引的分段总数。"
}
}
},
"description": "索引状态条目列表。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"indexing_status": "completed",
"processing_started_at": 1741267200,
"parsing_completed_at": 1741267200,
"cleaning_completed_at": 1741267200,
"splitting_completed_at": 1741267200,
"completed_at": 1741267200,
"paused_at": null,
"error": null,
"stopped_at": null,
"completed_segments": 5,
"total_segments": 5
}
]
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 知识库未找到。/ 文档未找到。",
"content": {
"application/json": {
"examples": {
"dataset_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"documents_not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Documents not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/update-by-text": {
"post": {
"tags": [
"文档"
],
"summary": "用文本更新文档",
"description": "更新现有文档的文本内容、名称或处理配置。内容变更时将重新触发索引。",
"operationId": "updateDocumentByText",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "文档名称。当提供 `text` 时必填。"
},
"text": {
"type": "string",
"description": "文档文本内容。"
},
"process_rule": {
"type": "object",
"description": "分块处理规则。",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"automatic",
"custom",
"hierarchical"
],
"description": "处理模式。`automatic` 使用内置规则，`custom` 允许手动配置，`hierarchical` 启用父子分段结构（配合 `doc_form: hierarchical_model` 使用）。"
},
"rules": {
"type": "object",
"properties": {
"pre_processing_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"remove_stopwords",
"remove_extra_spaces",
"remove_urls_emails"
],
"description": "规则标识符。"
},
"enabled": {
"type": "boolean",
"description": "该预处理规则是否启用。"
}
}
}
},
"segmentation": {
"type": "object",
"properties": {
"separator": {
"type": "string",
"default": "\n",
"description": "用于拆分文本的自定义分隔符。"
},
"max_tokens": {
"type": "integer",
"description": "每个分段的最大令牌数。"
},
"chunk_overlap": {
"type": "integer",
"default": 0,
"description": "分段之间的令牌重叠数。"
}
}
}
}
}
}
},
"doc_form": {
"type": "string",
"enum": [
"text_model",
"hierarchical_model",
"qa_model"
],
"default": "text_model",
"description": "`text_model` 为标准文本分段，`hierarchical_model` 为父子分段结构，`qa_model` 为问答对提取。"
},
"doc_language": {
"type": "string",
"default": "English",
"description": "用于处理优化的文档语言。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "文档更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "用于跟踪索引进度的批次 ID。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 未找到有效的模型供应商凭据。前往 Settings -> Model Provider 补全供应商凭据。\n- `invalid_param` : 提供 `text` 时必须提供 `name`，或 `doc_form` 无效。\n- `invalid_param` : 文档不可用，无法更新（仅可更新处于可用状态的文档）。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_name": {
"summary": "invalid_param (name required)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "name is required when text is provided."
}
},
"invalid_param_not_available": {
"summary": "invalid_param (not available)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document is not available"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/update-by-file": {
"post": {
"tags": [
"文档"
],
"summary": "用文件更新文档",
"description": "已弃用。改用 [更新文档](/api-reference/文档/更新文档)。通过上传新文件更新现有文档并重新触发索引。",
"operationId": "updateDocumentByFile",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "要上传的文件。"
},
"data": {
"type": "string",
"description": "包含配置信息的 JSON 字符串。接受与 [从文本创建文档](/api-reference/文档/从文本创建文档) 相同的字段（`indexing_technique`、`doc_form`、`doc_language`、`process_rule`、`retrieval_model`、`embedding_model`、`embedding_model_provider`），但不包括 `name` 和 `text`。",
"example": "{\"indexing_technique\":\"high_quality\",\"doc_form\":\"text_model\",\"doc_language\":\"English\",\"process_rule\":{\"mode\":\"automatic\"}}"
}
}
}
}
}
},
"responses": {
"200": {
"description": "文档更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
},
"batch": {
"type": "string",
"description": "用于跟踪索引进度的批次 ID。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"position": 1,
"data_source_type": "upload_file",
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_detail_dict": {
"upload_file": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "guide.txt",
"size": 2048,
"extension": "txt",
"mime_type": "text/plain",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200
}
},
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"name": "guide.txt",
"created_from": "api",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"tokens": 512,
"indexing_status": "completed",
"error": null,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"archived": false,
"display_status": "available",
"word_count": 350,
"hit_count": 0,
"doc_form": "text_model",
"doc_metadata": [],
"summary_index_status": null,
"need_summary": false
},
"batch": "20250306150245647595"
}
}
}
}
}
},
"400": {
"description": "- `too_many_files` : 仅允许上传一个文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。前往 Settings -> Model Provider 补全供应商凭据。\n- `invalid_param` : 文档不可用，无法更新（仅可更新处于可用状态的文档）。",
"content": {
"application/json": {
"examples": {
"too_many_files": {
"summary": "too_many_files",
"value": {
"status": 400,
"code": "too_many_files",
"message": "Only one file is allowed."
}
},
"filename_not_exists_error": {
"summary": "filename_not_exists_error",
"value": {
"status": 400,
"code": "filename_not_exists_error",
"message": "The specified filename does not exist."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_not_available": {
"summary": "invalid_param (not available)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document is not available"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
},
"413": {
"description": "`file_too_large` : 文件大小超出限制。",
"content": {
"application/json": {
"examples": {
"file_too_large": {
"summary": "file_too_large",
"value": {
"status": 413,
"code": "file_too_large",
"message": "File size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_file_type` : 不支持的文件类型。",
"content": {
"application/json": {
"examples": {
"unsupported_file_type": {
"summary": "unsupported_file_type",
"value": {
"status": 415,
"code": "unsupported_file_type",
"message": "File type not allowed."
}
}
}
}
}
}
},
"deprecated": true
}
},
"/datasets/{dataset_id}/documents/download-zip": {
"post": {
"tags": [
"文档"
],
"summary": "批量下载文档（ZIP）",
"description": "将多个上传文件文档下载为单个 ZIP 压缩包。最多接受 `100` 个文档 ID。",
"operationId": "downloadDocumentsZipZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"document_ids"
],
"properties": {
"document_ids": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "string",
"format": "uuid"
},
"description": "要包含在 ZIP 压缩包中的文档 ID 数组。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "包含所请求文档的 ZIP 压缩包。",
"content": {
"application/zip": {
"schema": {
"type": "string",
"format": "binary",
"description": "ZIP 压缩包二进制流。"
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到文档。\n- `not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/status/{action}": {
"patch": {
"tags": [
"文档"
],
"summary": "批量更新文档状态",
"description": "批量启用、禁用、归档或取消归档多个文档。",
"operationId": "batchUpdateDocumentStatus",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "action",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"enable",
"disable",
"archive",
"un_archive"
]
},
"description": "`enable` 启用，`disable` 停用，`archive` 归档，`un_archive` 从归档中恢复。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"document_ids"
],
"properties": {
"document_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "要更新的文档 ID 列表。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "文档更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "操作结果。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"result": "success"
}
}
}
}
}
},
"400": {
"description": "`invalid_action` : 操作无效，或某个文档处于不允许该操作的状态（例如仍在索引中或尚未处理完成）。",
"content": {
"application/json": {
"examples": {
"invalid_action": {
"summary": "invalid_action",
"value": {
"status": 400,
"code": "invalid_action",
"message": "Invalid action."
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 知识库未找到。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/segments": {
"post": {
"tags": [
"分段"
],
"summary": "向文档添加分段",
"description": "在文档中创建一个或多个分段。每个分段的 `content` 为必填项；对于问答模式（`qa_model`）文档，`answer` 也为必填项。`keywords` 为可选项。",
"operationId": "createSegments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"segments"
],
"properties": {
"segments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "分段文本内容。",
"minLength": 1
},
"answer": {
"type": "string",
"description": "QA 模式的回答内容。"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "分段的关键词。"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "附件文件 ID。"
}
},
"required": [
"content"
]
},
"description": "要创建的分段对象数组。",
"minItems": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "分段创建成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Segment"
},
"description": "已创建的分段列表。"
},
"doc_form": {
"type": "string",
"description": "该文档使用的分块模式。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
}
],
"doc_form": "text_model"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 未找到有效的模型供应商凭据。前往 Settings -> Model Provider 补全供应商凭据。\n- `invalid_param` : 分段校验失败（例如内容为空）或超出分段数量上限。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_limit": {
"summary": "invalid_param (segments limit)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Exceeded maximum segments limit of 1000."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 文档尚未处理完成。\n- `not_found` : 文档已被禁用。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document is not completed."
}
},
"not_found_4": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document is disabled."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"分段"
],
"summary": "从文档获取分段",
"description": "返回文档内分段的分页列表。支持按关键词和状态筛选。",
"operationId": "listSegments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1
},
"description": "要获取的页码。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20
},
"description": "每页的项目数量。服务器上限为 `100`。"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "按索引状态筛选分段，例如 `completed`、`indexing`、`error`。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "搜索关键词。"
}
],
"responses": {
"200": {
"description": "分段列表。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Segment"
},
"description": "分段列表。"
},
"doc_form": {
"type": "string",
"description": "该文档使用的分块模式。"
},
"total": {
"type": "integer",
"description": "匹配的分段总数。"
},
"has_more": {
"type": "boolean",
"description": "下一页是否还有更多项目。"
},
"limit": {
"type": "integer",
"description": "每页条目数。"
},
"page": {
"type": "integer",
"description": "当前页码。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
}
],
"doc_form": "text_model",
"total": 1,
"has_more": false,
"limit": 20,
"page": 1
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": {
"get": {
"tags": [
"分段"
],
"summary": "获取文档中的分段详情",
"description": "获取指定分段的详细信息，包括内容、关键词和索引状态。",
"operationId": "getSegmentDetail",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"responses": {
"200": {
"description": "分段详情。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Segment"
},
"doc_form": {
"type": "string",
"description": "该文档使用的分块模式。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
},
"doc_form": "text_model"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
},
"post": {
"tags": [
"分段"
],
"summary": "更新文档中的分段",
"description": "更新分段的内容、关键词或回答。修改后的分段将重新触发索引。",
"operationId": "updateSegment",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"segment"
],
"properties": {
"segment": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "分段文本内容。"
},
"answer": {
"type": "string",
"description": "QA 模式的回答内容。"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "分段的关键词。"
},
"enabled": {
"type": "boolean",
"description": "分段是否已启用。"
},
"regenerate_child_chunks": {
"type": "boolean",
"default": false,
"description": "是否重新生成子分段。"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "附件文件 ID。"
},
"summary": {
"type": "string",
"nullable": true,
"description": "摘要索引的摘要内容。"
}
},
"description": "要更新的分段数据。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "分段更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/Segment"
},
"doc_form": {
"type": "string",
"description": "该文档使用的分块模式。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 0,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"child_chunks": [],
"attachments": [],
"summary": null
},
"doc_form": "text_model"
}
}
}
}
}
},
"400": {
"description": "- `provider_not_initialize` : 未找到有效的模型供应商凭据。前往 Settings -> Model Provider 补全供应商凭据。\n- `invalid_param` : 分段正在索引中或已被禁用，无法更新，或索引配置无效。",
"content": {
"application/json": {
"examples": {
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"invalid_param_state": {
"summary": "invalid_param (state)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Segment is indexing, please try again later"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"分段"
],
"summary": "删除文档中的分段",
"description": "从文档中永久删除一个分段。",
"operationId": "deleteSegment",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": {
"post": {
"tags": [
"分段"
],
"summary": "创建子分段",
"description": "在父分段下创建子分段。适用于使用父子（`hierarchical_model`）分块模式的文档。",
"operationId": "createChildChunk",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"description": "子分段文本内容。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "子分段创建成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/ChildChunk"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": {
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"content": "Dify is an open-source platform.",
"position": 1,
"word_count": 6,
"type": "customized",
"created_at": 1741267200,
"updated_at": 1741267200
}
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 创建子分段索引失败。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Create child chunk index failed."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"分段"
],
"summary": "获取子分段",
"description": "返回特定父分段下子分段的分页列表。",
"operationId": "getChildChunks",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
},
"description": "要获取的页码。"
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 20,
"minimum": 1
},
"description": "每页的项目数量。服务器上限为 `100`。"
},
{
"name": "keyword",
"in": "query",
"schema": {
"type": "string"
},
"description": "搜索关键词。"
}
],
"responses": {
"200": {
"description": "子分段列表。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChildChunk"
},
"description": "子分段列表。"
},
"total": {
"type": "integer",
"description": "子分段总数。"
},
"total_pages": {
"type": "integer",
"description": "总页数。"
},
"page": {
"type": "integer",
"description": "当前页码。"
},
"limit": {
"type": "integer",
"description": "每页条目数。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"content": "Dify is an open-source platform.",
"position": 1,
"word_count": 6,
"type": "customized",
"created_at": 1741267200,
"updated_at": 1741267200
}
],
"total": 1,
"total_pages": 1,
"page": 1,
"limit": 20
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": {
"patch": {
"tags": [
"分段"
],
"summary": "更新子分段",
"description": "更新现有子分段的内容。",
"operationId": "updateChildChunk",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
},
{
"name": "child_chunk_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "子分段 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"description": "子分段文本内容。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "子分段更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/ChildChunk"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": {
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"content": "Dify is an open-source platform.",
"position": 1,
"word_count": 6,
"type": "customized",
"created_at": 1741267200,
"updated_at": 1741267200
}
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 更新子分段索引失败。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Update child chunk index failed."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 向量空间容量已达到您订阅套餐的上限。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (vector space)",
"value": {
"status": 403,
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_4": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。\n- `not_found` : 未找到子分段。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
},
"not_found_4": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Child chunk not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"分段"
],
"summary": "删除子分段",
"description": "从父分段中永久删除一个子分段。",
"operationId": "deleteChildChunk",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "文档 ID."
},
{
"name": "segment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Chunk ID."
},
{
"name": "child_chunk_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "子分段 ID。"
}
],
"responses": {
"204": {
"description": "Success."
},
"400": {
"description": "`invalid_param` : 删除子分段索引失败。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Delete child chunk index failed."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。\n- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
},
"forbidden_3": {
"summary": "forbidden (upgrade plan)",
"value": {
"status": 403,
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
}
}
}
}
}
},
"404": {
"description": "- `not_found` : 未找到知识库。\n- `not_found` : 未找到文档。\n- `not_found` : 未找到分段。\n- `not_found` : 未找到子分段。",
"content": {
"application/json": {
"examples": {
"not_found_1": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
},
"not_found_2": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Document not found."
}
},
"not_found_3": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Segment not found."
}
},
"not_found_4": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Child chunk not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/retrieve": {
"post": {
"tags": [
"知识库"
],
"summary": "从知识库检索分段 / 测试检索",
"description": "对知识库执行搜索查询，检索最相关的分段。此接口可用于生产环境检索和测试检索。",
"operationId": "retrieveSegments",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"maxLength": 250,
"description": "搜索查询文本。"
},
"retrieval_model": {
"$ref": "#/components/schemas/RetrievalModel",
"description": "检索模型配置。控制查询此知识库时如何搜索和排序分段。"
},
"attachment_ids": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "要包含在检索上下文中的附件 ID 列表。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "检索结果。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "object",
"description": "原始查询对象。",
"properties": {
"content": {
"type": "string",
"description": "查询文本。"
}
}
},
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"segment": {
"type": "object",
"description": "从知识库中匹配的分段。",
"properties": {
"id": {
"type": "string",
"description": "分段的唯一标识符。"
},
"position": {
"type": "integer",
"description": "分段在文档中的位置。"
},
"document_id": {
"type": "string",
"description": "该分段所属文档的 ID。"
},
"content": {
"type": "string",
"description": "分段的文本内容。"
},
"sign_content": {
"type": "string",
"description": "用于完整性验证的签名内容哈希。"
},
"answer": {
"type": "string",
"description": "回答内容，用于问答模式文档。"
},
"word_count": {
"type": "integer",
"description": "分段内容的字数。"
},
"tokens": {
"type": "integer",
"description": "分段内容的令牌数。"
},
"keywords": {
"type": "array",
"description": "与该分段关联的关键词，用于基于关键词的检索。",
"items": {
"type": "string"
}
},
"index_node_id": {
"type": "string",
"description": "向量存储中索引节点的 ID。"
},
"index_node_hash": {
"type": "string",
"description": "索引内容的哈希值，用于检测变更。"
},
"hit_count": {
"type": "integer",
"description": "该分段在检索查询中被匹配的次数。"
},
"enabled": {
"type": "boolean",
"description": "该分段是否启用检索。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "分段被禁用的时间戳。启用时为 `null`。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "禁用该分段的用户 ID。启用时为 `null`。"
},
"status": {
"type": "string",
"description": "分段的索引状态。"
},
"created_by": {
"type": "string",
"description": "创建该分段的用户 ID。"
},
"created_at": {
"type": "number",
"description": "创建时间戳（Unix 纪元，单位为秒）。"
},
"indexing_at": {
"type": "number",
"nullable": true,
"description": "索引开始的时间戳。尚未开始时为 `null`。"
},
"completed_at": {
"type": "number",
"nullable": true,
"description": "索引完成的时间戳。尚未完成时为 `null`。"
},
"error": {
"type": "string",
"nullable": true,
"description": "索引失败时的错误消息。无错误时为 `null`。"
},
"stopped_at": {
"type": "number",
"nullable": true,
"description": "索引停止的时间戳。未停止时为 `null`。"
},
"document": {
"type": "object",
"description": "匹配分段的父文档信息。",
"properties": {
"id": {
"type": "string",
"description": "文档的唯一标识符。"
},
"data_source_type": {
"type": "string",
"description": "文档的创建方式。"
},
"name": {
"type": "string",
"description": "文档名称。"
},
"doc_type": {
"type": "string",
"nullable": true,
"description": "文档类型分类。未设置时为 `null`。"
},
"doc_metadata": {
"type": "object",
"nullable": true,
"description": "文档的元数据值。未配置元数据时为 `null`。"
}
}
}
}
},
"child_chunks": {
"type": "array",
"description": "使用分层索引时，分段内匹配的子分段。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "子分段的唯一标识符。"
},
"content": {
"type": "string",
"description": "子分段的文本内容。"
},
"position": {
"type": "integer",
"description": "子分段在父分段中的位置。"
},
"score": {
"type": "number",
"description": "子分段的相关性得分。"
}
}
}
},
"score": {
"type": "number",
"description": "相关性得分。"
},
"tsne_position": {
"type": "object",
"nullable": true,
"description": "t-SNE 可视化位置。"
},
"files": {
"type": "array",
"description": "附加到该分段的文件。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "附件文件标识符。"
},
"name": {
"type": "string",
"description": "原始文件名。"
},
"size": {
"type": "integer",
"description": "文件大小（字节）。"
},
"extension": {
"type": "string",
"description": "文件扩展名。"
},
"mime_type": {
"type": "string",
"description": "文件的 MIME 类型。"
},
"source_url": {
"type": "string",
"description": "访问附件的 URL。"
}
}
}
},
"summary": {
"type": "string",
"nullable": true,
"description": "通过摘要索引检索到的摘要内容。"
}
}
},
"description": "匹配的检索记录列表。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"query": {
"content": "What is Dify?"
},
"records": [
{
"segment": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 1,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"data_source_type": "upload_file",
"name": "guide.txt",
"doc_type": null,
"doc_metadata": null
}
},
"child_chunks": [],
"score": 0.92,
"tsne_position": null,
"files": [],
"summary": null
}
]
}
}
}
}
}
},
"400": {
"description": "- `dataset_not_initialized` : 知识库仍在初始化或索引中。请稍候。\n- `provider_not_initialize` : 未找到有效的模型供应商凭据。请前往设置 -> 模型供应商完成凭据配置。\n- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.\n- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 model.\n- `completion_request_error` : Completion request failed.\n- `invalid_param` : Invalid parameter value.",
"content": {
"application/json": {
"examples": {
"dataset_not_initialized": {
"summary": "dataset_not_initialized",
"value": {
"status": 400,
"code": "dataset_not_initialized",
"message": "The dataset is still being initialized or indexing. Please wait a moment."
}
},
"provider_not_initialize": {
"summary": "provider_not_initialize",
"value": {
"status": 400,
"code": "provider_not_initialize",
"message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials."
}
},
"provider_quota_exceeded": {
"summary": "provider_quota_exceeded",
"value": {
"status": 400,
"code": "provider_quota_exceeded",
"message": "Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials."
}
},
"model_currently_not_support": {
"summary": "model_currently_not_support",
"value": {
"status": 400,
"code": "model_currently_not_support",
"message": "Dify Hosted OpenAI trial currently not support the GPT-4 model."
}
},
"completion_request_error": {
"summary": "completion_request_error",
"value": {
"status": 400,
"code": "completion_request_error",
"message": "Completion request failed."
}
},
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Invalid parameter value."
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 知识库未找到。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
},
"500": {
"description": "`internal_server_error` : 检索过程中发生内部错误。",
"content": {
"application/json": {
"examples": {
"internal_server_error": {
"summary": "internal_server_error",
"value": {
"status": 500,
"code": "internal_server_error",
"message": "An internal error occurred."
}
}
}
}
}
}
}
}
},
"/datasets/tags": {
"post": {
"tags": [
"标签"
],
"summary": "创建知识库标签",
"description": "创建新标签以组织知识库。",
"operationId": "createKnowledgeTag",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Tag name."
}
}
}
}
}
},
"responses": {
"200": {
"description": "标签创建成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "标签标识符。"
},
"name": {
"type": "string",
"description": "标签显示名称。"
},
"type": {
"type": "string",
"description": "标签类型。知识库标签始终为 `knowledge`。"
},
"binding_count": {
"type": "string",
"nullable": true,
"description": "绑定到该标签的知识库数量。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs",
"type": "knowledge",
"binding_count": "0"
}
}
}
}
}
}
}
},
"get": {
"tags": [
"标签"
],
"summary": "获取知识库标签列表",
"description": "返回工作区中所有知识库标签的列表。",
"operationId": "getKnowledgeTags",
"responses": {
"200": {
"description": "标签列表。",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "标签标识符。"
},
"name": {
"type": "string",
"description": "标签显示名称。"
},
"type": {
"type": "string",
"description": "标签类型。知识库标签始终为 `knowledge`。"
},
"binding_count": {
"type": "string",
"nullable": true,
"description": "绑定到该标签的知识库数量。"
}
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": [
{
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs",
"type": "knowledge",
"binding_count": "0"
}
]
}
}
}
}
}
}
},
"patch": {
"tags": [
"标签"
],
"summary": "修改知识库标签",
"description": "重命名现有的知识库标签。",
"operationId": "updateKnowledgeTag",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tag_id",
"name"
],
"properties": {
"tag_id": {
"type": "string",
"description": "要更新的标签 ID。"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "新标签名称。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "标签更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "标签标识符。"
},
"name": {
"type": "string",
"description": "标签显示名称。"
},
"type": {
"type": "string",
"description": "标签类型。知识库标签始终为 `knowledge`。"
},
"binding_count": {
"type": "string",
"nullable": true,
"description": "绑定到该标签的知识库数量。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs",
"type": "knowledge",
"binding_count": "0"
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"标签"
],
"summary": "删除知识库标签",
"description": "永久删除知识库标签。不会删除已被标记的知识库。",
"operationId": "deleteKnowledgeTag",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tag_id"
],
"properties": {
"tag_id": {
"type": "string",
"description": "要删除的标签 ID。"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Success."
}
}
}
},
"/datasets/tags/binding": {
"post": {
"tags": [
"标签"
],
"summary": "绑定标签到知识库",
"description": "将一个或多个标签绑定到知识库。一个知识库可以有多个标签。",
"operationId": "bindTagsToDataset",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tag_ids",
"target_id"
],
"properties": {
"tag_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "要绑定的标签 ID。"
},
"target_id": {
"type": "string",
"description": "知识库 ID。"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Success."
}
}
}
},
"/datasets/tags/unbinding": {
"post": {
"tags": [
"标签"
],
"summary": "解除标签与知识库的绑定",
"description": "从知识库中移除一个或多个标签。",
"operationId": "unbindTagFromDataset",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"target_id"
],
"properties": {
"tag_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "要解绑的标签 ID 列表。未提供旧版 `tag_id` 时必填。"
},
"tag_id": {
"type": "string",
"deprecated": true,
"description": "旧版单标签字段。服务端将其归一化为 `tag_ids`。新接入应使用 `tag_ids`。"
},
"target_id": {
"type": "string",
"description": "知识库 ID。"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Success."
}
}
}
},
"/datasets/{dataset_id}/tags": {
"get": {
"tags": [
"标签"
],
"summary": "获取知识库绑定的标签",
"description": "返回绑定到特定知识库的标签列表。",
"operationId": "queryDatasetTags",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"responses": {
"200": {
"description": "绑定到知识库的标签。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "标签标识符。"
},
"name": {
"type": "string",
"description": "标签显示名称。"
}
}
},
"description": "绑定到此知识库的标签列表。"
},
"total": {
"type": "integer",
"description": "绑定到该知识库的标签总数。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"id": "f4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
"name": "Product Docs"
}
],
"total": 1
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata": {
"post": {
"tags": [
"元数据"
],
"summary": "创建元数据字段",
"description": "为知识库创建自定义元数据字段。元数据字段可用于为文档添加结构化信息标注。",
"operationId": "createMetadataFieldZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"string",
"number",
"time"
],
"description": "`string` 为文本值，`number` 为数值，`time` 为日期/时间值。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
}
}
}
}
}
},
"responses": {
"201": {
"description": "元数据字段创建成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "元数据字段标识符。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
},
"type": {
"type": "string",
"description": "元数据字段类型。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
"name": "author",
"type": "string"
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 元数据名称已存在、超过 255 个字符，或与内置字段冲突。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Metadata name already exists."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"get": {
"tags": [
"元数据"
],
"summary": "获取元数据字段列表",
"description": "返回知识库的所有元数据字段列表（包括自定义和内置字段），以及使用每个字段的文档数量。",
"operationId": "listMetadataFieldsZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"responses": {
"200": {
"description": "知识库的元数据字段。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"doc_metadata": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "元数据字段标识符。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
},
"type": {
"type": "string",
"description": "元数据字段类型。"
},
"count": {
"type": "integer",
"description": "使用该元数据字段的文档数量。"
}
}
},
"description": "元数据字段定义列表。"
},
"built_in_field_enabled": {
"type": "boolean",
"description": "该知识库是否启用了内置元数据字段。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"doc_metadata": [
{
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
"name": "author",
"type": "string",
"count": 3
}
],
"built_in_field_enabled": true
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata/{metadata_id}": {
"patch": {
"tags": [
"元数据"
],
"summary": "更新元数据字段",
"description": "重命名自定义元数据字段。",
"operationId": "updateMetadataFieldZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "metadata_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "元数据字段 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "新元数据字段名称。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "元数据字段更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "元数据字段标识符。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
},
"type": {
"type": "string",
"description": "元数据字段类型。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
"name": "author",
"type": "string"
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 元数据名称已存在、超过 255 个字符，或与内置字段冲突。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Metadata name already exists."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"元数据"
],
"summary": "删除元数据字段",
"description": "永久删除自定义元数据字段。使用此字段的文档将丢失其对应的元数据值。",
"operationId": "deleteMetadataFieldZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "metadata_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "元数据字段 ID。"
}
],
"responses": {
"204": {
"description": "Success."
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata/built-in": {
"get": {
"tags": [
"元数据"
],
"summary": "获取内置元数据字段",
"description": "返回系统提供的内置元数据字段列表（例如文档类型、来源 URL）。",
"operationId": "getBuiltInMetadataFieldsZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"responses": {
"200": {
"description": "内置元数据字段。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"fields": {
"type": "array",
"description": "系统提供的元数据字段列表。",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "内置字段标识符。`document_name` 表示文档标题，`uploader` 表示创建者，`upload_date` 表示创建时间，`last_update_date` 表示最后修改时间，`source` 表示文档来源。"
},
"type": {
"type": "string",
"description": "字段数据类型。文本值为 `string`，日期/时间值为 `time`。"
}
}
}
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"fields": [
{
"name": "document_name",
"type": "string"
},
{
"name": "uploader",
"type": "string"
},
{
"name": "upload_date",
"type": "time"
},
{
"name": "last_update_date",
"type": "time"
},
{
"name": "source",
"type": "string"
}
]
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/metadata/built-in/{action}": {
"post": {
"tags": [
"元数据"
],
"summary": "更新内置元数据字段",
"description": "启用或禁用知识库的内置元数据字段。",
"operationId": "toggleBuiltInMetadataFieldZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "action",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"enable",
"disable"
]
},
"description": "`enable` 启用内置元数据字段，`disable` 停用内置元数据字段。"
}
],
"responses": {
"200": {
"description": "内置元数据字段切换成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "操作结果。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"result": "success"
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/documents/metadata": {
"post": {
"tags": [
"元数据"
],
"summary": "批量更新文档元数据",
"description": "批量更新多个文档的元数据值。请求中的每个文档将接收指定的元数据键值对。",
"operationId": "batchUpdateDocumentMetadataZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"operation_data"
],
"properties": {
"operation_data": {
"type": "array",
"items": {
"type": "object",
"required": [
"document_id",
"metadata_list"
],
"properties": {
"document_id": {
"type": "string",
"description": "要更新元数据的文档 ID。"
},
"metadata_list": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "元数据字段 ID。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
},
"value": {
"description": "元数据值。可以是字符串、数字或 `null`。"
}
}
}
},
"partial_update": {
"type": "boolean",
"default": false,
"description": "是否部分更新元数据，保留未指定字段的现有值。"
}
}
},
"description": "文档元数据更新操作数组。每个条目将一个文档 ID 映射到其元数据键值对。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "文档元数据更新成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "操作结果。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"result": "success"
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 引用的文档不存在，或该知识库已有另一个元数据操作正在进行。",
"content": {
"application/json": {
"examples": {
"invalid_param_doc": {
"summary": "invalid_param (document)",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Document not found."
}
}
}
}
}
},
"403": {
"description": "- `forbidden` : 该知识库未启用 API 访问。\n- `forbidden` : 已达到您订阅套餐的知识库请求速率限制。",
"content": {
"application/json": {
"examples": {
"forbidden_1": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
},
"forbidden_2": {
"summary": "forbidden (rate limit)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/workspaces/current/models/model-types/{model_type}": {
"get": {
"tags": [
"模型"
],
"summary": "获取可用模型",
"description": "按类型获取可用模型列表。主要用于查询知识库配置所需的 `text-embedding` 和 `rerank` 模型。",
"operationId": "getAvailableModelsZh",
"parameters": [
{
"name": "model_type",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"text-embedding",
"rerank",
"llm",
"tts",
"speech2text",
"moderation"
]
},
"description": "要获取的模型类型。对于知识库配置，使用 `text-embedding` 获取嵌入模型，使用 `rerank` 获取重排序模型。"
}
],
"responses": {
"200": {
"description": "指定类型的可用模型。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "模型供应商及其可用模型的列表。",
"items": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "模型供应商标识符，例如 `openai`、`cohere`。"
},
"label": {
"type": "object",
"description": "供应商的本地化显示名称。",
"properties": {
"en_US": {
"type": "string",
"description": "英文显示名称。"
},
"zh_Hans": {
"type": "string",
"description": "中文显示名称。"
}
}
},
"icon_small": {
"type": "object",
"description": "供应商小图标的 URL。",
"properties": {
"en_US": {
"type": "string",
"description": "小图标 URL。"
}
}
},
"icon_large": {
"type": "object",
"description": "供应商大图标的 URL。",
"properties": {
"en_US": {
"type": "string",
"description": "大图标 URL。"
}
}
},
"status": {
"type": "string",
"description": "供应商状态。凭证已配置且有效时为 `active`。"
},
"models": {
"type": "array",
"description": "该供应商的可用模型列表。",
"items": {
"type": "object",
"properties": {
"model": {
"type": "string",
"description": "模型标识符。创建或更新知识库时，将此值作为 `embedding_model` 参数使用。"
},
"label": {
"type": "object",
"description": "模型的本地化显示名称。",
"properties": {
"en_US": {
"type": "string",
"description": "英文模型名称。"
},
"zh_Hans": {
"type": "string",
"description": "中文模型名称。"
}
}
},
"model_type": {
"type": "string",
"description": "模型类型，与 `model_type` 路径参数匹配。"
},
"features": {
"type": "array",
"nullable": true,
"description": "模型支持的功能，无功能时为 `null`。",
"items": {
"type": "string"
}
},
"fetch_from": {
"type": "string",
"description": "模型定义的来源。`predefined-model` 表示内置模型，`customizable-model` 表示用户自配置的模型。"
},
"model_properties": {
"type": "object",
"description": "模型特定的属性，例如 `context_size`。"
},
"status": {
"type": "string",
"description": "模型可用状态。就绪时为 `active`。"
}
}
}
}
}
}
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"data": [
{
"provider": "openai",
"label": {
"en_US": "OpenAI",
"zh_Hans": "OpenAI"
},
"icon_small": {
"en_US": "https://example.com/openai-small.svg"
},
"icon_large": {
"en_US": "https://example.com/openai-large.svg"
},
"status": "active",
"models": [
{
"model": "text-embedding-3-small",
"label": {
"en_US": "text-embedding-3-small",
"zh_Hans": "text-embedding-3-small"
},
"model_type": "text-embedding",
"features": null,
"fetch_from": "predefined-model",
"model_properties": {
"context_size": 8191
},
"status": "active"
}
]
}
]
}
}
}
}
}
}
}
}
},
"/datasets/pipeline/file-upload": {
"post": {
"tags": [
"知识流水线"
],
"summary": "上传流水线文件",
"description": "上传文件以在知识流水线中使用。通过 `multipart/form-data` 接受单个文件。",
"operationId": "uploadPipelineFileZh",
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "要上传的文件。"
}
}
}
}
}
},
"responses": {
"201": {
"description": "文件上传成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "已上传文件的唯一标识符。"
},
"name": {
"type": "string",
"description": "原始文件名。"
},
"size": {
"type": "integer",
"description": "文件大小（字节）。"
},
"extension": {
"type": "string",
"description": "文件扩展名。"
},
"mime_type": {
"type": "string",
"nullable": true,
"description": "文件的 MIME 类型。若上传未包含 MIME 类型则可能为 `null`。"
},
"created_by": {
"type": "string",
"description": "上传文件的用户 ID。"
},
"created_at": {
"type": "string",
"nullable": true,
"description": "上传时间戳（ISO 8601 格式）。在记录创建过程中可能为 `null`。"
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "report.pdf",
"size": 524288,
"extension": "pdf",
"mime_type": "application/pdf",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": "2025-03-06T12:00:00"
}
}
}
}
}
},
"400": {
"description": "- `no_file_uploaded` : 请上传文件。\n- `filename_not_exists_error` : 指定的文件名不存在。\n- `too_many_files` : 仅允许上传一个文件。",
"content": {
"application/json": {
"examples": {
"no_file_uploaded": {
"summary": "no_file_uploaded",
"value": {
"status": 400,
"code": "no_file_uploaded",
"message": "Please upload your file."
}
},
"filename_not_exists_error": {
"summary": "filename_not_exists_error",
"value": {
"status": 400,
"code": "filename_not_exists_error",
"message": "The specified filename does not exist."
}
},
"too_many_files": {
"summary": "too_many_files",
"value": {
"status": 400,
"code": "too_many_files",
"message": "Only one file is allowed."
}
}
}
}
}
},
"413": {
"description": "`file_too_large` : 文件大小超出限制。",
"content": {
"application/json": {
"examples": {
"file_too_large": {
"summary": "file_too_large",
"value": {
"status": 413,
"code": "file_too_large",
"message": "File size exceeded."
}
}
}
}
}
},
"415": {
"description": "`unsupported_file_type` : 不允许的文件类型。",
"content": {
"application/json": {
"examples": {
"unsupported_file_type": {
"summary": "unsupported_file_type",
"value": {
"status": 415,
"code": "unsupported_file_type",
"message": "File type not allowed."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/pipeline/datasource-plugins": {
"get": {
"tags": [
"知识流水线"
],
"summary": "获取数据源插件列表",
"description": "列出知识流水线中已配置的数据源节点。每个节点包含其使用的插件，以及运行该节点所需的元数据。",
"operationId": "listDatasourcePluginsZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "is_published",
"in": "query",
"schema": {
"type": "boolean",
"default": true
},
"description": "是否从已发布的流水线中获取节点。默认为 `true`，返回已发布版本中的节点。"
}
],
"responses": {
"200": {
"description": "流水线中已配置的数据源节点列表。",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"node_id": {
"type": "string",
"description": "流水线工作流中数据源节点的 ID。调用 [执行数据源节点](/api-reference/知识流水线/执行数据源节点) 时作为 `node_id` 传入，或调用 [运行流水线](/api-reference/知识流水线/运行流水线) 时作为 `start_node_id` 传入。"
},
"plugin_id": {
"type": "string",
"description": "提供该节点的数据源插件的 ID。"
},
"provider_name": {
"type": "string",
"description": "数据源插件注册的提供商名称。"
},
"datasource_type": {
"type": "string",
"description": "数据源类型。取值为 `local_file`、`online_document`、`online_drive`、`website_crawl` 之一。"
},
"title": {
"type": "string",
"description": "为该节点配置的显示标题。"
},
"user_input_variables": {
"type": "array",
"description": "调用方需要为该数据源提供的流水线输入变量，来自节点数据源参数中 `{{#...#}}` 引用的变量。每一项遵循工作流使用的流水线变量结构。",
"items": {
"type": "object",
"additionalProperties": true
}
},
"credentials": {
"type": "array",
"description": "可用于对该数据源进行认证的凭证列表。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "凭证 ID。调用 [执行数据源节点](/api-reference/知识流水线/执行数据源节点) 时作为 `credential_id` 传入，或作为 [运行流水线](/api-reference/知识流水线/运行流水线) 各数据源项中的 `credential_id` 字段。"
},
"name": {
"type": "string",
"description": "凭证的显示名称。"
},
"type": {
"type": "string",
"description": "数据源插件定义的凭证类型。"
},
"is_default": {
"type": "boolean",
"description": "该凭证是否为提供商的默认凭证。"
}
}
}
}
}
}
},
"examples": {
"success": {
"summary": "响应示例",
"value": [
{
"node_id": "1719288585006",
"plugin_id": "langgenius/notion_datasource",
"provider_name": "notion",
"datasource_type": "online_document",
"title": "Notion Documents",
"user_input_variables": [],
"credentials": [
{
"id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
"name": "Production Notion",
"type": "api-key",
"is_default": true
}
]
}
]
}
}
}
}
},
"400": {
"description": "`invalid_param` : 该知识库未配置处理流水线。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Pipeline not found"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/pipeline/datasource/nodes/{node_id}/run": {
"post": {
"tags": [
"知识流水线"
],
"summary": "执行数据源节点",
"description": "在知识流水线中执行单个数据源节点。返回包含节点执行结果的流式响应。",
"operationId": "runDatasourceNodeZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
},
{
"name": "node_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "要执行的数据源节点 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"inputs",
"datasource_type",
"is_published"
],
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "数据源节点的输入变量。"
},
"datasource_type": {
"type": "string",
"enum": [
"online_document",
"local_file",
"website_crawl",
"online_drive"
],
"description": "数据源类型。"
},
"credential_id": {
"type": "string",
"nullable": true,
"description": "用于数据源认证的凭证 ID。"
},
"is_published": {
"type": "boolean",
"description": "运行节点的已发布版本还是草稿版本。`true` 运行已发布版本，`false` 运行草稿版本。"
}
}
}
}
}
},
"responses": {
"200": {
"description": "包含节点执行事件的流式响应。",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "包含节点执行进度和结果的 Server-Sent Events 流。"
}
}
}
},
"400": {
"description": "`invalid_param` : 该知识库未配置处理流水线，或请求体校验失败。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Pipeline not found"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
}
}
}
},
"/datasets/{dataset_id}/pipeline/run": {
"post": {
"tags": [
"知识流水线"
],
"summary": "运行流水线",
"description": "为知识库执行完整的知识流水线。支持流式和阻塞两种响应模式。",
"operationId": "runPipelineZh",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "知识库 ID。"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"inputs",
"datasource_type",
"datasource_info_list",
"start_node_id",
"is_published",
"response_mode"
],
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true,
"description": "流水线输入变量的键值对，对应工作流中定义的流水线变量。如果流水线没有输入变量，传 `{}`。"
},
"datasource_type": {
"type": "string",
"enum": [
"local_file",
"online_document",
"website_crawl",
"online_drive"
],
"description": "数据源类型。决定 `datasource_info_list` 中条目所需的字段。"
},
"datasource_info_list": {
"type": "array",
"description": "待处理的数据源对象列表。条目结构取决于 `datasource_type`。",
"items": {
"oneOf": [
{
"title": "Local File",
"type": "object",
"required": [
"reference"
],
"properties": {
"reference": {
"type": "string",
"description": "使用 [上传流水线文件](/api-reference/知识流水线/上传流水线文件) 端点返回的 `id`。`related_id` 可作为别名使用。"
},
"name": {
"type": "string",
"description": "文档标题。默认为 `\"untitled\"`。"
}
}
},
{
"title": "Online Document",
"type": "object",
"required": [
"workspace_id",
"page"
],
"properties": {
"workspace_id": {
"type": "string",
"description": "外部平台中的工作空间或数据库 ID（例如 Notion 工作空间 ID）。"
},
"page": {
"type": "object",
"description": "页面详情。",
"required": [
"page_id",
"type"
],
"properties": {
"page_id": {
"type": "string",
"description": "页面标识符。"
},
"type": {
"type": "string",
"description": "由数据源插件定义的页面类型（例如 `\"page\"`、`\"database\"`）。"
},
"page_name": {
"type": "string",
"description": "显示名称。默认为 `\"untitled\"`。"
}
}
},
"credential_id": {
"type": "string",
"description": "用于与外部平台认证的凭证。通过 Dify 控制台管理。如省略，则使用该供应商的默认凭证。"
}
}
},
{
"title": "Website Crawl",
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "待爬取的 URL。"
},
"title": {
"type": "string",
"description": "用作文档名称。默认为 `\"untitled\"`。"
}
}
},
{
"title": "Online Drive",
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "文件或文件夹 ID。"
},
"type": {
"type": "string",
"enum": [
"file",
"folder"
],
"description": "该条目是单个文件还是待展开的文件夹。"
},
"bucket": {
"type": "string",
"description": "存储桶名称。部分存储供应商需要此字段（例如 S3 兼容存储）；如果供应商不使用存储桶，可省略。"
},
"name": {
"type": "string",
"description": "文件名称。默认为 `\"untitled\"`。"
}
}
}
]
}
},
"start_node_id": {
"type": "string",
"description": "流水线开始执行的数据源节点 ID。"
},
"is_published": {
"type": "boolean",
"description": "运行流水线的已发布版本还是草稿版本。`true` 运行最新已发布版本；`false` 运行当前草稿（适用于测试未发布的更改）。"
},
"response_mode": {
"type": "string",
"enum": [
"streaming",
"blocking"
],
"description": "流水线执行的响应模式。`streaming` 返回服务器发送事件流，`blocking` 等待并返回完整结果。"
}
}
},
"examples": {
"local_file": {
"summary": "请求示例—本地文件",
"value": {
"inputs": {},
"datasource_type": "local_file",
"datasource_info_list": [
{
"reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "quarterly-report.pdf"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "blocking"
}
},
"online_document": {
"summary": "请求示例—在线文档",
"value": {
"inputs": {},
"datasource_type": "online_document",
"datasource_info_list": [
{
"workspace_id": "ws-abc123",
"page": {
"page_id": "pg-def456",
"type": "page",
"page_name": "Product Roadmap"
},
"credential_id": "cred-789xyz"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "streaming"
}
},
"website_crawl": {
"summary": "请求示例—网站爬取",
"value": {
"inputs": {},
"datasource_type": "website_crawl",
"datasource_info_list": [
{
"url": "https://example.com/docs/getting-started",
"title": "Getting Started Guide"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "blocking"
}
},
"online_drive": {
"summary": "请求示例—在线存储",
"value": {
"inputs": {},
"datasource_type": "online_drive",
"datasource_info_list": [
{
"id": "file-abc123",
"type": "file",
"bucket": "my-bucket",
"name": "meeting-notes.docx"
}
],
"start_node_id": "1719288585006",
"is_published": true,
"response_mode": "blocking"
}
}
}
}
}
},
"responses": {
"200": {
"description": "流水线执行结果。格式取决于 `response_mode`：流式返回 `text/event-stream`，阻塞返回完整的 JSON 结果。",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "服务器发送事件流。每行格式为 `data: {JSON}\\n\\n`。主要事件：`workflow_started`（执行开始）、`node_started` / `node_finished`（逐节点进度，包含 `node_id`、`node_type`、`status`、`inputs`、`outputs`）、`workflow_finished`（最终结果，包含 `status`、`outputs`、`total_tokens`、`elapsed_time`）、`ping`（心跳保活）。"
}
},
"application/json": {
"schema": {
"type": "object",
"description": "完整的流水线执行结果。当 `response_mode` 为 `blocking` 时返回。",
"additionalProperties": true
},
"examples": {
"success": {
"summary": "Blocking Response Example",
"value": {
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"workflow_run_id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
"data": {
"id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
"status": "succeeded",
"outputs": {},
"created_at": 1741267200,
"finished_at": 1741267210
}
}
}
}
}
}
},
"400": {
"description": "`invalid_param` : 该知识库未配置处理流水线，或请求体校验失败。",
"content": {
"application/json": {
"examples": {
"invalid_param": {
"summary": "invalid_param",
"value": {
"status": 400,
"code": "invalid_param",
"message": "Pipeline not found"
}
}
}
}
}
},
"403": {
"description": "`forbidden` : 该知识库未启用 API 访问。",
"content": {
"application/json": {
"examples": {
"forbidden": {
"summary": "forbidden (api access)",
"value": {
"status": 403,
"code": "forbidden",
"message": "Dataset api access is not enabled."
}
}
}
}
}
},
"404": {
"description": "`not_found` : 未找到知识库。",
"content": {
"application/json": {
"examples": {
"not_found": {
"summary": "not_found",
"value": {
"status": 404,
"code": "not_found",
"message": "Dataset not found."
}
}
}
}
}
},
"500": {
"description": "`pipeline_run_error` : 流水线执行失败。",
"content": {
"application/json": {
"examples": {
"pipeline_run_error": {
"summary": "pipeline_run_error",
"value": {
"status": 500,
"code": "pipeline_run_error",
"message": "Pipeline execution failed: connection timeout"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Dataset": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "知识库的唯一标识符。"
},
"name": {
"type": "string",
"description": "知识库的显示名称。在工作区内唯一。"
},
"description": {
"type": "string",
"description": "描述知识库用途或内容的可选文本。"
},
"provider": {
"type": "string",
"description": "供应商类型。内部管理为 `vendor`，外部知识库连接为 `external`。"
},
"permission": {
"type": "string",
"description": "控制谁可以访问此知识库。可选值：`only_me`、`all_team_members`、`partial_members`。"
},
"data_source_type": {
"type": "string",
"description": "文档的数据源类型，尚未配置时为 `null`。"
},
"indexing_technique": {
"type": "string",
"description": "`high_quality` 使用嵌入模型进行精确搜索；`economy` 使用基于关键词的索引。"
},
"app_count": {
"type": "integer",
"description": "当前使用该知识库的应用数量。"
},
"document_count": {
"type": "integer",
"description": "知识库中的文档总数。"
},
"word_count": {
"type": "integer",
"description": "所有文档的总字数。"
},
"created_by": {
"type": "string",
"description": "创建该知识库的用户 ID。"
},
"author_name": {
"type": "string",
"description": "创建者的显示名称。"
},
"created_at": {
"type": "number",
"description": "创建时间戳（Unix 纪元，单位为秒）。"
},
"updated_by": {
"type": "string",
"description": "最后更新该知识库的用户 ID。"
},
"updated_at": {
"type": "number",
"description": "最后更新时间戳（Unix 纪元，单位为秒）。"
},
"embedding_model": {
"type": "string",
"description": "用于索引的嵌入模型名称。"
},
"embedding_model_provider": {
"type": "string",
"description": "嵌入模型供应商。使用 [获取可用模型](/api-reference/模型/获取可用模型) 中 `model_type=text-embedding` 返回的 `provider` 字段值。"
},
"embedding_available": {
"type": "boolean",
"description": "配置的嵌入模型当前是否可用。"
},
"retrieval_model_dict": {
"type": "object",
"description": "知识库的检索配置。",
"properties": {
"search_method": {
"type": "string",
"description": "用于检索的搜索方式。`keyword_search` 表示关键词匹配，`semantic_search` 表示基于嵌入的语义相似度，`full_text_search` 表示全文索引，`hybrid_search` 表示语义和关键词混合搜索。"
},
"reranking_enable": {
"type": "boolean",
"description": "是否启用重排序。"
},
"reranking_mode": {
"type": "string",
"nullable": true,
"description": "重排序模式。`reranking_model` 表示基于模型的重排序，`weighted_score` 表示基于分数的加权。重排序禁用时为 `null`。"
},
"reranking_model": {
"type": "object",
"description": "重排序模型配置。",
"properties": {
"reranking_provider_name": {
"type": "string",
"description": "重排序模型的供应商名称。"
},
"reranking_model_name": {
"type": "string",
"description": "重排序模型名称。"
}
}
},
"weights": {
"type": "object",
"nullable": true,
"description": "混合搜索的权重配置。",
"properties": {
"weight_type": {
"type": "string",
"description": "平衡语义搜索和关键词搜索权重的策略。"
},
"vector_setting": {
"type": "object",
"description": "语义搜索权重设置。",
"properties": {
"vector_weight": {
"type": "number",
"description": "分配给语义（向量）搜索结果的权重。"
},
"embedding_provider_name": {
"type": "string",
"description": "用于向量搜索的嵌入模型供应商。"
},
"embedding_model_name": {
"type": "string",
"description": "用于向量搜索的嵌入模型名称。"
}
}
},
"keyword_setting": {
"type": "object",
"description": "关键词搜索权重设置。",
"properties": {
"keyword_weight": {
"type": "number",
"description": "分配给关键词搜索结果的权重。"
}
}
}
}
},
"top_k": {
"type": "integer",
"description": "返回的最大结果数。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "是否启用分数阈值过滤。"
},
"score_threshold": {
"type": "number",
"description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。"
}
}
},
"summary_index_setting": {
"type": "object",
"nullable": true,
"description": "摘要索引配置。",
"properties": {
"enable": {
"type": "boolean",
"description": "是否已启用摘要索引。"
},
"model_name": {
"type": "string",
"description": "用于生成摘要的模型名称。"
},
"model_provider_name": {
"type": "string",
"description": "摘要生成模型的供应商。"
},
"summary_prompt": {
"type": "string",
"description": "用于摘要生成的提示词模板。"
}
}
},
"tags": {
"type": "array",
"description": "与该知识库关联的标签。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "标签标识符。"
},
"name": {
"type": "string",
"description": "Tag name."
},
"type": {
"type": "string",
"description": "标签类型。知识库标签始终为 `knowledge`。"
}
}
}
},
"doc_form": {
"type": "string",
"description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。"
},
"external_knowledge_info": {
"type": "object",
"nullable": true,
"description": "外部知识库的连接详情。当 `provider` 为 `external` 时存在。",
"properties": {
"external_knowledge_id": {
"type": "string",
"description": "外部知识库的 ID。"
},
"external_knowledge_api_id": {
"type": "string",
"description": "外部知识库 API 连接的 ID。"
},
"external_knowledge_api_name": {
"type": "string",
"description": "外部知识库 API 的显示名称。"
},
"external_knowledge_api_endpoint": {
"type": "string",
"description": "外部知识库 API 的端点 URL。"
}
}
},
"external_retrieval_model": {
"type": "object",
"nullable": true,
"description": "外部知识库的检索设置。内部知识库时为 `null`。",
"properties": {
"top_k": {
"type": "integer",
"description": "从外部知识库返回的最大结果数量。"
},
"score_threshold": {
"type": "number",
"description": "最低相关性得分阈值。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "是否启用分数阈值过滤。"
}
}
},
"doc_metadata": {
"type": "array",
"description": "知识库的元数据字段定义。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "元数据字段标识符。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
},
"type": {
"type": "string",
"description": "元数据字段值类型。"
}
}
}
},
"built_in_field_enabled": {
"type": "boolean",
"description": "是否启用内置元数据字段（例如 `document_name`、`uploader`）。"
},
"pipeline_id": {
"type": "string",
"nullable": true,
"description": "自定义处理流水线的 ID（如果已配置）。"
},
"runtime_mode": {
"type": "string",
"nullable": true,
"description": "运行时处理模式。"
},
"chunk_structure": {
"type": "string",
"nullable": true,
"description": "分段结构配置。"
},
"icon_info": {
"type": "object",
"nullable": true,
"description": "知识库的图标显示配置。",
"properties": {
"icon_type": {
"type": "string",
"description": "图标类型。"
},
"icon": {
"type": "string",
"description": "图标标识符或表情符号。"
},
"icon_background": {
"type": "string",
"description": "图标的背景颜色。"
},
"icon_url": {
"type": "string",
"description": "自定义图标图片的 URL。"
}
}
},
"is_published": {
"type": "boolean",
"description": "知识库是否已发布。"
},
"total_documents": {
"type": "integer",
"description": "文档总数。"
},
"total_available_documents": {
"type": "integer",
"description": "已启用且可用的文档数量。"
},
"enable_api": {
"type": "boolean",
"description": "该知识库是否启用 API 访问。"
},
"is_multimodal": {
"type": "boolean",
"description": "是否启用多模态内容处理。"
},
"maintainer": {
"type": "string",
"nullable": true,
"description": "知识库维护者的显示名称。未设置时为 `null`。"
},
"partial_member_list": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "当 `permission` 为 `partial_members` 时被授予访问权限的成员账户 ID。更新响应中始终返回；详情响应中仅当 `permission` 为 `partial_members` 时返回。"
}
}
},
"Document": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "文档的唯一标识符。"
},
"position": {
"type": "integer",
"description": "文档在列表中的显示位置。"
},
"data_source_type": {
"type": "string",
"description": "文档的创建方式。文件上传为 `upload_file`，Notion 导入为 `notion_import`。"
},
"data_source_info": {
"type": "object",
"description": "原始数据源信息，随 `data_source_type` 而异。"
},
"data_source_detail_dict": {
"type": "object",
"description": "详细的数据源信息，包括文件详情。"
},
"dataset_process_rule_id": {
"type": "string",
"description": "应用于该文档的处理规则 ID。"
},
"name": {
"type": "string",
"description": "文档名称。"
},
"created_from": {
"type": "string",
"description": "文档来源。通过 API 创建时为 `api`，通过 UI 创建时为 `web`。"
},
"created_by": {
"type": "string",
"description": "创建该文档的用户 ID。"
},
"created_at": {
"type": "number",
"description": "创建时间戳（Unix 纪元，单位为秒）。"
},
"tokens": {
"type": "integer",
"description": "文档中的令牌总数。"
},
"indexing_status": {
"type": "string",
"description": "当前索引状态。`waiting` 表示排队中，`parsing` 表示正在提取内容，`cleaning` 表示正在去噪，`splitting` 表示正在分块，`indexing` 表示正在构建向量，`completed` 表示就绪，`error` 表示失败，`paused` 表示手动暂停。"
},
"error": {
"type": "string",
"nullable": true,
"description": "索引失败时的错误消息。无错误时为 `null`。"
},
"enabled": {
"type": "boolean",
"description": "该文档是否启用检索。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "文档被禁用的时间戳。启用时为 `null`。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "禁用该文档的用户 ID。启用时为 `null`。"
},
"archived": {
"type": "boolean",
"description": "文档是否已归档。"
},
"display_status": {
"type": "string",
"description": "基于 `indexing_status` 和 `enabled` 状态派生的面向用户的显示状态。"
},
"word_count": {
"type": "integer",
"description": "文档的总字数。"
},
"hit_count": {
"type": "integer",
"description": "该文档在检索查询中被匹配的次数。"
},
"doc_form": {
"type": "string",
"description": "文档分块模式。`text_model` 表示标准文本分块，`hierarchical_model` 表示父子结构，`qa_model` 表示问答对提取。"
},
"doc_metadata": {
"type": "array",
"description": "分配给该文档的元数据值。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "元数据字段标识符。"
},
"name": {
"type": "string",
"description": "元数据字段名称。"
},
"type": {
"type": "string",
"description": "元数据字段值类型。"
},
"value": {
"type": "string",
"description": "此文档的元数据值。"
}
}
}
},
"summary_index_status": {
"type": "string",
"nullable": true,
"description": "该文档的摘要索引状态。未配置摘要索引时为 `null`。"
},
"need_summary": {
"type": "boolean",
"description": "是否需要为该文档生成摘要。"
}
}
},
"Segment": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "分段的唯一标识符。"
},
"position": {
"type": "integer",
"description": "分段在文档中的位置。"
},
"document_id": {
"type": "string",
"description": "该分段所属文档的 ID。"
},
"content": {
"type": "string",
"description": "分段的文本内容。"
},
"sign_content": {
"type": "string",
"description": "用于完整性验证的签名内容哈希。"
},
"answer": {
"type": "string",
"description": "回答内容，用于问答模式文档。"
},
"word_count": {
"type": "integer",
"description": "分段内容的字数。"
},
"tokens": {
"type": "integer",
"description": "分段内容的令牌数。"
},
"keywords": {
"type": "array",
"description": "与该分段关联的关键词，用于基于关键词的检索。",
"items": {
"type": "string"
}
},
"index_node_id": {
"type": "string",
"description": "向量存储中索引节点的 ID。"
},
"index_node_hash": {
"type": "string",
"description": "索引内容的哈希值，用于检测变更。"
},
"hit_count": {
"type": "integer",
"description": "该分段在检索查询中被匹配的次数。"
},
"enabled": {
"type": "boolean",
"description": "该分段是否启用检索。"
},
"disabled_at": {
"type": "number",
"nullable": true,
"description": "分段被禁用的时间戳。启用时为 `null`。"
},
"disabled_by": {
"type": "string",
"nullable": true,
"description": "禁用该分段的用户 ID。启用时为 `null`。"
},
"status": {
"type": "string",
"description": "分段的当前索引状态，例如 `completed`、`indexing`、`error`。"
},
"created_by": {
"type": "string",
"description": "创建该分段的用户 ID。"
},
"created_at": {
"type": "number",
"description": "创建时间戳（Unix 纪元，单位为秒）。"
},
"updated_at": {
"type": "number",
"description": "最后更新时间戳（Unix 纪元，单位为秒）。"
},
"updated_by": {
"type": "string",
"description": "最后更新该分段的用户 ID。"
},
"indexing_at": {
"type": "number",
"nullable": true,
"description": "索引开始的时间戳。尚未开始时为 `null`。"
},
"completed_at": {
"type": "number",
"nullable": true,
"description": "索引完成的时间戳。尚未完成时为 `null`。"
},
"error": {
"type": "string",
"nullable": true,
"description": "索引失败时的错误消息。无错误时为 `null`。"
},
"stopped_at": {
"type": "number",
"nullable": true,
"description": "索引停止的时间戳。未停止时为 `null`。"
},
"child_chunks": {
"type": "array",
"description": "属于该分段的子分段。仅在分层模式文档中存在。",
"items": {
"$ref": "#/components/schemas/ChildChunk"
}
},
"attachments": {
"type": "array",
"description": "附加到该分段的文件。",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "附件文件标识符。"
},
"name": {
"type": "string",
"description": "原始文件名。"
},
"size": {
"type": "integer",
"description": "文件大小（字节）。"
},
"extension": {
"type": "string",
"description": "文件扩展名。"
},
"mime_type": {
"type": "string",
"description": "文件的 MIME 类型。"
},
"source_url": {
"type": "string",
"description": "访问附件的 URL。"
}
}
}
},
"summary": {
"type": "string",
"nullable": true,
"description": "AI 生成的分段内容摘要。未启用摘要索引时为 `null`。"
}
}
},
"ChildChunk": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "子分段的唯一标识符。"
},
"segment_id": {
"type": "string",
"description": "该子分段所属的父分段 ID。"
},
"content": {
"type": "string",
"description": "子分段的文本内容。"
},
"position": {
"type": "integer",
"description": "子分段在父分段中的位置。"
},
"word_count": {
"type": "integer",
"description": "子分段内容的字数。"
},
"type": {
"type": "string",
"description": "子分段的创建方式。通过 API 创建或更新的子分段始终为 `customized`。系统生成的子分段为 `automatic`。"
},
"created_at": {
"type": "number",
"description": "创建时间戳（Unix 纪元，单位为秒）。"
},
"updated_at": {
"type": "number",
"description": "最后更新时间戳（Unix 纪元，单位为秒）。"
}
}
},
"RetrievalModel": {
"type": "object",
"required": [
"search_method",
"reranking_enable",
"top_k",
"score_threshold_enabled"
],
"properties": {
"search_method": {
"type": "string",
"description": "用于检索的搜索方法。",
"enum": [
"keyword_search",
"semantic_search",
"full_text_search",
"hybrid_search"
]
},
"reranking_enable": {
"type": "boolean",
"description": "是否启用重排序。"
},
"reranking_model": {
"type": "object",
"description": "重排序模型配置。",
"properties": {
"reranking_provider_name": {
"type": "string",
"description": "重排序模型的供应商名称。"
},
"reranking_model_name": {
"type": "string",
"description": "重排序模型名称。"
}
}
},
"reranking_mode": {
"type": "string",
"enum": [
"reranking_model",
"weighted_score"
],
"nullable": true,
"description": "重排序模式。当 `reranking_enable` 为 `true` 时必填。"
},
"top_k": {
"type": "integer",
"description": "返回的最大结果数。"
},
"score_threshold_enabled": {
"type": "boolean",
"description": "是否启用分数阈值过滤。"
},
"score_threshold": {
"type": "number",
"nullable": true,
"description": "结果的最低相关性分数。仅在 `score_threshold_enabled` 为 `true` 时生效。"
},
"weights": {
"type": "object",
"nullable": true,
"description": "混合搜索的权重配置。",
"properties": {
"weight_type": {
"type": "string",
"description": "平衡语义搜索和关键词搜索权重的策略。",
"enum": [
"semantic_first",
"keyword_first",
"customized"
]
},
"vector_setting": {
"type": "object",
"description": "语义搜索权重设置。",
"properties": {
"vector_weight": {
"type": "number",
"description": "分配给语义（向量）搜索结果的权重。"
},
"embedding_provider_name": {
"type": "string",
"description": "用于向量搜索的嵌入模型供应商。"
},
"embedding_model_name": {
"type": "string",
"description": "用于向量搜索的嵌入模型名称。"
}
}
},
"keyword_setting": {
"type": "object",
"description": "关键词搜索权重设置。",
"properties": {
"keyword_weight": {
"type": "number",
"description": "分配给关键词搜索结果的权重。"
}
}
}
}
},
"metadata_filtering_conditions": {
"type": "object",
"nullable": true,
"description": "仅检索文档元数据匹配指定条件的分段。条件由服务端基于文档元数据字段评估。",
"properties": {
"logical_operator": {
"type": "string",
"enum": [
"and",
"or"
],
"default": "and",
"nullable": true,
"description": "多个条件之间的组合方式。"
},
"conditions": {
"type": "array",
"nullable": true,
"description": "要评估的元数据条件列表。",
"items": {
"type": "object",
"required": [
"name",
"comparison_operator"
],
"properties": {
"name": {
"type": "string",
"description": "用于比较的元数据字段名称。"
},
"comparison_operator": {
"type": "string",
"description": "应用的比较方式。字符串运算符（`contains`、`not contains`、`start with`、`end with`、`is`、`is not`、`empty`、`not empty`、`in`、`not in`）作用于字符串或数组类型的元数据。数值运算符（`=`、`≠`、`>`、`<`、`≥`、`≤`）作用于数值类型的元数据。时间运算符（`before`、`after`）作用于时间类型的元数据。",
"enum": [
"contains",
"not contains",
"start with",
"end with",
"is",
"is not",
"empty",
"not empty",
"in",
"not in",
"=",
"≠",
">",
"<",
"≥",
"≤",
"before",
"after"
]
},
"value": {
"nullable": true,
"description": "用于比较的值。类型取决于 `comparison_operator`：大多数字符串运算符使用字符串；`in` 和 `not in` 使用字符串数组；数值运算符使用数字；`empty` 和 `not empty` 时省略。",
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "number"
}
]
}
}
}
}
}
}
}
}
},
"securitySchemes": {
"ApiKeyAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API_KEY",
"description": "API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。**缺少或无效的 API Key 会返回 HTTP `401`，错误码为 `unauthorized`。"
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink