HTTP API

概述

RAGFlow 提供了一个遵循标准 HTTP 约定的综合性 RESTful API。所有 API 端点都以 /api/v1/ 为前缀，通常需要通过 API 密钥进行身份验证。

来源： docs/references/http_api_reference.md1-9 api/utils/api_utils.py281-297

身份验证

所有 API 请求都需要使用 Authorization 标头中的 bearer token 进行身份验证。

身份验证示例

来源： api/utils/api_utils.py281-297

错误代码

API 返回标准的 HTTP 状态代码以及特定于应用程序的错误代码，以实现更详细的错误处理。

代码	消息	描述
400	错误请求	无效的请求参数
401	未授权	未经授权的访问
403	禁止	访问被拒绝
404	未找到	资源未找到
500	内部服务器错误	服务器内部错误
1001	无效的块 ID	无效的块 ID
1002	块更新失败	块更新失败

来源： docs/references/http_api_reference.md12-25

OpenAI 兼容 API

RAGFlow 提供与 OpenAI 兼容的端点，它们遵循与 OpenAI API 相同的请求和响应格式，允许您以最少的更改使用现有的 OpenAI 客户端库。

聊天补全

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

此端点为给定的聊天会话创建模型响应。

请求参数

model (Body 参数) string, 必填
用于生成响应的模型。
messages (Body 参数) list[object], 必填
用于生成响应的历史聊天消息列表。
stream (Body 参数) boolean
是否将响应作为流接收。

示例请求

代理补全

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

此端点为使用预定义流程的给定代理创建模型响应。

请求参数

与聊天补全端点类似。

来源： docs/references/http_api_reference.md28-318 api/apps/sdk/session.py178-396

数据集管理 API

数据集是 RAGFlow 中文档的顶级容器。

创建数据集

POST /api/v1/datasets

使用指定的属性创建新数据集。

请求参数

name (Body 参数) string, 必填
要创建的数据集的唯一名称。
avatar (Body 参数) string
头像的 Base64 编码。
description (Body 参数) string
数据集的简要描述。
embedding_model (Body 参数) string
要使用的嵌入模型的名称。
permission (Body 参数) string
指定谁可以访问数据集（“me”或“team”）。
chunk_method (Body 参数) enum<string>
数据集的分块方法。
parser_config (Body 参数) object
数据集解析器的配置设置。

示例

删除数据集

DELETE /api/v1/datasets

按 ID 删除一个或多个数据集。

请求参数

ids (Body 参数) list[string]
要删除的数据集 ID。如果未指定，将删除所有数据集。

更新数据集

PUT /api/v1/datasets/{dataset_id}

更新指定数据集的配置。

路径参数

dataset_id (Path 参数) string, 必填
要更新的数据集的 ID。

请求参数

name (Body 参数) string
数据集的新名称。
embedding_model (Body 参数) string
更新的嵌入模型名称。
chunk_method (Body 参数) enum<string>
更新的分块方法。

列出数据集

GET /api/v1/datasets

列出具有可选筛选和分页的数据集。

查询参数

page (Query 参数) integer, 默认: 1
分页的页码。
page_size (Query 参数) integer, 默认: 30
每页的项目数。
orderby (Query 参数) string, 默认: "create_time"
用于排序的字段。
desc (Query 参数) boolean, 默认: true
是否按降序排序。
name (Query 参数) string
按数据集名称筛选。
id (Query 参数) string
按数据集 ID 筛选。

来源： docs/references/http_api_reference.md320-596 api/apps/sdk/dataset.py37-188 api/apps/sdk/dataset.py190-277 api/apps/sdk/dataset.py280-451 api/apps/sdk/dataset.py453-520

文档管理 API

文档包含在数据集中，代表可以被解析成块的单个文件。

上传文档

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

将文档上传到指定数据集。

路径参数

dataset_id (Path 参数) string, 必填
将上传文档的associated 数据集的 ID。

请求参数

file (Form 参数) file, 必填
要上传的文档文件。

示例

更新文档

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

更新指定文档的配置。

路径参数

