RAGFlow API 文档

原创

已于 2025-03-19 12:45:59 修改 · 3.2k 阅读

30 ·

CC 4.0 BY-SA版权

文章标签：

#python

于 2025-03-19 12:45:17 首次发布

RAGFlow API 文档

API 服务器

http://1.1.1.0:80

HTTP API

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

OpenAI 兼容 API

创建聊天补全

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

为给定的聊天对话创建模型响应。此 API 跟 OpenAI 的 API 采用相同的请求和响应格式，允许您以与使用 OpenAI API 类似的方式与模型进行交互。

请求

方法：POST
URL：/api/v1/chats_openai/{chat_id}/chat/completions

请求头：

'content-Type: application/json'
'Authorization: Bearer <YOUR_API_KEY>'

请求体：

{
  "model": "string",
  "messages": [
    {
      "role": "user",
      "content": "string"
    }
  ],
  "stream": true
}

请求示例

curl --request POST \
     --url http://{address}/api/v1/chats_openai/{chat_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
      }'

请求参数

model (请求体参数)：string，必需。用于生成响应的模型。服务器会自动解析此参数，因此目前您可以将其设置为任意值。
messages (请求体参数)：list[object]，必需。用于生成响应的历史聊天消息列表。此列表中必须至少包含一个用户角色的消息。
stream (请求体参数)：boolean。是否以流的形式接收响应。如果您希望一次性接收完整响应而不是流式响应，请明确将其设置为 false。

响应

流式响应示例：

