HTTP API

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

---

错误代码

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

---

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"：object list
  • "stream"：boolean

请求示例

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 (Body parameter) string，必填
  用于生成回复的模型。服务器会自动解析此字段，因此您可以暂时将其设置为任何值。

• messages (Body parameter) list[object]，必填
  用于生成回复的历史聊天消息列表。此参数必须包含至少一条具有user角色的消息。

• stream (Body parameter) boolean
  是否以流式接收响应。如果您希望一次性接收完整响应而不是分块传输，请显式设置为false。

创建代理完成

响应

流式：

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]

非流式：

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

失败：

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

---

创建代理完成

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

为给定的聊天对话生成模型响应。

此API遵循与OpenAI API相同请求和响应格式。您可以像使用OpenAI的API一样与模型交互。

请求

• 方法：POST
• URL：/api/v1/agents_openai/{agent_id}/chat/completions
• 头部：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文：
  • "model"：string，必需
  • "messages"：object 列表，必需
  • "stream"：boolean

请求示例

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

请求参数

• model (Body parameter) string，必需
  用于生成响应的模型。服务器会自动解析此值，因此您可以将其设置为任何值。

• "messages" (Body parameter) object 列表，必需
  包含消息内容和角色的对象列表。

• "stream" (Body parameter) boolean，可选
  是否启用流式响应。默认为 false。

响应

流式输出：

data: {
    "id": "5fa65c94-e316-4954-800a-06dfd5827052",
    "object": "chat.completion.chunk",
    "model": "99ee29d6783511f09c921a6272e682d8",
    "choices": [
        {
            "delta": {
                "content": "Hello"
            },
            "finish_reason": null,
            "index": 0
        }
    ]
}

data: {"id": "518022d9-545b-4100-89ed-ecd9e46fa753", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": "!"}, "finish_reason": null, "index": 0}]}

data: {"id": "f37c4af0-8187-4c86-8186-048c3c6ffe4e", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " How"}, "finish_reason": null, "index": 0}]}

data: {"id": "3ebc0fcb-0f85-4024-b4a5-3b03234a16df", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " can"}, "finish_reason": null, "index": 0}]}

data: {"id": "efa1f3cf-7bc4-47a4-8e53-cd696f290587", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " I"}, "finish_reason": null, "index": 0}]}

data: {"id": "2eb6f741-50a3-4d3d-8418-88be27895611", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " assist"}, "finish_reason": null, "index": 0}]}

data: {"id": "f1227e4f-bf8b-462c-8632-8f5269492ce9", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " you"}, "finish_reason": null, "index": 0}]}

data: {"id": "35b669d0-b2be-4c0c-88d8-17ff98592b21", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": " today"}, "finish_reason": null, "index": 0}]}

data: {"id": "f00d8a39-af60-4f32-924f-d64106a7fdf1", "object": "chat.completion.chunk", "model": "99ee29d6783511f09c921a6272e682d8", "choices": [{"delta": {"content": "?"}, "finish_reason": null, "index": 0}]}

data: [DONE]

非流式输出：

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "Hello! How can I assist you today?",
                "role": "assistant"
            }
        }
    ],
    "created": null,
    "id": "17aa4ec5-6d36-40c6-9a96-1b069c216d59",
    "model": "99ee29d6783511f09c921a6272e682d8",
    "object": "chat.completion",
    "param": null,
    "usage": {
        "completion_tokens": 9,
        "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
        },
        "prompt_tokens": 1,
        "total_tokens": 10
    }
}

失败情况：

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

数据集管理

创建数据集接口

请求示例

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": (Body parameter), string, 必填
  数据集的唯一名称。必须符合以下要求：

  • 只能包含基本多语言平面 (BMP) 字符
  • 最大长度为128个字符
  • 不区分大小写

• "avatar": (Body parameter), string
  头像的Base64编码。

  • 最大长度为65535个字符

• "description": (Body parameter), string
  数据集的简要描述。

  • 最大长度为65535个字符

• "embedding_model": (Body parameter), string
  要使用的嵌入模型名称。例如： "BAAI/bge-large-zh-v1.5@BAAI"

  • 最大长度为255个字符
  • 必须遵循 model_name@model_factory 格式

• "permission": (Body parameter), string
  指定谁可以创建和管理该数据集。可用选项：

  • "me": (默认) 只有你自己可以管理这个数据集。
  • "team": 团队所有成员都可以管理这个数据集。

• "chunk_method": (Body parameter), 枚举<string>
  数据集的分块方法。可用选项：

  • "naive": 通用 (默认)
  • "book": 图书
  • "email": 邮件
  • "laws": 法律文件
  • "manual": 手动
  • "one": 单个文档
  • "paper": 论文
  • "picture": 图片
  • "presentation": 演示文稿
  • "qa": 问答对
  • "table": 表格
  • "tag": 标签

• "parser_config": (Body parameter), 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> 参考 使用标签集
      • 必须包含一个数据集ID列表，每个数据集都是使用 标签分块方法进行解析的
    • "task_page_size": int 仅适用于PDF。
      • 默认为 12
      • 最小值：1
    • "raptor": object RAPTOR特定设置。
      • 默认为：{"use_raptor": false}
    • "graphrag": object GRAPHRAG特定设置。
      • 默认为：{"use_graphrag": false}
  • 如果 "chunk_method" 是 "qa", "manuel", "paper", "book", "laws", 或 "presentation", 则 "parser_config" 对象包含以下属性：
    • "raptor": object RAPTOR特定设置。
      • 默认为：{"use_raptor": false}.
  • 如果 "chunk_method" 是 "table", "picture", "one", 或 "email", 则 "parser_config" 是一个空的JSON对象。

响应

成功：

{
    "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 示例",
        "pagerank": 0,
        "parser_config": {
            "chunk_token_num": 128, 
            "delimiter": "\\n!?;。；！？", 
            "html4excel": false, 
            "layout_recognize": "DeepDOC", 
            "raptor": {
                "use_raptor": false
            }
        },
        "status": "active"
    }
}

失败：

{
    "code": 500,
    "message": "内部服务器错误",
    "data": {}
}

删除数据集的请求示例

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

删除数据集

请求参数

• "ids": (Body parameter), list[string] 或 null, 必填
  指定要删除的数据集：
  • 如果为 null，将删除所有数据集
  • 如果是 ID 数组，仅删除指定数据集
  • 如果是空数组，则不删除任何数据集

响应

成功：

{
    "code": 0 
}

失败：

{
    "code": 102,
    "message": "您没有该数据集的所有权。"
}

---

更新数据集

PUT /api/v1/datasets/{dataset_id}

更新指定数据集的配置。

请求

• 方法: 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

请求示例

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: (Path parameter)
  要更新的数据集 ID。
• "name": (Body parameter), string
  数据集的新名称。
  • 只支持基本多语言平面 (BMP) 字符
  • 最大长度 128 个字符
  • 不区分大小写
• "avatar": (Body parameter), string
  数据集头像的更新 Base64 编码。
  • 最大长度 65535 个字符
• "embedding_model": (Body parameter), string
  数据集嵌入模型名称。
  • 更新前请确保 "chunk_count" 为 0
  • 最大长度 255 个字符
  • 必须遵循 model_name@model_factory 格式
• "permission": (Body parameter), string
  数据集权限更新。可用选项：
  • "me": (默认) 只有您自己可以管理该数据集。
  • "team": 团队所有成员都可以管理该数据集。
• "pagerank": (Body parameter), int
  参考 设置页面排名
  • 默认值：0
  • 最小值：0
  • 最大值：100
• "chunk_method": (Body parameter), 枚举<string>
  数据集的切分方法。可用选项：
  • "naive": 通用 (默认)
  • "book": 图书
  • "email": 邮件
  • "laws": 法律文件
  • "manual": 手动
  • "one": 单页
  • "paper": 论文
  • "picture": 图片
  • "presentation": 演示文稿
  • "qa": Q&A
  • "table": 表格
  • "tag": 标签
• "parser_config": (Body parameter), 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": bool 表示是否启用布局识别功能。
      • 默认值：true
    • "ocr_lang": string OCR 语言设置。
      • 默认值："eng"
  • 如果 "chunk_method" 是其他方法，则 "parser_config" 对象可能包含不同的属性，请参考具体文档。

