AI/ragflow
1
0
Fork 0
mirror of https://git.mirrors.martin98.com/https://github.com/infiniflow/ragflow.git synced 2025-08-13 06:09:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

Miscellaneous updates to HTTP and PYthon APIs (#3000)

Browse Source 
### What problem does this PR solve?


### Type of change


- [x] Documentation Update
This commit is contained in:
writinwaters 2024-10-24 16:14:07 +08:00 committed by GitHub
parent 765a114be7
commit 524699da7d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 233 additions and 219 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

231
api/http_api_reference.md
View File

@ -37,17 +37,15 @@ Creates a dataset.
#### Request example #### Request example
```bash ```bash
# "name": name is required and can't be duplicated.
# "embedding_model": embedding_model must not be provided.
# "naive" means general.
curl --request POST \ curl --request POST \
--url http://{address}/api/v1/dataset \ --url http://{address}/api/v1/dataset \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"name": "test", "name": "test",
"chunk_method": "naive" "chunk_method": "naive"
}' }'
``` ```
#### Request parameters #### Request parameters
@ -97,7 +95,7 @@ curl --request POST \
- `"parser_config"`: (*Body parameter*) - `"parser_config"`: (*Body parameter*)
The configuration settings for the dataset parser. A `ParserConfig` object contains the following attributes: The configuration settings for the dataset parser. A `ParserConfig` object contains the following attributes:
- `"chunk_token_count"`: Defaults to `128`. - `"chunk_token_count"`: Defaults to `128`.
- `"layout_recognize"`: Defaults to `True`. - `"layout_recognize"`: Defaults to `true`.
- `"delimiter"`: Defaults to `"\n!?。；！？"`. - `"delimiter"`: Defaults to `"\n!?。；！？"`.
- `"task_page_size"`: Defaults to `12`. - `"task_page_size"`: Defaults to `12`.
@ -168,24 +166,20 @@ Deletes datasets by ID.
- Body: - Body:
- `"ids"`: `list[string]` - `"ids"`: `list[string]`
#### Request example #### Request example
```bash ```bash
# Either id or name must be provided, but not both.
curl --request DELETE \ curl --request DELETE \
--url http://{address}/api/v1/dataset \ --url http://{address}/api/v1/dataset \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '{"ids": ["test_1", "test_2"]}'
"ids": ["test_1", "test_2"]
}'
``` ```
#### Request parameters #### Request parameters
- `"ids"`: (*Body parameter*) - `"ids"`: (*Body parameter*), `list[string]`, *Required*
The IDs of the datasets to delete. Defaults to `""`. If not specified, all datasets in the system will be deleted. The IDs of the datasets to delete.
### Response ### Response
@ -221,7 +215,7 @@ Updates configurations for a specified dataset.
- Headers: - Headers:
- `'content-Type: application/json'` - `'content-Type: application/json'`
- `'Authorization: Bearer {YOUR_API_KEY}'` - `'Authorization: Bearer {YOUR_API_KEY}'`
- Body: - Body:
- `"name"`: `string` - `"name"`: `string`
- `"embedding_model"`: `string` - `"embedding_model"`: `string`
- `"chunk_method"`: `enum<string>` - `"chunk_method"`: `enum<string>`
@ -229,25 +223,24 @@ Updates configurations for a specified dataset.
#### Request example #### Request example
```bash ```bash
# "id": id is required.
# "name": If you update name, it can't be duplicated.
# "embedding_model": If you update embedding_model, it can't be changed.
# "parse_method": If you update parse_method, chunk_count must be 0.
# "naive" means general.
curl --request PUT \ curl --request PUT \
--url http://{address}/api/v1/dataset/{dataset_id} \ --url http://{address}/api/v1/dataset/{dataset_id} \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"name": "test", "name": "test",
"embedding_model": "BAAI/bge-zh-v1.5", "embedding_model": "BAAI/bge-zh-v1.5",
"parse_method": "naive" "chunk_method": "naive"
}' }'
``` ```
#### Request parameters #### Request parameters
- `"name"`: `string` The name of the dataset to update. - `dataset_id`: (*Path parameter*)
The ID of the dataset to update.
- `"name"`: `string`
The name of the dataset to update.
- `"embedding_model"`: `string` The embedding model name to update. - `"embedding_model"`: `string` The embedding model name to update.
- Ensure that `"chunk_count"` is `0` before updating `"embedding_model"`. - Ensure that `"chunk_count"` is `0` before updating `"embedding_model"`.
- `"chunk_method"`: `enum<string>` The chunking method for the dataset. Available options: - `"chunk_method"`: `enum<string>` The chunking method for the dataset. Available options:
@ -298,14 +291,9 @@ Lists datasets.
- Headers: - Headers:
- `'Authorization: Bearer {YOUR_API_KEY}'` - `'Authorization: Bearer {YOUR_API_KEY}'`
#### Request example #### Request example
```bash ```bash
# If no page parameter is passed, the default is 1
# If no page_size parameter is passed, the default is 1024
# If no order_by parameter is passed, the default is "create_time"
# If no desc parameter is passed, the default is True
curl --request GET \ curl --request GET \
--url http://{address}/api/v1/dataset?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id} \ --url http://{address}/api/v1/dataset?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id} \
--header 'Authorization: Bearer {YOUR_API_KEY}' --header 'Authorization: Bearer {YOUR_API_KEY}'
@ -313,20 +301,20 @@ curl --request GET \
#### Request parameters #### Request parameters
- `"page"`: (*Path parameter*) - `page`: (*Path parameter*)
Specifies the page on which the datasets will be displayed. Defaults to `1`. Specifies the page on which the datasets will be displayed. Defaults to `1`.
- `"page_size"`: (*Path parameter*) - `page_size`: (*Path parameter*)
The number of datasets on each page. Defaults to `1024`. The number of datasets on each page. Defaults to `1024`.
- `"orderby"`: (*Path parameter*) - `orderby`: (*Path parameter*)
The field by which datasets should be sorted. Available options: The field by which datasets should be sorted. Available options:
- `"create_time"` (default) - `create_time` (default)
- `"update_time"` - `update_time`
- `"desc"`: (*Path parameter*) - `desc`: (*Path parameter*)
Indicates whether the retrieved datasets should be sorted in descending order. Defaults to `True`. Indicates whether the retrieved datasets should be sorted in descending order. Defaults to `true`.
- `"id"`: (*Path parameter*) - `name`: (*Path parameter*)
The ID of the dataset to retrieve.
- `"name"`: (*Path parameter*)
The name of the dataset to retrieve. The name of the dataset to retrieve.
- `id`: (*Path parameter*)
The ID of the dataset to retrieve.
### Response ### Response
@ -470,7 +458,8 @@ curl --request PUT \
--url http://{address}/api/v1/dataset/{dataset_id}/info/{document_id} \ --url http://{address}/api/v1/dataset/{dataset_id}/info/{document_id} \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--data '{ --data '
{
"name": "manual.txt", "name": "manual.txt",
"chunk_method": "manual", "chunk_method": "manual",
"parser_config": {"chunk_token_count": 128} "parser_config": {"chunk_token_count": 128}
@ -498,7 +487,7 @@ curl --request PUT \
- `"parser_config"`: (*Body parameter*), `object` - `"parser_config"`: (*Body parameter*), `object`
The parsing configuration for the document: The parsing configuration for the document:
- `"chunk_token_count"`: Defaults to `128`. - `"chunk_token_count"`: Defaults to `128`.
- `"layout_recognize"`: Defaults to `True`. - `"layout_recognize"`: Defaults to `true`.
- `"delimiter"`: Defaults to `"\n!?。；！？"`. - `"delimiter"`: Defaults to `"\n!?。；！？"`.
- `"task_page_size"`: Defaults to `12`. - `"task_page_size"`: Defaults to `12`.
@ -582,7 +571,7 @@ Lists documents in a specified dataset.
### Request ### Request
- Method: GET - Method: GET
- URL: `/api/v1/dataset/{dataset_id}/info?keywords={keyword}&page={page}&page_size={limit}&orderby={orderby}&desc={desc}&name={name` - URL: `/api/v1/dataset/{dataset_id}/info?keywords={keyword}&page={page}&page_size={limit}&orderby={orderby}&desc={desc}&name={name}`
- Headers: - Headers:
- `'content-Type: application/json'` - `'content-Type: application/json'`
- `'Authorization: Bearer {YOUR_API_KEY}'` - `'Authorization: Bearer {YOUR_API_KEY}'`
@ -610,8 +599,8 @@ curl --request GET \
- `"create_time"` (default) - `"create_time"` (default)
- `"update_time"` - `"update_time"`
- `"desc"`: (*Filter parameter*), `boolean` - `"desc"`: (*Filter parameter*), `boolean`
Indicates whether the retrieved documents should be sorted in descending order. Defaults to `True`. Indicates whether the retrieved documents should be sorted in descending order. Defaults to `true`.
- `"document_id"`: (*Filter parameter*) - `"id"`: (*Filter parameter*), `string`
The ID of the document to retrieve. The ID of the document to retrieve.
### Response ### Response
@ -693,13 +682,16 @@ curl --request DELETE \
--url http://{address}/api/v1/dataset/{dataset_id}/document \ --url http://{address}/api/v1/dataset/{dataset_id}/document \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: {YOUR_API_KEY}' \ --header 'Authorization: {YOUR_API_KEY}' \
--data '{ --data '
{
"ids": ["id_1","id_2"] "ids": ["id_1","id_2"]
}' }'
``` ```
#### Request parameters #### Request parameters
- `"dataset_id"`: (*Path parameter*)
The dataset ID.
- `"ids"`: (*Body parameter*), `list[string]` - `"ids"`: (*Body parameter*), `list[string]`
The IDs of the documents to delete. If not specified, all documents in the dataset will be deleted. The IDs of the documents to delete. If not specified, all documents in the dataset will be deleted.
@ -747,14 +739,17 @@ curl --request POST \
--url http://{address}/api/v1/dataset/{dataset_id}/chunk \ --url http://{address}/api/v1/dataset/{dataset_id}/chunk \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{"document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]}' --data '
{
"document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]
}'
``` ```
#### Request parameters #### Request parameters
- `"dataset_id"`: (*Path parameter*) - `"dataset_id"`: (*Path parameter*)
The dataset ID. The dataset ID.
- `"document_ids"`: (*Body parameter*), `list[string]` - `"document_ids"`: (*Body parameter*), `list[string]`, *Required*
The IDs of the documents to parse. The IDs of the documents to parse.
### Response ### Response
@ -801,7 +796,10 @@ curl --request DELETE \
--url http://{address}/api/v1/dataset/{dataset_id}/chunk \ --url http://{address}/api/v1/dataset/{dataset_id}/chunk \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{"document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]}' --data '
{
"document_ids": ["97a5f1c2759811efaa500242ac120004","97ad64b6759811ef9fc30242ac120004"]
}'
``` ```
#### Request parameters #### Request parameters
@ -832,7 +830,6 @@ Failure:
--- ---
## Add chunks ## Add chunks
**POST** `/api/v1/dataset/{dataset_id}/document/{document_id}/chunk` **POST** `/api/v1/dataset/{dataset_id}/document/{document_id}/chunk`
@ -857,9 +854,10 @@ curl --request POST \
--url http://{address}/api/v1/dataset/{dataset_id}/document/{document_id}/chunk \ --url http://{address}/api/v1/dataset/{dataset_id}/document/{document_id}/chunk \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"content": "<SOME_CHUNK_CONTENT_HERE>" "content": "<SOME_CHUNK_CONTENT_HERE>"
}' }'
``` ```
#### Request parameters #### Request parameters
@ -1019,7 +1017,8 @@ curl --request DELETE \
--url http://{address}/api/v1/dataset/{dataset_id}/document/{document_id}/chunk \ --url http://{address}/api/v1/dataset/{dataset_id}/document/{document_id}/chunk \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"chunk_ids": ["test_1", "test_2"] "chunk_ids": ["test_1", "test_2"]
}' }'
``` ```
@ -1075,10 +1074,11 @@ curl --request PUT \
--url http://{address}/api/v1/dataset/{dataset_id}/document/{document_id}/chunk/{chunk_id} \ --url http://{address}/api/v1/dataset/{dataset_id}/document/{document_id}/chunk/{chunk_id} \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: {YOUR_API_KEY}' \ --header 'Authorization: {YOUR_API_KEY}' \
--data '{ --data '
{
"content": "ragflow123", "content": "ragflow123",
"important_keywords": [], "important_keywords": [],
}' }'
``` ```
#### Request parameters #### Request parameters
@ -1089,8 +1089,8 @@ curl --request PUT \
A list of key terms or phrases to tag with the chunk. A list of key terms or phrases to tag with the chunk.
- `"available"`: (*Body parameter*) `boolean` - `"available"`: (*Body parameter*) `boolean`
The chunk's availability status in the dataset. Value options: The chunk's availability status in the dataset. Value options:
- `False`: Unavailable - `true`: Available
- `True`: Available - `false`: Unavailable
### Response ### Response
@ -1128,8 +1128,8 @@ Retrieves chunks from specified datasets.
- `'Authorization: Bearer {YOUR_API_KEY}'` - `'Authorization: Bearer {YOUR_API_KEY}'`
- Body: - Body:
- `"question"`: `string` - `"question"`: `string`
- `"datasets"`: `list[string]` - `"dataset_ids"`: `list[string]`
- `"documents"`: `list[string]` - `"document_ids"`: `list[string]`
- `"offset"`: `integer` - `"offset"`: `integer`
- `"limit"`: `integer` - `"limit"`: `integer`
- `"similarity_threshold"`: `float` - `"similarity_threshold"`: `float`
@ -1146,24 +1146,21 @@ curl --request POST \
--url http://{address}/api/v1/retrieval \ --url http://{address}/api/v1/retrieval \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: {YOUR_API_KEY}' \ --header 'Authorization: {YOUR_API_KEY}' \
--data '{ --data '
{
"question": "What is advantage of ragflow?", "question": "What is advantage of ragflow?",
"datasets": [ "dataset_ids": ["b2a62730759d11ef987d0242ac120004"],
"b2a62730759d11ef987d0242ac120004" "document_ids": ["77df9ef4759a11ef8bdd0242ac120004"]
], }'
"documents": [
"77df9ef4759a11ef8bdd0242ac120004"
]
}'
``` ```
#### Request parameter #### Request parameter
- `"question"`: (*Body parameter*), `string`, *Required* - `"question"`: (*Body parameter*), `string`, *Required*
The user query or query keywords. Defaults to `""`. The user query or query keywords. Defaults to `""`.
- `"datasets"`: (*Body parameter*) `list[string]`, *Required* - `"dataset_ids"`: (*Body parameter*) `list[string]`, *Required*
The IDs of the datasets to search from. The IDs of the datasets to search from.
- `"documents"`: (*Body parameter*), `list[string]` - `"document_ids"`: (*Body parameter*), `list[string]`
The IDs of the documents to search from. The IDs of the documents to search from.
- `"offset"`: (*Body parameter*), `integer` - `"offset"`: (*Body parameter*), `integer`
The starting index for the documents to retrieve. Defaults to `1`. The starting index for the documents to retrieve. Defaults to `1`.
@ -1179,12 +1176,12 @@ curl --request POST \
The ID of the rerank model. The ID of the rerank model.
- `"keyword"`: (*Body parameter*), `boolean` - `"keyword"`: (*Body parameter*), `boolean`
Indicates whether to enable keyword-based matching: Indicates whether to enable keyword-based matching:
- `True`: Enable keyword-based matching. - `true`: Enable keyword-based matching.
- `False`: Disable keyword-based matching (default). - `false`: Disable keyword-based matching (default).
- `"highlight"`: (*Body parameter*), `boolean` - `"highlight"`: (*Body parameter*), `boolean`
Specifies whether to enable highlighting of matched terms in the results: Specifies whether to enable highlighting of matched terms in the results:
- `True`: Enable highlighting of matched terms. - `true`: Enable highlighting of matched terms.
- `False`: Disable highlighting of matched terms (default). - `false`: Disable highlighting of matched terms (default).
### Response ### Response
@ -1260,7 +1257,7 @@ Creates a chat assistant.
- Body: - Body:
- `"name"`: `string` - `"name"`: `string`
- `"avatar"`: `string` - `"avatar"`: `string`
- `"knowledgebases"`: `list[string]` - `"dataset_ids"`: `list[string]`
- `"llm"`: `object` - `"llm"`: `object`
- `"prompt"`: `object` - `"prompt"`: `object`
@ -1271,8 +1268,8 @@ curl --request POST \
--url http://{address}/api/v1/chat \ --url http://{address}/api/v1/chat \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' --header 'Authorization: Bearer {YOUR_API_KEY}'
--data-binary '{ --data '{
"knowledgebases": [ "dataset_ids": [
{ {
"avatar": null, "avatar": null,
"chunk_count": 0, "chunk_count": 0,
@ -1305,7 +1302,7 @@ curl --request POST \
The name of the chat assistant. The name of the chat assistant.
- `"avatar"`: (*Body parameter*) - `"avatar"`: (*Body parameter*)
Base64 encoding of the avatar. Defaults to `""`. Base64 encoding of the avatar. Defaults to `""`.
- `"knowledgebases"`: (*Body parameter*) - `"dataset_ids"`: (*Body parameter*)
The IDs of the associated datasets. Defaults to `[""]`. The IDs of the associated datasets. Defaults to `[""]`.
- `"llm"`: (*Body parameter*), `object` - `"llm"`: (*Body parameter*), `object`
The LLM settings for the chat assistant to create. When the value is `None`, a dictionary with the following values will be generated as the default. An `llm` object contains the following attributes: The LLM settings for the chat assistant to create. When the value is `None`, a dictionary with the following values will be generated as the default. An `llm` object contains the following attributes:
@ -1329,11 +1326,11 @@ curl --request POST \
- `"variables"`: `object[]` This argument lists the variables to use in the 'System' field of **Chat Configurations**. Note that: - `"variables"`: `object[]` This argument lists the variables to use in the 'System' field of **Chat Configurations**. Note that:
- `"knowledge"` is a reserved variable, which will be replaced with the retrieved chunks. - `"knowledge"` is a reserved variable, which will be replaced with the retrieved chunks.
- All the variables in 'System' should be curly bracketed. - All the variables in 'System' should be curly bracketed.
- The default value is `[{"key": "knowledge", "optional": True}]` - 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. Defaults to `""`. - `"rerank_model"`: `string` If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used. Defaults to `""`.
- `"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. - `"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?"`. - `"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`. - `"show_quote`: `boolean` Indicates whether the source of text should be displayed. Defaults to `true`.
- `"prompt"`: `string` The prompt content. Defaults to `You are an intelligent assistant. Please summarize the content of the dataset 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. - `"prompt"`: `string` The prompt content. Defaults to `You are an intelligent assistant. Please summarize the content of the dataset 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.
Here is the knowledge base: Here is the knowledge base:
{knowledge} {knowledge}
@ -1438,7 +1435,7 @@ Updates configurations for a specified chat assistant.
- Body: - Body:
- `"name"`: `string` - `"name"`: `string`
- `"avatar"`: `string` - `"avatar"`: `string`
- `"knowledgebases"`: `list[string]` - `"dataset_ids"`: `list[string]`
- `"llm"`: `object` - `"llm"`: `object`
- `"prompt"`: `object` - `"prompt"`: `object`
@ -1449,18 +1446,21 @@ curl --request PUT \
--url http://{address}/api/v1/chat/{chat_id} \ --url http://{address}/api/v1/chat/{chat_id} \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"name":"Test" "name":"Test"
}' }'
``` ```
#### Parameters #### Parameters
- `chat_id`: (*Path parameter*)
The ID of the chat assistant to update.
- `"name"`: (*Body parameter*), `string`, *Required* - `"name"`: (*Body parameter*), `string`, *Required*
The name of the chat assistant. The name of the chat assistant.
- `"avatar"`: (*Body parameter*) - `"avatar"`: (*Body parameter*)
Base64 encoding of the avatar. Defaults to `""`. Base64 encoding of the avatar. Defaults to `""`.
- `"knowledgebases"`: (*Body parameter*) - `"dataset_ids"`: (*Body parameter*)
The IDs of the associated datasets. Defaults to `[""]`. The IDs of the associated datasets. Defaults to `[""]`.
- `"llm"`: (*Body parameter*), `object` - `"llm"`: (*Body parameter*), `object`
The LLM settings for the chat assistant to create. When the value is `None`, a dictionary with the following values will be generated as the default. An `llm` object contains the following attributes: The LLM settings for the chat assistant to create. When the value is `None`, a dictionary with the following values will be generated as the default. An `llm` object contains the following attributes:
@ -1484,11 +1484,11 @@ curl --request PUT \
- `"variables"`: `object[]` This argument lists the variables to use in the 'System' field of **Chat Configurations**. Note that: - `"variables"`: `object[]` This argument lists the variables to use in the 'System' field of **Chat Configurations**. Note that:
- `"knowledge"` is a reserved variable, which will be replaced with the retrieved chunks. - `"knowledge"` is a reserved variable, which will be replaced with the retrieved chunks.
- All the variables in 'System' should be curly bracketed. - All the variables in 'System' should be curly bracketed.
- The default value is `[{"key": "knowledge", "optional": True}]` - 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. Defaults to `""`. - `"rerank_model"`: `string` If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used. Defaults to `""`.
- `"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. - `"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?"`. - `"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`. - `"show_quote`: `boolean` Indicates whether the source of text should be displayed. Defaults to `true`.
- `"prompt"`: `string` The prompt content. Defaults to `You are an intelligent assistant. Please summarize the content of the dataset 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. - `"prompt"`: `string` The prompt content. Defaults to `You are an intelligent assistant. Please summarize the content of the dataset 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.
Here is the knowledge base: Here is the knowledge base:
{knowledge} {knowledge}
@ -1534,15 +1534,14 @@ Deletes chat assistants by ID.
#### Request example #### Request example
```bash ```bash
# Either id or name must be provided, but not both.
curl --request DELETE \ curl --request DELETE \
--url http://{address}/api/v1/chat \ --url http://{address}/api/v1/chat \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"ids": ["test_1", "test_2"] "ids": ["test_1", "test_2"]
}' }'
}'
``` ```
#### Request parameters #### Request parameters
@ -1594,19 +1593,19 @@ curl --request GET \
#### Request parameters #### Request parameters
- `"page"`: (*Path parameter*), `integer` - `page`: (*Path parameter*), `integer`
Specifies the page on which the chat assistants will be displayed. Defaults to `1`. Specifies the page on which the chat assistants will be displayed. Defaults to `1`.
- `"page_size"`: (*Path parameter*), `integer` - `page_size`: (*Path parameter*), `integer`
The number of chat assistants on each page. Defaults to `1024`. The number of chat assistants on each page. Defaults to `1024`.
- `"orderby"`: (*Path parameter*), `string` - `orderby`: (*Path parameter*), `string`
The attribute by which the results are sorted. Available options: The attribute by which the results are sorted. Available options:
- `"create_time"` (default) - `"create_time"` (default)
- `"update_time"` - `"update_time"`
- `"desc"`: (*Path parameter*), `boolean` - `"desc"`: (*Path parameter*), `boolean`
Indicates whether the retrieved chat assistants should be sorted in descending order. Defaults to `True`. Indicates whether the retrieved chat assistants should be sorted in descending order. Defaults to `true`.
- `"id"`: (*Path parameter*), `string` - `id`: (*Path parameter*), `string`
The ID of the chat assistant to retrieve. The ID of the chat assistant to retrieve.
- `"name"`: (*Path parameter*), `string` - `name`: (*Path parameter*), `string`
The name of the chat assistant to retrieve. The name of the chat assistant to retrieve.
### Response ### Response
@ -1722,17 +1721,19 @@ curl --request POST \
--url http://{address}/api/v1/chat/{chat_id}/session \ --url http://{address}/api/v1/chat/{chat_id}/session \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"name": "new session" "name": "new session"
}' }'
``` ```
#### Request parameters #### Request parameters
- `chat_id`: (*Path parameter*)
The ID of the associated chat assistant.
- `"name"`: (*Body parameter*), `string` - `"name"`: (*Body parameter*), `string`
The name of the chat session to create. The name of the chat session to create.
### Response ### Response
Success: Success:
@ -1773,7 +1774,7 @@ Failure:
**PUT** `/api/v1/chat/{chat_id}/session/{session_id}` **PUT** `/api/v1/chat/{chat_id}/session/{session_id}`
Update a chat session Updates a chat session.
### Request ### Request
@ -1791,14 +1792,18 @@ curl --request PUT \
--url http://{address}/api/v1/chat/{chat_id}/session/{session_id} \ --url http://{address}/api/v1/chat/{chat_id}/session/{session_id} \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data '{ --data '
{
"name": "Updated session" "name": "Updated session"
}' }'
``` ```
#### Request Parameter #### Request Parameter
- `chat_id`: (*Path parameter*)
The ID of the associated chat assistant.
- `session_id`: (*Path parameter*)
The ID of the session to update.
- `"name`: (*Body Parameter), `string` - `"name`: (*Body Parameter), `string`
The name of the session to update. The name of the session to update.
@ -1840,12 +1845,14 @@ Lists sessions associated with a specified chat assistant.
```bash ```bash
curl --request GET \ curl --request GET \
--url http://{address}/api/v1/chat/{chat_id}/session?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id} \ --url http://{address}/api/v1/chat/{chat_id}/session?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id} \
--header 'Authorization: Bearer {YOUR_API_KEY}' --header 'Authorization: Bearer {YOUR_API_KEY}'
``` ```
#### Request Parameters #### Request Parameters
- `chat_id`: (*Path parameter*)
The ID of the associated chat assistant.
- `"page"`: (*Path parameter*), `integer` - `"page"`: (*Path parameter*), `integer`
Specifies the page on which the sessions will be displayed. Defaults to `1`. Specifies the page on which the sessions will be displayed. Defaults to `1`.
- `"page_size"`: (*Path parameter*), `integer` - `"page_size"`: (*Path parameter*), `integer`
@ -1855,11 +1862,11 @@ curl --request GET \
- `"create_time"` (default) - `"create_time"` (default)
- `"update_time"` - `"update_time"`
- `"desc"`: (*Path parameter*), `boolean` - `"desc"`: (*Path parameter*), `boolean`
Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `True`. Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `true`.
- `"id"`: (*Path parameter*), `string`
The ID of the chat session to retrieve.
- `"name"`: (*Path parameter*) `string` - `"name"`: (*Path parameter*) `string`
The name of the chat session to retrieve. The name of the chat session to retrieve.
- `"id"`: (*Path parameter*), `string`
The ID of the chat session to retrieve.
### Response ### Response
@ -1920,16 +1927,19 @@ Deletes sessions by ID.
```bash ```bash
# Either id or name must be provided, but not both. # Either id or name must be provided, but not both.
curl --request DELETE \ curl --request DELETE \
--url http://{address}/api/v1/chat/{chat_id}/session \ --url http://{address}/api/v1/chat/{chat_id}/session \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bear {YOUR_API_KEY}' \ --header 'Authorization: Bear {YOUR_API_KEY}' \
--data '{ --data '
{
"ids": ["test_1", "test_2"] "ids": ["test_1", "test_2"]
}' }'
``` ```
#### Request Parameters #### Request Parameters
- `chat_id`: (*Path parameter*)
The ID of the associated chat assistant.
- `"ids"`: (*Body Parameter*), `list[string]` - `"ids"`: (*Body Parameter*), `list[string]`
The IDs of the sessions to delete. If not specified, all sessions associated with the current chat assistant will be deleted. The IDs of the sessions to delete. If not specified, all sessions associated with the current chat assistant will be deleted.
@ -1979,7 +1989,8 @@ curl --request POST \
--url http://{address} /api/v1/chat/{chat_id}/completion \ --url http://{address} /api/v1/chat/{chat_id}/completion \
--header 'Content-Type: application/json' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \
--data-binary '{ --data-binary '
{
"question": "Hello!", "question": "Hello!",
"stream": true "stream": true
}' }'
@ -1987,14 +1998,16 @@ curl --request POST \
#### Request Parameters #### Request Parameters
- `chat_id`: (*Path parameter*)
The ID of the associated chat assistant.
- `"question"`: (*Body Parameter*), `string` *Required* - `"question"`: (*Body Parameter*), `string` *Required*
The question to start an AI chat. The question to start an AI chat.
- `"stream"`: (*Body Parameter*), `string` - `"stream"`: (*Body Parameter*), `string`
Indicates whether to output responses in a streaming way: Indicates whether to output responses in a streaming way:
- `True`: Enable streaming. - `true`: Enable streaming.
- `False`: (Default) Disable streaming. - `false`: (Default) Disable streaming.
- `"session_id"`: (*Body Parameter*) - `"session_id"`: (*Body Parameter*)
The ID of session. If not provided, a new session will be generated.??????????????? The ID of session. If not provided, a new session will be generated.
### Response ### Response

33
api/python_api_reference.md
View File

@ -105,16 +105,16 @@ dataset = rag_object.create_dataset(name="kb_1")
## Delete datasets ## Delete datasets
```python ```python
RAGFlow.delete_datasets(ids: list[str] = None) RAGFlow.delete_datasets(ids: list[str])
``` ```
Deletes specified datasets or all datasets in the system. Deletes specified datasets or all datasets in the system.
### Parameters ### Parameters
#### ids: `list[str]` #### ids: `list[str]`, *Required*
The IDs of the datasets to delete. Defaults to `None`. If not specified, all datasets in the system will be deleted. The IDs of the datasets to delete.
### Returns ### Returns
@ -410,7 +410,7 @@ A `Document` object contains the following attributes:
- `id`: The document ID. Defaults to `""`. - `id`: The document ID. Defaults to `""`.
- `name`: The document name. Defaults to `""`. - `name`: The document name. Defaults to `""`.
- `thumbnail`: The thumbnail image of the document. Defaults to `None`. - `thumbnail`: The thumbnail image of the document. Defaults to `None`.
- `knowledgebase_id`: The dataset ID associated with the document. Defaults to `None`. - `dataset_id`: The dataset ID associated with the document. Defaults to `None`.
- `chunk_method` The chunk method name. Defaults to `"naive"`. - `chunk_method` The chunk method name. Defaults to `"naive"`.
- `parser_config`: `ParserConfig` Configuration object for the parser. Defaults to `{"pages": [[1, 1000000]]}`. - `parser_config`: `ParserConfig` Configuration object for the parser. Defaults to `{"pages": [[1, 1000000]]}`.
- `source_type`: The source type of the document. Defaults to `"local"`. - `source_type`: The source type of the document. Defaults to `"local"`.
@ -592,7 +592,7 @@ A `Chunk` object contains the following attributes:
- `important_keywords`: `list[str]` A list of key terms or phrases tagged with the chunk. - `important_keywords`: `list[str]` A list of key terms or phrases tagged with the chunk.
- `create_time`: `str` The time when the chunk was created (added to the document). - `create_time`: `str` The time when the chunk was created (added to the document).
- `create_timestamp`: `float` The timestamp representing the creation time of the chunk, expressed in seconds since January 1, 1970. - `create_timestamp`: `float` The timestamp representing the creation time of the chunk, expressed in seconds since January 1, 1970.
- `knowledgebase_id`: `str` The ID of the associated dataset. - `dataset_id`: `str` The ID of the associated dataset.
- `document_name`: `str` The name of the associated document. - `document_name`: `str` The name of the associated document.
- `document_id`: `str` The ID of the associated document. - `document_id`: `str` The ID of the associated document.
- `available`: `bool` The chunk's availability status in the dataset. Value options: - `available`: `bool` The chunk's availability status in the dataset. Value options:
@ -740,7 +740,7 @@ chunk.update({"content":"sdfx..."})
## Retrieve chunks ## Retrieve chunks
```python ```python
RAGFlow.retrieve(question:str="", datasets:list[str]=None, document=list[str]=None, offset:int=1, limit:int=1024, similarity_threshold:float=0.2, vector_similarity_weight:float=0.3, top_k:int=1024,rerank_id:str=None,keyword:bool=False,higlight:bool=False) -> list[Chunk] RAGFlow.retrieve(question:str="", dataset_ids:list[str]=None, document_ids=list[str]=None, offset:int=1, limit:int=1024, similarity_threshold:float=0.2, vector_similarity_weight:float=0.3, top_k:int=1024,rerank_id:str=None,keyword:bool=False,higlight:bool=False) -> list[Chunk]
``` ```
Retrieves chunks from specified datasets. Retrieves chunks from specified datasets.
@ -751,11 +751,11 @@ Retrieves chunks from specified datasets.
The user query or query keywords. Defaults to `""`. The user query or query keywords. Defaults to `""`.
#### datasets: `list[str]`, *Required* #### dataset_ids: `list[str]`, *Required*
The IDs of the datasets to search from. The IDs of the datasets to search from.
#### document: `list[str]` #### document_ids: `list[str]`
The IDs of the documents to search from. Defaults to `None`. The IDs of the documents to search from. Defaults to `None`.
@ -817,7 +817,7 @@ doc = dataset.list_documents(name=name)
doc = doc[0] doc = doc[0]
dataset.async_parse_documents([doc.id]) dataset.async_parse_documents([doc.id])
for c in rag_object.retrieve(question="What's ragflow?", for c in rag_object.retrieve(question="What's ragflow?",
datasets=[dataset.id], documents=[doc.id], dataset_ids=[dataset.id], document_ids=[doc.id],
offset=1, limit=30, similarity_threshold=0.2, offset=1, limit=30, similarity_threshold=0.2,
vector_similarity_weight=0.3, vector_similarity_weight=0.3,
top_k=1024 top_k=1024
@ -839,7 +839,7 @@ Chat Assistant Management
RAGFlow.create_chat( RAGFlow.create_chat(
name: str, name: str,
avatar: str = "", avatar: str = "",
knowledgebases: list[str] = [], dataset_ids: list[str] = [],
llm: Chat.LLM = None, llm: Chat.LLM = None,
prompt: Chat.Prompt = None prompt: Chat.Prompt = None
) -> Chat ) -> Chat
@ -857,7 +857,7 @@ The name of the chat assistant.
Base64 encoding of the avatar. Defaults to `""`. Base64 encoding of the avatar. Defaults to `""`.
#### knowledgebases: `list[str]` #### dataset_ids: `list[str]`
The IDs of the associated datasets. Defaults to `[""]`. The IDs of the associated datasets. Defaults to `[""]`.
@ -914,7 +914,7 @@ datasets = rag_object.list_datasets(name="kb_1")
dataset_ids = [] dataset_ids = []
for dataset in datasets: for dataset in datasets:
dataset_ids.append(dataset.id) dataset_ids.append(dataset.id)
assistant = rag_object.create_chat("Miss R", knowledgebases=dataset_ids) assistant = rag_object.create_chat("Miss R", dataset_ids=dataset_ids)
``` ```
--- ---
@ -935,7 +935,7 @@ A dictionary representing the attributes to update, with the following keys:
- `"name"`: `str` The name of the chat assistant to update. - `"name"`: `str` The name of the chat assistant to update.
- `"avatar"`: `str` Base64 encoding of the avatar. Defaults to `""` - `"avatar"`: `str` Base64 encoding of the avatar. Defaults to `""`
- `"knowledgebases"`: `list[str]` The datasets to update. - `"dataset_ids"`: `list[str]` The datasets to update.
- `"llm"`: `dict` The LLM settings: - `"llm"`: `dict` The LLM settings:
- `"model_name"`, `str` The chat model name. - `"model_name"`, `str` The chat model name.
- `"temperature"`, `float` Controls the randomness of the model's predictions. - `"temperature"`, `float` Controls the randomness of the model's predictions.
@ -969,7 +969,8 @@ from ragflow import RAGFlow
rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380") rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
datasets = rag_object.list_datasets(name="kb_1") datasets = rag_object.list_datasets(name="kb_1")
assistant = rag_object.create_chat("Miss R", knowledgebases=datasets) dataset_id = datasets[0].id
assistant = rag_object.create_chat("Miss R", dataset_ids=[dataset_id])
assistant.update({"name": "Stefan", "llm": {"temperature": 0.8}, "prompt": {"top_n": 8}}) assistant.update({"name": "Stefan", "llm": {"temperature": 0.8}, "prompt": {"top_n": 8}})
``` ```
@ -1238,7 +1239,7 @@ assistant.delete_sessions(ids=["id_1","id_2"])
--- ---
## Chat ## Converse
```python ```python
Session.ask(question: str, stream: bool = False) -> Optional[Message, iter[Message]] Session.ask(question: str, stream: bool = False) -> Optional[Message, iter[Message]]
@ -1290,7 +1291,7 @@ A list of `Chunk` objects representing references to the message, each containin
The name of the referenced document. The name of the referenced document.
- `position` `list[str]` - `position` `list[str]`
The location information of the chunk within the referenced document. The location information of the chunk within the referenced document.
- `knowledgebase_id` `str` - `dataset_id` `str`
The ID of the dataset to which the referenced document belongs. The ID of the dataset to which the referenced document belongs.
- `similarity` `float` - `similarity` `float`
A composite similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity. A composite similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity.