RAGFlow API 文档

RAGFlow API 文档

目录

1. API 服务器

2. HTTP API

3. OpenAI 兼容 API

   • 创建聊天补全

4. 数据集管理

   • 创建数据集

   • 删除数据集

   • 更新数据集

   • 列出数据集

5. 数据集内的文件管理

   • 上传文档

   • 更新文档

   • 下载文档

   • 列出文档

   • 删除文档

   • 解析文档

   • 停止解析文档

6. 数据集内的块管理

   • 添加块

   • 列出块

   • 删除块

   • 更新块

   • 检索块

7. 聊天助手管理

   • 创建聊天助手

   • 创建聊天助手

   • 更新聊天助手

   • 删除聊天助手

   • 列出聊天助手

8. 会话管理

   • 与聊天助手创建会话

   • 更新聊天助手的会话

   • 列出聊天助手的会话

   • 删除聊天助手的会话

   • 与聊天助手对话

9. 代理管理

   • 与代理创建会话

   • 与代理对话

   • 列出代理会话

10. 列出代理

API 服务器

http://1.1.1.0:80

HTTP API

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

OpenAI 兼容 API

创建聊天补全

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

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

请求

• 方法：POST

• URL：/api/v1/chats_openai/{chat_id}/chat/completions

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

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

请求示例

curl --request POST \
     --url http://{address}/api/v1/chats_openai/{chat_id}/chat/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer ' \
     --data '{
        "model": "model",
        "messages": [{"role": "user", "content": "Say this is a test!"}],
        "stream": true
      }'

请求参数

• model (请求体参数)：string，必需。用于生成响应的模型。服务器会自动解析此参数，因此目前您可以将其设置为任意值。

• messages (请求体参数)：list[object]，必需。用于生成响应的历史聊天消息列表。此列表中必须至少包含一个用户角色的消息。

• stream (请求体参数)：boolean。是否以流的形式接收响应。如果您希望一次性接收完整响应而不是流式响应，请明确将其设置为 false。

响应

• 流式响应示例：

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

  // 省略重复信息

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

  // 最后一个块

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

• 非流式响应示例：

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

• 失败响应示例：

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

数据集管理

创建数据集

POST /api/v1/datasets

请求

• 方法：POST

• URL：/api/v1/datasets

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "name": "string",
    "avatar": "string",
    "description": "string",
    "language": "string",
    "embedding_model": "string",
    "permission": "string",
    "chunk_method": "string",
    "parser_config": {}
  }
  

请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer ' \
     --data '{
      "name": "test_1"
      }'

请求参数

• name (请求体参数)：string，必需。要创建的数据集的唯一名称。它必须符合以下要求：
  • 允许的字符包括：

    • 英文字母（a-z，A-Z）

    • 数字（0-9）

    • "_"（下划线）

  • 必须以英文字母或下划线开头。

  • 最多 65,535 个字符。

  • 不区分大小写。

• avatar (请求体参数)：string。头像的 base64 编码。

• description (请求体参数)：string。要创建的数据集的简要描述。

• language (请求体参数)：string。要创建的数据集的语言设置。可选值：

  • "English"（默认）

  • "Chinese"

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

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

  • "me"：（默认）只有您可以管理数据集。

  • "team"：所有团队成员都可以管理数据集。

• chunk_method (请求体参数)：enum。要创建的数据集的分块方法。可选值：

  • "naive"：通用（默认）

  • "manual"：手动

  • "qa"：问答

  • "table"：表格

  • "paper"：论文

  • "book"：书籍

  • "laws"：法律

  • "presentation"：演示文稿

  • "picture"：图片

  • "one"：单个

  • "knowledge_graph"：知识图谱

    • 在选择此选项之前，请确保您的 LLM 已在设置页面上正确配置。请注意，知识图谱会消耗大量 Tokens！

  • "email"：电子邮件

• parser_config (请求体参数)：object。数据集解析器的配置设置。此 JSON 对象中的属性会根据所选的 chunk_method 而变化：
  • 如果 chunk_method 是 "naive"，则 parser_config 对象包含以下属性：

    • "chunk_token_count"：默认为 128。

    • "layout_recognize"：默认为 true。

    • "html4excel"：是否将 Excel 文档转换为 HTML 格式。默认为 false。

    • "delimiter"：默认为 "\n!?。；！？"。

    • "task_page_size"：默认为 12。仅适用于 PDF。

    • "raptor"：Raptor 特定设置。默认为：{"use_raptor": false}。

  • 如果 chunk_method 是 "qa"、"manuel"、"paper"、"book"、"laws" 或 "presentation"，则 parser_config 对象包含以下属性：

    • "raptor"：Raptor 特定设置。默认为：{"use_raptor": false}。

  • 如果 chunk_method 是 "table"、"picture"、"one" 或 "email"，则 parser_config 是一个空的 JSON 对象。

  • 如果 chunk_method 是 "knowledge_graph"，则 parser_config 对象包含以下属性：

    • "chunk_token_count"：默认为 128。

    • "delimiter"：默认为 "\n!?。；！？"。

    • "entity_types"：默认为 ["organization","person","location","event","time"]。

