跳到主要内容

HTTP API

RAGFlow RESTful API 的完整参考手册。在继续之前，请确保您已准备好用于身份验证的 RAGFlow API 密钥 (API Key)。

错误码 (ERROR CODES)

状态码消息 (Message)描述 (Description)
400Bad Request请求参数无效
401Unauthorized未授权的访问
403Forbidden访问被拒绝
404Not Found未找到资源
500Internal Server Error服务器内部错误
1001Invalid Chunk ID无效的块 ID
1002Chunk Update Failed块更新失败

兼容 OpenAI 的 API (OpenAI-Compatible API)

创建对话补全 (Create chat completion)

POST /api/v1/openai/{chat_id}/chat/completions

为给定的对话生成模型回复。

已废弃

先前的接口 POST /api/v1/chats_openai/{chat_id}/chat/completions 已被废弃，请使用当前接口代替。

此 API 遵循与 OpenAI API 相同的请求和响应格式。它允许您以类似于使用 OpenAI API 的方式与模型进行交互。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/openai/{chat_id}/chat/completions
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "model": string
    • "messages": object list
    • "stream": boolean
    • "extra_body": object（可选）
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/openai/{chat_id}/chat/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "model": "glm-4-flash@ZHIPU-AI",
        "messages": [{"role": "user", "content": "Say this is a test!"}],
        "stream": true,
        "extra_body": {
          "reference": true,
          "reference_metadata": {
            "include": true,
            "fields": ["author", "year", "source"]
          },
          "metadata_condition": {
            "logic": "and",
            "conditions": [
              {
                "name": "author",
                "comparison_operator": "is",
                "value": "bob"
              }
            ]
          }
        }
      }'
请求参数 (Request Parameters)

  • chat_id (路径参数) string, 必填 已有的对话助手 ID。请求将使用该对话助手的知识库和设置。

  • model (请求体参数) string, 必填 用于生成回复的模型。当提供了 chat_id 时，您也可以使用遗留的占位符值 "model" 以继续使用该对话助手所配置的模型。

  • messages (请求体参数) list[object], 必填 用于生成回复的历史对话消息列表。该列表必须至少包含一条角色为 user 的消息。

  • stream (请求体参数) boolean 是否以流式接收回复。如果您希望一次性接收完整的回复而不是流式回复，请显式将此值设置为 false。

  • extra_body (请求体参数) object 附加请求参数：

    • reference: boolean - 是否在最终块（流式）或最终消息（非流式）中包含引用。
    • reference_metadata: object - 是否在每个引用块中包含文档元数据。
      • include: boolean - 启用在引用块中包含文档元数据。
      • fields: list[string] - 可选的元数据键允许列表。省略此值将包含所有键，使用空列表则不包含任何键。
    • metadata_condition: object - 应用于检索结果的元数据过滤条件。

响应 (Response)

流式 (Stream)：

data:{
    "id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
    "choices": [
        {
            "delta": {
                "content": "Hello! It seems like you're just greeting me. If you have a specific",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null,
                "reasoning_content": null
            },
            "finish_reason": null,
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1755084508,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": null
}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " question or need information, feel free to ask, and I'll do my best", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " to assist you based on the knowledge base provided.", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null}

data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": null, "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": "stop", "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": {"prompt_tokens": 5, "completion_tokens": 188, "total_tokens": 193}}

data:[DONE]

非流式 (Non-stream)：

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "Hello! I'm your smart assistant. What can I do for you?",
                "role": "assistant"
            }
        }
    ],
    "created": 1755084403,
    "id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728",
    "model": "model",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 55,
        "completion_tokens_details": {
            "accepted_prediction_tokens": 55,
            "reasoning_tokens": 5,
            "rejected_prediction_tokens": 0
        },
        "prompt_tokens": 5,
        "total_tokens": 60
    }
}

失败 (Failure)：

{
  "code": 102,
  "message": "The last content of this conversation is not from user."
}

创建智能体回复 (Create agent completion)

POST /api/v1/agents_openai/{agent_id}/chat/completions

为给定的对话生成智能体 (Agent) 模型回复。

此 API 遵循与 OpenAI API 相同的请求和响应格式。它允许您以类似于使用 OpenAI API 的方式与模型进行交互。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/agents_openai/{agent_id}/chat/completions
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "model": string
    • "messages": object list
    • "stream": boolean
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/agents_openai/{agent_id}/chat/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "model": "model",
        "messages": [{"role": "user", "content": "Say this is a test!"}],
        "stream": true
      }'
请求参数 (Request Parameters)

  • model (请求体参数) string, 必填 用于生成回复的模型。服务器会自动解析此项，因此您当前可以将其设置为任何值。

  • messages (请求体参数) list[object], 必填 用于生成回复的历史对话消息列表。该列表必须至少包含一条角色为 user 的消息。

  • stream (请求体参数) boolean 是否以流式接收回复。如果您希望一次性接收完整的回复而不是流式回复，请显式将此值设置为 false。

  • session_id (请求体参数) string 智能体会话 ID。

响应 (Response)

流式 (Stream)：

...

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": " terminal"
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": "."
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": "",
                "reference": {
                    "chunks": {
                        "20": {
                            "id": "4b8935ac0a22deb1",
                            "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                            "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "document_name": "INSTALL22.md",
                            "document_metadata": {
                                "author": "bob",
                                "year": "2023",
                                "source": "internal"
                            },
                            "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                            "image_id": "",
                            "positions": [
                                [
                                    12,
                                    11,
                                    11,
                                    11,
                                    11
                                ]
                            ],
                            "url": null,
                            "similarity": 0.5697155305154673,
                            "vector_similarity": 0.7323851005515574,
                            "term_similarity": 0.5000000005,
                            "doc_type": ""
                        }
                    },
                    "doc_aggs": {
                        "INSTALL22.md": {
                            "doc_name": "INSTALL22.md",
                            "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "count": 3
                        },
                        "INSTALL.md": {
                            "doc_name": "INSTALL.md",
                            "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                            "count": 2
                        },
                        "INSTALL(1).md": {
                            "doc_name": "INSTALL(1).md",
                            "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                            "count": 2
                        },
                        "INSTALL3.md": {
                            "doc_name": "INSTALL3.md",
                            "doc_id": "4bdab5825e1511f0907f09f583941b45",
                            "count": 1
                        }
                    }
                }
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: [DONE]

非流式 (Non-stream)：

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For Windows:\n1. **Download from GitHub**: \n   - Visit the [Neovim releases page](https://github.com/neovim/neovim/releases)\n   - Download the latest Windows installer (nvim-win64.msi)\n   - Run the installer and follow the prompts\n\n2. **Using winget** (Windows Package Manager):\n...",
                "reference": {
                    "chunks": {
                        "20": {
                            "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                            "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                            "doc_type": "",
                            "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "document_name": "INSTALL22.md",
                            "document_metadata": {
                                "author": "bob",
                                "year": "2023",
                                "source": "internal"
                            },
                            "id": "4b8935ac0a22deb1",
                            "image_id": "",
                            "positions": [
                                [
                                    12,
                                    11,
                                    11,
                                    11,
                                    11
                                ]
                            ],
                            "similarity": 0.5697155305154673,
                            "term_similarity": 0.5000000005,
                            "url": null,
                            "vector_similarity": 0.7323851005515574
                        }
                    },
                    "doc_aggs": {
                        "INSTALL(1).md": {
                            "count": 2,
                            "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                            "doc_name": "INSTALL(1).md"
                        },
                        "INSTALL.md": {
                            "count": 2,
                            "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                            "doc_name": "INSTALL.md"
                        },
                        "INSTALL22.md": {
                            "count": 3,
                            "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "doc_name": "INSTALL22.md"
                        },
                        "INSTALL3.md": {
                            "count": 1,
                            "doc_id": "4bdab5825e1511f0907f09f583941b45",
                            "doc_name": "INSTALL3.md"
                        }
                    }
                },
                "role": "assistant"
            }
        }
    ],
    "created": null,
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "object": "chat.completion",
    "param": null,
    "usage": {
        "completion_tokens": 415,
        "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
        },
        "prompt_tokens": 6,
        "total_tokens": 421
    }
}

失败 (Failure)：

{
  "code": 102,
  "message": "The last content of this conversation is not from user."
}

数据集管理 (DATASET MANAGEMENT)

创建数据集 (Create dataset)

POST /api/v1/datasets

创建一个数据集 (Dataset)。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/datasets
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string
    • "avatar": string
    • "description": string
    • "embedding_model": string
    • "permission": string
    • "chunk_method": string
    • "parser_config": object
    • "parse_type": int
    • "pipeline_id": string
基础请求示例 (A basic request example)
curl --request POST \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
      "name": "test_1"
      }'
指定摄入管道的请求示例 (A request example specifying ingestion pipeline)
警告

指定摄入管道 (Ingestion Pipeline) 时，您切勿包含 "chunk_method" 或 "parser_config"。

curl --request POST \
  --url http://{address}/api/v1/datasets \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
   "name": "test-sdk",
   "parse_type": <NUMBER_OF_PARSERS_IN_YOUR_PARSER_COMPONENT>,
   "pipeline_id": "<PIPELINE_ID_32_HEX>"
  }'
请求参数 (Request parameters)

  • "name": (请求体参数), string, 必填 要创建的数据集的唯一名称。它必须符合以下要求：

    • 仅限基本多语言平面 (BMP) 字符
    • 最多 128 个字符
    • 不区分大小写

  • "avatar": (请求体参数), string 头像的 Base64 编码。

    • 最多 65535 个字符

  • "description": (请求体参数), string 对要创建的数据集的简短描述。

    • 最多 65535 个字符

  • "embedding_model": (请求体参数), string 要使用的嵌入模型 (Embedding Model) 名称。例如："BAAI/bge-large-zh-v1.5@BAAI"

    • 最多 255 个字符
    • 必须遵循 model_name@model_factory 格式

  • "permission": (请求体参数), string 指定谁可以访问要创建的数据集。可用选项：

    • "me"：（默认）仅您自己能管理该数据集。
    • "team"：所有团队成员都可以管理该数据集。

  • "chunk_method": (请求体参数), enum<string> 要创建的数据集的默认分块方法 (Chunk Method)。与 "parse_type" 和 "pipeline_id" 互斥。如果您设置了 "chunk_method"，请不要包含 "parse_type" 或 "pipeline_id"。 可用选项：

    • "naive"：通用（默认）
    • "book"：图书
    • "email"：电子邮件
    • "laws"：法律
    • "manual"：手动
    • "one"：单文档
    • "paper"：论文
    • "picture"：图片
    • "presentation"：演示文稿 (PPT)
    • "qa"：问答 (Q&A)
    • "table"：表格
    • "tag"：标签

  • "parser_config": (请求体参数), object 数据集解析器 (Parser) 的配置设置。此 JSON 对象中的属性随选定的 "chunk_method" 而变化：

    • 如果 "chunk_method" 为 "naive"，则 "parser_config" 对象包含以下属性：
      • "auto_keywords": int
        • 默认值：0
        • 最小值：0
        • 最大值：32
      • "auto_questions": int
        • 默认值：0
        • 最小值：0
        • 最大值：10
      • "chunk_token_num": int
        • 默认值：512
        • 最小值：1
        • 最大值：2048
      • "delimiter": string
        • 默认值："\n"。
      • "html4excel": bool
        • 是否将 Excel 文档转换为 HTML 格式。
        • 默认值：false
      • "layout_recognize": string
        • 默认值：DeepDOC
      • "tag_kb_ids": array<string>
        • 使用 Tag（标签分块）方法解析的数据集 ID。
        • 在设置此项之前，请确保已创建并正确配置了标签集。详情请见使用标签集 (Use tag sets)。
      • "task_page_size": int
        • 仅适用于 PDF。
        • 默认值：12
        • 最小值：1
      • "raptor": object RAPTOR 相关设置。
        • 默认值：{"use_raptor": false}
      • "graphrag": object GRAPHRAG 相关设置。
        • 默认值：{"use_graphrag": false}
      • "parent_child": object 父子分块设置。启用后，每个块将使用 children_delimiter 进一步拆分为更小的子分块。在检索时，匹配到的子分块在传递给 LLM 之前，会被替换为其完整的父分块文本，从而在获得更广上下文的同时确保精准的向量匹配。
        • "use_parent_child": bool 是否启用父子分块。默认值为 false。
        • "children_delimiter": string 用于将父分块拆分为子分块的分隔符。仅在 "use_parent_child" 为 true 时生效。默认值为 "\n"。
    • 如果 "chunk_method" 为 "qa"、"manual"、"paper"、"book"、"laws" 或 "presentation"，则 "parser_config" 对象包含以下属性：
      • "raptor": object RAPTOR 相关设置。
        • 默认值：{"use_raptor": false}。
    • 如果 "chunk_method" 为 "table"、"picture"、"one" 或 "email"，则 "parser_config" 为空 JSON 对象。

  • "parse_type": (请求体参数), int 摄入管道 (Ingestion Pipeline) 的解析类型标识符，即您的 Parser（解析器）组件中的解析器数量。

    • 在指定摄入管道时，此项为必填项（与 "pipeline_id" 一起提供）。
    • 指定了 "chunk_method" 时，切勿包含此项。

  • "pipeline_id": (请求体参数), string 摄入管道的 ID。可以在 RAGFlow UI 的对应 URL 中找到。

    • 在指定摄入管道时，此项为必填项（与 "parse_type" 一起提供）。
    • 必须是一个 32 字符的低位十六进制字符串，例如 "d0bebe30ae2211f0970942010a8e0005"。
    • 指定了 "chunk_method" 时，切勿包含此项。
