Skip to main content
Version: DEV

HTTP API

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

数据集管理​

创建数据集​

POST /api/v1/datasets

创建一个数据集。

请求​

  • 方法: POST
  • URL: /api/v1/datasets
  • Headers:
    • '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": object
请求示例​
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, Required
    要创建的数据集的唯一名称。它必须符合以下要求：

    • Permitted characters include:
      • English letters (a-z, A-Z)
      • Digits (0-9)
      • "_" (underscore)
    • Must begin with an English letter or underscore.
    • Maximum 65,535 characters.
    • Case-insensitive.

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

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

  • "language": (Body parameter), string
    创建数据集的语言设置。可用选项：

    • "English" (default)
    • "Chinese"

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

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

    • "me": (Default) Only you can manage the dataset.
    • "team": All team members can manage the dataset.

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

    • "naive": General (default)
    • "manual": Manual
    • "qa": Q&A
    • "table": Table
    • "paper": Paper
    • "book": Book
    • "laws": Laws
    • "presentation": Presentation
    • "picture": Picture
    • "one": One
    • "knowledge_graph": Knowledge Graph
      Ensure your LLM is properly configured on the Settings page before selecting this. Please also note that Knowledge Graph consumes a large number of Tokens!
    • "email": Email

  • "parser_config": (Body parameter), object
    数据集解析器的配置设置。此JSON对象中的属性随所选的"chunk_method"而变化：

    • If "chunk_method" is "naive", the "parser_config" object contains the following attributes:
      • "chunk_token_count": Defaults to 128.
      • "layout_recognize": Defaults to true.
      • "html4excel": Indicates whether to convert Excel documents into HTML format. Defaults to false.
      • "delimiter": Defaults to "\n!?。；！？".
      • "task_page_size": Defaults to 12. For PDF only.
      • "raptor": Raptor-specific settings. Defaults to: {"use_raptor": false}.
    • If "chunk_method" is "qa", "manuel", "paper", "book", "laws", or "presentation", the "parser_config" object contains the following attribute:
      • "raptor": Raptor-specific settings. Defaults to: {"use_raptor": false}.
    • If "chunk_method" is "table", "picture", "one", or "email", "parser_config" is an empty JSON object.
    • If "chunk_method" is "knowledge_graph", the "parser_config" object contains the following attributes:
      • "chunk_token_count": Defaults to 128.
      • "delimiter": Defaults to "\n!?。；！？".
      • "entity_types": Defaults to ["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."
}

删除数据集​

删除 /api/v1/datasets

通过ID删除数据集。