dataset_id (Path 参数) string, 必填
associated 数据集的 ID。
document_id (Path 参数) string, 必填
要更新的文档的 ID。

请求参数

name (Body 参数) string
文档的新名称。
meta_fields (Body 参数) object
文档的元数据字段。
chunk_method (Body 参数) string
应用于文档的解析方法。
parser_config (Body 参数) object
文档解析器的配置设置。

下载文档

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

从指定的数据集中下载文档。

路径参数

dataset_id (Path 参数) string, 必填
associated 数据集的 ID。
document_id (Path 参数) string, 必填
要下载的文档的 ID。

列出文档

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

列出指定数据集中的文档，并提供可选的筛选和分页。

路径参数

dataset_id (Path 参数) string, 必填
数据集的 ID。

查询参数

page (Query 参数) integer, 默认: 1
分页的页码。
page_size (Query 参数) integer, 默认: 30
每页的项目数。
orderby (Query 参数) string, 默认: "create_time"
用于排序的字段。
desc (Query 参数) boolean, 默认: true
是否按降序排序。
keywords (Query 参数) string
按文档关键词筛选。
id (Query 参数) string
按文档 ID 筛选。
name (Query 参数) string
按文档名称筛选。

删除文档

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

从指定数据集中删除一个或多个文档。

路径参数

dataset_id (Path 参数) string, 必填
associated 数据集的 ID。

请求参数

ids (Body 参数) list[string]
要删除的文档的 ID。如果未指定，将删除数据集中的所有文档。

来源： docs/references/http_api_reference.md698-1069 api/apps/sdk/doc.py71-180 api/apps/sdk/doc.py183-335 api/apps/sdk/doc.py338-403 api/apps/sdk/doc.py406-539 api/apps/sdk/doc.py542-647

块管理 API

块是 RAGFlow 中内容的最基本单元，通过解析文档创建。

解析文档

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

开始将文档解析成块。

路径参数

dataset_id (Path 参数) string, 必填
数据集的 ID。

请求参数

document_ids (Body 参数) list[string], 必填
要解析的文档的 ID。

示例

停止解析

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

停止指定文档的解析过程。

路径参数

dataset_id (Path 参数) string, 必填
数据集的 ID。

请求参数

document_ids (Body 参数) list[string], 必填
要停止解析的文档的 ID。

列出块

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

列出指定文档的块。

路径参数

dataset_id (Path 参数) string, 必填
数据集的 ID。
document_id (Path 参数) string, 必填
文档的 ID。

查询参数

page (Query 参数) integer, 默认: 1
分页的页码。
page_size (Query 参数) integer, 默认: 30
每页的项目数。
id (Query 参数) string
按块 ID 筛选。

添加块

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

将自定义块添加到文档。

路径参数

dataset_id (Path 参数) string, 必填
数据集的 ID。
document_id (Path 参数) string, 必填
文档的 ID。

请求参数

content (请求体参数) string, 必需
块的内容。
important_keywords (请求体参数) list[string]
块的重要关键词。

来源： docs/references/http_api_reference.md1076-1119 api/apps/sdk/doc.py651-730 api/apps/sdk/doc.py733-800 api/apps/sdk/doc.py803-969 api/apps/sdk/doc.py972-1081

聊天API

聊天API支持聊天会话的程序化管理和获取聊天完成。

创建聊天

POST /api/v1/chats

创建新的聊天配置。

创建聊天会话

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

为特定聊天创建新的聊天会话。

路径参数

chat_id (路径参数) string, 必需
聊天的ID。

请求参数

name (Body 参数) string
会话的名称。
user_id (请求体参数) string
与此会话关联的用户的ID。

获取聊天完成

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

为聊天对话获取响应。

路径参数

chat_id (路径参数) string, 必需
聊天的ID。

请求参数

session_id (请求体参数) string
聊天会话的ID。
question (请求体参数) string, 必需
要提出的问题。
stream (请求体参数) boolean, 默认值：true
是否流式传输响应。

列出聊天会话

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

列出特定聊天的会话。

路径参数