警告

在创建数据集时，您可以选择以下摄入选项之一，但不能同时选择两者：

  • 使用内置的分块方法 -- 指定 "chunk_method"（可选择带有 "parser_config"）。
  • 使用摄入管道 -- 同时指定 "parse_type" 和 "pipeline_id"。

如果 "chunk_method"、"parse_type" 或 "pipeline_id" 均未提供，系统默认使用 chunk_method = "naive"。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "avatar": null,
        "chunk_count": 0,
        "chunk_method": "naive",
        "create_date": "Mon, 28 Apr 2025 18:40:41 GMT",
        "create_time": 1745836841611,
        "created_by": "3af81804241d11f0a6a79f24fc270c7f",
        "description": null,
        "document_count": 0,
        "embedding_model": "BAAI/bge-large-zh-v1.5@BAAI",
        "id": "3b4de7d4241d11f0a6a79f24fc270c7f",
        "language": "English",
        "name": "RAGFlow example",
        "pagerank": 0,
        "parser_config": {
            "chunk_token_num": 128,
            "delimiter": "\\n!?;。；！？",
            "html4excel": false,
            "layout_recognize": "DeepDOC",
            "raptor": {
                "use_raptor": false
                }
            },
        "permission": "me",
        "similarity_threshold": 0.2,
        "status": "1",
        "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
        "token_num": 0,
        "update_date": "Mon, 28 Apr 2025 18:40:41 GMT",
        "update_time": 1745836841611,
        "vector_similarity_weight": 0.3
    }
}

失败 (Failure)：

{
    "code": 101,
    "message": "Field: <name> - Message: <String should have at least 1 character> - Value: <>"
}

删除数据集 (Delete datasets)

DELETE /api/v1/datasets

根据 ID 删除数据集。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/datasets
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string] 或 null
    • "delete_all": boolean
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["d94a8dc02c9711f0930f7fbc369eab6d", "e94a8dc02c9711f0930f7fbc369eab6e"]
     }'
curl --request DELETE \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "delete_all": true
     }'
请求参数 (Request parameters)
  • "ids": (请求体参数), list[string] 或 null 指定要删除的数据集：
    • 如果省略、或者设置为 null/空数组，则不删除任何数据集。
    • 如果提供了 ID 数组，则仅删除与这些 ID 匹配的数据集。
  • "delete_all": (请求体参数), boolean 当省略 "ids" 或将其设置为 null/空数组时，是否删除当前用户拥有的所有数据集。默认值为 false。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

失败 (Failure)：

{
    "code": 108,
    "message": "User '<tenant_id>' lacks permission for datasets: '<dataset_ids>'"
}

更新数据集 (Update dataset)

PUT /api/v1/datasets/{dataset_id}

更新指定数据集的配置。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string
    • "avatar": string
    • "description": string
    • "embedding_model": string
    • "permission": string
    • "chunk_method": string
    • "pagerank": int
    • "parser_config": object
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "name": "updated_dataset"
     }'
请求参数 (Request parameters)
  • dataset_id: (路径参数) 要更新的数据集的 ID。
  • "name": (请求体参数), string 修改后的数据集名称。
    • 仅限基本多语言平面 (BMP) 字符
    • 最多 128 个字符
    • 不区分大小写
  • "avatar": (请求体参数), string 更新后的头像 Base64 编码。
    • 最多 65535 个字符
  • "embedding_model": (请求体参数), string 更新后的嵌入模型名称。
    • 在更新 "embedding_model" 之前，请确保 "chunk_count" 为 0。
    • 最多 255 个字符
    • 必须遵循 model_name@model_factory 格式
  • "permission": (请求体参数), string 更新后的数据集权限。可用选项：
    • "me"：（默认）仅您自己能管理该数据集。
    • "team"：所有团队成员都可以管理该数据集。
  • "pagerank": (请求体参数), int 参考 设置页面权重 (Set page rank)
    • 默认值：0
    • 最小值：0
    • 最大值：100
  • "chunk_method": (请求体参数), enum<string> 数据集的分块方法。可用选项：
    • "naive"：通用（默认）
    • "book"：图书
    • "email"：电子邮件
    • "laws"：法律
    • "manual"：手动
    • "one"：单文档
    • "paper"：论文
    • "picture"：图片
    • "presentation"：演示文稿 (PPT)
    • "qa"：问答 (Q&A)
    • "table"：表格
    • "tag"：标签
  • "parser_config": (请求体参数), object 数据集解析器的配置设置。此 JSON 对象中的属性随选定的 "chunk_method" 而变化：
    • 如果 "chunk_method" 为 "naive"，则 "parser_config" 对象包含以下属性：
      • "auto_keywords": int
        • 默认值：0
        • 最小值：0
        • 最大值：32
      • "auto_questions": int
        • 默认值：0
        • 最小值：0
        • 最大值：10
      • "chunk_token_num": int
        • 默认值：512
        • 最小值：1
        • 最大值：2048
      • "delimiter": string
        • 默认值："\n"。
      • "html4excel": bool
        • 是否将 Excel 文档转换为 HTML 格式。
        • 默认值：false
      • "layout_recognize": string
        • 默认值：DeepDOC
      • "tag_kb_ids": array<string>
        • 使用 Tag（标签分块）方法解析的数据集 ID。
        • 在设置此项之前，请确保已创建并正确配置了标签集。详情请见使用标签集 (Use tag sets)。
      • "task_page_size": int
        • 仅适用于 PDF。
        • 默认值：12
        • 最小值：1
      • "raptor": object RAPTOR 相关设置。
        • 默认值：{"use_raptor": false}
      • "graphrag": object GRAPHRAG 相关设置。
        • 默认值：{"use_graphrag": false}
      • "parent_child": object 父子分块设置。
        • "use_parent_child": bool 是否启用父子分块。默认值为 false。
        • "children_delimiter": string 用于将父分块拆分为子分块的分隔符。仅在 "use_parent_child" 为 true 时生效。默认值为 "\n"。
    • 如果 "chunk_method" 为 "qa"、"manual"、"paper"、"book"、"laws" 或 "presentation"，则 "parser_config" 对象包含以下属性：
      • "raptor": object RAPTOR 相关设置。
        • 默认值：{"use_raptor": false}。
    • 如果 "chunk_method" 为 "table"、"picture"、"one" 或 "email"，则 "parser_config" 为空 JSON 对象。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

失败 (Failure)：

{
    "code": 102,
    "message": "Dataset not found!"
}

获取数据集列表 (List datasets)

GET /api/v1/datasets

获取数据集列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
    • id: string
    • name: string
    • include_parsing_status: boolean
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/datasets?page=1&page_size=30&orderby=create_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • page (查询参数) int 指定显示数据集的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的数据集数量。默认值为 30。

  • orderby (查询参数) string 对数据集进行排序的属性。可用选项：

    • "create_time"（默认）
    • "update_time"

  • desc (查询参数) boolean 指示检索到的数据集是否按降序排序。默认值为 true。

  • id (查询参数) string 要检索的数据集的 ID。

  • name (查询参数) string 要检索的数据集名称。

  • include_parsing_status (查询参数) boolean 是否在每个返回的 DataSet 对象中包含文档解析状态计数。默认值为 false。当设置为 true 时，每个 DataSet 对象将包含以下附加属性：

    • unstart_count: int 尚未开始解析的文档数量。
    • running_count: int 当前正在解析的文档数量。
    • cancel_count: int 已取消解析的文档数量。
    • done_count: int 已成功解析的文档数量。
    • fail_count: int 解析失败的文档数量。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "avatar": null,
            "chunk_count": 0,
            "chunk_method": "naive",
            "create_date": "Mon, 28 Apr 2025 18:40:41 GMT",
            "create_time": 1745836841611,
            "created_by": "3af81804241d11f0a6a79f24fc270c7f",
            "description": null,
            "document_count": 0,
            "embedding_model": "BAAI/bge-large-zh-v1.5@BAAI",
            "id": "3b4de7d4241d11f0a6a79f24fc270c7f",
            "language": "English",
            "name": "RAGFlow example",
            "pagerank": 0,
            "parser_config": {
                "chunk_token_num": 128,
                "delimiter": "\\n!?;。；！？",
                "html4excel": false,
                "layout_recognize": "DeepDOC",
                "raptor": {
                    "use_raptor": false
                    }
                },
            "permission": "me",
            "similarity_threshold": 0.2,
            "status": "1",
            "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
            "token_num": 0,
            "update_date": "Mon, 28 Apr 2025 18:40:41 GMT",
            "update_time": 1745836841611,
            "vector_similarity_weight": 0.3
        }
    ]
}

获取知识图谱 (Get knowledge graph)

GET /api/v1/datasets/{dataset_id}/knowledge_graph

获取指定数据集的知识图谱 (Knowledge Graph)。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/knowledge_graph
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": {
    "nodes": [
      {"id": "node_1", "label": "Entity A"},
      {"id": "node_2", "label": "Entity B"}
    ],
    "edges": [
      {"source": "node_1", "target": "node_2", "label": "RELATED_TO"}
    ]
  }
}

失败 (Failure)：

{
  "code": 102,
  "message": "Dataset not found!"
}

删除知识图谱 (Delete knowledge graph)

DELETE /api/v1/datasets/{dataset_id}/knowledge_graph

删除指定数据集的知识图谱。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/datasets/{dataset_id}/knowledge_graph
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

构建知识图谱 (Construct knowledge graph)

POST /api/v1/datasets/{dataset_id}/knowledge_graph

为指定的数据集异步启动知识图谱构建任务。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/knowledge_graph
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

获取知识图谱构建状态 (Get knowledge graph construction status)

GET /api/v1/datasets/{dataset_id}/knowledge_graph/status

获取指定数据集的知识图谱构建状态。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/knowledge_graph/status
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph/status \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": {
    "status": "running" 
  }
}

其 "status" 可以是 "running"（正在运行）、"completed"（已完成）、"failed"（失败）或 "not_started"（未开始）。

构建 RAPTOR (Construct RAPTOR)

POST /api/v1/datasets/{dataset_id}/raptor

为指定的数据集异步启动 RAPTOR（递归摘要树）构建任务。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/raptor
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/raptor \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

获取 RAPTOR 构建状态 (Get RAPTOR construction status)

GET /api/v1/datasets/{dataset_id}/raptor/status

获取指定数据集的 RAPTOR 构建状态。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/raptor/status
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/raptor/status \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": {
    "status": "running"
  }
}

其 "status" 可以是 "running"（正在运行）、"completed"（已完成）、"failed"（失败）或 "not_started"（未开始）。

数据集内文件管理 (FILE MANAGEMENT WITHIN DATASET)

上传文档 (Upload documents)

POST /api/v1/datasets/{dataset_id}/documents