响应

成功：

{
    "code": 0,
    "message": "数据集更新成功"
}

失败：

{
    "code": 102,
    "message": "无法更改租户 ID。"
}

---

列出数据集

GET /api/v1/datasets

请求示例

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": "naive",
            "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"
}

---

获取数据集的知识图谱

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

检索指定数据集的知识图谱。

请求

• 方法: GET
• URL: /api/v1/datasets/{dataset_id}/knowledge_graph
• 头部:
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

请求参数

• dataset_id: (路径参数)
  目标数据集的ID。

响应

成功：

{
    "code": 0,
    "data": {
        "graph": {
            "directed": false,
            "edges": [
                {
                    "description": "通知是一种传达风险警告和操作警报的文档。<SEP>通知是风险预警框架下发布的具体通知实例。",
                    "keywords": ["9", "8"],
                    "source": "notice",
                    "source_id": ["8a46cdfe4b5c11f0a5281a58e595aa1c"],
                    "src_id": "xxx",
                    "target": "xxx",
                    "tgt_id": "xxx",
                    "weight": 17.0
                }
            ],
            "graph": {
                "source_id": ["8a46cdfe4b5c11f0a5281a58e595aa1c", "8a7eb6424b5c11f0a5281a58e595aa1c"]
            },
            "multigraph": false,
            "nodes": [
                {
                    "description": "xxx",
                    "entity_name": "xxx",
                    "entity_type": "ORGANIZATION",
                    "id": "xxx",
                    "pagerank": 0.10804906590624092,
                    "rank": 3,
                    "source_id": ["8a7eb6424b5c11f0a5281a58e595aa1c"]
                }
            ]
        },
        "mind_map": {}
    }
}

失败：

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

---

删除数据集的知识图谱

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

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

请求

• 方法: DELETE
• URL: /api/v1/datasets/{dataset_id}/knowledge_graph
• 头部:
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

请求参数

• dataset_id: (路径参数)
  目标数据集的ID。

响应

成功：

{
    "code": 0,
    "data": true
}

失败：

{
    "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": {
                    "use_raptor": false
                }
            },
            "run": "UNSTART",
            "size": 17966,
            "thumbnail": "",
            "type": "doc"
        }
    ]
}

失败:

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

---

更新文档

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

更新指定文档的配置。

请求

• 方法: PUT
• URL: /api/v1/datasets/{dataset_id}/documents/{document_id}
• 头部:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 主体:
  • "name":string
  • "meta_fields":object
  • "chunk_method":string
  • "parser_config":object

请求示例

curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
     {
          "name": "manual.txt", 
          "chunk_method": "manual", 
          "parser_config": {"chunk_token_num": 128}
     }'

请求参数

• dataset_id: (路径参数)
  关联的数据集 ID。
• document_id: (路径参数)
  要更新的文档 ID。
• "name": (主体参数), string
• "meta_fields": (主体参数), dict[str, Any] 文档的元字段。
• "chunk_method": (主体参数), string
  应用于文档的解析方法:
  • "naive": 通用
  • `"manual": 手动
  • `"qa": Q&A
  • `"table": 表格
  • `"paper": 论文
  • `"book": 书籍
  • `"laws": 法律
  • `"presentation": 演示文稿
  • `"picture": 图片
  • `"one": 单页
  • `"email": 邮件
• "parser_config": (主体参数), object
  数据集解析器的配置设置。此 JSON 对象中的属性因选择的 "chunk_method" 而异:
  • 如果 "chunk_method" 是 "naive", 则 "parser_config" 对象包含以下属性:
    • "chunk_token_num": 默认为 256。
    • "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 对象。

响应

成功:

{
    "code": 0
}

失败:

{
    "code": 102,
    "message": "The dataset does not have the document."
}

---

下载文档

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

从指定数据集下载文档。

请求

• 方法: GET
• URL: /api/v1/datasets/{dataset_id}/documents/{document_id}
• 头部:
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 输出:
  • '{PATH_TO_THE_FILE}'

请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --output '{path_to_file}'

注：实际使用时请将 {path_to_file} 替换为具体的文件保存路径

请求参数

• dataset_id: (路径参数)
  关联的数据集 ID。
• documents_id: (路径参数)
  要下载的文档 ID。

响应

成功:

This is a test to verify the file download feature.

失败:

{
    "code": 102,
    "message": "You do not own the dataset 7898da028a0511efbf750242ac1220005."
}

---

列出文档

GET /api/v1/datasets/{dataset_id}/documents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&keywords={keywords}&id={document_id}&name={document_name}&create_time_from={timestamp}&create_time_to={timestamp}

列出指定数据集中文档。

请求

• 方法: GET
• URL: /api/v1/datasets/{dataset_id}/documents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&keywords={keywords}&id={document_id}&name={document_name}&create_time_from={timestamp}&create_time_to={timestamp}
• 头部:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

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

请求参数

• dataset_id: (路径参数)
  关联的数据集 ID。
• keywords: (过滤器参数), string
  用于匹配文档标题的关键词。
• page: (过滤器参数), integer 指定显示文档的页码。默认为 1。
• page_size: (过滤器参数), integer
  每页显示的最大文档数量。默认为 30。
• orderby: (过滤器参数), string
  用于排序文档的字段。可用选项:
  • create_time (默认)
  • update_time
• desc: (过滤器参数), boolean
  指示是否按降序排列检索到的文档。默认为 true。
• id: (过滤器参数), string
  要检索的文档 ID。
• create_time_from: (过滤器参数), integer 过滤创建时间在此Unix时间戳之后的文档。0 表示无过滤。默认为 0。
• create_time_to: (过滤器参数), integer 过滤创建时间在此之前Unix时间戳的文档。0 表示无过滤。默认为 0。

响应

成功:

{
    "code": 0,
    "data": {
        "docs": [
            {
                "chunk_count": 0,
                "create_date": "Mon, 14 Oct 2024 09:11:01 GMT",
                "create_time": 1728897061948,
                "created_by": "69736c5e723611efb51b0242ac120007",
                "id": "3bcfbf8a8a0c11ef8aba0242ac120006",
                "knowledgebase_id": "7898da028a0511efbf750242ac120005",
                "location": "Test_2.txt",
                "name": "Test_2.txt",
                "parser_config": {
                    "chunk_token_count": 128,
                    "delimiter": "\n",
                    "layout_recognize": true,
                    "task_page_size": 12
                },
                "chunk_method": "naive",
                "process_begin_at": null,
                "process_duration": 0.0,
                "progress": 0.0,
                "progress_msg": "",
                "run": "0",
                "size": 7,
                "source_type": "local",
                "status": "1",
                "thumbnail": null,
                "token_count": 0,
                "type": "doc",
                "update_date": "Mon, 14 Oct 2024 09:11:01 GMT",
                "update_time": 1728897061948
            }
        ],
        "total": 1
    }
}

失败:

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

---

删除文档

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

通过 ID 删除文档。

请求

• 方法: DELETE
• URL: /api/v1/datasets/{dataset_id}/documents
• 头部:
  • 'Content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • "ids": list[string]

请求示例

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": ["id_1","id_2"]
     }'

请求参数

• dataset_id: (路径参数)
  关联的数据集 ID。
• "ids": (正文参数), list[string]
  要删除的文档 ID。如果未指定，将删除指定数据集中所有文档。

响应

成功：

{
    "code": 0
}.

失败：

{
    "code": 102,
    "message": "你没有拥有数据集7898da028a0511efbf750242ac1220005。"
}

---

分割文档

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

对指定数据集中的文档进行解析。

请求

• 方法：POST
• URL：/api/v1/datasets/{dataset_id}/chunks
• 头部：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文：
  • "document_ids"：list[string]

请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]
     }'

请求参数

• dataset_id：(路径参数)
  数据集 ID。
• "document_ids"：(正文参数)，list[string]，必填
  要解析的文档 ID 列表。

响应

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "`document_ids` 是必需的"
}

---

停止解析文档

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

停止解析指定的文档。

请求

• 方法：DELETE
• URL：/api/v1/datasets/{dataset_id}/chunks
• 头部：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文：
  • "document_ids"：list[string]

请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]
     }'

请求参数