chat_id (路径参数) string, 必需
聊天的ID。

查询参数

page (Query 参数) integer, 默认: 1
分页的页码。
page_size (Query 参数) integer, 默认: 30
每页的项目数。
orderby (Query 参数) string, 默认: "create_time"
用于排序的字段。
desc (Query 参数) boolean, 默认: true
是否按降序排序。
id (Query 参数) string
按会话 ID 过滤。
user_id (查询参数) string
按用户 ID 过滤。

来源： api/apps/sdk/chat.py30-156 api/apps/sdk/session.py39-64 api/apps/sdk/session.py149-175 api/apps/sdk/session.py439-489

代理API

代理API支持代理会话的程序化管理和获取代理完成。

创建代理会话

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

为特定代理创建新的代理会话。

路径参数

agent_id (路径参数) string, 必需
代理的ID。

请求参数

取决于代理的配置，可能包括

代理定义的表单字段
用于处理的文件上传

获取代理完成

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

从代理获取响应。

路径参数

agent_id (路径参数) string, 必需
代理的ID。

请求参数

session_id (请求体参数) string
代理会话的ID。
question (请求体参数) string, 必需
要提出的问题。
stream (请求体参数) boolean, 默认值：true
是否流式传输响应。
sync_dsl (请求体参数) boolean, 默认值：false
是否从代理同步DSL到会话。

列出代理会话

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

列出特定代理的会话。

路径参数

agent_id (路径参数) string, 必需
代理的ID。

查询参数

page (Query 参数) integer, 默认: 1
分页的页码。
page_size (Query 参数) integer, 默认: 30
每页的项目数。
orderby (查询参数) string, 默认值："update_time"
用于排序的字段。
desc (Query 参数) boolean, 默认: true
是否按降序排序。
id (Query 参数) string
按会话 ID 过滤。
user_id (查询参数) string
按用户 ID 过滤。
dsl (查询参数) boolean, 默认值：true
是否在响应中包含DSL。

来源： api/apps/sdk/session.py67-124 api/apps/sdk/session.py398-436 api/apps/sdk/session.py492-542

API响应格式

大多数API端点以一致的JSON格式返回响应

对于流式响应（当stream=true时），服务器会发送一系列SSE（Server-Sent Events）消息，每条消息都带有data:前缀，其中包含一个JSON对象，带有增量内容。

来源： api/utils/api_utils.py300-308 api/utils/api_utils.py311-322

HTTP Headers and Parameters

所有HTTP请求都应包含以下标头

Authorization: Bearer <YOUR_API_KEY>

对于具有JSON主体的POST和PUT请求，请包含

Content-Type: application/json

对于文件上传，使用

Content-Type: multipart/form-data

来源： api/utils/api_utils.py281-297

API速率限制

RAGFlow API实施速率限制以防止滥用。如果在短时间内向应用程序发出过多请求，您可能会收到429 Too Many Requests响应。当这种情况发生时，请实施指数退避（带抖动）来重试请求。

来源： api/utils/api_utils.py88-97

HTTP API

概述

身份验证

身份验证示例

错误代码

OpenAI 兼容 API

聊天补全

请求参数

示例请求

代理补全

请求参数

数据集管理 API

创建数据集

请求参数

示例

删除数据集

请求参数

更新数据集

路径参数

请求参数

列出数据集

查询参数

文档管理 API

上传文档

路径参数

请求参数

示例

更新文档

路径参数

请求参数

下载文档

路径参数

列出文档

路径参数

查询参数

删除文档

路径参数

请求参数

块管理 API

解析文档

路径参数

请求参数

示例

停止解析

路径参数

请求参数

列出块

路径参数

查询参数

添加块

路径参数

请求参数

聊天API

创建聊天

创建聊天会话

路径参数

请求参数

获取聊天完成

路径参数

请求参数

列出聊天会话

路径参数

查询参数

代理API

创建代理会话

路径参数

请求参数

获取代理完成

路径参数

请求参数

列出代理会话

路径参数

查询参数

API响应格式

HTTP Headers and Parameters

API速率限制

本页内容