向指定的数据集上传文档。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/documents
  • 请求头 (Headers)：
    • 'Content-Type: multipart/form-data'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body) (Form-data)：
    • file: file list, 必填 包含所要上传的二进制文件的数组。
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form 'file=@/Users/admin/Downloads/test.txt' \
     --form 'file=@/Users/admin/Downloads/test2.txt'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

  • file (请求体参数 - 表单数据) file list, 必填 包含所要上传的文件的数组。支持多种常见文件类型，包括 .txt、.pdf、.docx、.xlsx、.pptx 等。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "chunk_num": 0,
            "create_date": "Mon, 28 Apr 2025 19:28:44 GMT",
            "create_time": 1745839724611,
            "created_by": "3af81804241d11f0a6a79f24fc270c7f",
            "dataset_id": "3b4de7d4241d11f0a6a79f24fc270c7f",
            "id": "3b6cf9c8241d11f0a6a79f24fc270c7f",
            "name": "test.txt",
            "parser_config": {
                "chunk_token_num": 128,
                "delimiter": "\\n!?;。；！？",
                "html4excel": false,
                "layout_recognize": "DeepDOC",
                "raptor": {
                    "use_raptor": false
                }
            },
            "parser_id": "naive",
            "process_begin_at": null,
            "process_duration": 0.0,
            "progress": 0.0,
            "progress_msg": "",
            "run": "UNSTART",
            "size": 128,
            "source_type": "local",
            "status": "1",
            "thumbnail": null,
            "token_num": 0,
            "type": "doc",
            "update_date": "Mon, 28 Apr 2025 19:28:44 GMT",
            "update_time": 1745839724611
        }
    ]
}

失败 (Failure)：

{
    "code": 102,
    "message": "Dataset not found!"
}

更新文档 (Update document)

PUT /api/v1/datasets/{dataset_id}/documents/{document_id}

更新指定文档的配置。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "display_name": string
    • "meta_fields": object
    • "chunk_method": string
    • "parser_config": object
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
      "display_name": "new_name.txt"
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 该文档所属的数据集 ID。

  • document_id (路径参数) string, 必填 要更新的文档的 ID。

  • "display_name": (请求体参数), string 要更新的文档的名称。

    • 最多 128 个字符

  • "meta_fields": (请求体参数), object 文档的自定义元数据字段。您可以为此文档定义包含键值对的 JSON 对象，并在检索过滤时使用。

  • "chunk_method": (请求体参数), string 应用于文档的解析方法。可用选项：

    • "naive"：通用
    • "manual"：手动
    • "qa"：问答 (Q&A)
    • "table"：表格
    • "paper"：论文
    • "book"：图书
    • "laws"：法律
    • "presentation"：演示文稿 (PPT)
    • "picture"：图片
    • "one"：单文档
    • "email"：电子邮件

  • "parser_config": (请求体参数), object 文档解析器的配置设置。此 JSON 对象中的属性随选定的 "chunk_method" 而变化：

    • 如果 "chunk_method" 为 "naive"，则 "parser_config" 对象包含以下属性：
      • "auto_keywords": int
        • 默认值：0
        • 最小值：0
        • 最大值：32
      • "auto_questions": int
        • 默认值：0
        • 最小值：0
        • 最大值：10
      • "chunk_token_num": int
        • 默认值：512
        • 最小值：1
        • 最大值：2048
      • "delimiter": string
        • 默认值："\n"。
      • "html4excel": bool
        • 是否将 Excel 文档转换为 HTML 格式。
        • 默认值：false
      • "layout_recognize": string
        • 默认值：DeepDOC
      • "tag_kb_ids": array<string>
        • 使用 Tag（标签分块）方法解析的数据集 ID。
        • 在设置此项之前，请确保已创建并正确配置了标签集。详情请见使用标签集 (Use tag sets)。
      • "task_page_size": int
        • 仅适用于 PDF。
        • 默认值：12
        • 最小值：1
      • "raptor": object RAPTOR 相关设置。
        • 默认值：{"use_raptor": false}
      • "graphrag": object GRAPHRAG 相关设置。
        • 默认值：{"use_graphrag": false}
      • "parent_child": object 父子分块设置。
        • "use_parent_child": bool 是否启用父子分块。默认值为 false。
        • "children_delimiter": string 用于将父分块拆分为子分块的分隔符。仅在 "use_parent_child" 为 true 时生效。默认值为 "\n"。
    • 如果 "chunk_method" 为 "qa"、"manual"、"paper"、"book"、"laws" 或 "presentation"，则 "parser_config" 对象包含以下属性：
      • "raptor": object RAPTOR 相关设置。
        • 默认值：{"use_raptor": false}。
    • 如果 "chunk_method" 为 "table"、"picture"、"one" 或 "email"，则 "parser_config" 为空 JSON 对象。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

失败 (Failure)：

{
    "code": 102,
    "message": "Document not found!"
}

下载文档 (Download document)

GET /api/v1/datasets/{dataset_id}/documents/{document_id}

下载指定的文档。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

  • document_id (路径参数) string, 必填 要下载的文档的 ID。

响应 (Response)

成功： 返回要下载的二进制文件内容，带有 Content-Disposition: attachment; filename="<FILENAME>" 的响应头。

列出文档 (List documents)

GET /api/v1/datasets/{dataset_id}/documents

获取指定数据集中的文档列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/documents
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
    • id: string
    • name: string
    • create_time_from: int
    • create_time_to: int
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/datasets/{dataset_id}/documents?page=1&page_size=30&orderby=create_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 要列出文档的数据集 ID。

  • page (查询参数) int 指定显示文档的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大文档数量。默认值为 30。

  • orderby (查询参数) string 文档排序的属性。可用选项：

    • "create_time"（默认）
    • "update_time"

  • desc (查询参数) boolean 指示检索到的文档是否按降序排序。默认值为 true。

  • id (查询参数) string 要检索的文档 ID。

  • name (查询参数) string 要检索的文档名称（支持模糊匹配）。

  • create_time_from (查询参数) int Unix 时间戳，用于过滤在此时间之后创建的文档。0 表示无过滤。默认值为 0。

  • create_time_to (查询参数) int Unix 时间戳，用于过滤在此时间之前创建的文档。0 表示无过滤。默认值为 0。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "chunk_num": 0,
            "create_date": "Mon, 28 Apr 2025 19:28:44 GMT",
            "create_time": 1745839724611,
            "created_by": "3af81804241d11f0a6a79f24fc270c7f",
            "dataset_id": "3b4de7d4241d11f0a6a79f24fc270c7f",
            "id": "3b6cf9c8241d11f0a6a79f24fc270c7f",
            "name": "test.txt",
            "parser_config": {
                "chunk_token_num": 128,
                "delimiter": "\\n!?;。；！？",
                "html4excel": false,
                "layout_recognize": "DeepDOC",
                "raptor": {
                    "use_raptor": false
                }
            },
            "parser_id": "naive",
            "process_begin_at": null,
            "process_duration": 0.0,
            "progress": 0.0,
            "progress_msg": "",
            "run": "UNSTART",
            "size": 128,
            "source_type": "local",
            "status": "1",
            "thumbnail": null,
            "token_num": 0,
            "type": "doc",
            "update_date": "Mon, 28 Apr 2025 19:28:44 GMT",
            "update_time": 1745839724611
        }
    ]
}

删除文档 (Delete documents)

DELETE /api/v1/datasets/{dataset_id}/documents

根据 ID 从指定数据集中删除文档。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/datasets/{dataset_id}/documents
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string] 或 null
    • "delete_all": boolean
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["d94a8dc02c9711f0930f7fbc369eab6d", "e94a8dc02c9711f0930f7fbc369eab6e"]
     }'
curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "delete_all": true
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

  • "ids": (请求体参数), list[string] 或 null 指定要删除的文档：

    • 如果省略、或者设置为 null/空数组，则不删除任何文档。
    • 如果提供了 ID 数组，则仅删除与这些 ID 匹配的文档。

  • "delete_all": (请求体参数), boolean 当省略 "ids" 或将其设置为 null/空数组时，是否删除当前数据集中的所有文档。默认值为 false。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

解析文档 (Parse documents)

POST /api/v1/datasets/{dataset_id}/documents/start

异步启动对指定文档的解析任务。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/documents/start
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string]
    • "run": string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/start \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["d94a8dc02c9711f0930f7fbc369eab6d", "e94a8dc02c9711f0930f7fbc369eab6e"]
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

  • "ids": (请求体参数), list[string], 必填 要解析的文档 ID 列表。

  • "run": (请求体参数), string 指定运行模式：

    • "1"：（默认）异步启动解析任务。
    • "2"：代表取消/重新开始。一般直接省略该参数，仅传 ids 即可。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

停止解析文档 (Stop parsing documents)

POST /api/v1/datasets/{dataset_id}/documents/stop

停止指定文档的解析任务。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/documents/stop
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string], 必填
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/stop \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["d94a8dc02c9711f0930f7fbc369eab6d", "e94a8dc02c9711f0930f7fbc369eab6e"]
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

  • "ids": (请求体参数), list[string], 必填 要停止解析的文档 ID 列表。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

数据集内分块管理 (CHUNK MANAGEMENT WITHIN DATASET)

添加块 (Add chunk)

POST /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

向指定文档添加一个分块 (Chunk)。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "content": string
    • "important_keywords": list[string]
    • "questions": list[string]
    • "image_base64": string
    • "tag_kwd": list[string]
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "content": "This is a manually added chunk content.",
        "important_keywords": ["manual", "chunk"]
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 该文档所属的数据集 ID。

  • document_id (路径参数) string, 必填 要添加分块的文档 ID。

  • "content": (请求体参数), string, 必填 块的文本内容。

  • "important_keywords": (请求体参数), list[string] 用于标记该块的关键术语或短语。

  • "questions": (请求体参数), list[string] 嵌入该块时使用的可选问题列表。

  • "image_base64": (请求体参数), string 与该块关联的 Base64 编码的图像。如果该块已包含图像，新图像将垂直拼接在现有图像下方。

  • "tag_kwd": (请求体参数), list[string] 与该块关联的标签关键词列表。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "available": true,
        "content": "This is a manually added chunk content.",
        "create_time": "Mon, 28 Apr 2025 19:40:41 GMT",
        "create_timestamp": 1745840441611,
        "dataset_id": "3b4de7d4241d11f0a6a79f24fc270c7f",
        "document_id": "3b6cf9c8241d11f0a6a79f24fc270c7f",
        "document_name": "test.txt",
        "id": "3b8ef9c8241d11f0a6a79f24fc270c7f",
        "image_id": "",
        "important_keywords": [
            "manual",
            "chunk"
        ],
        "questions": [],
        "tag_kwd": []
    }
}

列出块 (List chunks)

GET /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

获取指定文档中的分块列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • keywords: string
    • id: string
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?page=1&page_size=30' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 数据集 ID。

  • document_id (路径参数) string, 必填 目标文档 ID。

  • page (查询参数) int 指定显示分块的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大分块数量。默认值为 30。

  • keywords (查询参数) string 用于过滤匹配分块内容的关键词（支持模糊检索）。

  • id (查询参数) string 要检索的指定分块的 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "available": true,
            "content": "This is a manually added chunk content.",
            "create_time": "Mon, 28 Apr 2025 19:40:41 GMT",
            "create_timestamp": 1745840441611,
            "dataset_id": "3b4de7d4241d11f0a6a79f24fc270c7f",
            "document_id": "3b6cf9c8241d11f0a6a79f24fc270c7f",
            "document_name": "test.txt",
            "id": "3b8ef9c8241d11f0a6a79f24fc270c7f",
            "image_id": "",
            "important_keywords": [
                "manual",
                "chunk"
            ],
            "questions": [],
            "tag_kwd": []
        }
    ]
}

获取块 (Get chunk)

GET /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}

获取文档中特定分块的详细信息。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 该文件所属的数据集 ID。

  • document_id (路径参数) string, 必填 该文件 ID。

  • chunk_id (路径参数) string, 必填 目标分块的 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "available": true,
        "content": "This is a manually added chunk content.",
        "create_time": "Mon, 28 Apr 2025 19:40:41 GMT",
        "create_timestamp": 1745840441611,
        "dataset_id": "3b4de7d4241d11f0a6a79f24fc270c7f",
        "document_id": "3b6cf9c8241d11f0a6a79f24fc270c7f",
        "document_name": "test.txt",
        "id": "3b8ef9c8241d11f0a6a79f24fc270c7f",
        "image_id": "",
        "important_keywords": [
            "manual",
            "chunk"
        ],
        "questions": [],
        "tag_kwd": []
    }
}

删除块 (Delete chunks)

DELETE /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