请求​

  • 方法: DELETE
  • URL: /api/v1/datasets
  • 头部信息:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
    • 主体内容:
      • "ids": list[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": (Body parameter), 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}
  • Headers:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 正文:
    • "name": string
    • "embedding_model": string
    • "chunk_method": enum<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": (Body parameter), string
    数据集修订后的名称。
  • "embedding_model": (Body parameter), string
    更新后的嵌入模型名称。
    • 在更新"embedding_model"之前，请确保"chunk_count"为0。
  • "chunk_method": (Body parameter), enum<string>
    数据集的切分方法。可用选项：
    • "naive": 通用
    • "manual: 手动
    • "qa": 问答
    • "table": 表格
    • "paper": 论文
    • "book": 书籍
    • "laws": 法律
    • "presentation": 演示文稿
    • "picture": 图片
    • "one": 单一
    • "email": 电子邮件
    • "knowledge_graph": 知识图谱
      在选择此选项之前，请确保您的LLM在设置页面中已正确配置。请注意，知识图谱会消耗大量的Token！

响应​

成功：

{
    "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': (Body parameter)
    要上传的文档。

响应​

成功：

{
    "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}/documents/{document_id}

更新指定文档的配置。

请求​

  • 方法: PUT
  • URL: /api/v1/datasets/{dataset_id}/documents/{document_id}
  • Headers:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 正文:
    • "name":string
    • "chunk_method":string
    • "parser_config":object
请求示例​
curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/info/{document_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
     {
          "name": "manual.txt", 
          "chunk_method": "manual", 
          "parser_config": {"chunk_token_count": 128}
     }'

请求参数​
  • dataset_id: (路径参数)
    关联数据集的ID。
  • document_id: (路径参数)
    要更新的文档的ID。
  • "name": (主体参数), string
  • "chunk_method": (Body parameter), string
    应用于文档的解析方法：
    • "naive": 通用
    • "manual: 手动
    • "qa": 问答
    • "table": 表格
    • "paper": 论文
    • "book": 书籍
    • "laws": 法律
    • "presentation": 演示文稿
    • "picture": 图片
    • "one": 单一
    • "knowledge_graph": 知识图谱
      在选择此选项之前，请确保您的LLM在设置页面中已正确配置。请注意，知识图谱会消耗大量的Token！
    • "email": 电子邮件
  • "parser_config": (Body parameter), 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
}

失败：

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

下载文档​

获取 /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 ./ragflow.txt
请求参数​
  • 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}

列出指定数据集中的文档。

请求​

  • 方法: 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}
  • Headers:
    • '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} \
     --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。

响应​

成功：

{
    "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_duation": 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. "
}

删除文档​

删除 /api/v1/datasets/{dataset_id}/documents

按ID删除文档。

请求​

  • 方法: DELETE
  • URL: /api/v1/datasets/{dataset_id}/documents
  • Headers:
    • 'Content-Type: application/json'
    • 'Authorization: Bearer '
  • 正文:
    • "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": (Body parameter), list[string]
    要删除的文档的ID。如果未指定，将删除指定数据集中的所有文档。

响应​

成功：

{
    "code": 0
}.

失败：

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

解析文档​

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

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

请求​

  • 方法: POST
  • URL: /api/v1/datasets/{dataset_id}/chunks
  • Headers:
    • '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": (Body parameter), list[string], Required
    要解析的文档的ID。

响应​

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "`document_ids` is required"
}

停止解析文档​

删除 /api/v1/datasets/{dataset_id}/chunks

停止解析指定的文档。

请求​

  • 方法: DELETE
  • URL: /api/v1/datasets/{dataset_id}/chunks
  • Headers:
    • '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": (Body parameter), list[string], Required
    应停止解析的文档的ID。

响应​

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "`document_ids` is required"
}

数据集中的块管理​

添加块​

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

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

请求​

  • 方法: POST
  • URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
  • Headers:
    • '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": (Body parameter), string, Required
    文本块的内容。
  • "important_keywords(Body parameter), list[string]
    用于标记块的关键词或短语。
  • "questions"(Body parameter), list[string] 如果有给定的问题，嵌入的块将基于它们

响应​

成功：

{
    "code": 0,
    "data": {
        "chunk": {
            "content": "who are you",
            "create_time": "2024-12-30 16:59:55",
            "create_timestamp": 1735549195.969164,
            "dataset_id": "72f36e1ebdf411efb7250242ac120006",
            "document_id": "61d68474be0111ef98dd0242ac120006",
            "id": "12ccdc56e59837e5",
            "important_keywords": [],
            "questions": []
        }
    }
}

失败：

{
    "code": 102,
    "message": "`content` is required"
}

列出块​

获取 /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={id}

列出指定文档中的块。

请求​

  • 方法: GET
  • URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={chunk_id}
  • 头部信息:
    • 'Authorization: Bearer <YOUR_API_KEY>'
请求示例​
curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={chunk_id} \
     --header 'Authorization: Bearer <YOUR_API_KEY>'
请求参数​
  • dataset_id: (路径参数)
    关联的数据集ID。
  • document_ids: (路径参数)
    关联的文档ID。
  • keywords(过滤参数), string
    用于匹配块内容的关键字。
  • page(过滤参数), integer
    指定显示块的页面。默认为 1。
  • page_size(过滤参数), integer
    每页的最大块数。默认为 1024。
  • id(过滤参数), string
    要检索的块的ID。

响应​

成功：

