A complete reference for RAGFlow's RESTful API. Before proceeding, please ensure you [have your RAGFlow API key ready for authentication](../guides/models/llm_api_key_setup.md).
Creates a model response for a given chat conversation.
This API follows the same request and response format as OpenAI's API. It allows you to interact with the model in a manner similar to how you would with [OpenAI's API](https://platform.openai.com/docs/api-reference/chat/create).
A list of historical chat messages used to generate the response. This must contain at least one message with the `user` role.
-`stream` (*Body parameter*) `boolean`
Whether to receive the response as a stream. Set this to `false` explicitly if you prefer to receive the entire response in one go instead of as a stream.
"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
}
}
```
Failure:
```json
{
"code": 102,
"message": "The last content of this conversation is not from user."
The chunking method of the dataset to create. Available options:
-`"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`
The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected `"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"]`
#### Response
Success:
```json
{
"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
}
}
```
Failure:
```json
{
"code": 102,
"message": "Duplicated knowledgebase name in creating dataset."
}
```
---
### Delete datasets
**DELETE** `/api/v1/datasets`
Deletes datasets by ID.
#### Request
- Method: DELETE
- URL: `/api/v1/datasets`
- Headers:
-`'content-Type: application/json'`
-`'Authorization: Bearer <YOUR_API_KEY>'`
- Body:
-`"ids"`: `list[string]`
##### Request example
```bash
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"]
}'
```
##### Request parameters
-`"ids"`: (*Body parameter*), `list[string]`
The IDs of the datasets to delete. If it is not specified, all datasets will be deleted.
The chunking method for the dataset. Available options:
-`"naive"`: General
-`"manual`: Manual
-`"qa"`: Q&A
-`"table"`: Table
-`"paper"`: Paper
-`"book"`: Book
-`"laws"`: Laws
-`"presentation"`: Presentation
-`"picture"`: Picture
-`"one"`:One
-`"email"`: Email
-`"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!
The configuration settings for the dataset parser. The attributes in this JSON object vary with the selected `"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"]`
#### Response
Success:
```json
{
"code": 0
}
```
Failure:
```json
{
"code": 102,
"message": "The dataset does not have the document."
The IDs of the documents to search. Ensure that all selected documents use the same embedding model. Otherwise, an error will occur. If you do not set this argument, ensure that you set `"dataset_ids"`.
-`"page"`: (*Body parameter*), `integer`
Specifies the page on which the chunks will be displayed. Defaults to `1`.
-`"page_size"`: (*Body parameter*)
The maximum number of chunks on each page. Defaults to `30`.
The weight of vector cosine similarity. Defaults to `0.3`. If x represents the weight of vector cosine similarity, then (1 - x) is the term similarity weight.
-`"top_k"`: (*Body parameter*), `integer`
The number of chunks engaged in vector cosine computation. Defaults to `1024`.
-`"rerank_id"`: (*Body parameter*), `integer`
The ID of the rerank model.
-`"keyword"`: (*Body parameter*), `boolean`
Indicates whether to enable keyword-based matching:
The LLM settings for the chat assistant to create. If it is not explicitly set, a JSON object with the following values will be generated as the default. An `llm` JSON object contains the following attributes:
-`"model_name"`, `string`
The chat model name. If not set, the user's default chat model will be used.
-`"temperature"`: `float`
Controls the randomness of the model's predictions. A lower temperature results in more conservative responses, while a higher temperature yields more creative and diverse responses. Defaults to `0.1`.
-`"top_p"`: `float`
Also known as “nucleus sampling”, this parameter sets a threshold to select a smaller set of words to sample from. It focuses on the most likely words, cutting off the less probable ones. Defaults to `0.3`
-`"presence_penalty"`: `float`
This discourages the model from repeating the same information by penalizing words that have already appeared in the conversation. Defaults to `0.2`.
-`"frequency penalty"`: `float`
Similar to the presence penalty, this reduces the model’s tendency to repeat the same words frequently. Defaults to `0.7`.
-`"max_token"`: `integer`
The maximum length of the model's output, measured in the number of tokens (words or pieces of words). Defaults to `512`. If disabled, you lift the maximum token limit, allowing the model to determine the number of tokens in its responses.
-`"prompt"`: (*Body parameter*), `object`
Instructions for the LLM to follow. If it is not explicitly set, a JSON object with the following values will be generated as the default. A `prompt` JSON object contains the following attributes:
-`"similarity_threshold"`: `float` RAGFlow employs either a combination of weighted keyword similarity and weighted vector cosine similarity, or a combination of weighted keyword similarity and weighted reranking score during retrieval. This argument sets the threshold for similarities between the user query and chunks. If a similarity score falls below this threshold, the corresponding chunk will be excluded from the results. The default value is `0.2`.
-`"keywords_similarity_weight"`: `float` This argument sets the weight of keyword similarity in the hybrid similarity score with vector cosine similarity or reranking model similarity. By adjusting this weight, you can control the influence of keyword similarity in relation to other similarity measures. The default value is `0.7`.
-`"top_n"`: `int` This argument specifies the number of top chunks with similarity scores above the `similarity_threshold` that are fed to the LLM. The LLM will *only* access these 'top N' chunks. The default value is `8`.
-`"variables"`: `object[]` This argument lists the variables to use in the 'System' field of **Chat Configurations**. Note that:
-`"knowledge"` is a reserved variable, which represents the retrieved chunks.
- All the variables in 'System' should be curly bracketed.
- The default value is `[{"key": "knowledge", "optional": true}]`.
-`"rerank_model"`: `string` If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used.
-`top_k`: `int` Refers to the process of reordering or selecting the top-k items from a list or set based on a specific ranking criterion. Default to 1024.
-`"empty_response"`: `string` If nothing is retrieved in the dataset for the user's question, this will be used as the response. To allow the LLM to improvise when nothing is found, leave this blank.
-`"opener"`: `string` The opening greeting for the user. Defaults to `"Hi! I am your assistant, can I help you?"`.
-`"show_quote`: `boolean` Indicates whether the source of text should be displayed. Defaults to `true`.
-`"prompt"`: `string` The prompt content.
#### Response
Success:
```json
{
"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
}
}
```
Failure:
```json
{
"code": 102,
"message": "Duplicated chat name in creating dataset."
}
```
---
### Update chat assistant
**PUT** `/api/v1/chats/{chat_id}`
Updates configurations for a specified chat assistant.
The LLM settings for the chat assistant to create. If it is not explicitly set, a dictionary with the following values will be generated as the default. An `llm` object contains the following attributes:
-`"model_name"`, `string`
The chat model name. If not set, the user's default chat model will be used.
-`"temperature"`: `float`
Controls the randomness of the model's predictions. A lower temperature results in more conservative responses, while a higher temperature yields more creative and diverse responses. Defaults to `0.1`.
-`"top_p"`: `float`
Also known as “nucleus sampling”, this parameter sets a threshold to select a smaller set of words to sample from. It focuses on the most likely words, cutting off the less probable ones. Defaults to `0.3`
-`"presence_penalty"`: `float`
This discourages the model from repeating the same information by penalizing words that have already appeared in the conversation. Defaults to `0.2`.
-`"frequency penalty"`: `float`
Similar to the presence penalty, this reduces the model’s tendency to repeat the same words frequently. Defaults to `0.7`.
-`"max_token"`: `integer`
The maximum length of the model's output, measured in the number of tokens (words or pieces of words). Defaults to `512`. If disabled, you lift the maximum token limit, allowing the model to determine the number of tokens in its responses.
-`"prompt"`: (*Body parameter*), `object`
Instructions for the LLM to follow. A `prompt` object contains the following attributes:
-`"similarity_threshold"`: `float` RAGFlow employs either a combination of weighted keyword similarity and weighted vector cosine similarity, or a combination of weighted keyword similarity and weighted rerank score during retrieval. This argument sets the threshold for similarities between the user query and chunks. If a similarity score falls below this threshold, the corresponding chunk will be excluded from the results. The default value is `0.2`.
-`"keywords_similarity_weight"`: `float` This argument sets the weight of keyword similarity in the hybrid similarity score with vector cosine similarity or reranking model similarity. By adjusting this weight, you can control the influence of keyword similarity in relation to other similarity measures. The default value is `0.7`.
-`"top_n"`: `int` This argument specifies the number of top chunks with similarity scores above the `similarity_threshold` that are fed to the LLM. The LLM will *only* access these 'top N' chunks. The default value is `8`.
-`"variables"`: `object[]` This argument lists the variables to use in the 'System' field of **Chat Configurations**. Note that:
-`"knowledge"` is a reserved variable, which represents the retrieved chunks.
- All the variables in 'System' should be curly bracketed.
- The default value is `[{"key": "knowledge", "optional": true}]`
-`"rerank_model"`: `string` If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used.
-`"empty_response"`: `string` If nothing is retrieved in the dataset for the user's question, this will be used as the response. To allow the LLM to improvise when nothing is found, leave this blank.
-`"opener"`: `string` The opening greeting for the user. Defaults to `"Hi! I am your assistant, can I help you?"`.
-`"show_quote`: `boolean` Indicates whether the source of text should be displayed. Defaults to `true`.
-`"prompt"`: `string` The prompt content.
#### Response
Success:
```json
{
"code": 0
}
```
Failure:
```json
{
"code": 102,
"message": "Duplicated chat name in updating dataset."
}
```
---
### Delete chat assistants
**DELETE** `/api/v1/chats`
Deletes chat assistants by ID.
#### Request
- Method: DELETE
- URL: `/api/v1/chats`
- Headers:
-`'content-Type: application/json'`
-`'Authorization: Bearer <YOUR_API_KEY>'`
- Body:
-`"ids"`: `list[string]`
##### Request example
```bash
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"]
}'
```
##### Request parameters
-`"ids"`: (*Body parameter*), `list[string]`
The IDs of the chat assistants to delete. If it is not specified, all chat assistants in the system will be deleted.
"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",
Indicates whether to output responses in a streaming way:
-`true`: Enable streaming (default).
-`false`: Disable streaming.
-`"session_id"`: (*Body Parameter*)
The ID of session. If it is not provided, a new session will be generated.
-`"user_id"`: (*Body parameter*), `string`
The optional user-defined ID. Valid *only* when no `session_id` is provided.
#### Response
Success without `session_id`:
```json
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
}
```
Success with `session_id`:
```json
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.",
"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.",
"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?",