根据 ID 从指定文档中删除分块。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string] 或 null
    • "delete_all": boolean
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["3b8ef9c8241d11f0a6a79f24fc270c7f"]
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 该文件所属的数据集 ID。

  • document_id (路径参数) string, 必填 该文档的 ID。

  • "ids": (请求体参数), list[string] 或 null 指定要删除的分块：

    • 如果省略、或者设置为 null/空数组，则不删除任何分块。
    • 如果提供了 ID 数组，则仅删除与这些 ID 匹配的分块。

  • "delete_all": (请求体参数), boolean 当省略 "ids" 或将其设置为 null/空数组时，是否删除当前文档中的所有分块。默认值为 false。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

更新块 (Update chunk)

PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}

更新特定分块的内容或配置。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "content": string
    • "important_keywords": list[string]
    • "questions": list[string]
    • "tag_kwd": list[string]
    • "positions": list
    • "available": boolean
    • "image_base64": string
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "content": "This is an updated manually added chunk content.",
        "important_keywords": ["manual", "chunk", "update"]
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 该文档所属的数据集 ID。

  • document_id (路径参数) string, 必填 该文档 ID。

  • chunk_id (路径参数) string, 必填 要更新的分块 ID。

  • "content": (请求体参数), string 更新后的块文本内容。

  • "important_keywords": (请求体参数), list[string] 用于标记该块的关键术语或短语。

  • "questions": (请求体参数), list[string] 与该块关联的问题列表。

  • "tag_kwd": (请求体参数), list[string] 与该块关联的标签关键词。

  • "positions": (请求体参数), list 块在源文档中的新位置信息。

  • "available": (请求体参数), boolean 分块在数据集中的可用状态：

    • false：不可用。
    • true：（默认）可用。

  • "image_base64": (请求体参数), string 与该块关联的 Base64 编码的图像。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

更新块的可用状态 (Update chunk availability)

PUT /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}/switch

启用或禁用指定的块。一旦块被禁用，它将不会被检索。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}/switch
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "available": boolean, 必填
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}/switch \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "available": false
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 目标数据集的 ID。

  • document_id (路径参数) string, 必填 目标文档的 ID。

  • chunk_id (路径参数) string, 必填 要更新状态的分块 ID。

  • "available": (请求体参数), boolean, 必填 分块的可用状态。

    • true：启用分块，可以参与检索。
    • false：禁用分块，不参与检索。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

从数据集中检索元数据摘要 (Retrieve a metadata summary from a dataset)

GET /api/v1/datasets/{dataset_id}/metadata

检索指定数据集中的元数据摘要。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/datasets/{dataset_id}/metadata
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/metadata \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • dataset_id (路径参数) string, 必填 数据集 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": {
    "author": ["bob", "alice"],
    "year": ["2023", "2024"]
  }
}

更新或删除元数据 (Update or delete metadata)

PUT /api/v1/datasets/{dataset_id}/metadata

更新或删除指定数据集的元数据字段名称或元数据字段值。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/datasets/{dataset_id}/metadata
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "action": string
    • "meta_field": string
    • "new_meta_field": string
    • "meta_value": string
    • "new_meta_value": string
更新元数据字段名称的请求示例 (Request example for updating a metadata field name)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/metadata \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "action": "update_meta_field",
        "meta_field": "author",
        "new_meta_field": "creator"
     }'
删除元数据字段名称的请求示例 (Request example for deleting a metadata field name)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/metadata \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "action": "delete_meta_field",
        "meta_field": "author"
     }'
更新元数据值的请求示例 (Request example for updating a metadata value)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/metadata \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "action": "update_meta_value",
        "meta_field": "author",
        "meta_value": "bob",
        "new_meta_value": "robert"
     }'
删除元数据值的请求示例 (Request example for deleting a metadata value)
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/metadata \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "action": "delete_meta_value",
        "meta_field": "author",
        "meta_value": "bob"
     }'
请求参数 (Request parameters)

  • dataset_id (路径参数) string, 必填 数据集 ID。

  • "action": (请求体参数), string, 必填 要执行的操作。可用选项：

    • "update_meta_field"：更新元数据字段名称。
    • "delete_meta_field"：删除元数据字段。
    • "update_meta_value"：更新元数据字段对应的值。
    • "delete_meta_value"：删除元数据值。

  • "meta_field": (请求体参数), string, 必填 目标元数据字段。

  • "new_meta_field": (请求体参数), string 更新后的元数据字段新名称（仅在 action 为 "update_meta_field" 时需要）。

  • "meta_value": (请求体参数), string 要更新或删除的目标元数据值（在 action 为 "update_meta_value" 或 "delete_meta_value" 时需要）。

  • "new_meta_value": (请求体参数), string 更新后的元数据新值（仅在 action 为 "update_meta_value" 时需要）。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

检索块 (Retrieve chunks)

POST /api/v1/retrieval

从指定的数据集检索相关块。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/retrieval
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "question": string
    • "dataset_ids": list[string]
    • "document_ids": list[string]
    • "page": int
    • "page_size": int
    • "similarity_threshold": float
    • "vector_similarity_weight": float
    • "top_k": int
    • "rerank_id": string
    • "keyword": boolean
    • "cross_languages": list[string]
    • "metadata_condition": object
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/retrieval \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "question": "what is RAGFlow?",
        "dataset_ids": ["3b4de7d4241d11f0a6a79f24fc270c7f"],
        "metadata_condition": {
          "logic": "and",
          "conditions": [
            {
              "name": "author",
              "comparison_operator": "is",
              "value": "bob"
            }
          ]
        }
     }'
请求参数 (Request parameters)

  • "question": (请求体参数), string, 必填 用户查询或检索的关键词。默认值为 ""。

  • "dataset_ids": (请求体参数), list[string], 必填 要检索的目标数据集 ID 列表。

  • "document_ids": (请求体参数), list[string] 可选的文档 ID 列表。限制检索仅在这些特定的文档范围内进行。

  • "page": (请求体参数), int 显示检索到的分块的页码。默认值为 1。

  • "page_size": (请求体参数), int 每页返回的检索块的最大数量。默认值为 30。

  • "similarity_threshold": (请求体参数), float 最小相似度分数阈值。只有得分高于该阈值的块才会被返回。默认值为 0.2。

  • "vector_similarity_weight": (请求体参数), float 向量检索的评分权重。默认值为 0.3。如果以 x 代表向量评分权重，则 (1 - x) 是关键词词频 (Term Similarity) 评分的权重。

  • "top_k": (请求体参数), int 检索匹配阶段初始候选块的数量。默认值为 1024。

  • "rerank_id": (请求体参数), string 用于重排检索结果的重排模型 (Rerank Model) ID。默认值为 null。

  • "keyword": (请求体参数), boolean 是否启用关键词精准匹配：

    • true：启用。
    • false：（默认）禁用。

  • "cross_languages": (请求体参数), list[string] 需要自动翻译的查询语言列表，以支持在多语言文档环境下的检索。

  • "metadata_condition": (请求体参数), object 元数据过滤条件 JSON 对象。详情参阅 构建元数据过滤条件 (Build metadata filter condition)。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "available": true,
            "content": "This is a manually added chunk content.",
            "create_time": "Mon, 28 Apr 2025 19:40:41 GMT",
            "create_timestamp": 1745840441611,
            "dataset_id": "3b4de7d4241d11f0a6a79f24fc270c7f",
            "document_id": "3b6cf9c8241d11f0a6a79f24fc270c7f",
            "document_name": "test.txt",
            "id": "3b8ef9c8241d11f0a6a79f24fc270c7f",
            "image_id": "",
            "important_keywords": [
                "manual",
                "chunk"
            ],
            "questions": [],
            "similarity": 0.5697155305154673,
            "tag_kwd": [],
            "term_similarity": 0.5000000005,
            "vector_similarity": 0.7323851005515574
        }
    ]
}

对话助手管理 (CHAT ASSISTANT MANAGEMENT)

创建对话助手 (Create chat assistant)

POST /api/v1/chats

创建一个对话助手。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/chats
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string
    • "icon": string
    • "dataset_ids": list[string]
    • "llm_id": string
    • "llm_setting": object
    • "prompt_config": object
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/chats \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "Miss R",
        "dataset_ids": ["3b4de7d4241d11f0a6a79f24fc270c7f"]
     }'
请求参数 (Request parameters)

  • "name": (请求体参数), string, 必填 对话助手的名称。

    • 最多 128 个字符

  • "icon": (请求体参数), string 头像的 Base64 编码。

    • 默认值为 ""。

  • "dataset_ids": (请求体参数), list[string] 关联的数据集 ID 列表。默认值为 []。省略或为空时，SDK 会创建一个空的对话助手，您可以在稍后绑定数据集。

  • "llm_id": (请求体参数), string 要使用的 LLM 模型名称/ID。如果为 null，则使用用户的默认对话模型。默认值为 null。

  • "llm_setting": (请求体参数), object LLM 生成参数的配置。默认值为 null（此时应用服务器端默认配置）。支持的属性：

    • "temperature": float - 控制模型输出的随机性。值越高，输出越有创意；值越低，回复越确定。默认值为 0.1。
    • "top_p": float - 设置核采样阈值。模型仅考虑累计概率达到 top_p 的 Token。默认值为 0.3。
    • "presence_penalty": float - 根据 Token 到目前为止是否在文本中出现进行惩罚，增加模型讨论新话题的可能性。默认值为 0.4。
    • "frequency_penalty": float - 根据 Token 在文本中的现有频率进行惩罚，降低模型重复相同内容的可能性。默认值为 0.7。
    • "max_token": int - 回复中生成的最大 Token 数量。默认值为 512。

  • "prompt_config": (请求体参数), object 针对 LLM 的提示词行为配置。默认值为 null（此时应用服务器端默认配置）。支持的属性：

    • "system": string - 核心系统提示词 (System Prompt)，用于定义助手的角色。
    • "empty_response": string - 在未检索到任何相关信息时返回的特定消息。若留空，LLM 将会自行生成回复。默认值为 null。
    • "prologue": string - 向用户展示的开场白问候语。默认值为 "Hi! I’m your assistant. What can I do for you?"。
    • "quote": boolean - 决定助手是否应在回复中包含引用或来源信息。默认值为 true。
    • "parameters": list[dict] - 系统提示词中使用的变量列表。每个条目必须包含一个 "key" (string) 和一个 "optional" (boolean) 状态。knowledge 键保留用于检索到的上下文块。默认值：[{"key": "knowledge", "optional": true}]。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "avatar": "",
        "create_date": "Mon, 28 Apr 2025 20:00:24 GMT",
        "create_time": 1745841624611,
        "created_by": "3af81804241d11f0a6a79f24fc270c7f",
        "dataset_ids": [
            "3b4de7d4241d11f0a6a79f24fc270c7f"
        ],
        "id": "3baef9c8241d11f0a6a79f24fc270c7f",
        "llm_id": "glm-4-flash@ZHIPU-AI",
        "llm_setting": {
            "frequency_penalty": 0.7,
            "max_token": 512,
            "presence_penalty": 0.4,
            "temperature": 0.1,
            "top_p": 0.3
        },
        "name": "Miss R",
        "prompt_config": {
            "empty_response": "",
            "parameters": [
                {
                    "key": "knowledge",
                    "optional": true
                }
            ],
            "prologue": "Hi! I’m Miss R. What can I do for you?",
            "quote": true,
            "system": "You are a smart assistant."
        },
        "rerank_id": "",
        "similarity_threshold": 0.2,
        "status": "1",
        "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
        "top_k": 1024,
        "top_n": 6,
        "update_date": "Mon, 28 Apr 2025 20:00:24 GMT",
        "update_time": 1745841624611,
        "vector_similarity_weight": 0.3
    }
}

更新对话助手 (Update chat assistant)

PUT /api/v1/chats/{chat_id}