{
    "code": 0,
    "data": {
        "chunks": [
            {
                "available_int": 1,
                "content": "This is a test 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": {
                    "user_raptor": false
                }
            },
            "process_begin_at": "Thu, 24 Oct 2024 09:56:44 GMT",
            "process_duation": 0.54213,
            "progress": 0.0,
            "progress_msg": "Task dispatched...",
            "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": "You don't own the document 5c5999ec7be811ef9cab0242ac12000e5."
}

删除块​

删除 /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

按ID删除块。

请求​

  • 方法: DELETE
  • URL: /api/v1/datasets/{dataset_id}/documents/{document_id}/chunks
  • Headers:
    • '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": (Body parameter), list[string]
    要删除的块的ID。如果未指定，将删除指定文档的所有块。

响应​

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "`chunk_ids` is required"
}

更新数据块​

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}
  • Headers:
    • '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": (Body parameter), string
    文本块的内容。
  • "important_keywords": (Body parameter), list[string]
    一个关键术语或短语的列表，用于标记该块。
  • "available": (Body parameter) boolean
    数据集中块的可用状态。值选项：
    • true: 可用（默认）
    • false: 不可用

响应​

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "Can't find this chunk 29a2d9987e16ba331fb4d7d30d99b71d2"
}

检索块​

POST /api/v1/retrieval

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

请求​

  • 方法: POST
  • URL: /api/v1/retrieval
  • Headers:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 正文:
    • "question": string
    • "dataset_ids": list[string]
    • "document_ids": list[string]
    • "page": integer
    • "page_size": integer
    • "similarity_threshold": float
    • "vector_similarity_weight": float
    • "top_k": integer
    • "rerank_id": string
    • "keyword": boolean
    • "highlight": boolean
请求示例​
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"]
     }'
请求参数​
  • "question": (Body parameter), string, Required
    用户查询或查询关键词。
  • "dataset_ids": (Body parameter) list[string]
    要搜索的数据集的ID。如果未设置此参数，请确保设置了"document_ids"。
  • "document_ids": (Body parameter), list[string]
    要搜索的文档的ID。确保所有选定的文档使用相同的嵌入模型。否则，将会发生错误。如果不设置此参数，请确保设置了"dataset_ids"。
  • "page": (Body parameter), integer
    指定显示块的页面。默认为 1。
  • "page_size": (Body parameter)
    每页的最大块数。默认为 30。
  • "similarity_threshold": (Body parameter)
    最小相似度分数。默认为 0.2。
  • "vector_similarity_weight": (Body parameter), float
    向量余弦相似度的权重。默认为 0.3。如果 x 表示向量余弦相似度的权重，则 (1 - x) 是术语相似度的权重。
  • "top_k": (Body parameter), integer
    参与向量余弦计算的块数。默认为 1024。
  • "rerank_id": (Body parameter), integer
    重新排序模型的ID。
  • "keyword": (Body parameter), boolean
    指示是否启用基于关键字的匹配：
    • true: 启用基于关键字的匹配。
    • false: 禁用基于关键字的匹配（默认）。
  • "highlight": (Body parameter), boolean
    指定是否在结果中启用匹配项的高亮显示：
    • true: 启用匹配项的高亮显示。
    • false: 禁用匹配项的高亮显示（默认）。

响应​

成功：

{
    "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` is required."
}

聊天助手管理​

创建聊天助手​

POST /api/v1/chats

创建一个聊天助手。