• dataset_id：(路径参数)
  关联的数据集 ID。
• "document_ids"：(正文参数)，list[string]，必填
  要停止解析的文档 ID 列表。

响应

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "`document_ids` 是必需的"
}

---

数据集中的分块管理

---

添加分块

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

向指定数据集中的特定文档添加一个分块。

请求

• 方法：POST
• URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
• 头部：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文：
  • "content"：string
  • "important_keywords"：list[string]

请求示例

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

请求参数

• dataset_id：(路径参数)
  关联的数据集 ID。
• document_ids：(路径参数)
  关联的文档 ID。
• "content"：(正文参数)，string，必填
  分块的文本内容。
• "important_keywords"(正文参数)，list[string]
  要与分块一起标记的关键术语或短语。
• "questions"(正文参数)，list[string]
  如果有给定的问题，则基于这些问题嵌入分块。

响应

成功：

{
    "code": 0,
    "data": {
        "chunk": {
            "id": string,
            "content": string,
            "important_keywords": list,
            "questions": list
        }
    }
}

失败：

{
    "code": 102,
    "message": "内容不能为空"
}

---

获取分块

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

获取指定数据集中特定文档的所有分块。

请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

响应

成功：

{
    "code": 0,
    "data": {
        "chunks": list
    }
}

失败：

{
    "code": 102,
    "message": "文档不存在"
}

---

请求参数

• dataset_id: (路径参数) 关联的数据集 ID。
• document_id: (路径参数) 关联的文档 ID。
• keywords(过滤器参数), string 用于匹配段落内容的关键字。
• page(过滤器参数), integer 指定显示段落的页面。默认值为 1。
• page_size(过滤器参数), integer 每页显示的最大段落数量。默认值为 1024。
• id(过滤器参数), string 获取特定段落的 ID。

响应

成功：

{
    "code": 0,
    "data": {
        "chunks": [
            {
                "available": true,
                "content": "这是测试内容。",
                "docnm_kwd": "1.txt",
                "document_id": "b330ec2e91ec11efbc510242ac120004",
                "id": "b48c170e90f70af998485c1065490726",
                "image_id": "",
                "important_keywords": "",
                "positions": [
                    ""
                ]
            }
        ],
        "doc": {
            "chunk_count": 1,
            "chunk_method": "naive",
            "create_date": "Thu, 24 Oct 2024 09:45:27 GMT",
            "create_time": 1729763127646,
            "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": {
                    "use_raptor": false
                }
            },
            "process_begin_at": "Thu, 24 Oct 2024 09:56:44 GMT",
            "process_duration": 0.54213,
            "progress": 0.0,
            "progress_msg": "任务已分派...",
            "run": "2",
            "size": 17966,
            "source_type": "local",
            "status": "1",
            "thumbnail": "",
            "token_count": 8,
            "type": "doc",
            "update_date": "Thu, 24 Oct 2024 11:03:15 GMT",
            "update_time": 1729767795721
        },
        "total": 1
    }
}

失败：

{
    "code": 102,
    "message": "你没有拥有文档 5c5999ec7be811ef9cab0242ac12000e5。"
}

---

删除段落

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

根据 ID 删除段落。

请求

• 方法: DELETE
• URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
• 标头:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • "chunk_ids": list[string]

请求示例

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 '
     {
          "chunk_ids": ["test_1", "test_2"]
     }'

请求参数

• dataset_id: (路径参数) 关联的数据集 ID。
• document_ids: (路径参数) 关联的文档 ID。
• "chunk_ids": (正文参数), list[string] 要删除的段落 ID。如果未指定，将删除指定文档的所有段落。

响应

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "`chunk_ids` 是必需的"
}

---

更新段落

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

更新指定段落的内容或配置。

请求

• 方法: PUT
• URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}
• 标头:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • "content": string
  • "important_keywords": list[string]
  • "available": boolean

请求示例

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": "ragflow123",  
          "important_keywords": []  
     }'

请求参数更新片段

• dataset_id: (路径参数)
  • 关联的数据集 ID。
• document_ids: (路径参数)
  • 关联的文档 ID。
• chunk_id: (路径参数)
  • 要更新的分块 ID。
• "content": (请求正文参数), string
  • 分块中的文本内容。
• "important_keywords": (请求正文参数), list[string]
  • 与该分块关联的关键术语或短语列表。
• "available": (请求正文参数) boolean
  • 分块在数据集中的可用状态。值选项：
    • true: 可用（默认）
    • false: 不可用

成功响应：

{
    "code": 0
}

失败响应：

{
    "code": 102,
    "message": "无法找到分块 29a2d9987e16ba331fb4d7d30d99b71d2"
}

---

检索分块

POST /api/v1/retrieval

从指定数据集中检索分块。

请求

• 方法: POST
• URL: /api/v1/retrieval
• 请求头:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • "question": string
    • 用户查询或查询关键字。
  • "dataset_ids": list[string]
    • 要搜索的数据集 ID 列表。如果未设置此参数，请确保设置了 "document_ids"。
  • "document_ids": list[string]
    • 要搜索的文档 ID 列表。请确保所有选定文档使用相同的嵌入模型。否则将引发错误。如果未设置此参数，请确保设置了 "dataset_ids".
  • "page": (正文参数) integer
    • 指定分块显示的页码，默认为 1。
  • "page_size": (正文参数)
    • 每页的最大分块数，默认为 30。
  • "similarity_threshold": (正文参数)
    • 最小相似度分数，默认为 0.2。
  • "vector_similarity_weight": (正文参数) float
    • 向量余弦相似度的权重，默认为 0.3。如果 x 表示向量余弦相似度的权重，则 (1 - x) 是术语相似度的权重。
  • "top_k": (正文参数) integer
    • 参与向量余弦计算的分块数量，默认为 1024。
  • "rerank_id": (正文参数) integer
    • 重排模型的 ID。
  • "keyword": (正文参数) boolean
    • 表示是否启用基于关键词的匹配：
      • true: 启用基于关键词的匹配。
      • false: 禁用基于关键词的匹配（默认）。
  • "highlight": (正文参数) boolean
    • 指定是否在结果中突出显示匹配项：
      • true: 启用匹配项的高亮显示。
      • false: 禁用匹配项的高亮显示（默认）。
  • "cross_languages": (正文参数) list[string]
    • 要翻译成的目标语言列表，按顺序实现多语言关键词检索。

请求示例

curl --request POST \
     --url http://{address}/api/v1/retrieval \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "question": "What is advantage of ragflow?",
          "dataset_ids": ["b2a62730759d11ef987d0242ac120004"],
          "document_ids": ["77df9ef4759a11ef8bdd0242ac120004"]
     }'

响应

成功：

{
    "code": 0,
    "data": {
        "chunks": [
            {
                "content": "ragflow content",
                "content_ltks": "ragflow content",
                "document_id": "5c5999ec7be811ef9cab0242ac120005",
                "document_keyword": "1.txt",
                "highlight": "<em>ragflow</em> content",
                "id": "d78435d142bd5cf6704da62c778795c5",
                "image_id": "",
                "important_keywords": [
                    ""
                ],
                "kb_id": "c7ee74067a2c11efb21c0242ac120006",
                "positions": [
                    ""
                ],
                "similarity": 0.9669436601210759,
                "term_similarity": 1.0,
                "vector_similarity": 0.8898122004035864
            }
        ],
        "doc_aggs": [
            {
                "count": 1,
                "doc_id": "5c5999ec7be811ef9cab0242ac120005",
                "doc_name": "1.txt"
            }
        ],
        "total": 1
    }
}

失败：

{
    "code": 102,
    "message": "`datasets` 是必需的。"
}

---

聊天助手管理

创建聊天助手

POST /api/v1/chats

创建一个聊天助手。

请求

• 方法： POST
• URL： /api/v1/chats
• Headers：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• Body：
  • "name"： string
  • "avatar"： string
  • "dataset_ids"： list[string]
  • "llm"： object
  • "prompt"： object

请求示例

curl --request POST \
     --url http://{address}/api/v1/chats \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
    "dataset_ids": ["0b2cbc8c877f11ef89070242ac120005"],
    "name":"new_chat_1"
}'

请求参数