更新指定对话助手的全部配置。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/chats/{chat_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string
    • "icon": string
    • "dataset_ids": list[string]
    • "llm_id": string
    • "llm_setting": object
    • "prompt_config": object
    • "similarity_threshold": float
    • "vector_similarity_weight": float
    • "top_n": int
    • "top_k": int
    • "rerank_id": string
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/chats/{chat_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "Updated Miss R",
        "dataset_ids": ["3b4de7d4241d11f0a6a79f24fc270c7f"],
        "llm_setting": {
            "temperature": 0.5
        }
     }'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 目标对话助手的 ID。

  • "name": (请求体参数), string 更新后的名称。

  • "icon": (请求体参数), string 更新后的头像 Base64 编码。

  • "dataset_ids": (请求体参数), list[string] 关联的数据集 ID 列表。

  • "llm_id": (请求体参数), string 要使用的新 LLM 模型。

  • "llm_setting": (请求体参数), object LLM 生成参数的配置（各字段参考创建对话助手）。

  • "prompt_config": (请求体参数), object 提示词相关的行为设置（各字段参考创建对话助手）。

  • "similarity_threshold": (请求体参数), float 检索到的上下文块所需的最小相似度分数。默认值为 0.2。

  • "vector_similarity_weight": (请求体参数), float 混合检索评分中向量相似度的权重。默认值为 0.3。

  • "top_n": (请求体参数), int 提供给 LLM 作为上下文的相关度前 N 的分块数量。默认值为 6。

  • "top_k": (请求体参数), int 检索用于重排的初始候选池大小。默认值为 1024。

  • "rerank_id": (请求体参数), string 重排模型的唯一标识符。如果留空，则使用标准向量相似度。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

获取对话助手 (Get chat assistant)

GET /api/v1/chats/{chat_id}

获取指定对话助手的详细配置配置。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/chats/{chat_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/chats/{chat_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • chat_id (路径参数) string, 必填 目标对话助手的 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "avatar": "",
        "create_date": "Mon, 28 Apr 2025 20:00:24 GMT",
        "create_time": 1745841624611,
        "created_by": "3af81804241d11f0a6a79f24fc270c7f",
        "dataset_ids": [
            "3b4de7d4241d11f0a6a79f24fc270c7f"
        ],
        "id": "3baef9c8241d11f0a6a79f24fc270c7f",
        "llm_id": "glm-4-flash@ZHIPU-AI",
        "llm_setting": {
            "frequency_penalty": 0.7,
            "max_token": 512,
            "presence_penalty": 0.4,
            "temperature": 0.1,
            "top_p": 0.3
        },
        "name": "Miss R",
        "prompt_config": {
            "empty_response": "",
            "parameters": [
                {
                    "key": "knowledge",
                    "optional": true
                }
            ],
            "prologue": "Hi! I’m Miss R. What can I do for you?",
            "quote": true,
            "system": "You are a smart assistant."
        },
        "rerank_id": "",
        "similarity_threshold": 0.2,
        "status": "1",
        "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
        "top_k": 1024,
        "top_n": 6,
        "update_date": "Mon, 28 Apr 2025 20:00:24 GMT",
        "update_time": 1745841624611,
        "vector_similarity_weight": 0.3
    }
}

部分更新对话助手 (Partially update chat assistant)

PATCH /api/v1/chats/{chat_id}

部分更新指定对话助手的配置设置。

请求 (Request)

  • 方法：PATCH
  • URL：/api/v1/chats/{chat_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)： JSON 对象中包含要修改的配置属性。省略的字段将在服务器端保持原样。
请求示例 (Request example)
curl --request PATCH \
     --url http://{address}/api/v1/chats/{chat_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "Partially Updated Miss R"
     }'

响应 (Response)

成功 (Success)：

{
    "code": 0
}

删除对话助手 (Delete chat assistant)

DELETE /api/v1/chats/{chat_id}

删除指定的对话助手。

DEPRECATED

此接口已被废弃。请改用 /api/v1/chats（传递 ids 列表）的批量删除接口。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/chats/{chat_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/chats/{chat_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

响应 (Response)

成功 (Success)：

{
    "code": 0
}

批量删除对话助手 (Delete chat assistants)

DELETE /api/v1/chats

批量删除指定的对话助手。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/chats
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string] 或 null
    • "delete_all": boolean
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/chats \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["d94a8dc02c9711f0930f7fbc369eab6d", "e94a8dc02c9711f0930f7fbc369eab6e"]
     }'
请求参数 (Request parameters)
  • "ids": (请求体参数), list[string] 或 null 指定要删除的对话助手：
    • 如果省略、或者设置为 null/空数组，则不删除任何对话助手。
    • 如果提供了 ID 数组，则仅删除与这些 ID 匹配的对话助手。
  • "delete_all": (请求体参数), boolean 当省略 "ids" 或将其设置为 null/空数组时，是否删除当前用户拥有的所有对话助手。默认值为 false。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

获取对话助手列表 (List chat assistants)

GET /api/v1/chats

获取所有可用的对话助手列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/chats
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
    • id: string
    • name: string
    • keywords: string
    • owner_ids: string 或 list[string]
    • parser_id: string
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/chats?page=1&page_size=30&orderby=create_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • page (查询参数) int 指定显示对话助手的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大对话助手数量。默认值为 30。

  • orderby (查询参数) string 对话助手排序的属性。可用选项：

    • "create_time"（默认）
    • "update_time"

  • desc (查询参数) boolean 指示检索到的对话助手是否按降序排序。默认值为 true。

  • id (查询参数) string 要检索的指定对话助手的 ID。

  • name (查询参数) string 要检索的指定对话助手的名称。

  • keywords (查询参数) string 对对话助手名称进行不区分大小写的模糊匹配关键字。

  • owner_ids (查询参数) string 或 list[string] 过滤属于指定所有者租户 ID 的对话助手。

  • parser_id (查询参数) string 根据特定的解析器类型过滤结果。

如果指定了 id 或 name，精确过滤的优先级高于 keywords 提供的模糊检索。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "avatar": "",
            "create_date": "Mon, 28 Apr 2025 20:00:24 GMT",
            "create_time": 1745841624611,
            "created_by": "3af81804241d11f0a6a79f24fc270c7f",
            "dataset_ids": [
                "3b4de7d4241d11f0a6a79f24fc270c7f"
            ],
            "id": "3baef9c8241d11f0a6a79f24fc270c7f",
            "llm_id": "glm-4-flash@ZHIPU-AI",
            "llm_setting": {
                "frequency_penalty": 0.7,
                "max_token": 512,
                "presence_penalty": 0.4,
                "temperature": 0.1,
                "top_p": 0.3
            },
            "name": "Miss R",
            "prompt_config": {
                "empty_response": "",
                "parameters": [
                    {
                        "key": "knowledge",
                        "optional": true
                    }
                ],
                "prologue": "Hi! I’m Miss R. What can I do for you?",
                "quote": true,
                "system": "You are a smart assistant."
            },
            "rerank_id": "",
            "similarity_threshold": 0.2,
            "status": "1",
            "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
            "top_k": 1024,
            "top_n": 6,
            "update_date": "Mon, 28 Apr 2025 20:00:24 GMT",
            "update_time": 1745841624611,
            "vector_similarity_weight": 0.3
        }
    ]
}

会话管理 (SESSION MANAGEMENT)

创建与对话助手的会话 (Create session with chat assistant)

POST /api/v1/chats/{chat_id}/sessions

创建与当前对话助手的会话。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/chats/{chat_id}/sessions
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/chats/{chat_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "New session"
     }'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 目标对话助手的 ID。

  • "name": (请求体参数), string 创建的会话名称。

    • 默认值为 "New session"。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "chat_id": "3baef9c8241d11f0a6a79f24fc270c7f",
        "create_date": "Mon, 28 Apr 2025 20:10:41 GMT",
        "create_time": 1745842241611,
        "id": "3bc1cf9c241d11f0a6a79f24fc270c7f",
        "message": [
            {
                "content": "Hi! I am Miss R, your assistant. What can I do for you?",
                "role": "assistant"
            }
        ],
        "name": "New session",
        "update_date": "Mon, 28 Apr 2025 20:10:41 GMT",
        "update_time": 1745842241611
    }
}

更新会话 (Update chat assistant's session)

PUT /api/v1/chats/{chat_id}/sessions/{session_id}

修改指定会话的名称。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/chats/{chat_id}/sessions/{session_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string, 必填
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/chats/{chat_id}/sessions/{session_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "updated session name"
     }'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 该会话所属的对话助手 ID。

  • session_id (路径参数) string, 必填 要更新的会话 ID。

  • "name": (请求体参数), string, 必填 更新后的会话新名称。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

列出对话会话 (List chat assistant's sessions)

GET /api/v1/chats/{chat_id}/sessions

获取与特定对话助手关联的所有会话列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/chats/{chat_id}/sessions
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
    • id: string
    • name: string
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/chats/{chat_id}/sessions?page=1&page_size=30&orderby=create_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 目标对话助手 ID。

  • page (查询参数) int 指定显示会话的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大会话数量。默认值为 30。

  • orderby (查询参数) string 会话排序的排序。可用选项：

    • "create_time"（默认）
    • "update_time"

  • desc (查询参数) boolean 指示检索到的会话是否按降序排序。默认值为 true。

  • id (查询参数) string 要检索的特定会话的 ID。

  • name (查询参数) string 要检索的特定会话的名称。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "chat_id": "3baef9c8241d11f0a6a79f24fc270c7f",
            "create_date": "Mon, 28 Apr 2025 20:10:41 GMT",
            "create_time": 1745842241611,
            "id": "3bc1cf9c241d11f0a6a79f24fc270c7f",
            "message": [
                {
                    "content": "Hi! I am Miss R, your assistant. What can I do for you?",
                    "role": "assistant"
                }
            ],
            "name": "New session",
            "update_date": "Mon, 28 Apr 2025 20:10:41 GMT",
            "update_time": 1745842241611
        }
    ]
}

获取会话详情 (Get chat assistant's session)

GET /api/v1/chats/{chat_id}/sessions/{session_id}

获取指定会话的完整聊天记录。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/chats/{chat_id}/sessions/{session_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/chats/{chat_id}/sessions/{session_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 该会话所属的对话助手 ID。

  • session_id (路径参数) string, 必填 目标会话 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "chat_id": "3baef9c8241d11f0a6a79f24fc270c7f",
        "create_date": "Mon, 28 Apr 2025 20:10:41 GMT",
        "create_time": 1745842241611,
        "id": "3bc1cf9c241d11f0a6a79f24fc270c7f",
        "message": [
            {
                "content": "Hi! I am Miss R, your assistant. What can I do for you?",
                "role": "assistant"
            },
            {
                "content": "tell me about RAGFlow",
                "role": "user"
            },
            {
                "content": "RAGFlow is a RAG engine...",
                "role": "assistant"
            }
        ],
        "name": "New session",
        "update_date": "Mon, 28 Apr 2025 20:20:41 GMT",
        "update_time": 1745842841611
    }
}

删除会话中的消息 (Delete a message from a chat assistant's session)

DELETE /api/v1/chats/{chat_id}/sessions/{session_id}/messages/{message_id}

从指定的对话会话中删除特定消息（仅在允许修改历史记录的情况下）。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/chats/{chat_id}/sessions/{session_id}/messages/{message_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/chats/{chat_id}/sessions/{session_id}/messages/{message_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 该会话所属的对话助手 ID。

  • session_id (路径参数) string, 必填 该会话 ID。

  • message_id (路径参数) string, 必填 要删除的指定消息 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

更新消息的反馈评价 (Update message feedback in a chat assistant's session)

PUT /api/v1/chats/{chat_id}/sessions/{session_id}/messages/{message_id}/feedback

更新对话会话中特定消息的用户反馈状态（例如点赞或点踩，以及可选的评语内容）。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/chats/{chat_id}/sessions/{session_id}/messages/{message_id}/feedback
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "thumb": boolean
    • "feedback": string
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/chats/{chat_id}/sessions/{session_id}/messages/{message_id}/feedback \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "thumb": true,
        "feedback": "Very accurate and helpful answer!"
     }'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 该会话所属的对话助手 ID。

  • session_id (路径参数) string, 必填 目标会话 ID。

  • message_id (路径参数) string, 必填 要评价的消息 ID。

  • "thumb": (请求体参数), boolean 是否给与正面评价：

    • true：正面好评（赞）。
    • false：负面评价（踩）。

  • "feedback": (请求体参数), string 可选的用户附加反馈评价或修改意见评语。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

批量删除会话 (Delete chat assistant's sessions)

DELETE /api/v1/chats/{chat_id}/sessions

批量删除指定对话助手下的会话。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/chats/{chat_id}/sessions
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string] 或 null
    • "delete_all": boolean
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/chats/{chat_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["3bc1cf9c241d11f0a6a79f24fc270c7f"]
     }'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 该会话所属的对话助手 ID。

  • "ids": (请求体参数), list[string] 或 null 指定要删除的会话：

    • 如果省略、或者设置为 null/空数组，则不删除任何会话。
    • 如果提供了 ID 数组，则仅删除与这些 ID 匹配的会话。

  • "delete_all": (请求体参数), boolean 当省略 "ids" 或将其设置为 null/空数组时，是否删除当前对话助手下的所有会话。默认值为 false。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

与对话助手对话 (Converse with chat assistant)

POST /api/v1/chats/{chat_id}/sessions/{session_id}/completion

向指定的会话发送问题以获取 AI 生成的回复。

注意

在流式传输模式下，并非所有回复都包含引用 (Reference)，这取决于系统的综合检索与推理。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/chats/{chat_id}/sessions/{session_id}/completion
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "question": string
    • "stream": boolean
    • "quote": boolean
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/chats/{chat_id}/sessions/{session_id}/completion \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "question": "What is RAGFlow?",
        "stream": true
     }'
请求参数 (Request parameters)

  • chat_id (路径参数) string, 必填 要进行对话的对话助手 ID。

  • session_id (路径参数) string, 必填 该对话的会话 ID。

  • "question": (请求体参数), string, 必填 用户发送的问题。

  • "stream": (请求体参数), boolean 是否流式返回。默认值为 true。

  • "quote": (请求体参数), boolean 是否展示检索的来源文档引用。默认值为 true。

响应 (Response)

(参见上面兼容 OpenAI 的接口响应规范)。

创建与智能体的会话 (Create session with agent)

POST /api/v1/agents/{agent_id}/sessions

创建与当前智能体 (Agent) 的会话。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/agents/{agent_id}/sessions
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "inputs": object（可选）
    • "release": boolean（可选）
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "inputs": {
            "name": "robert"
        }
     }'
请求参数 (Request parameters)

  • agent_id (路径参数) string, 必填 目标智能体的 ID。

  • "inputs": (请求体参数), object 传入工作流 Begin（开始）组件中定义的初始输入变量参数字典。

  • "release": (请求体参数), boolean 是否仅与已经发布的最新智能体版本进行会话。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "agent_id": "c1f79142831f11f09cc51795b9eb07c0",
        "create_date": "Mon, 28 Apr 2025 20:10:41 GMT",
        "create_time": 1745842241611,
        "id": "c39f6f9c83d911f0858253708ecb6573",
        "message": [
            {
                "content": "Hi! I am Miss R, your assistant. What can I do for you?",
                "role": "assistant"
            }
        ],
        "update_date": "Mon, 28 Apr 2025 20:10:41 GMT",
        "update_time": 1745842241611
    }
}