请求​

  • 方法: POST
  • URL: /api/v1/chats
  • Headers:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 正文:
    • "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, Required
    聊天助手的名称。
  • "avatar": (Body parameter), string
    头像的Base64编码。
  • "dataset_ids": (Body parameter), list[string]
    关联数据集的ID。
  • "llm": (Body parameter), object
    创建聊天助手的LLM设置。如果未明确设置，将生成一个包含以下值的JSON对象作为默认值。一个llm JSON对象包含以下属性：
    • "model_name", string
      聊天模型名称。如果未设置，将使用用户的默认聊天模型。
    • "temperature": float
      控制模型预测的随机性。较低的温度会导致更保守的响应，而较高的温度会产生更具创造性和多样性的响应。默认为0.1。
    • "top_p": float
      也称为“核采样”，此参数设置一个阈值以选择较小的单词集进行采样。它专注于最可能的单词，剔除不太可能的单词。默认为0.3。
    • "presence_penalty": float
      通过惩罚已经在对话中出现的单词，阻止模型重复相同的信息。默认为0.2。
    • "frequency penalty": float
      与存在惩罚类似，这减少了模型频繁重复相同单词的倾向。默认为0.7。
    • "max_token": integer
      模型输出的最大长度，以令牌（单词或单词片段）的数量衡量。默认为512。如果禁用，您将取消最大令牌限制，允许模型确定其响应中的令牌数量。
  • "prompt": (Body parameter), object
    LLM遵循的指令。如果未明确设置，将生成一个包含以下值的JSON对象作为默认值。一个prompt JSON对象包含以下属性：
    • "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" 是一个保留变量，表示检索到的块。
      • “系统”中的所有变量都应使用大括号括起来。
      • 默认值为[{"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,
            "max_tokens": 512,
            "model_name": "qwen-plus@Tongyi-Qianwen",
            "presence_penalty": 0.4,
            "temperature": 0.1,
            "top_p": 0.3
        },
        "name": "12234",
        "prompt": {
            "empty_response": "Sorry! No relevant content was found in the knowledge base!",
            "keywords_similarity_weight": 0.3,
            "opener": "Hi! I'm your assistant, what can I do for you?",
            "prompt": "You are an intelligent assistant. Please summarize the content of the knowledge base to answer the question. Please list the data in the knowledge base and answer in detail. When all knowledge base content is irrelevant to the question, your answer must include the sentence \"The answer you are looking for is not found in the knowledge base!\" Answers need to consider chat history.\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": "Duplicated chat name in creating dataset."
}

更新聊天助手​

PUT /api/v1/chats/{chat_id}

更新指定聊天助手的配置。

请求​

  • 方法: PUT
  • URL: /api/v1/chats/{chat_id}
  • Headers:
    • '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: (路径参数)
    要更新的聊天助手的ID。
  • "name": (Body parameter), string, Required
    聊天助手的修订名称。
  • "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。
    • "max_token": integer
      模型输出的最大长度，以令牌（单词或单词片段）的数量衡量。默认为512。如果禁用，您将取消最大令牌限制，允许模型确定其响应中的令牌数量。
  • "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[] 此参数列出了在 Chat Configurations 的 'System' 字段中使用的变量。请注意：
      • "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": "Duplicated chat name in updating dataset."
}

删除聊天助手​

删除 /api/v1/chats

通过ID删除聊天助手。

请求​

  • 方法: DELETE
  • URL: /api/v1/chats
  • Headers:
    • '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={dataset_name}&id={dataset_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={dataset_name}&id={dataset_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,
                "max_tokens": 512,
                "model_name": "qwen-plus@Tongyi-Qianwen",
                "presence_penalty": 0.4,
                "temperature": 0.1,
                "top_p": 0.3
            },
            "name": "13243",
            "prompt": {
                "empty_response": "Sorry! No relevant content was found in the knowledge base!",
                "keywords_similarity_weight": 0.3,
                "opener": "Hi! I'm your assistant, what can I do for you?",
                "prompt": "You are an intelligent assistant. Please summarize the content of the knowledge base to answer the question. Please list the data in the knowledge base and answer in detail. When all knowledge base content is irrelevant to the question, your answer must include the sentence \"The answer you are looking for is not found in the knowledge base!\" Answers need to consider chat history.\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": "The chat doesn't exist"
}

会话管理​

创建与聊天助手的会话​

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

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

请求​

  • 方法: POST
  • URL: /api/v1/chats/{chat_id}/sessions
  • Headers:
    • '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": (Body parameter), string
    要创建的聊天会话的名称。
  • "user_id": (Body parameter), 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": "Hi! I am your assistant，can I help you?",
                "role": "assistant"
            }
        ],
        "name": "new session",
        "update_date": "Fri, 11 Oct 2024 08:46:14 GMT",
        "update_time": 1728636374571
    }
}

失败：

{
    "code": 102,
    "message": "Name cannot be empty."
}

更新聊天助手的会话​

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

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

请求​

  • 方法: PUT
  • URL: /api/v1/chats/{chat_id}/sessions/{session_id}
  • Headers:
    • '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": (Body Parameter), string
    会话的修订名称。
  • "user_id": (Body parameter), string
    可选的用户定义ID。

响应​

成功：

{
    "code": 0
}

失败：

{
    "code": 102,
    "message": "Name cannot be empty."
}