{
    "id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
    "choices": [
        {
            "delta": {
                "content": "This is a test. If you have any specific questions or need information, feel",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            },
            "finish_reason": null,
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1740543996,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": null
}

// 省略重复信息

{"choices":[{"delta":{"content":" free to ask, and I will do my best to provide an answer based on","role":"assistant"}}]}
{"choices":[{"delta":{"content":" the knowledge I have. If your question is unrelated to the provided knowledge base,","role":"assistant"}}]}
{"choices":[{"delta":{"content":" I will let you know.","role":"assistant"}}]}

// 最后一个块

{
    "id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
    "choices": [
        {
            "delta": {
                "content": null,
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "created": 1740543996,
    "model": "model",
    "object": "chat.completion.chunk",
    "system_fingerprint": "",
    "usage": {
        "prompt_tokens": 18,
        "completion_tokens": 225,
        "total_tokens": 243
    }
}

非流式响应示例：

{
    "choices":[
        {
            "finish_reason":"stop",
            "index":0,
            "logprobs":null,
            "message":{
                "content":"This is a test. If you have any specific questions or need information, feel free to ask, and I will do my best to provide an answer based on the knowledge I have. If your question is unrelated to the provided knowledge base, I will let you know.",
                "role":"assistant"
            }
        }
    ],
    "created":1740543499,
    "id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
    "model":"model",
    "object":"chat.completion",
    "usage":{
        "completion_tokens":246,
        "completion_tokens_details":{
            "accepted_prediction_tokens":246,
            "reasoning_tokens":18,
            "rejected_prediction_tokens":0
        },
        "prompt_tokens":18,
        "total_tokens":264
    }
}

失败响应示例：

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

数据集管理

创建数据集

POST /api/v1/datasets

请求

方法：POST
URL：/api/v1/datasets

请求头：

'content-Type: application/json'
'Authorization: Bearer <YOUR_API_KEY>'

请求体：

{
  "name": "string",
  "avatar": "string",
  "description": "string",
  "language": "string",
  "embedding_model": "string",
  "permission": "string",
  "chunk_method": "string",
  "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_1"
      }'

请求参数

name (请求体参数)：string，必需。要创建的数据集的唯一名称。它必须符合以下要求：
- 允许的字符包括：
  - 英文字母（a-z，A-Z）
  - 数字（0-9）
  - "_"（下划线）
- 必须以英文字母或下划线开头。
- 最多 65,535 个字符。
- 不区分大小写。
avatar (请求体参数)：string。头像的 base64 编码。
description (请求体参数)：string。要创建的数据集的简要描述。
language (请求体参数)：string。要创建的数据集的语言设置。可选值：
- "English"（默认）
- "Chinese"
embedding_model (请求体参数)：string。要使用的嵌入模型的名称。例如："BAAI/bge-zh-v1.5"
permission (请求体参数)：string。指定谁可以访问要创建的数据集。可选值：
- "me"：（默认）只有您可以管理数据集。
- "team"：所有团队成员都可以管理数据集。
chunk_method (请求体参数)：enum。要创建的数据集的分块方法。可选值：
- "naive"：通用（默认）
- "manual"：手动
- "qa"：问答
- "table"：表格
- "paper"：论文
- "book"：书籍
- "laws"：法律
- "presentation"：演示文稿
- "picture"：图片
- "one"：单个
- "knowledge_graph"：知识图谱
  - 在选择此选项之前，请确保您的 LLM 已在设置页面上正确配置。请注意，知识图谱会消耗大量 Tokens！
- "email"：电子邮件
parser_config (请求体参数)：object。数据集解析器的配置设置。此 JSON 对象中的属性会根据所选的 chunk_method 而变化：
- 如果 chunk_method 是 "naive"，则 parser_config 对象包含以下属性：
  - "chunk_token_count"：默认为 128。
  - "layout_recognize"：默认为 true。
  - "html4excel"：是否将 Excel 文档转换为 HTML 格式。默认为 false。
  - "delimiter"：默认为 "\n!?。；！？"。
  - "task_page_size"：默认为 12。仅适用于 PDF。
  - "raptor"：Raptor 特定设置。默认为：{"use_raptor": false}。
- 如果 chunk_method 是 "qa"、"manuel"、"paper"、"book"、"laws" 或 "presentation"，则 parser_config 对象包含以下属性：
  - "raptor"：Raptor 特定设置。默认为：{"use_raptor": false}。
- 如果 chunk_method 是 "table"、"picture"、"one" 或 "email"，则 parser_config 是一个空的 JSON 对象。
- 如果 chunk_method 是 "knowledge_graph"，则 parser_config 对象包含以下属性：
  - "chunk_token_count"：默认为 128。
  - "delimiter"：默认为 "\n!?。；！？"。
  - "entity_types"：默认为 ["organization","person","location","event","time"]。

响应

成功响应示例：

{
    "code": 0,
    "data": {
        "avatar": null,
        "chunk_count": 0,
        "chunk_method": "naive",
        "create_date": "Thu, 24 Oct 2024 09:14:07 GMT",
        "create_time": 1729761247434,
        "created_by": "69736c5e723611efb51b0242ac120007",
        "description": null,
        "document_count": 0,
        "embedding_model": "BAAI/bge-large-zh-v1.5",
        "id": "527fa74891e811ef9c650242ac120006",
        "language": "English",
        "name": "test_1",
        "parser_config": {
            "chunk_token_num": 128,
            "delimiter": "\\n!?;。；！？",
            "html4excel": false,
            "layout_recognize": true,
            "raptor": {
                "user_raptor": false
            }
        },
        "permission": "me",
        "similarity_threshold": 0.2,
        "status": "1",
        "tenant_id": "69736c5e723611efb51b0242ac120007",
        "token_num": 0,
        "update_date": "Thu, 24 Oct 2024 09:14:07 GMT",
        "update_time": 1729761247434,
        "vector_similarity_weight": 0.3
    }
}

失败响应示例：

{
    "code": 102,
    "message": "Duplicated knowledgebase name in creating dataset."
}

删除数据集

DELETE /api/v1/datasets

请求

方法：DELETE
URL：/api/v1/datasets

请求头：

'content-Type: application/json'
'Authorization: Bearer <YOUR_API_KEY>'

请求体：
```
{
  "ids": ["string"]
}
```

请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["test_1", "test_2"]
     }'

请求参数

ids (请求体参数)：list[string]。要删除的数据集的 ID 列表。如果未指定，则删除所有数据集。

响应

成功响应示例：
```
{
    "code": 0 
}
```

失败响应示例：

{
    "code": 102,
    "message": "You don't own the dataset."
}

更新数据集

PUT /api/v1/datasets/{dataset_id}

请求

方法：PUT
URL：/api/v1/datasets/{dataset_id}

请求头：

'content-Type: application/json'
'Authorization: Bearer <YOUR_API_KEY>'

请求体：

{
  "name": "string",
  "embedding_model": "string",
  "chunk_method": "string"
}

请求示例

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"
     }'

请求参数

dataset_id (路径参数)：要更新的数据集的 ID。
name (请求体参数)：string。数据集的新名称。
embedding_model (请求体参数)：string。更新后的嵌入模型名称。在更新 embedding_model 之前，请确保 chunk_count 为 0。
chunk_method (请求体参数)：enum。数据集的分块方法。可选值：
- "naive"：通用
- "manual"：手动
- "qa"：问答
- "table"：表格
- "paper"：论文
- "book"：书籍
- "laws"：法律
- "presentation"：演示文稿
- "picture"：图片
- "one"：单个
- "knowledge_graph"：知识图谱
  - 在选择此选项之前，请确保您的 LLM 已在设置页面上正确配置。请注意，知识图谱会消耗大量 Tokens！
- "email"：电子邮件

响应

成功响应示例：
```
{
    "code": 0 
}
```

失败响应示例：

{
    "code": 102,
    "message": "Can't change tenant_id."
}

列出数据集

GET /api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}

请求

方法：GET
URL：/api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}

请求头：

'Authorization: Bearer <YOUR_API_KEY>'

请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

请求参数

page (筛选参数)：指定将显示数据集的页面。默认为 1。
page_size (筛选参数)：每页的数据集数量。默认为 30。
orderby (筛选参数)：数据集应按其排序的字段。可选值：
- create_time（默认）
- update_time
desc (筛选参数)：是否按降序检索数据集。默认为 true。
name (筛选参数)：要检索的数据集的名称。
id (筛选参数)：要检索的数据集的 ID。

响应

成功响应示例：

{
    "code": 0,
    "data": [
        {
            "avatar": "",
            "chunk_count": 59,
            "create_date": "Sat, 14 Sep 2024 01:12:37 GMT",
            "create_time": 1726276357324,
            "created_by": "69736c5e723611efb51b0242ac120007",
            "description": null,
            "document_count": 1,
            "embedding_model": "BAAI/bge-large-zh-v1.5",
            "id": "6e211ee0723611efa10a0242ac120007",
            "language": "English",
            "name": "mysql",
            "chunk_method": "knowledge_graph",
            "parser_config": {
                "chunk_token_num": 8192,
                "delimiter": "\\n!?;。；！？",
                "entity_types": [
                    "organization",
                    "person",
                    "location",
                    "event",
                    "time"
                ]
            },
            "permission": "me",
            "similarity_threshold": 0.2,
            "status": "1",
            "tenant_id": "69736c5e723611efb51b0242ac120007",
            "token_num": 12744,
            "update_date": "Thu, 10 Oct 2024 04:07:23 GMT",
            "update_time": 1728533243536,
            "vector_similarity_weight": 0.3
        }
    ]
}

失败响应示例：

{
    "code": 102,
    "message": "The dataset doesn't exist"
}

数据集内的文件管理

上传文档

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

请求

方法：POST
URL：/api/v1/datasets/{dataset_id}/documents

请求头：

'Content-Type: multipart/form-data'
'Authorization: Bearer <YOUR_API_KEY>'

表单数据：
```
'file=@{FILE_PATH}'
```

请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Content-Type: multipart/form-data' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --form 'file=@./test1.txt' \
     --form 'file=@./test2.pdf'

请求参数

dataset_id (路径参数)：要上传文档的数据集的 ID。
file (请求体参数)：要上传的文档。

响应

成功响应示例：

{
    "code": 0,
    "data": [
        {
            "chunk_method": "naive",
            "created_by": "69736c5e723611efb51b0242ac120007",
            "dataset_id": "527fa74891e811ef9c650242ac120006",
            "id": "b330ec2e91ec11efbc510242ac120004",
            "location": "1.txt",
            "name": "1.txt",
            "parser_config": {
                "chunk_token_num": 128,
                "delimiter": "\\n!?;。；！？",
                "html4excel": false,
                "layout_recognize": true,
                "raptor": {
                    "user_raptor": false
                }
            },
            "run": "UNSTART",
            "size": 17966,
            "thumbnail": "",
            "type": "doc"
        }
    ]
}

失败响应示例：

{
    "code": 101,
    "message": "No file part!"
}

更新文档

PUT /api/v1/datasets/{dataset_id}

最低0.47元/天解锁文章

RAGFlow API 文档

RAGFlow API 文档

目录

API 服务器

HTTP API

OpenAI 兼容 API

创建聊天补全

数据集管理

创建数据集

删除数据集

更新数据集

列出数据集

数据集内的文件管理

上传文档

更新文档