响应

• 成功响应示例：

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

• 失败响应示例：

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

删除数据集

DELETE /api/v1/datasets

请求

• 方法：DELETE

• URL：/api/v1/datasets

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "ids": ["string"]
  }
  

请求示例

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

请求参数

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

响应

• 成功响应示例：

  {
      "code": 0 
  }
  

• 失败响应示例：

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

更新数据集

PUT /api/v1/datasets/{dataset_id}

请求

• 方法：PUT

• URL：/api/v1/datasets/{dataset_id}

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

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

请求示例

curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer ' \
     --data '
     {
          "name": "updated_dataset"
     }'

请求参数

• dataset_id (路径参数)：要更新的数据集的 ID。

• name (请求体参数)：string。数据集的新名称。

• embedding_model (请求体参数)：string。更新后的嵌入模型名称。在更新 embedding_model 之前，请确保 chunk_count 为 0。

• chunk_method (请求体参数)：enum。数据集的分块方法。可选值：

  • "naive"：通用

  • "manual"：手动

  • "qa"：问答

  • "table"：表格

  • "paper"：论文

  • "book"：书籍

  • "laws"：法律

  • "presentation"：演示文稿

  • "picture"：图片

  • "one"：单个

  • "knowledge_graph"：知识图谱

    • 在选择此选项之前，请确保您的 LLM 已在设置页面上正确配置。请注意，知识图谱会消耗大量 Tokens！

  • "email"：电子邮件

响应

• 成功响应示例：

  {
      "code": 0 
  }
  

• 失败响应示例：

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

列出数据集

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

请求

• 方法：GET

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

• 请求头：

  'Authorization: Bearer '
  

请求示例

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 '

请求参数

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

• 表单数据：

  'file=@{FILE_PATH}'
  

请求示例

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

请求参数

• dataset_id (路径参数)：要上传文档的数据集的 ID。

• file (请求体参数)：要上传的文档。

响应

• 成功响应示例：

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

• 失败响应示例：

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

更新文档

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

请求

• 方法：PUT

• URL：/api/v1/datasets/{dataset_id}/documents/{document_id}

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

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

请求示例

curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id}/info/{document_id} \
     --header 'Authorization: Bearer ' \
     --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 (请求体参数)：string。要应用于文档的解析方法：

  • "naive"：通用

  • "manual"：手动

  • "qa"：问答

  • "table"：表格

  • "paper"：论文

  • "book"：书籍

  • "laws"：法律

  • "presentation"：演示文稿

  • "picture"：图片

  • "one"：单个

  • "knowledge_graph"：知识图谱

    • 在选择此选项之前，请确保您的 LLM 已在设置页面上正确配置。请注意，知识图谱会消耗大量 Tokens！

  • "email"：电子邮件

• parser_config (请求体参数)：object。数据集解析器的配置设置。此 JSON 对象中的属性会根据所选的 chunk_method 而变化：
  • 如果 chunk_method 是 "naive"，则 parser_config 对象包含以下属性：

    • "chunk_token_count"：默认为 128。

    • "layout_recognize"：默认为 true。

    • "html4excel"：是否将 Excel 文档转换为 HTML 格式。默认为 false。

    • "delimiter"：默认为 "\n!?。；！？"。

    • "task_page_size"：默认为 12。仅适用于 PDF。

    • "raptor"：Raptor 特定设置。默认为：{"use_raptor": false}。

  • 如果 chunk_method 是 "qa"、"manuel"、"paper"、"book"、"laws" 或 "presentation"，则 parser_config 对象包含以下属性：

    • "raptor"：Raptor 特定设置。默认为：{"use_raptor": false}。

  • 如果 chunk_method 是 "table"、"picture"、"one" 或 "email"，则 parser_config 是一个空的 JSON 对象。

  • 如果 chunk_method 是 "knowledge_graph"，则 parser_config 对象包含以下属性：

    • "chunk_token_count"：默认为 128。

    • "delimiter"：默认为 "\n!?。；！？"。

    • "entity_types"：默认为 ["organization","person","location","event","time"]。