列出聊天助手的会话​

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}&user_id={user_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": "Hi! I am your assistant，can I help you?",
                    "role": "assistant"
                }
            ],
            "name": "new session",
            "update_date": "Fri, 11 Oct 2024 08:46:43 GMT",
            "update_time": 1728636403974
        }
    ]
}

失败：

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

删除聊天助手的会话​

删除 /api/v1/chats/{chat_id}/sessions

通过ID删除聊天助手的会话。

请求​

  • 方法: DELETE
  • URL: /api/v1/chats/{chat_id}/sessions
  • Headers:
    • '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": (Body Parameter), list[string]
    要删除的会话的ID。如果未指定，将删除与指定聊天助手关联的所有会话。

响应​

成功：

{
    "code": 0
}

失败：

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

与聊天助手对话​

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

向指定的聊天助手提问以启动AI驱动的对话。

NOTE
  • 在流模式下，并非所有响应都包含参考，因为这取决于系统的判断。
  • 在流模式下，最后一条消息是空消息： 
    data:
    {
      "code": 0,
      "data": true
    }

请求​

  • 方法: POST
  • URL: /api/v1/chats/{chat_id}/completions
  • Headers:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 正文:
    • "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": (Body Parameter), string, Required
    用于启动AI驱动的对话的问题。
  • "stream": (Body Parameter), boolean
    指示是否以流式方式输出响应：
    • true: 启用流式（默认）。
    • false: 禁用流式。
  • "session_id": (Body Parameter)
    会话的ID。如果未提供，将生成一个新的会话。
  • "user_id": (Body parameter), 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": "",
                    "similarity": 0.7,
                    "vector_similarity": 0.0,
                    "term_similarity": 1.0,
                    "positions": [
                        ""
                    ]
                }
            ],
            "doc_aggs": [
                {
                    "doc_name": "1.txt",
                    "doc_id": "dd58f58e888511ef89c90242ac120006",
                    "count": 1
                }
            ]
        },
        "prompt": "xxxxxxxxxxx",
        "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d",
        "session_id": "82b0ab2a9c1911ef9d870242ac120006"
    }
}
data:{
    "code": 0,
    "data": true
}

失败：

{
    "code": 102,
    "message": "Please input your question."
}

创建与代理的会话​

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

创建一个与代理的会话。

请求​

  • 方法: POST
  • URL: /api/v1/agents/{agent_id}/sessions
  • Headers:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 正文:
    • 必需的参数:str
    • 可选的参数:str
      • "user_id": string
        可选的用户定义ID。
请求示例​

如果代理中的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 '{
     }'

如果代理中的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 '{
            "lang":"Japanese",
            "file":"Who are you"
     }'
请求参数​
  • agent_id: (路径参数)
    关联代理的ID。

响应​

成功：

{
    "code": 0,
    "data": {
        "agent_id": "b4a39922b76611efaa1a0242ac120006",
        "dsl": {
            "answer": [],
            "components": {
                "Answer:GreenReadersDrum": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Answer",
                        "inputs": [],
                        "output": null,
                        "params": {}
                    },
                    "upstream": []
                },
                "begin": {
                    "downstream": [],
                    "obj": {
                        "component_name": "Begin",
                        "inputs": [],
                        "output": {},
                        "params": {}
                    },
                    "upstream": []
                }
            },
            "embed_id": "",
            "graph": {
                "edges": [],
                "nodes": [
                    {
                        "data": {
                            "label": "Begin",
                            "name": "begin"
                        },
                        "dragging": false,
                        "height": 44,
                        "id": "begin",
                        "position": {
                            "x": 53.25688640427177,
                            "y": 198.37155679786412
                        },
                        "positionAbsolute": {
                            "x": 53.25688640427177,
                            "y": 198.37155679786412
                        },
                        "selected": false,
                        "sourcePosition": "left",
                        "targetPosition": "right",
                        "type": "beginNode",
                        "width": 200
                    },
                    {
                        "data": {
                            "form": {},
                            "label": "Answer",
                            "name": "dialog_0"
                        },
                        "dragging": false,
                        "height": 44,
                        "id": "Answer:GreenReadersDrum",
                        "position": {
                            "x": 360.43473114516974,
                            "y": 207.29298425089348
                        },
                        "positionAbsolute": {
                            "x": 360.43473114516974,
                            "y": 207.29298425089348
                        },
                        "selected": false,
                        "sourcePosition": "right",
                        "targetPosition": "left",
                        "type": "logicNode",
                        "width": 200
                    }
                ]
            },
            "history": [],
            "messages": [],
            "path": [
                [
                    "begin"
                ],
                []
            ],
            "reference": []
        },
        "id": "2581031eb7a311efb5200242ac120005",
        "message": [
            {
                "content": "Hi! I'm your smart assistant. What can I do for you?",
                "role": "assistant"
            }
        ],
        "source": "agent",
        "user_id": "69736c5e723611efb51b0242ac120007"
    }
}