• "name"： (Body parameter)，string，必填
  聊天助手的名称。
• "avatar"： (Body parameter)，string
  头像的Base64编码。
• "dataset_ids"： (Body parameter)，list[string]
  关联的数据集ID。
• "llm"： (Body parameter)，object
  聊天助手创建时使用的LLM设置。如果未显式设置，默认生成包含以下值的对象。一个 llm JSON对象包含以下属性：
  • "model_name"，string
    聊天模型名称。若未设置，则使用用户的默认聊天模型。
  • "temperature"： float
    控制模型预测结果的随机性。温度值越低，模型的回答越保守；温度值越高，回答越富有创造性和多样性。默认为 0.1。
  • "top_p"： float
    又称为“核选择采样”，此参数设置一个阈值，以从较小的单词集合中进行采样。它专注于最可能的单词，并排除不太可能的单词。默认为 0.3
  • "presence_penalty"： float
    通过惩罚已经在对话中出现过的词汇来防止模型重复信息，默认为 0.4。
  • "frequency penalty"： float
    类似于存在惩罚，此参数减少模型频繁重复相同单词的倾向，默认为 0.7。
• "prompt"： (Body parameter)，object
  LLM需要遵循的指令。如果未显式设置，默认生成包含以下值的对象。一个 prompt JSON对象包含以下属性：
  • "similarity_threshold"： float RAGFlow在检索过程中采用加权关键词相似度和加权余弦相似度向量，或加权关键词相似度和加权重排分数的组合。此参数设置用户查询与片段之间的相似性阈值。如果相似度得分低于该阈值，则对应的片段将从结果中排除。默认值为 0.2。
  • "keywords_similarity_weight"： float 此参数设置关键词相似度在混合相似度分数（向量余弦相似度或重排模型相似度）中的权重。通过调整此权重，可以控制关键词相似度与其他相似度衡量之间的影响力。默认值为 0.7。
  • "top_n"： int 此参数指定相似度得分高于 similarity_threshold 的前N个片段数量，这些片段将传递给LLM。LLM将仅访问这些“前N名”片段。默认值为 6。
  • "variables"： object[] 此参数列出在聊天配置的“系统”字段中使用的变量。注意事项包括：
    • "knowledge" 是一个保留变量，表示检索到的片段。
    • “System”中的所有变量均应使用大括号括起来。
    • 默认值为 [{"key": "knowledge", "optional": true}]。
  • "rerank_model"： string 如果未指定，默认使用向量余弦相似度；否则，将使用重排分数。
  • top_k： int 指定根据特定排名标准对列表或集合中的项重新排序或选择前K个项目的参数。默认为 1024。
  • "empty_response"： string 如果在数据集中未找到用户问题的相关内容，此字段将作为响应使用。为了允许LLM自由发挥，请留空。
  • "opener"： string 用户的开场问候语。默认值为 "Hi! I am your assistant, can I help you?"。
  • "show_quote： boolean 表示是否显示文本来源。默认为 true。
  • "prompt"： string 提示内容。

响应

成功：

{
    "code": 0,
    "data": {
        "avatar": "",
        "create_date": "Thu, 24 Oct 2024 11:18:29 GMT",
        "create_time": 1729768709023,
        "dataset_ids": [
            "527fa74891e811ef9c650242ac120006"
        ],
        "description": "A helpful Assistant",
        "do_refer": "1",
        "id": "b1f2f15691f911ef81180242ac120003",
        "language": "English",
        "llm": {
            "frequency_penalty": 0.7,
            "model_name": "qwen-plus@Tongyi-Qianwen",
            "presence_penalty": 0.4,
            "temperature": 0.1,
            "top_p": 0.3
        },
        "name": "12234",
        "prompt": {
            "empty_response": "抱歉！知识库中未找到相关内容。",
            "keywords_similarity_weight": 0.3,
            "opener": "你好！我是你的助手。有什么可以帮助你的吗？",
            "prompt": "你是一个智能助手。请总结知识库的内容以回答问题。请列出知识库中的数据并详细作答。当所有知识库内容都与问题无关时，你的答案中必须包含“你要找的答案不在知识库中！”这句话。回答需要考虑聊天历史。\n ",
            "rerank_model": "",
            "similarity_threshold": 0.2,
            "top_n": 6,
            "variables": [
                {
                    "key": "knowledge",
                    "optional": false
                }
            ]
        },
        "prompt_type": "simple",
        "status": "1",
        "tenant_id": "69736c5e723611efb51b0242ac120007",
        "top_k": 1024,
        "update_date": "Thu, 24 Oct 2024 11:18:29 GMT",
        "update_time": 1729768709023
    }
}

失败：

{
    "code": 102,
    "message": "创建数据集时重复的聊天名称。"
}

---

更新聊天助手

PUT /api/v1/chats/{chat_id}

更新指定聊天机器人的配置。

请求

• 方法: PUT
• URL: /api/v1/chats/{chat_id}
• 头部:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • "name": string
  • "avatar": string
  • "dataset_ids": list[string]
  • "llm": object
  • "prompt": object

请求示例

curl --request PUT \
     --url http://{address}/api/v1/chats/{chat_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '
     {
          "name":"Test"
     }'

参数

• chat_id: (Path parameter)
  要更新的聊天助手 ID。
• "name": (Body parameter), string, 必填项
  聊天助手的新名称。
• "avatar": (Body parameter), string
  头像的 Base64 编码。
• "dataset_ids": (Body parameter), list[string]
  关联的数据集 ID 列表。
• "llm": (Body parameter), object
  聊天助手的 LLM 设置。如果没有显式设置，默认会生成一个包含以下值的字典。一个 llm 对象包含以下属性：
  • "model_name": string
    聊天模型名称。如果未设置，将使用用户的默认聊天模型。
  • "temperature": float
    控制模型预测结果的随机性。温度值越低，模型的回答越保守；温度值越高，回答越具有创造性和多样性。默认为 0.1。
  • "top_p": float
    又称为“核心采样”，此参数设置一个阈值，从概率分布中选择较小的一部分单词进行采样。它专注于最可能的单词，并排除不太可能的单词。默认为 0.3。
  • "presence_penalty": float
    通过惩罚已经在对话中出现过的单词来减少模型重复信息的可能性。默认为 0.2。
  • "frequency penalty": float
    类似于存在惩罚，此参数减少了模型频繁重复相同单词的倾向性。默认为 0.7。
• "prompt": (Body parameter), object
  LLM 需要遵循的指令。一个 prompt 对象包含以下属性：
  • "similarity_threshold": float RAGFlow 在检索过程中使用加权关键词相似性和向量余弦相似性的组合，或加权关键词相似性与重新排序模型相似性的组合。此参数设置用户查询和片段之间的相似性阈值。如果相似度得分低于该阈值，则相应的片段将被排除在结果之外。默认值为 0.2。
  • "keywords_similarity_weight": float 此参数设置混合相似性评分中关键词相似性的权重，与向量余弦相似性或重新排序模型相似性结合使用。通过调整此权重，可以控制关键词相似性与其他相似度衡量之间的影响力。默认值为 0.7。
  • "top_n": int 此参数指定相似度得分高于 similarity_threshold 的前 N 个片段数量，这些片段将传递给 LLM。LLM 只能访问这些“顶部 N”片段。默认值为 8。
  • "variables": object[] 此参数列出了在 聊天配置 中“系统”字段中使用的变量。注意：
    • "knowledge" 是一个保留变量，表示检索到的片段。
    • “System” 字段中的所有变量均应使用大括号括起来。
    • 默认值为 [{"key": "knowledge", "optional": true}]
  • "rerank_model": string 如果未指定，默认使用向量余弦相似性；否则，将使用重新排序分数。
  • "empty_response": string 如果在数据集中没有找到用户问题的相关内容，则此字段将用作响应。为了允许 LLM 在没有结果时进行自由发挥，请留空。
  • "opener": string 用户的开场问候语。默认为 "Hi! I am your assistant, can I help you?".
  • "show_quote: boolean 表示是否显示文本的来源。默认为 true。
  • "prompt": string 提示内容。

响应

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "更新数据集中重复的聊天名称。"
}

---

删除聊天助手

DELETE /api/v1/chats

通过 ID 删除聊天助手。

请求