与智能体对话 (Converse with agent)

POST /api/v1/agents/{agent_id}/sessions/{session_id}/completion

向指定的智能体会话发送问题，并接收 AI 生成的回复。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/agents/{agent_id}/sessions/{session_id}/completion
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "question": string
    • "stream": boolean
    • "inputs": object
    • "return_trace": boolean
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/sessions/{session_id}/completion \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "question": "What is RAGFlow?",
        "stream": true,
        "inputs": {
            "name": "bob"
        }
     }'
请求参数 (Request parameters)

  • agent_id (路径参数) string, 必填 目标智能体的 ID。

  • session_id (路径参数) string, 必填 目标会话的 ID。

  • "question": (请求体参数), string, 必填 发送给智能体的用户消息。若智能体的 Begin（开始）组件带有其它参数，此处可以为空字符串。

  • "stream": (请求体参数), boolean 是否以流式输出回复。默认值为 true。

  • "inputs": (请求体参数), object 智能体工作流输入参数字典，用于重置或提供 Begin 组件所需的配置值。

  • "return_trace": (请求体参数), boolean 是否在最终响应中返回详细的组件级执行轨迹信息。默认值为 false。

响应 (Response)

流式 (Stream)：

...

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": " terminal"
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": "."
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: {
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "object": "chat.completion.chunk",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "choices": [
        {
            "delta": {
                "content": "",
                "reference": {
                    "chunks": {
                        "20": {
                            "id": "4b8935ac0a22deb1",
                            "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                            "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "document_name": "INSTALL22.md",
                            "document_metadata": {
                                "author": "bob",
                                "year": "2023",
                                "source": "internal"
                            },
                            "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                            "image_id": "",
                            "positions": [
                                [
                                    12,
                                    11,
                                    11,
                                    11,
                                    11
                                ]
                            ],
                            "url": null,
                            "similarity": 0.5697155305154673,
                            "vector_similarity": 0.7323851005515574,
                            "term_similarity": 0.5000000005,
                            "doc_type": ""
                        }
                    },
                    "doc_aggs": {
                        "INSTALL22.md": {
                            "doc_name": "INSTALL22.md",
                            "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "count": 3
                        },
                        "INSTALL.md": {
                            "doc_name": "INSTALL.md",
                            "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                            "count": 2
                        },
                        "INSTALL(1).md": {
                            "doc_name": "INSTALL(1).md",
                            "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                            "count": 2
                        },
                        "INSTALL3.md": {
                            "doc_name": "INSTALL3.md",
                            "doc_id": "4bdab5825e1511f0907f09f583941b45",
                            "count": 1
                        }
                    }
                }
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: [DONE]

非流式 (Non-stream)：

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For Windows:\n1. **Download from GitHub**: \n   - Visit the [Neovim releases page](https://github.com/neovim/neovim/releases)\n   - Download the latest Windows installer (nvim-win64.msi)\n   - Run the installer and follow the prompts\n\n2. **Using winget** (Windows Package Manager):\n...",
                "reference": {
                    "chunks": {
                        "20": {
                            "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.",
                            "dataset_id": "456ce60c5e1511f0907f09f583941b45",
                            "doc_type": "",
                            "document_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "document_name": "INSTALL22.md",
                            "document_metadata": {
                                "author": "bob",
                                "year": "2023",
                                "source": "internal"
                            },
                            "id": "4b8935ac0a22deb1",
                            "image_id": "",
                            "positions": [
                                [
                                    12,
                                    11,
                                    11,
                                    11,
                                    11
                                ]
                            ],
                            "similarity": 0.5697155305154673,
                            "term_similarity": 0.5000000005,
                            "url": null,
                            "vector_similarity": 0.7323851005515574
                        }
                    },
                    "doc_aggs": {
                        "INSTALL(1).md": {
                            "count": 2,
                            "doc_id": "4bdfb42e5e1511f0907f09f583941b45",
                            "doc_name": "INSTALL(1).md"
                        },
                        "INSTALL.md": {
                            "count": 2,
                            "doc_id": "4bd7fdd85e1511f0907f09f583941b45",
                            "doc_name": "INSTALL.md"
                        },
                        "INSTALL22.md": {
                            "count": 3,
                            "doc_id": "4bdd2ff65e1511f0907f09f583941b45",
                            "doc_name": "INSTALL22.md"
                        },
                        "INSTALL3.md": {
                            "count": 1,
                            "doc_id": "4bdab5825e1511f0907f09f583941b45",
                            "doc_name": "INSTALL3.md"
                        }
                    }
                },
                "role": "assistant"
            }
        }
    ],
    "created": null,
    "id": "c39f6f9c83d911f0858253708ecb6573",
    "model": "d1f79142831f11f09cc51795b9eb07c0",
    "object": "chat.completion",
    "param": null,
    "usage": {
        "completion_tokens": 415,
        "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
        },
        "prompt_tokens": 6,
        "total_tokens": 421
    }
}

获取智能体会话列表 (List agent sessions)

GET /api/v1/agents/{agent_id}/sessions

获取与特定智能体关联的所有会话列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/agents/{agent_id}/sessions
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
    • id: string
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/agents/{agent_id}/sessions?page=1&page_size=30&orderby=update_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • agent_id (路径参数) string, 必填 目标智能体的 ID。

  • page (查询参数) int 指定显示会话的页码。默认值为 1。

  • page_size (查询参数) int 每页返回的会话最大数量。默认值为 30。

  • orderby (查询参数) string 排序的会话字段。可用选项：

    • "create_time"
    • "update_time"（默认）

  • desc (查询参数) boolean 指示结果是否以降序排序。默认值为 true。

  • id (查询参数) string 要检索的指定智能体会话的 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "agent_id": "c1f79142831f11f09cc51795b9eb07c0",
            "create_date": "Mon, 28 Apr 2025 20:10:41 GMT",
            "create_time": 1745842241611,
            "id": "c39f6f9c83d911f0858253708ecb6573",
            "message": [
                {
                    "content": "Hi! I am Miss R, your assistant. What can I do for you?",
                    "role": "assistant"
                }
            ],
            "update_date": "Mon, 28 Apr 2025 20:10:41 GMT",
            "update_time": 1745842241611
        }
    ]
}

删除智能体会话 (Delete agent's sessions)

DELETE /api/v1/agents/{agent_id}/sessions

批量删除指定智能体下的会话。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/agents/{agent_id}/sessions
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string] 或 null
    • "delete_all": boolean
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/agents/{agent_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["c39f6f9c83d911f0858253708ecb6573"]
     }'
请求参数 (Request parameters)

  • agent_id (路径参数) string, 必填 该会话所属的智能体 ID。

  • "ids": (请求体参数), list[string] 或 null 指定要删除的会话：

    • 如果省略、或者设置为 null/空数组，则不删除任何会话。
    • 如果提供了 ID 数组，则仅删除与这些 ID 匹配的会话。

  • "delete_all": (请求体参数), boolean 当省略 "ids" 或将其设置为 null/空数组时，是否删除当前智能体下的所有会话。默认值为 false。

响应 (Response)

成功 (Success)：

{
    "code": 0
}

文本转语音 (Text-to-speech)

POST /api/v1/tts

将文本内容转换为语音（音频流）。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/tts
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "text": string
    • "voice": string
    • "tts_id": string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/tts \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "text": "Hello world, welcome to RAGFlow!"
     }'
请求参数 (Request parameters)

  • "text": (请求体参数), string, 必填 要转换为语音的文本内容。

  • "voice": (请求体参数), string 要使用的发音人/声音名称。省略时采用默认声音。

  • "tts_id": (请求体参数), string TTS（文本转语音）服务的模型名称或 ID。

响应 (Response)

成功： 返回音频文件内容（例如二进制 .mp3 或 .wav 音频流），并附带适当的音频 Content-Type 响应头。

语音转文字 (Speech-to-text)

POST /api/v1/stt

将录制的语音音频文件转换为文本。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/stt
  • 请求头 (Headers)：
    • 'Content-Type: multipart/form-data'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body) (Form-data)：
    • file: file, 必填
    • stt_id: string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/stt \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form 'file=@/path/to/voice.mp3'
请求参数 (Request parameters)

  • file (请求体参数 - 表单数据) file, 必填 要转换的音频文件。

  • stt_id (请求体参数 - 表单数据) string 指定使用的 STT（语音转文字/ASR）模型 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": "Hello world welcome to RAGFlow"
}

生成思维导图 (Generate mind map)

POST /api/v1/canvas/mindmap

为给定的聊天会话内容异步生成思维导图结构。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/canvas/mindmap
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "session_id": string, 必填
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/canvas/mindmap \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "session_id": "3bc1cf9c241d11f0a6a79f24fc270c7f"
     }'

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": {
    "topic": "RAGFlow Overview",
    "children": [
      {
        "topic": "Key Features",
        "children": [
          {"topic": "DeepDOC Ingestion"},
          {"topic": "OpenAI Compatibility"}
        ]
      }
    ]
  }
}

POST /api/v1/canvas/related_questions

基于给定的聊天会话内容推荐或生成用户可能感兴趣的后续相关问题列表。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/canvas/related_questions
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "session_id": string, 必填
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/canvas/related_questions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "session_id": "3bc1cf9c241d11f0a6a79f24fc270c7f"
     }'

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": [
    "How does DeepDOC parsing work?",
    "What models does RAGFlow support?",
    "How can I deploy RAGFlow on my machine?"
  ]
}

智能体管理 (AGENT MANAGEMENT)

获取智能体列表 (List agents)

GET /api/v1/agents