失败：

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

与代理对话​

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

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

NOTE
  • 在流模式下，并非所有响应都包含参考，因为这取决于系统的判断。
  • 在流模式下，最后一条消息是空消息： 
    data:
    {
      "code": 0,
      "data": true
    }

请求​

  • 方法: POST
  • URL: /api/v1/agents/{agent_id}/completions
  • Headers:
    • 'content-Type: application/json'
    • 'Authorization: Bearer <YOUR_API_KEY>'
  • 正文:
    • "question": string
    • "stream": boolean
    • "session_id": string
    • "user_id": string(可选)
    • 其他参数: 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 '
     {
     }'

如果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 '
     {
          "lang":"English",
          "file":"How is the weather tomorrow?"
     }'

以下代码将执行完成过程

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": (Body Parameter), string, Required
    用于启动AI驱动的对话的问题。
  • "stream": (Body Parameter), boolean
    指示是否以流式方式输出响应：
    • true: 启用流式（默认）。
    • false: 禁用流式。
  • "session_id": (Body Parameter)
    会话的ID。如果未提供，将生成一个新的会话。
  • "user_id": (Body parameter), string
    可选的用户定义ID。仅在未提供session_id时有效。
  • 其他参数: (Body Parameter)
    开始组件中的参数。

响应​

成功，没有提供session_id，并且在begin组件中没有参数：

data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "Hi! I'm your smart assistant. What can I do for you?",
        "reference": {},
        "id": "31e6091d-88d4-441b-ac65-eae1c055be7b",
        "session_id": "2987ad3eb85f11efb2a70242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": true
}

成功，未提供session_id，并且在begin组件中包含参数：

data:{
    "code": 0,
    "message": "",
    "data": {
        "session_id": "eacb36a0bdff11ef97120242ac120006",
        "answer": "",
        "reference": [],
        "param": [
            {
                "key": "lang",
                "name": "Target Language",
                "optional": false,
                "type": "line",
                "value": "English"
            },
            {
                "key": "file",
                "name": "Files",
                "optional": false,
                "type": "file",
                "value": "How is the weather tomorrow?"
            },
            {
                "key": "hhyt",
                "name": "hhty",
                "optional": true,
                "type": "line"
            }
        ]
    }
}
data:

在begin组件中使用参数成功：

data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather tomorrow",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather tomorrow?",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": {
        "answer": "How is the weather tomorrow?",
        "reference": {},
        "id": "0379ac4c-b26b-4a44-8b77-99cebf313fdf",
        "session_id": "4399c7d0b86311efac5b0242ac120005"
    }
}
data:{
    "code": 0,
    "message": "",
    "data": true
}

失败：

{
    "code": 102,
    "message": "`question` is required."
}

列出代理会话​

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

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

请求​

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

响应​

成功：

{
    "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",
                            "max_tokens": 256,
                            "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,
                                "max_tokens": 256,
                                "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
                    }
                ]
            },
            "history": [],
            "messages": [],
            "path": [],
            "reference": []
        },
        "id": "792dde22b2fa11ef97550242ac120006",
        "message": [
            {
                "content": "Hi! I'm your smart assistant. What can I do for you?",
                "role": "assistant"
            }
        ],
        "source": "agent",
        "user_id": ""
    }
}

失败：

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

代理管理​

列出代理​

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。
  • id: (过滤参数), string
    要检索的代理的ID。
  • name: (过滤参数), string
    要检索的代理的名称。

响应​

成功：

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