• 方法：DELETE
• URL：/api/v1/chats
• 头部：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文：
  • "ids": list[string]

请求示例

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

请求参数

• "ids": (Body parameter), list[string]
  要删除的聊天助手 ID 列表。如果未指定，将删除系统中的所有聊天助手。

响应

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "ids are required"
}

---

列出聊天助手

GET /api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id}

列出聊天助手。

请求

• 方法: GET
• URL: /api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id}
• 请求头:
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

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

请求参数

• page: (过滤参数)，integer
  指定在第几页显示聊天助手，默认为 1。
• page_size: (过滤参数)，integer
  每页显示的聊天助手数量，默认为 30。
• orderby: (过滤参数)，string
  结果按照哪个属性排序。可选值:
  • create_time（默认）
  • update_time
• desc: (过滤参数)，boolean
  表示是否按降序排列获取的聊天助手，默认为 true。
• id: (过滤参数)，string
  获取指定ID的聊天助手。
• name: (过滤参数)，string
  获取指定名称的聊天助手。

响应

成功:

{
    "code": 0,
    "data": [
        {
            "avatar": "",
            "create_date": "Fri, 18 Oct 2024 06:20:06 GMT",
            "create_time": 1729232406637,
            "description": "A helpful Assistant",
            "do_refer": "1",
            "id": "04d0d8e28d1911efa3630242ac120006",
            "dataset_ids": ["527fa74891e811ef9c650242ac120006"],
            "language": "English",
            "llm": {
                "frequency_penalty": 0.7,
                "model_name": "qwen-plus@Tongyi-Qianwen",
                "presence_penalty": 0.4,
                "temperature": 0.1,
                "top_p": 0.3
            },
            "name": "13243",
            "prompt": {
                "empty_response": "抱歉！知识库中未找到相关内容！",
                "keywords_similarity_weight": 0.3,
                "opener": "你好！我是你的助手。有什么我可以帮您的吗？",
                "prompt": "你是一个智能助手。请总结知识库中的内容以回答问题。请列出知识库中的数据并详细回答。\n当所有知识库内容都与问题无关时，您的答案必须包含句子“您要找的答案不在知识库中！”。答案需要考虑聊天记录。\n",
                "rerank_model": "",
                "similarity_threshold": 0.2,
                "top_n": 6,
                "variables": [
                    {
                        "key": "knowledge",
                        "optional": false
                    }
                ]
            },
            "prompt_type": "simple",
            "status": "1",
            "tenant_id": "69736c5e723611efb51b0242ac120007",
            "top_k": 1024,
            "update_date": "Fri, 18 Oct 2024 06:20:06 GMT",
            "update_time": 1729232406638
        }
    ]
}

失败:

{
    "code": 102,
    "message": "聊天不存在"
}

---

会话管理

---

创建聊天助手的会话

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

创建一个聊天助手的会话。

请求

• 方法: POST
• URL: /api/v1/chats/{chat_id}/sessions
• 请求头:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 请求体:
  • "name": string
  • "user_id": string（可选）

请求示例

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

请求参数

• chat_id: (路径参数)
  关联的聊天助手ID。
• "name": (请求体参数), string
  创建的聊天会话名称。
• "user_id": (请求体参数), string
  可选自定义用户ID。

响应

成功:

{
    "code": 0,
    "data": {
        "chat_id": "2ca4b22e878011ef88fe0242ac120005",
        "create_date": "Fri, 11 Oct 2024 08:46:14 GMT",
        "create_time": 1728636374571,
        "id": "4606b4ec87ad11efbc4f0242ac120006",
        "messages": [
            {
                "content": "你好！我是你的助手，有什么可以帮您的吗？",
                "role": "assistant"
            }
        ],
        "name": "new session",
        "update_date": "Fri, 11 Oct 2024 08:46:14 GMT",
        "update_time": 1728636374571
    }
}

失败:

{
    "code": 102,
    "message": "名称不能为空。"
}

---

更新聊天助手的会话

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

更新指定聊天助手的会话。

请求方法 PUT

• 请求方法: PUT
• URL: /api/v1/chats/{chat_id}/sessions/{session_id}
• 头信息:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 请求体:
  • "name": string
  • "user_id": string（可选）

请求示例

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

请求参数

• chat_id: (路径参数)
  • 联系的聊天助手 ID。
• session_id: (路径参数)
  • 要更新的会话 ID。
• "name": (请求体参数), string
  • 修订后的会话名称。
• "user_id": (请求体参数), string
  • 可选的用户自定义 ID。

响应

成功

{
    "code": 0
}

失败

{
    "code": 102,
    "message": "名称不能为空。"
}

---

列出会话

GET /api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}

列出指定聊天助手关联的会话。

请求

• 请求方法: GET
• URL: /api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}
• 头信息:
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

curl --request GET \
     --url http://{address}/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

请求参数

• chat_id: (路径参数)
  • 联系的聊天助手 ID。
• page: (过滤器参数), integer
  • 指定显示会话所在的页码，默认为 1。
• page_size: (过滤器参数), integer
  • 每页显示的会话数量，默认为 30。
• orderby: (过滤器参数), string
  • 按哪个字段排序会话。可用选项：
    • create_time（默认）
    • update_time
• desc: (过滤器参数), boolean
  • 是否按降序排列检索到的会话，默认为 true。
• name: (过滤器参数) string
  • 要检索的聊天会话名称。
• id: (过滤器参数), string
  • 要检索的聊天会话 ID。
• user_id: (过滤器参数), string
  • 创建会话时传递的可选用户自定义 ID。

响应

成功

{
    "code": 0,
    "data": [
        {
            "chat": "2ca4b22e878011ef88fe0242ac120005",
            "create_date": "Fri, 11 Oct 2024 08:46:43 GMT",
            "create_time": 1728636403974,
            "id": "578d541e87ad11ef96b90242ac120006",
            "messages": [
                {
                    "content": "你好！我是你的助手，有什么可以帮助你的吗？",
                    "role": "assistant"
                }
            ],
            "name": "new session",
            "update_date": "Fri, 11 Oct 2024 08:46:43 GMT",
            "update_time": 1728636403974
        }
    ]
}

失败

{
    "code": 102,
    "message": "会话不存在"
}

---

删除聊天助手的会话

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

按 ID 删除聊天助手的会话。

请求

• 请求方法: DELETE
• URL: /api/v1/chats/{chat_id}/sessions
• 头信息:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 请求体:
  • "ids": list[string]

请求示例

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": ["test_1", "test_2"]
     }'

请求参数

• chat_id: (路径参数)
  • 联系的聊天助手 ID。
• "ids": (请求体参数), list[string]
  • 要删除的会话 ID 列表。如果未指定，将删除与指定聊天助手关联的所有会话。

响应

成功

{
    "code": 0
}

---

注意事项

• 所有代码块和链接均保持原样，确保功能正常。
• 公司名称如Anthropic、Azure-OpenAI等保持英文不变，国内公司名称适当翻译（如有）。
• 技术术语如API、SDK等保持原样，框架名称如React、Vue保留不变。
• 请求示例中的curl命令和JSON结构均未修改，确保与原始内容一致。

请求

• 方法：POST
• URL：/api/v1/chats/{chat_id}/completions
• Headers：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• Body：
  • "question"：string
  • "stream"：boolean
  • "session_id"：string（可选）
  • "user_id"：string（可选）

请求示例

curl --request POST \
     --url http://{address}/api/v1/chats/{chat_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
     }'

curl --request POST \
     --url http://{address}/api/v1/chats/{chat_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
          "question": "Who are you",
          "stream": true,
          "session_id":"9fa7691cb85c11ef9c5f0242ac120005"
     }'

请求参数

• chat_id：（路径参数）
  关联的聊天助手ID。
• "question"：（正文参数），string，必需
  启动AI对话的问题。
• "stream"：（正文参数），boolean
  表示是否以流式输出响应：
  • true：启用流式输出（默认）。
  • false：禁用流式输出。
• "session_id"：（正文参数）
  会话ID。如果未提供，将生成新会话。
• "user_id"：（正文参数），string
  可选用户自定义ID。仅在没有 session_id 时有效。

响应

无 session_id 成功：