响应

• 成功响应示例：

  {
      "code": 0
  }
  

• 失败响应示例：

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

输出

'{PATH_TO_THE_FILE}'

请求示例

curl --request GET \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \
     --header 'Authorization: Bearer ' \
     --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}

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

请求示例

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 '

请求参数

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

删除文档

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

请求

• 方法：DELETE

• URL：/api/v1/datasets/{dataset_id}/documents

• 请求头：

  'Content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "ids": ["string"]
  }
  

请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer ' \
     --data '
     {
          "ids": ["id_1","id_2"]
     }'

请求参数

• dataset_id (路径参数)：相关数据集的 ID。

• ids (请求体参数)：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

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "document_ids": ["string"]
  }
  

请求示例

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

请求参数

• dataset_id (路径参数)：数据集 ID。

• document_ids (请求体参数)：list[string]，必需。要解析的文档的 ID 列表。

响应

• 成功响应示例：

  {
      "code": 0
  }
  

• 失败响应示例：

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

停止解析文档

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

请求

• 方法：DELETE

• URL：/api/v1/datasets/{dataset_id}/chunks

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "document_ids": ["string"]
  }
  

请求示例

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

请求参数

• dataset_id (路径参数)：相关数据集的 ID。

• document_ids (请求体参数)：list[string]，必需。要停止解析的文档的 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

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "content": "string",
    "important_keywords": ["string"]
  }
  

请求示例

curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer ' \
     --data '
     {
          "content": ""
     }'

请求参数

• dataset_id (路径参数)：相关数据集的 ID。

• document_ids (路径参数)：相关文档的 ID。

• content (请求体参数)：string，必需。块的文本内容。

• important_keywords (请求体参数)：list[string]。要标记在块上的关键术语或短语。

• questions (请求体参数)：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"
  }
  

列出块

GET /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 '
  

请求示例

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 ' 

请求参数

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

删除块

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

请求

• 方法：DELETE

• URL：/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "chunk_ids": ["string"]
  }
  

请求示例

curl --request DELETE \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer ' \
     --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` 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}

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "content": "string",
    "important_keywords": ["string"],
    "available": true
  }
  

请求示例

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 ' \
     --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": "Can't find this chunk 29a2d9987e16ba331fb4d7d30d99b71d2"
  }
  

检索块

POST /api/v1/retrieval

请求

• 方法：POST

• URL：/api/v1/retrieval

• 请求头：

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体：

  {
    "question": "string",
    "dataset_ids": ["string"],
    "document_ids": ["string"],
    "page": integer,
    "page_size": integer,
    "similarity_threshold": float,
    "vector_similarity_weight": float,
    "top_k": integer,
    "rerank_id": integer,
    "keyword": boolean,
    "highlight": boolean
  }
  

请求示例

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

请求参数

• question (请求体参数)：string，必需。用户查询或查询关键词。

• dataset_ids (请求体参数)：list[string]。要搜索的数据集的 ID 列表。如果您不设置此参数，请确保设置 document_ids。

• document_ids (请求体参数)：list[string]。要搜索的文档的 ID 列表。请确保所有选定的文档使用相同的嵌入模型，否则将导致错误。如果您不设置此参数，请确保设置 dataset_ids。

• page (请求体参数)：integer。指定将显示块的页面。默认为 1。

• page_size (请求体参数)：每页的最大块数量。默认为 30。

• similarity_threshold (请求体参数)：float。最小相似度分数。默认为 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：禁用匹配项的高亮显示（默认）。

响应