获取所有可用的智能体列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/agents
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/agents?page=1&page_size=30&orderby=update_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • page (查询参数) int 指定显示智能体的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大智能体数量。默认值为 30。

  • orderby (查询参数) string 智能体排序的属性。可用选项：

    • "create_time"
    • "update_time"（默认）

  • desc (查询参数) boolean 指示检索到的智能体是否按降序排序。默认值为 true。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "avatar": null,
            "canvas_type": "smart",
            "create_date": "Mon, 28 Apr 2025 20:00:24 GMT",
            "create_time": 1745841624611,
            "created_by": "3af81804241d11f0a6a79f24fc270c7f",
            "description": "A test agent",
            "dsl": {
                "components": {}
            },
            "id": "c1f79142831f11f09cc51795b9eb07c0",
            "status": "1",
            "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
            "title": "Test Agent",
            "update_date": "Mon, 28 Apr 2025 20:00:24 GMT",
            "update_time": 1745841624611,
            "user_id": "3af81804241d11f0a6a79f24fc270c7f"
        }
    ]
}

创建智能体 (Create agent)

POST /api/v1/agents

新建一个画布智能体应用。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/agents
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "title": string, 必填
    • "dsl": object, 必填
    • "description": string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/agents \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "title": "Test Agent",
        "description": "A test agent",
        "dsl": {
            "components": {}
        }
     }'
请求参数 (Request parameters)

  • "title": (请求体参数), string, 必填 智能体的标题。

  • "dsl": (请求体参数), object, 必填 智能体的画布流程组件 DSL。

  • "description": (请求体参数), string 对智能体的功能描述。默认值为 null。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

更新智能体 (Update agent)

PUT /api/v1/agents/{agent_id}

更新指定智能体应用的标题、描述和画布 DSL。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/agents/{agent_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "title": string
    • "description": string
    • "dsl": object
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/agents/{agent_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "title": "Updated Test Agent",
        "description": "An updated test agent",
        "dsl": {
            "components": {}
        }
     }'
请求参数 (Request parameters)

  • agent_id (路径参数) string, 必填 目标智能体的 ID。

  • "title": (请求体参数), string 智能体的新标题。传入 null 或省略则不修改。

  • "description": (请求体参数), string 智能体的新描述。传入 null 或省略则不修改。

  • "dsl": (请求体参数), object 智能体的新画布组件 DSL。传入 null 或省略则不修改。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

删除智能体 (Delete agent)

DELETE /api/v1/agents/{agent_id}

删除指定的智能体。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/agents/{agent_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/agents/{agent_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • agent_id (路径参数) string, 必填 要删除的智能体 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

记忆体管理 (MEMORY MANAGEMENT)

创建记忆体 (Create Memory)

POST /api/v1/memories

创建一个记忆体 (Memory) 实例。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/memories
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string, 必填
    • "description": string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/memories \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "User memory",
        "description": "Store personal user preferences and facts"
     }'
请求参数 (Request parameters)

  • "name": (请求体参数), string, 必填 记忆体的唯一友好名称。

    • 最多 128 个字符

  • "description": (请求体参数), string 记忆体的简要功能描述。默认值为 ""。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "create_date": "Mon, 28 Apr 2025 21:00:24 GMT",
        "create_time": 1745845224611,
        "description": "Store personal user preferences and facts",
        "id": "e1f79142831f11f09cc51795b9eb07c0",
        "name": "User memory",
        "update_date": "Mon, 28 Apr 2025 21:00:24 GMT",
        "update_time": 1745845224611
    }
}

更新记忆体 (Update Memory)

PUT /api/v1/memories/{memory_id}

修改指定记忆体的友好名称或描述。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/memories/{memory_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string
    • "description": string
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/memories/{memory_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "Updated User memory",
        "description": "Updated Store personal user preferences and facts"
     }'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 要更新的记忆体 ID。

  • "name": (请求体参数), string 记忆体的新名称。

  • "description": (请求体参数), string 记忆体的新描述。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

获取记忆体列表 (List Memory)

GET /api/v1/memories

获取所有可用的记忆体列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/memories
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/memories?page=1&page_size=30&orderby=update_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • page (查询参数) int 指定显示记忆体的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大记忆体数量。默认值为 30。

  • orderby (查询参数) string 记忆体排序的属性。可用选项：

    • "create_time"
    • "update_time"（默认）

  • desc (查询参数) boolean 指示检索到的记忆体是否按降序排序。默认值为 true。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "create_date": "Mon, 28 Apr 2025 21:00:24 GMT",
            "create_time": 1745845224611,
            "description": "Store personal user preferences and facts",
            "id": "e1f79142831f11f09cc51795b9eb07c0",
            "name": "User memory",
            "update_date": "Mon, 28 Apr 2025 21:00:24 GMT",
            "update_time": 1745845224611
        }
    ]
}

获取记忆体配置 (Get Memory Config)

GET /api/v1/memories/{memory_id}

获取指定记忆体实例的详细信息或配置属性。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/memories/{memory_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/memories/{memory_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • memory_id (路径参数) string, 必填 目标记忆体的 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "create_date": "Mon, 28 Apr 2025 21:00:24 GMT",
        "create_time": 1745845224611,
        "description": "Store personal user preferences and facts",
        "id": "e1f79142831f11f09cc51795b9eb07c0",
        "name": "User memory",
        "update_date": "Mon, 28 Apr 2025 21:00:24 GMT",
        "update_time": 1745845224611
    }
}

删除记忆体 (Delete Memory)

DELETE /api/v1/memories/{memory_id}

删除指定的记忆体实例。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/memories/{memory_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/memories/{memory_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • memory_id (路径参数) string, 必填 要删除的记忆体 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

获取记忆体中的消息列表 (List messages of a memory)

GET /api/v1/memories/{memory_id}/messages

检索存储在指定记忆体中的所有历史消息。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/memories/{memory_id}/messages
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/memories/{memory_id}/messages?page=1&page_size=30&orderby=create_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 目标记忆体 ID。

  • page (查询参数) int 指定显示消息的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大消息数量。默认值为 30。

  • orderby (查询参数) string 排序的消息字段。可用选项：

    • "create_time"（默认）

  • desc (查询参数) boolean 指示消息是否按降序排序。默认值为 true。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "content": "This is a remembered statement or fact.",
            "create_date": "Mon, 28 Apr 2025 21:05:24 GMT",
            "create_time": 1745845524611,
            "id": "m1f79142831f11f09cc51795b9eb07c0",
            "memory_id": "e1f79142831f11f09cc51795b9eb07c0",
            "status": "active"
        }
    ]
}

添加消息到记忆体 (Add Message)

POST /api/v1/memories/{memory_id}/messages

向指定的记忆体中手动添加一条消息或事实事实。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/memories/{memory_id}/messages
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "content": string, 必填
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/memories/{memory_id}/messages \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "content": "Bob prefers dark theme for his IDE."
     }'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 目标记忆体 ID。

  • "content": (请求体参数), string, 必填 要存入记忆体的文本事实或陈述内容。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "content": "Bob prefers dark theme for his IDE.",
        "create_date": "Mon, 28 Apr 2025 21:05:24 GMT",
        "create_time": 1745845524611,
        "id": "m1f79142831f11f09cc51795b9eb07c0",
        "memory_id": "e1f79142831f11f09cc51795b9eb07c0",
        "status": "active"
    }
}

遗忘记忆体中的消息 (Forget Message)

DELETE /api/v1/memories/{memory_id}/messages/{message_id}

从指定的记忆体中永久删除（遗忘）某条消息。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/memories/{memory_id}/messages/{message_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/memories/{memory_id}/messages/{message_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 目标记忆体 ID。

  • message_id (路径参数) string, 必填 要遗忘的记忆消息 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

更新记忆体消息状态 (Update message status)

PUT /api/v1/memories/{memory_id}/messages/{message_id}

更改指定记忆消息的状态（例如将其激活或归档禁用）。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/memories/{memory_id}/messages/{message_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "status": string, 必填
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/memories/{memory_id}/messages/{message_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "status": "archived"
     }'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 目标记忆体 ID。

  • message_id (路径参数) string, 必填 目标消息 ID。

  • "status": (请求体参数), string, 必填 新的记忆消息状态。常用选项：

    • "active"：激活。
    • "archived"：已归档。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

检索记忆体消息 (Search Message)

POST /api/v1/memories/{memory_id}/messages/search

在记忆体中对存储的消息进行语义/向量相似度检索过滤。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/memories/{memory_id}/messages/search
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "query": string, 必填
    • "top_k": int
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/memories/{memory_id}/messages/search \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "query": "IDE theme preference",
        "top_k": 3
     }'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 目标记忆体 ID。

  • "query": (请求体参数), string, 必填 检索的文本查询内容。

  • "top_k": (请求体参数), int 要返回的相似度最接近的消息最大数量。默认值为 5。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "content": "Bob prefers dark theme for his IDE.",
            "create_date": "Mon, 28 Apr 2025 21:05:24 GMT",
            "create_time": 1745845524611,
            "id": "m1f79142831f11f09cc51795b9eb07c0",
            "memory_id": "e1f79142831f11f09cc51795b9eb07c0",
            "similarity": 0.812384,
            "status": "active"
        }
    ]
}

获取近期记忆消息 (Get Recent Messages)

GET /api/v1/memories/{memory_id}/messages/recent

获取指定记忆体中最近添加的历史消息记录。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/memories/{memory_id}/messages/recent
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • limit: int
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/memories/{memory_id}/messages/recent?limit=10' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 目标记忆体 ID。

  • limit (查询参数) int 检索的最新的消息条数。默认值为 10。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "content": "Bob prefers dark theme for his IDE.",
            "create_date": "Mon, 28 Apr 2025 21:05:24 GMT",
            "create_time": 1745845524611,
            "id": "m1f79142831f11f09cc51795b9eb07c0",
            "memory_id": "e1f79142831f11f09cc51795b9eb07c0",
            "status": "active"
        }
    ]
}

获取特定记忆消息内容 (Get Message Content)

GET /api/v1/memories/{memory_id}/messages/{message_id}

获取指定记忆体中某条消息的完整文本内容和状态详情。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/memories/{memory_id}/messages/{message_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/memories/{memory_id}/messages/{message_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • memory_id (路径参数) string, 必填 目标记忆体 ID。

  • message_id (路径参数) string, 必填 目标消息 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "content": "Bob prefers dark theme for his IDE.",
        "create_date": "Mon, 28 Apr 2025 21:05:24 GMT",
        "create_time": 1745845524611,
        "id": "m1f79142831f11f09cc51795b9eb07c0",
        "memory_id": "e1f79142831f11f09cc51795b9eb07c0",
        "status": "active"
    }
}

系统接口 (System)

检查系统健康状态 (Check system health)

GET /api/v1/health

检查 RAGFlow 服务及其依赖服务的健康可用状态。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/health
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/health \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

响应 (Response)

成功 (Success)：

{
  "code": 0,
  "data": {
    "status": "healthy"
  }
}

系统文件管理 (FILE MANAGEMENT)

上传系统文件 (Upload file)

POST /api/v1/document/upload

向系统级文件存储上传一个文件。此接口是用于向系统文件空间上传独立文件的通用接口。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/document/upload
  • 请求头 (Headers)：
    • 'Content-Type: multipart/form-data'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body) (Form-data)：
    • file: file, 必填
    • parent_id: string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/document/upload \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form 'file=@/path/to/localfile.pdf' \
     --form 'parent_id=root'
请求参数 (Request parameters)

  • file (请求体参数 - 表单数据) file, 必填 要上传的文件。

  • parent_id (请求体参数 - 表单数据) string 目标父文件夹的 ID。若要上传到根目录，可传入 "root" 或省略。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "id": "f1f79142831f11f09cc51795b9eb07c0",
        "name": "localfile.pdf",
        "parent_id": "root",
        "size": 1048576,
        "type": "file"
    }
}

上传并解析为文档 (Upload document)

POST /api/v1/document/upload_and_parse

上传一个文件并直接开始将其解析为指定数据集中的文档。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/document/upload_and_parse
  • 请求头 (Headers)：
    • 'Content-Type: multipart/form-data'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body) (Form-data)：
    • file: file, 必填
    • dataset_ids: string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/document/upload_and_parse \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form 'file=@/path/to/localfile.pdf' \
     --form 'dataset_ids=3b4de7d4241d11f0a6a79f24fc270c7f'