data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "Hi! I'm your assistant. What can I do for you?",
        "reference": {},
        "audio_binary": null,
        "id": null,
        "session_id": "b01eed84b85611efa0e90242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": true
}

有 session_id 成功：

data|{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a",
        "reference": {},
        "audio_binary": null,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data|{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a knowledge base. My responses are based on the information available in the knowledge base and",
        "reference": {},
        "audio_binary": null,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data|{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a knowledge base. My responses are based on the information available in the knowledge base and any relevant chat history.",
        "reference": {},
        "audio_binary": null,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data|{
    "code": 0,
    "data": {
        "answer": "I am an intelligent assistant designed to help answer questions by summarizing content from a knowledge base ##0$$. My responses are based on the information available in the knowledge base and any relevant chat history.",
        "reference": {
            "total": 1,
            "chunks": [
                {
                    "id": "faf26c791128f2d5e821f822671063bd",
                    "content": "xxxxxxxx",
                    "document_id": "dd58f58e888511ef89c90242ac120006",
                    "document_name": "1.txt",
                    "dataset_id": "8e83e57a884611ef9d760242ac120006",
                    "image_id": "",
                    "url": null,
                    "similarity": 0.7,
                    "vector_similarity": 0.0,
                    "term_similarity": 1.0,
                    "doc_type": [],
                    "positions": [
                        ""
                    ]
                }
            ],
            "doc_aggs": [
                {
                    "doc_name": "1.txt",
                    "doc_id": "dd58f58e888511ef89c90242ac120006",
                    "count": 1
                }
            ]
        },
        "prompt": "xxxxxxxxxxx",
        "created_at": 1755055623.6401553,
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data|{
    "code": 0,
    "data": true
}

失败：

{
    "code": 102,
    "message": "请提供您的问题。"
}

创建会话与代理

已弃用

此方法已过时且不被推荐使用。尽管仍然可以调用它，但请注意，调用 Converse with agent 会自动为关联的代理生成一个会话 ID。

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

创建与代理的会话。

请求

• 方法: POST
• URL: /api/v1/agents/{agent_id}/sessions?user_id={user_id}
• 头部:
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • 必填参数:str
  • 其他参数: 开始组件中指定的变量。

请求示例

如果您的代理中的 Begin 组件没有必填参数：

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/sessions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     }'

请求参数

• agent_id: (路径参数)
  关联代理的 ID。
• user_id: (过滤器参数)
  用户定义的可选 ID，用于在创建会话时解析文档（特别是图片）时使用。

响应

成功:

{
    "code": 0,
    "data": {
        "agent_id": "dbb4ed366e8611f09690a55a6daec4ef",
        "dsl": {
            "components": {
                "Message:EightyJobsAsk": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Message",
                        "params": {
                            "content": [
                                "{begin@var1}{begin@var2}"
                            ],
                            "debug_inputs": {},
                            "delay_after_error": 2.0,
                            "description": "",
                            "exception_default_value": null,
                            "exception_goto": null,
                            "exception_method": null,
                            "inputs": {},
                            "max_retries": 0,
                            "message_history_window_size": 22,
                            "outputs": {
                                "content": {
                                    "type": "str",
                                    "value": null
                                }
                            },
                            "stream": true
                        }
                    },
                    "upstream": [
                        "begin"
                    ]
                },
                "begin": {
                    "downstream": [
                        "Message:EightyJobsAsk"
                    ],
                    "obj": {
                        "component_name": "Begin",
                        "params": {
                            "debug_inputs": {},
                            "delay_after_error": 2.0,
                            "description": "",
                            "enablePrologue": true,
                            "enable_tips": true,
                            "exception_default_value": null,
                            "exception_goto": null,
                            "exception_method": null,
                            "inputs": {
                                "var1": {
                                    "name": "var1",
                                    "optional": false,
                                    "options": [],
                                    "type": "line",
                                    "value": null
                                },
                                "var2": {
                                    "name": "var2",
                                    "optional": false,
                                    "options": [],
                                    "type": "line",
                                    "value": null
                                }
                            },
                            "max_retries": 0,
                            "message_history_window_size": 22,
                            "mode": "conversational",
                            "outputs": {},
                            "prologue": "你好！我是你的助手。你能为我做些什么？",
                            "tips": "请填写表单"
                        }
                    },
                    "upstream": []
                }
            },
            "globals": {
                "sys.conversation_turns": 0,
                "sys.files": [],
                "sys.query": "",
                "sys.user_id": ""
            },
            "graph": {
                "edges": [
                    {
                        "data": {
                            "isHovered": false
                        },
                        "id": "xy-edge__beginstart-Message:EightyJobsAskend",
                        "markerEnd": "logo",
                        "source": "begin",
                        "sourceHandle": "start",
                        "style": {
                            "stroke": "rgba(151, 154, 171, 1)",
                            "strokeWidth": 1
                        },
                        "target": "Message:EightyJobsAsk",
                        "targetHandle": "end",
                        "type": "buttonEdge",
                        "zIndex": 1001
                    }
                ],
                "nodes": [
                    {
                        "data": {
                            "form": {
                                "enablePrologue": true,
                                "inputs": {
                                    "var1": {
                                        "name": "var1",
                                        "optional": false,
                                        "options": [],
                                        "type": "line"
                                    },
                                    "var2": {
                                        "name": "var2",
                                        "optional": false,

{
    "data": {
        "form": {
            "content": [
                "{begin@var1}{begin@var2}"
            ]
        },
        "label": "消息",
        "name": "Message_0"
    },
    "dragging": false,
    "id": "Message:EightyJobsAsk",
    "measured": {
        "height": 57,
        "width": 200
    },
    "position": {
        "x": 279.5,
        "y": 190
    },
    "selected": true,
    "sourcePosition": "right",
    "targetPosition": "left",
    "type": "messageNode"
},
{
    "data": {
        "form": {
            "content": [],
            "options": [],
            "type": "line"
        },
        "label": "开始",
        "name": "begin"
    },
    "dragging": false,
    "id": "begin",
    "measured": {
        "height": 112,
        "width": 200
    },
    "position": {
        "x": 270.64098070942583,
        "y": -56.320928437811176
    },
    "selected": false,
    "sourcePosition": "left",
    "targetPosition": "right",
    "type": "beginNode"
},
{
    "history": [],
    "memory": [],
    "messages": [],
    "path": [],
    "retrieval": [],
    "task_id": "dbb4ed366e8611f09690a55a6daec4ef"
},
{
    "id": "0b02fe80780e11f084adcfdc3ed1d902",
    "message": [
        {
            "content": "你好！我是你的助手。有什么我可以为你做的吗？",
            "role": "assistant"
        }
    ],
    "source": "agent",
    "user_id": "c3fb861af27a11efa69751e139332ced"
}

失败：

{
    "code": 102,
    "message": "Agent not found."
}

---

直接输出翻译后的中文内容，不添加额外说明。

与代理对话

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

向指定的代理提出一个问题，启动一个AI驱动的对话。

注意事项

• 在流式模式下，并非所有响应都包含引用，这取决于系统的判断。

• 在流式模式下，最后一条消息是一个空消息：

  [DONE]

请求

• 方法：POST
• URL： /api/v1/agents/{agent_id}/completions
• Headers：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• Body：
  • "question": string （必填）
  • "stream": boolean
  • "session_id": string（可选）
  • "inputs": object（可选）
  • "user_id": string（可选）

注意事项

你可以在请求体中包含自定义参数，但请首先确保这些参数在开始组件中已定义。

请求示例

• 如果 Begin 组件不接受参数：

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
        "question": "Hello",
        "stream": false,
     }'

• 如果 Begin 组件接受参数，请在 "inputs" 体中包含它们的值，如下所示：

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
    {
        "question": "Hello",
        "stream": false,
        "inputs": {
            "line_var": {
                "type": "line",
                "value": "I am line_var"
            },
            "int_var": {
                "type": "integer",
                "value": 1
            },
            "paragraph_var": {
                "type": "paragraph",
                "value": "a\nb\nc"
            },
            "option_var": {
                "type": "options",
                "value": "option 2"
            },
            "boolean_var": {
                "type": "boolean",
                "value": true
            }
        }
    }'

以下代码将执行完成过程

curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data-binary '
     {
          "question": "Hello",
          "stream": true,
          "session_id": "cb2f385cb86211efa36e0242ac120005"
     }'

请求参数

• agent_id：(路径参数)，string
  关联代理的ID。
• "question"：(正文参数)，string，必填
  启动AI驱动对话的问题。
• "stream"：(正文参数)，boolean
  表示是否以流式方式输出响应：
  • true：启用流式（默认）。
  • false：禁用流式。
• "session_id"：(正文参数)
  会话的ID。如果没有提供，将生成一个新的会话。
• "inputs"：(正文参数)
  Begin 组件中指定的变量。
• "user_id"：(正文参数)，string
  用户定义的可选ID。仅在没有 session_id 提供时有效。

注意事项

目前，此方法不支持文件类型输入/变量。作为 workaround，请使用以下方式上传文件到代理：
http://{address}/v1/canvas/upload/{agent_id}
你将从其响应正文获得相应的文件 ID.

响应

未提供 session_id 且 Begin 组件中未指定变量时的成功情况：

流：

data:{
    "event": "消息",
    "message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
    "created_at": 1755083342,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "Hello"
    },
    "session_id": "eaf19a8e783511f0b9b61a6272e682d8"
}

data:{
    "event": "消息",
    "message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
    "created_at": 1755083342,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "!"
    },
    "session_id": "eaf19a8e783511f0b9b61a6272e682d8"
}

data:{
    "event": "消息",
    "message_id": "eb0c0a5e783511f0b9b61a6272e682d8",
    "created_at": 1755083342,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": " How"
    },
    "session_id": "eaf19a8e783511f0b9b61a6272e682d8"
}

...

data:[DONE]

非流：

{
    "event": "workflow_finished",
    "message_id": "effdad8c783611f089261a6272e682d8",
    "session_id": "efe523b6783611f089261a6272e682d8",
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "outputs": {
            "_created_time": 547400.869271305,
            "_elapsed_time": 0.0001251999055966735,
            "content": "Hello there! How can I assist you today?"
        }
    }
}

Begin 组件中指定变量时的成功情况：

流：

data:{
    "event": "消息",
    "message_id": "5b62e790783711f0bc531a6272e682d8",
    "created_at": 1755083960,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "Hello"
    },
    "session_id": "979e450c781d11f095cb729e3aa55728"
}

data:{
    "event": "消息",
    "message_id": "5b62e790783711f0bc531a6272e682d8",
    "created_at": 1755083960,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": "!"
    },
    "session_id": "979e450c781d11f095cb729e3aa55728"
}

data:{
    "event": "消息",
    "message_id": "5b62e790783711f0bc531a6272e682d8",
    "created_at": 1755083960,
    "task_id": "99ee29d6783511f09c921a6272e682d8",
    "data": {
        "content": " You"
    },
    "session_id": "979e450c781d11f095cb729e3aa55728"
}

...

data:[DONE]

{
    "code": 0,
    "data": {
        "created_at": 1755084029,
        "data": {
            "created_at": 547650.750818867,
            "elapsed_time": 1.6227330720284954,
            "inputs": {},
            "outputs": {
                "_created_time": 547650.752800839,
                "_elapsed_time": 9.628792759031057e-05,
                "content": "你好！看起来你又发送了一个“你好”而没有额外的上下文。我在这里，并准备好响应任何请求或问题。是否有具体的事情你想讨论或了解？"
            }
        },
        "event": "workflow_finished",
        "message_id": "84eec534783711f08db41a6272e682d8",
        "session_id": "979e450c781d11f095cb729e3aa55728",
        "task_id": "99ee29d6783511f09c921a6272e682d8"
    }
}

失败：

{
    "code": 102,
    "message": "`question` 是必需的。"
}

列出会话

GET /api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id}&dsl={dsl}

列出与指定代理关联的会话。

请求

• 方法: GET
• URL: /api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}
• 头部:
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

curl --request GET \
     --url http://{address}/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

请求参数

• agent_id: (路径参数)
  关联代理的ID。
• page: (筛选参数), integer
  指定显示会话的页面编号。默认为 1。
• page_size: (筛选参数), integer
  每页显示的会话数量。默认为 30。
• orderby: (筛选参数), string
  按照哪个字段对会话进行排序。可用选项:
  • create_time (默认)
  • update_time
• desc: (筛选参数), boolean
  表示检索的会话是否应按降序排序。默认为 true。
• id: (筛选参数), string
  检索特定代理会话的ID。
• user_id: (筛选参数), string
  在创建会话时可选的用户自定义ID。
• dsl: (筛选参数), boolean
  表示响应中是否包含会话的dsl字段。默认为 true。

响应

成功：

{
    "code": 0,
    "data": [{
        "agent_id": "e9e2b9c2b2f911ef801d0242ac120006",
        "dsl": {
            "answer": [],
            "components": {
                "Answer:OrangeTermsBurn": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Answer",
                        "params": {}
                    },
                    "upstream": []
                },
                "Generate:SocialYearsRemain": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Generate",
                        "params": {
                            "cite": true,
                            "frequency_penalty": 0.7,
                            "llm_id": "gpt-4o___OpenAI-API@OpenAI-API-Compatible",
                            "message_history_window_size": 12,
                            "parameters": [],
                            "presence_penalty": 0.4,
                            "prompt": "Please summarize the following paragraph. Pay attention to the numbers and do not make things up. The paragraph is as follows:\n{input}\nThis is what you need to summarize.",
                            "temperature": 0.1,
                            "top_p": 0.3
                        }
                    },
                    "upstream": []
                },
                "begin": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Begin",
                        "params": {}
                    },
                    "upstream": []
                }
            },
            "graph": {
                "edges": [],
                "nodes": [
                    {
                        "data": {
                            "label": "Begin",
                            "name": "begin"
                        },
                        "height": 44,
                        "id": "begin",
                        "position": {
                            "x": 50,
                            "y": 200
                        },
                        "sourcePosition": "left",
                        "targetPosition": "right",
                        "type": "beginNode",
                        "width": 200
                    },
                    {
                        "data": {
                            "form": {
                                "cite": true,
                                "frequencyPenaltyEnabled": true,
                                "frequency_penalty": 0.7,
                                "llm_id": "gpt-4o___OpenAI-API@OpenAI-API-Compatible",
                                "maxTokensEnabled": true,
                                "message_history_window_size": 12,
                                "parameters": [],
                                "presencePenaltyEnabled": true,
                                "presence_penalty": 0.4,
                                "prompt": "Please summarize the following paragraph. Pay attention to the numbers and do not make things up. The paragraph is as follows:\n{input}\nThis is what you need to summarize.",
                                "temperature": 0.1,
                                "temperatureEnabled": true,
                                "topPEnabled": true,
                                "top_p": 0.3
                            },
                            "label": "Generate",
                            "name": "Generate Answer_0"
                        },
                        "dragging": false,
                        "height": 105,
                        "id": "Generate:SocialYearsRemain",
                        "position": {
                            "x": 561.3457829707513,
                            "y": 178.7211182312641
                        },
                        "positionAbsolute": {
                            "x": 561.3457829707513,
                            "y": 178.7211182312641
                        },
                        "selected": true,
                        "sourcePosition": "right",
                        "targetPosition": "left",
                        "type": "generateNode",
                        "width": 200
                    },
                    {
                        "data": {
                            "form": {},
                            "label": "Answer",
                            "name": "Dialogue_0"
                        },
                        "height": 44,
                        "id": "Answer:OrangeTermsBurn",
                        "position": {
                            "x": 317.2368194777658,
                            "y": 218.30635555445093
                        },
                        "sourcePosition": "right",
                        "targetPosition": "left",
                        "type": "logicNode",
                        "width": 200

{
    "children": [
        {
            "type": "doc",
            "id": "introduction"
        },
        {
            "type": "heading",
            "depth": 2,
            "children": [
                {
                    "text": "Getting Started"
                }
            ]
        },
        {
            "type": "paragraph",
            "children": [
                {
                    "text": "Welcome to our API documentation. Here, you will find everything you need to integrate and use our service effectively."
                }
            ]
        },
        {
            "type": "code_block",
            "language": null,
            "content": "curl https://api.example.com/v1"
        },
        {
            "type": "paragraph",
            "children": [
                {
                    "text": "For more detailed information, please refer to our API endpoints and examples."
                }
            ]
        },
        {
            "type": "heading",
            "depth": 3,
            "children": [
                {
                    "text": "Authentication"
                }
            ]
        },
        {
            "type": "ulist",
            "items": [
                {
                    "text": {
                        "type": "paragraph",
                        "children": [
                            {
                                "text": "Generate an API key from your dashboard."
                            }
                        ]
                    }
                },
                {
                    "text": {
                        "type": "paragraph",
                        "children": [
                            {
                                "text": "Include the API key in the headers of your requests."
                            }
                        ]
                    }
                }
            ]
        },
        {
            "type": "heading",
            "depth": 3,
            "children": [
                {
                    "text": "Parameters"
                }
            ]
        },
        {
            "type": "table",
            "header": [
                {
                    "text": "Parameter",
                    "align": "left"
                },
                {
                    "text": "Description",
                    "align": "left"
                },
                {
                    "text": "Type",
                    "align": "left"
                }
            ],
            "rows": [
                {
                    "text": "api_key",
                    "align": "left",
                    "type": "code_inline",
                    "children": []
                },
                {
                    "text": "Required API key for authentication.",
                    "align": "left",
                    "type": null,
                    "children": []
                }
            ]
        }
    ],
    "id": "792dde22b2fa11ef97550242ac120006"
}

错误：

{
    "code": 102,
    "message": "您没有拥有该代理：ccd2f856b12311ef94ca0242ac1200052。"
}

---

删除代理会话

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

根据ID删除代理的会话。

请求

• 方法：DELETE
• URL：/api/v1/agents/{agent_id}/sessions
• 头部：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文：
  • "ids": list[string]

请求示例

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": ["test_1", "test_2"]
     }'

请求参数

• agent_id：(路径参数)
  • 代理的ID。
• "ids"：(正文参数)，list[string]
  • 要删除的会话ID。如果未指定，则删除与指定代理关联的所有会话。

响应

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "The agent doesn't own the session cbd31e52f73911ef93b232903b842af6"
}

---

生成相关问题

POST /v1/sessions/related_questions

从用户的原始查询中生成5到10个替代问题字符串，以获取更多相关搜索结果。

此操作需要一个Bearer Login Token，该令牌通常在24小时内过期。您可以在浏览器的请求头中轻松找到它，如下所示：

注意

聊天模型会根据指令自主决定生成的问题数量，通常在5到10个之间。

请求

• 方法：POST
• URL：/v1/sessions/related_questions
• 头部：
  • 'content-Type: application/json'
  • 'Authorization: Bearer <YOUR_LOGIN_TOKEN>'
• 正文：
  • "question": string
  • "industry": string

请求示例

curl --request POST \
     --url http://{address}/v1/sessions/related_questions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_LOGIN_TOKEN>' \
     --data '
     {
          "question": "What are the key advantages of Neovim over Vim?",
          "industry": "software_development"
     }'

请求参数

• "question"：(正文参数)，string
  • 用户的原始问题。
• "industry"：(正文参数)，string
  • 问题所属行业。

响应

成功：

{
    "code": 0,
    "data": [
        "What makes Neovim superior to Vim in terms of features?",
        "How do the benefits of Neovim compare to those of Vim?",
        "What advantages does Neovim offer that are not present in Vim?",
        "In what ways does Neovim outperform Vim in functionality?",
        "What are the most significant improvements in Neovim compared to Vim?",
        "What unique advantages does Neovim bring to the table over Vim?",
        "How does the user experience in Neovim differ from Vim in terms of benefits?",
        "What are the top reasons to switch from Vim to Neovim?",
        "What features of Neovim are considered more advanced than those in Vim?"
    ],
    "message": "success"
}

失败：

{
    "code": 401,
    "data": null,
    "message": "<Unauthorized '401: Unauthorized'>"
}

---

代理管理

---

列出代理

GET /api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={agent_name}&id={agent_id}

列出代理。

请求

• 方法：GET
• URL：/api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={agent_name}&id={agent_id}
• 头部：
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

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

请求参数

• page：(过滤参数)，integer
  • 指定显示代理的页面。默认为1。
• page_size：(过滤参数)，integer
  • 每页显示的代理数量。默认为30。
• orderby：(过滤参数)，string
  • 结果按此属性排序。可用选项：
    • create_time（默认）
    • update_time
• desc：(过滤参数)，boolean
  • 是否降序排列。默认为true。
• name：(过滤参数)，string
  • 指定代理的名称。
• id：(过滤参数)，string
  • 指定代理的ID。

响应

成功：

{
    "code": 0,
    "data": [
        {
            "avatar": null,
            "canvas_type": null,
            "create_date": "Thu, 05 Dec 2024 19:10:36 GMT",
            "create_time": 1733397036424,
            "description": null,
            "dsl": {
                "answer": [],
                "components": {
                    "begin": {
                        "downstream": [],
                        "obj": {
                            "component_name": "Begin",
                            "params": {}
                        },
                        "upstream": []
                    }
                },
                "graph": {
                    "edges": [],
                    "nodes": [
                        {
                            "data": {
                                "label": "Begin",
                                "name": "begin"
                            },
                            "height": 44,
                            "id": "begin",
                            "position": {
                                "x": 50,
                                "y": 200
                            },
                            "sourcePosition": "left",
                            "targetPosition": "right",
                            "type": "beginNode",
                            "width": 200
                        }
                    ]
                },
                "history": [],
                "messages": [],
                "path": [],
                "reference": []
            },
            "id": "8d9ca0e2b2f911ef9ca20242ac120006",
            "title": "123465",
            "update_date": "Thu, 05 Dec 2024 19:10:56 GMT",
            "update_time": 1733397056801,
            "user_id": "69736c5e723611efb51b0242ac120007"
        }
    ]
}

失败：

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

---

创建代理

POST /api/v1/agents

创建一个代理。

请求

• 方法: POST
• URL: /api/v1/agents
• 头信息:
  • 'Content-Type: application/json
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • "title": string
  • "description": string
  • "dsl": object

请求示例

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": {
           // ... Canvas DSL here ...
         }
     }'