• 成功响应示例：

  {
      "code": 0,
      "data": {
          "chunks": [
              {
                  "content": "ragflow content",
                  "content_ltks": "ragflow content",
                  "document_id": "5c5999ec7be811ef9cab0242ac120005",
                  "document_keyword": "1.txt",
                  "highlight": "ragflow 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

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

  {
    "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 ' \
       --data '{
           "dataset_ids": ["0b2cbc8c877f11ef89070242ac120005"],
           "name":"new_chat_1"
       }'
  

• 请求参数:

  • name: 聊天助手的名称，必填。

  • avatar: 头像的base64编码。

  • dataset_ids: 关联的数据集ID列表。

  • llm: 聊天助手使用的LLM设置对象，若未明确设置，则使用默认值。

    • model_name: 聊天模型名称，若未设置，则使用用户的默认聊天模型。

    • temperature: 控制模型预测的随机性，值越低响应越保守，越高响应越多样化，默认0.1。

    • top_p: 核心采样参数，设置选择较小词汇的阈值，默认0.3。

    • presence_penalty: 避免模型重复信息，对已出现的词汇进行惩罚，默认0.2。

    • frequency penalty: 减少模型频繁重复词汇，默认0.7。

    • max_token: 模型输出的最大长度，以token数衡量，默认512，若禁用则模型自行决定响应的token数。

  • prompt: LLM遵循的指令对象，若未明确设置，则使用默认值。

    • similarity_threshold: 设置用户查询与片段之间的相似度阈值，默认0.2。

    • keywords_similarity_weight: 设置关键词相似度在混合相似度得分中的权重，默认0.7。

    • top_n: 指定相似度得分高于阈值的前N个片段输入LLM，默认8。

    • variables: 在聊天配置的'System'字段中使用的变量列表，默认为[{"key": "knowledge", "optional": true}]。

    • rerank_model: 若未指定，则使用向量余弦相似度；否则使用重新排序得分。

    • top_k: 根据特定排序标准重新排序或选择前k个项目的数量，默认1024。

    • empty_response: 若用户问题在数据集中未检索到内容时使用的响应，留空则允许LLM即兴发挥。

    • opener: 用户的开场问候，默认为"Hi! I am your assistant, can I help you?"。

    • show_quote: 是否显示文本的来源，默认为true。

    • prompt: 提示内容。

• 成功响应:

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

• URL: /api/v1/chats/{chat_id}

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

  {
      "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 ' \
       --data '
       {
            "name":"Test"
       }'
  

• 参数:

  • chat_id: 要更新的聊天助手ID。

  • name: 修订后的聊天助手名称，必填。

  • avatar: 头像的base64编码。

  • dataset_ids: 关联的数据集ID列表。

  • llm: 聊天助手使用的LLM设置对象，若未明确设置，则使用默认值。

  • prompt: LLM遵循的指令对象，包含以下属性：

    • similarity_threshold: 设置用户查询与片段之间的相似度阈值，默认0.2。

    • keywords_similarity_weight: 设置关键词相似度在混合相似度得分中的权重，默认0.7。

    • top_n: 指定相似度得分高于阈值的前N个片段输入LLM，默认8。

    • variables: 在聊天配置的'System'字段中使用的变量列表，默认为[{"key": "knowledge", "optional": true}]。

    • rerank_model: 若未指定，则使用向量余弦相似度；否则使用重新排序得分。

    • empty_response: 若用户问题在数据集中未检索到内容时使用的响应，留空则允许LLM即兴发挥。

    • opener: 用户的开场问候，默认为"Hi! I am your assistant, can I help you?"。

    • show_quote: 是否显示文本的来源，默认为true。

    • prompt: 提示内容。

• 成功响应:

  {
      "code": 0
  }
  

• 失败响应:

  {
      "code": 102,
      "message": "Duplicated chat name in updating dataset."
  }
  

删除聊天助手

• 方法: DELETE

• URL: /api/v1/chats

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

  {
      "ids": list[string]
  }
  

• 示例请求:

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

• 请求参数:

  • ids: 要删除的聊天助手ID列表，若未指定，则删除系统中所有聊天助手。

• 成功响应:

  {
      "code": 0
  }
  

• 失败响应:

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

列出聊天助手

• 方法: GET

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

• 请求头:

  'Authorization: Bearer '
  

• 示例请求:

  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 '
  

• 请求参数:

  • page: 显示聊天助手的页码，默认为1。

  • page_size: 每页的聊天助手数量，默认为30。

  • orderby: 排序依据的属性，可选create_time(默认)、update_time。

  • desc: 是否降序排列，默认为true。

  • id: 要检索的聊天助手ID。

  • name: 要检索的聊天助手名称。

• 成功响应:

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

• URL: /api/v1/chats/{chat_id}/sessions

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

  {
      "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 ' \
       --data '
       {
            "name": "new session"
       }'
  

• 请求参数:

  • chat_id: 相关聊天助手的ID。

  • name: 要创建的聊天会话名称。

  • user_id: 可选的用户自定义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

• URL: /api/v1/chats/{chat_id}/sessions/{session_id}

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

  {
      "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 ' \
       --data '
       {
            "name": ""
       }'
  

• 请求参数:

  • chat_id: 相关聊天助手的ID。

  • session_id: 要更新的会话ID。

  • name: 修订后的会话名称。

  • user_id: 可选的用户自定义ID。

• 成功响应:

  {
      "code": 0
  }
  

• 失败响应:

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

列出聊天助手的会话

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

• 示例请求:

  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 '
  

• 请求参数:

  • chat_id: 相关聊天助手的ID。

  • page: 显示会话的页码，默认为1。

  • page_size: 每页的会话数量，默认为30。

  • orderby: 会话排序依据的字段，可选create_time(默认)、update_time。

  • desc: 是否降序排列，默认为true。

  • name: 要检索的聊天会话名称。

  • id: 要检索的聊天会话ID。

  • user_id: 创建会话时传递的可选用户自定义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"
  }
  

删除聊天助手的会话

• 方法: DELETE

• URL: /api/v1/chats/{chat_id}/sessions

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

  {
      "ids": list[string]
  }
  

• 示例请求:

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

• 请求参数:

  • chat_id: 相关聊天助手的ID。

  • ids: 要删除的会话ID列表，若未指定，则删除指定聊天助手的所有会话。

• 成功响应:

  {
      "code": 0
  }
  

• 失败响应:

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

与聊天助手对话

• 方法: POST

• URL: /api/v1/chats/{chat_id}/completions

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

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

• 请求参数:

  • chat_id: 相关聊天助手的ID。

  • question: 开始AI对话的问题，必填。

  • stream: 是否以流式方式输出响应：

    • true: 启用流式（默认）。

    • false: 禁用流式。

  • session_id: 会话ID，若未提供，则生成新会话。

  • user_id: 可选的用户自定义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

• URL: /api/v1/agents/{agent_id}/sessions

• 请求头:

  'content-Type: application/json' 或 'multipart/form-data'
  'Authorization: Bearer '
  

• 请求体:

  所需参数：str
  其他参数：Begin组件中指定的参数。
  

• 示例请求:

  如果代理中的Begin组件不接受所需参数：
  
  curl --request POST \
       --url http://{address}/api/v1/agents/{agent_id}/sessions \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Bearer ' \
       --data '{
       }'
  如果代理中的Begin组件接受所需参数：
  
  curl --request POST \
       --url http://{address}/api/v1/agents/{agent_id}/sessions \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Bearer ' \
       --data '{
              "lang":"Japanese",
              "file":"Who are you"
       }'
  如果代理中的Begin组件接受所需文件参数：
  
  curl --request POST \
       --url http://{address}/api/v1/agents/{agent_id}/sessions?user_id={user_id} \
       --header 'Content-Type: multipart/form-data' \
       --header 'Authorization: Bearer ' \
       --form '=@./test1.png'    
  

• 请求参数:

  • agent_id: 相关代理的ID。

  • user_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

• URL: /api/v1/agents/{agent_id}/completions

• 请求头:

  'content-Type: application/json'
  'Authorization: Bearer '
  

• 请求体:

  {
      "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 ' \
       --data-binary '
       {
       }'
  如果Begin组件接受参数，以下代码将创建会话。
  
  curl --request POST \
       --url http://{address}/api/v1/agents/{agent_id}/completions \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Bearer ' \
       --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 ' \
       --data-binary '
       {
            "question": "Hello",
            "stream": true,
            "session_id": "cb2f385cb86211efa36e0242ac120005"
       }'
  

• 请求参数:

  • agent_id: 相关代理的ID。

  • question: 开始AI对话的问题，必填。

  • stream: 是否以流式方式输出响应：

    • true: 启用流式（默认）。

    • false: 禁用流式。

  • session_id: 会话ID，若未提供，则生成新会话。

  • user_id: 可选的用户自定义ID，仅在未提供session_id时有效。

  • 其他参数: Begin组件中指定的参数。

• 成功响应（未提供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:{
      "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

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

• 请求头:

  'Authorization: Bearer '
  

• 示例请求:

  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 '
  

• 请求参数:

  • agent_id: 相关代理的ID。

  • page: 显示会话的页码，默认为1。

  • page_size: 每页的会话数量，默认为30。

  • orderby: 会话排序依据的字段，可选create_time(默认)、update_time。

  • desc: 是否降序排列，默认为true。

  • id: 要检索的代理会话ID。

  • user_id: 创建会话时传递的可选用户自定义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

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

• 请求头:

  'Authorization: Bearer '
  

• 示例请求:

  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 '
  

• 请求参数:

  • page: 显示代理的页码，默认为1。

  • page_size: 每页的代理数量，默认为30。

  • orderby: 结果排序依据的属性，可选create_time(默认)、update_time。

  • desc: 是否降序排列，默认为true。

  • id: 要检索的代理ID。

  • name: 要检索的代理名称。

• 成功响应:

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