请求参数 (Request parameters)

  • file (请求体参数 - 表单数据) file, 必填 要上传的源文件。

  • dataset_ids (请求体参数 - 表单数据) string, 必填 要导入到的目标数据集 ID（若是多个，用逗号分隔，如 "id1,id2"）。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "document_id": "3b6cf9c8241d11f0a6a79f24fc270c7f",
        "status": "parsing"
    }
}

下载附件 (Download attachment)

GET /api/v1/document/download/{document_id}

下载系统中的附件或文件。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/document/download/{document_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/document/download/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • document_id (路径参数) string, 必填 目标文件的 ID。

响应 (Response)

成功： 返回要下载的二进制文件内容。

创建系统文件或文件夹 (Create file or folder)

POST /api/v1/document/create

在系统级文件空间中新建一个空白文件或空文件夹。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/document/create
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string, 必填
    • "parent_id": string
    • "type": string, 必填
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/document/create \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "New Folder",
        "parent_id": "root",
        "type": "folder"
     }'
请求参数 (Request parameters)

  • "name": (请求体参数), string, 必填 要创建的文件或文件夹的友好名称。

  • "parent_id": (请求体参数), string 目标父文件夹的 ID。若在根目录下创建，可传入 "root" 或省略。

  • "type": (请求体参数), string, 必填 要创建的项的类型。可用选项：

    • "file"：文件。
    • "folder"：文件夹。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "id": "g1f79142831f11f09cc51795b9eb07c0",
        "name": "New Folder",
        "parent_id": "root",
        "type": "folder"
    }
}

列出系统文件与文件夹 (List files)

GET /api/v1/document/list

获取系统级文件空间中的文件和文件夹列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/document/list
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • parent_id: string
    • keywords: string
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/document/list?page=1&page_size=30&parent_id=root' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • page (查询参数) int 指定显示列表的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大数量。默认值为 30。

  • parent_id (查询参数) string 要获取内容的父文件夹 ID。若为 "root" 或留空，则列出根目录下的内容。

  • keywords (查询参数) string 对文件名进行模糊搜索的过滤关键字。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "id": "g1f79142831f11f09cc51795b9eb07c0",
            "name": "New Folder",
            "parent_id": "root",
            "size": 0,
            "type": "folder"
        },
        {
            "id": "f1f79142831f11f09cc51795b9eb07c0",
            "name": "localfile.pdf",
            "parent_id": "root",
            "size": 1048576,
            "type": "file"
        }
    ]
}

获取父文件夹信息 (Get parent folder)

GET /api/v1/document/parent

获取指定文件或文件夹的直接父级文件夹详情。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/document/parent
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • id: string, 必填
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/document/parent?id=f1f79142831f11f09cc51795b9eb07c0' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • id (查询参数) string, 必填 目标文件或文件夹的 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "id": "root",
        "name": "root",
        "parent_id": null,
        "type": "folder"
    }
}

获取完整父文件夹链路路径 (Get all parent folders)

GET /api/v1/document/parent/all

获取指定项的从根目录到直接父目录的完整祖先文件夹链路路径列表（即面包屑导航树导航路径）。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/document/parent/all
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • id: string, 必填
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/document/parent/all?id=f1f79142831f11f09cc51795b9eb07c0' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • id (查询参数) string, 必填 目标文件或文件夹的 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "id": "root",
            "name": "root",
            "parent_id": null,
            "type": "folder"
        }
    ]
}

删除系统文件 (Delete files)

DELETE /api/v1/document/delete

从系统中批量物理删除指定的文件或文件夹。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/document/delete
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string], 必填
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/document/delete \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "ids": ["f1f79142831f11f09cc51795b9eb07c0", "g1f79142831f11f09cc51795b9eb07c0"]
     }'
请求参数 (Request parameters)
  • "ids": (请求体参数), list[string], 必填 要删除的文件和文件夹 ID 列表。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

下载指定的文件 (Download file)

GET /api/v1/document/get/{file_id}

下载系统中存储的特定实体文件的内容内容。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/document/get/{file_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/document/get/{file_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • file_id (路径参数) string, 必填 目标文件的 ID。

响应 (Response)

成功： 返回文件的原始二进制流数据。

移动或重命名文件 (Move or rename files)

POST /api/v1/document/move

将文件或文件夹移动到另一个父目录，或修改其名称。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/document/move
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "ids": list[string], 必填
    • "parent_id": string
    • "name": string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/document/move \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "ids": ["f1f79142831f11f09cc51795b9eb07c0"],
        "parent_id": "g1f79142831f11f09cc51795b9eb07c0",
        "name": "renamed_file.pdf"
     }'
请求参数 (Request parameters)

  • "ids": (请求体参数), list[string], 必填 要移动或重命名的文件及文件夹的 ID 列表。

  • "parent_id": (请求体参数), string 目标父文件夹 ID。若只修改名称，不进行层级移动，此参数可省略或与当前 parent_id 保持一致。

  • "name": (请求体参数), string 该项的新名称名称（通常仅在 ids 列表只包含一个 ID 时才应提供以实现改名功能）。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

POST /api/v1/document/link

将系统文件关联到指定的数据集并将其转化为可解析的文档。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/document/link
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "dataset_id": string, 必填
    • "document_ids": list[string], 必填
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/document/link \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "dataset_id": "3b4de7d4241d11f0a6a79f24fc270c7f",
        "document_ids": ["f1f79142831f11f09cc51795b9eb07c0"]
     }'
请求参数 (Request parameters)

  • "dataset_id": (请求体参数), string, 必填 关联的目标数据集的 ID。

  • "document_ids": (请求体参数), list[string], 必填 要链接并在数据集中转化为可解析文档的系统文件 ID 列表。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

搜索应用管理 (SEARCH APP MANAGEMENT)

创建搜索应用 (Create search app)

POST /api/v1/search_apps

创建一个以检索匹配信息为导向的搜索应用。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/search_apps
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string, 必填
    • "avatar": string
    • "dataset_ids": list[string]
    • "description": string
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/search_apps \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "Global Search Portal",
        "dataset_ids": ["3b4de7d4241d11f0a6a79f24fc270c7f"],
        "description": "Enterprise wide search portal"
     }'
请求参数 (Request parameters)

  • "name": (请求体参数), string, 必填 搜索应用的唯一友好名称。

    • 最多 128 个字符

  • "avatar": (请求体参数), string 头像图标的 Base64 编码。默认值为 ""。

  • "dataset_ids": (请求体参数), list[string] 用于检索查询的目标关联数据集 ID 列表。默认值为 []。

  • "description": (请求体参数), string 对本搜索应用的简短功能描述。默认值为 ""。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "avatar": "",
        "create_date": "Mon, 28 Apr 2025 22:00:24 GMT",
        "create_time": 1745848824611,
        "created_by": "3af81804241d11f0a6a79f24fc270c7f",
        "dataset_ids": [
            "3b4de7d4241d11f0a6a79f24fc270c7f"
        ],
        "description": "Enterprise wide search portal",
        "id": "s1f79142831f11f09cc51795b9eb07c0",
        "name": "Global Search Portal",
        "status": "1",
        "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
        "update_date": "Mon, 28 Apr 2025 22:00:24 GMT",
        "update_time": 1745848824611
    }
}

获取搜索应用列表 (List search apps)

GET /api/v1/search_apps

获取所有可用的搜索应用列表。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/search_apps
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 查询参数 (Query parameters)：
    • page: int
    • page_size: int
    • orderby: string
    • desc: boolean
请求示例 (Request example)
curl --request GET \
     --url 'http://{address}/api/v1/search_apps?page=1&page_size=30&orderby=update_time&desc=true' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)

  • page (查询参数) int 指定显示列表的页码。默认值为 1。

  • page_size (查询参数) int 每页显示的最大应用条数。默认值为 30。

  • orderby (查询参数) string 排序检索搜索应用的字段属性。可用选项：

    • "create_time"
    • "update_time"（默认）

  • desc (查询参数) boolean 指示搜索应用列表是否以降序排序。默认值为 true。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": [
        {
            "avatar": "",
            "create_date": "Mon, 28 Apr 2025 22:00:24 GMT",
            "create_time": 1745848824611,
            "created_by": "3af81804241d11f0a6a79f24fc270c7f",
            "dataset_ids": [
                "3b4de7d4241d11f0a6a79f24fc270c7f"
            ],
            "description": "Enterprise wide search portal",
            "id": "s1f79142831f11f09cc51795b9eb07c0",
            "name": "Global Search Portal",
            "status": "1",
            "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
            "update_date": "Mon, 28 Apr 2025 22:00:24 GMT",
            "update_time": 1745848824611
        }
    ]
}

获取搜索应用 (Get search app)

GET /api/v1/search_apps/{search_app_id}

获取特定搜索应用的详细配置属性。

请求 (Request)

  • 方法：GET
  • URL：/api/v1/search_apps/{search_app_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request GET \
     --url http://{address}/api/v1/search_apps/{search_app_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • search_app_id (路径参数) string, 必填 目标搜索应用的唯一 ID。

响应 (Response)

成功 (Success)：

{
    "code": 0,
    "data": {
        "avatar": "",
        "create_date": "Mon, 28 Apr 2025 22:00:24 GMT",
        "create_time": 1745848824611,
        "created_by": "3af81804241d11f0a6a79f24fc270c7f",
        "dataset_ids": [
            "3b4de7d4241d11f0a6a79f24fc270c7f"
        ],
        "description": "Enterprise wide search portal",
        "id": "s1f79142831f11f09cc51795b9eb07c0",
        "name": "Global Search Portal",
        "status": "1",
        "tenant_id": "3af81804241d11f0a6a79f24fc270c7f",
        "update_date": "Mon, 28 Apr 2025 22:00:24 GMT",
        "update_time": 1745848824611
    }
}

更新搜索应用 (Update search app)

PUT /api/v1/search_apps/{search_app_id}

修改指定搜索应用的全局配置，如关联的数据集或头像描述。

请求 (Request)

  • 方法：PUT
  • URL：/api/v1/search_apps/{search_app_id}
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "name": string
    • "avatar": string
    • "dataset_ids": list[string]
    • "description": string
请求示例 (Request example)
curl --request PUT \
     --url http://{address}/api/v1/search_apps/{search_app_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "name": "Updated Global Search Portal",
        "dataset_ids": ["3b4de7d4241d11f0a6a79f24fc270c7f"],
        "description": "Updated Enterprise wide search portal"
     }'
请求参数 (Request parameters)

  • search_app_id (路径参数) string, 必填 目标搜索应用 ID。

  • "name": (请求体参数), string 更新后的应用新名称。

  • "avatar": (请求体参数), string 新头像的 Base64 编码。

  • "dataset_ids": (请求体参数), list[string] 更新关联的目标数据集 ID 列表。

  • "description": (请求体参数), string 新的应用功能描述。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

删除搜索应用 (Delete search app)

DELETE /api/v1/search_apps/{search_app_id}

物理删除指定的搜索应用实例。

请求 (Request)

  • 方法：DELETE
  • URL：/api/v1/search_apps/{search_app_id}
  • 请求头 (Headers)：
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例 (Request example)
curl --request DELETE \
     --url http://{address}/api/v1/search_apps/{search_app_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数 (Request parameters)
  • search_app_id (路径参数) string, 必填 要删除的搜索应用 ID。

响应 (Response)

成功 (Success)：

{
  "code": 0
}

进行搜索信息补全与检索 (Search completion)

POST /api/v1/search_apps/{search_app_id}/completion

向指定的搜索应用提交提问问题，自动触发关联的知识库检索，并由大语言模型融合生成最终的检索与回答回答信息。

请求 (Request)

  • 方法：POST
  • URL：/api/v1/search_apps/{search_app_id}/completion
  • 请求头 (Headers)：
    • 'Content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 请求体 (Body)：
    • "question": string, 必填
    • "stream": boolean
    • "inputs": object
请求示例 (Request example)
curl --request POST \
     --url http://{address}/api/v1/search_apps/{search_app_id}/completion \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "question": "What datasets are currently indexed?",
        "stream": false
     }'
请求参数 (Request parameters)

  • search_app_id (路径参数) string, 必填 目标搜索应用的 ID。

  • "question": (请求体参数), string, 必填 要检索提问的文本。

  • "stream": (请求体参数), boolean 是否开启流式输出回答。默认值为 true。

  • "inputs": (请求体参数), object 传递给搜索流程组件中使用的额外参数对象。

响应 (Response)

(参见上面兼容 OpenAI 接口的响应规范)。

本页总览