请求参数

• title: (Body parameter), string, 必填项
  The title of the agent.
• description: (Body parameter), string
  The description of the agent. Defaults to None.
• dsl: (Body parameter), object, 必填项
  The canvas DSL object of the agent.

响应

成功：

{
    "code": 0,
    "data": true,
    "message": "success"
}

失败：

{
    "code": 102,
    "message": "Agent with title test already exists."
}

---

更新代理

PUT /api/v1/agents/{agent_id}

通过id更新一个代理。

请求

• 方法: PUT
• URL: /api/v1/agents/{agent_id}
• 头信息:
  • 'Content-Type: application/json
  • 'Authorization: Bearer <YOUR_API_KEY>'
• 正文:
  • "title": string
  • "description": string
  • "dsl": object

请求示例

curl --request PUT \
     --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
         "title": "Test Agent",
         "description": "A test agent",
         "dsl": {
           // ... Canvas DSL here ...
         }
     }'

请求参数

• agent_id: (Path parameter), string
  The id of the agent to be updated.
• title: (Body parameter), string
  The title of the agent.
• description: (Body parameter), string
  The description of the agent.
• dsl: (Body parameter), object
  The canvas DSL object of the agent.

仅在请求正文指定要更改的参数。如果某个参数不存在或为 None，则不会更新。

响应

成功：

{
    "code": 0,
    "data": true,
    "message": "success"
}

失败：

{
    "code": 103,
    "message": "Only owner of canvas authorized for this operation."
}

---

删除代理

DELETE /api/v1/agents/{agent_id}

通过id删除一个代理。

请求

• 方法: DELETE
• URL: /api/v1/agents/{agent_id}
• 头信息:
  • 'Content-Type: application/json
  • 'Authorization: Bearer <YOUR_API_KEY>'

请求示例

curl --request DELETE \
     --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{}'

请求参数

• agent_id: (路径参数), string
  要删除的代理的ID。

响应

成功:

{
    "code": 0,
    "data": true,
    "message": "success"
}

失败:

{
    "code": 103,
    "message": "Only owner of canvas authorized for this operation."
}