AI/ragflow
1
0
Fork 0
mirror of https://git.mirrors.martin98.com/https://github.com/infiniflow/ragflow.git synced 2025-08-12 18:39:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

API Documentation (#1526)

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

Adds the doc for the newly added API method.

### Type of change


- [x] Documentation Update
This commit is contained in:
cecilia-uu 2024-07-16 18:07:17 +08:00 committed by GitHub
parent 13389be3f4
commit 9e1421b77c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 352 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
api/apps/dataset_api.py
View File

@ -768,7 +768,10 @@ def show_parsing_status(dataset_id, document_id):
_, doc = DocumentService.get_by_id(document_id) # get doc object _, doc = DocumentService.get_by_id(document_id) # get doc object
doc_attributes = doc.to_dict() doc_attributes = doc.to_dict()
return construct_json_result(data={"progress": doc_attributes["progress"], "status": doc_attributes["status"]}, code=RetCode.SUCCESS) return construct_json_result(
data={"progress": doc_attributes["progress"], "status": TaskStatus(doc_attributes["status"]).name},
code=RetCode.SUCCESS
)
except Exception as e: except Exception as e:
return construct_error_response(e) return construct_error_response(e)
# ----------------------------list the chunks of the file----------------------------------------------------- # ----------------------------list the chunks of the file-----------------------------------------------------

348
docs/references/ragflow_api.md
View File

@ -428,7 +428,7 @@ This method deletes documents for a specific user.
## List documents ## List documents
This method deletes documents for a specific user. This method lists documents for a specific user.
### Request ### Request
@ -532,4 +532,350 @@ This method deletes documents for a specific user.
"message": "IndexError('Offset is out of the valid range.')" "message": "IndexError('Offset is out of the valid range.')"
} }
``` ```
## Update the details of the document
This method updates the details, including the name, enable and template type of a specific document for a specific user.
### Request
#### Request URI
| Method | Request URI |
|--------|-------------------------------------------------|
| PUT | `/dataset/{dataset_id}/documents/{document_id}` |
#### Request parameter
| Name | Type | Required | Description |
|--------------|--------|----------|------------------------------------------------------------------------------------------------------------|
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
| `document_id` | string | Yes | The ID of the document. Call ['GET' /document](#list-documents) to retrieve the ID. |
### Response
### Successful Response
```json
{
"code": 0,
"data": {
"chunk_num": 0,
"create_date": "Mon, 15 Jul 2024 16:55:03 GMT",
"create_time": 1721033703914,
"created_by": "b48110a0286411ef994a3043d7ee537e",
"id": "ed30167a428711efab193043d7ee537e",
"kb_id": "ed2d8770428711efaf583043d7ee537e",
"location": "test.txt",
"name": "new_name.txt",
"parser_config": {
"pages": [
[1, 1000000]
]
},
"parser_id": "naive",
"process_begin_at": null,
"process_duration": 0.0,
"progress": 0.0,
"progress_msg": "",
"run": "0",
"size": 14,
"source_type": "local",
"status": "1",
"thumbnail": null,
"token_num": 0,
"type": "doc",
"update_date": "Mon, 15 Jul 2024 16:55:03 GMT",
"update_time": 1721033703934
},
"message": "Success"
}
```
### Response for updating a document which does not exist.
```json
{
"code": 101,
"message": "This document weird_doc_id cannot be found!"
}
```
### Response for updating a document without giving parameters.
```json
{
"code": 102,
"message": "Please input at least one parameter that you want to update!"
}
```
### Response for updating a document in the nonexistent dataset.
```json
{
"code": 102,
"message": "This dataset fake_dataset_id cannot be found!"
}
```
### Response for updating a document with an extension name that differs from its original.
```json
{
"code": 101,
"data": false,
"message": "The extension of file cannot be changed"
}
```
### Response for updating a document with a duplicate name.
```json
{
"code": 101,
"message": "Duplicated document name in the same dataset."
}
```
### Response for updating a document's illegal parameter.
```json
{
"code": 101,
"message": "illegal_parameter is an illegal parameter."
}
```
### Response for updating a document's name without its name value.
```json
{
"code": 102,
"message": "There is no new name."
}
```
### Response for updating a document's with giving illegal enable's value.
```json
{
"code": 102,
"message": "Illegal value '?' for 'enable' field."
}
```
## Download the document
This method downloads a specific document for a specific user.
### Request
#### Request URI
| Method | Request URI |
|--------|-------------------------------------------------|
| GET | `/dataset/{dataset_id}/documents/{document_id}` |
#### Request parameter
| Name | Type | Required | Description |
|--------------|--------|----------|------------------------------------------------------------------------------------------------------------|
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
| `document_id` | string | Yes | The ID of the document. Call ['GET' /document](#list-documents) to retrieve the ID. |
### Response
### Successful Response
```json
{
"code": "0",
"data": "b'test\\ntest\\ntest'"
}
```
### Response for downloading a document which does not exist.
```json
{
"code": 101,
"message": "This document 'imagination.txt' cannot be found!"
}
```
### Response for downloading a document in the nonexistent dataset.
```json
{
"code": 102,
"message": "This dataset 'imagination' cannot be found!"
}
```
### Response for downloading an empty document.
```json
{
"code": 102,
"message": "This file is empty."
}
```
## Start parsing a document
This method enables a specific document to start parsing for a specific user.
### Request
#### Request URI
| Method | Request URI |
|--------|--------------------------------------------------------|
| POST | `/dataset/{dataset_id}/documents/{document_id}/status` |
#### Request parameter
| Name | Type | Required | Description |
|--------------|--------|----------|------------------------------------------------------------------------------------------------------------|
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
| `document_id` | string | Yes | The ID of the document. Call ['GET' /document](#list-documents) to retrieve the ID. |
### Response
### Successful Response
```json
{
"code": 0,
"message": ""
}
```
### Response for parsing a document which does not exist.
```json
{
"code": 101,
"message": "This document 'imagination.txt' cannot be found!"
}
```
### Response for parsing a document in the nonexistent dataset.
```json
{
"code": 102,
"message": "This dataset 'imagination.txt' cannot be found!"
}
```
### Response for parsing an empty document.
```json
{
"code": 0,
"message": "Empty data in the document: empty.txt;"
}
```
## Start parsing multiple documents
This method enables multiple documents, including all documents in the specific dataset or specified documents, to start parsing for a specific user.
### Request
#### Request URI
| Method | Request URI |
|--------|-------------------------------------------------------|
| POST | `/dataset/{dataset_id}/documents/status` |
#### Request parameter
| Name | Type | Required | Description |
|--------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------|
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
| `document_id` | string | Yes | The ID of the document. Call ['GET' /document](#list-documents) to retrieve the ID. |
| `doc_ids` | list | No | The document IDs of the documents that the user would like to parse. Default: None, means all documents in the specified dataset. |
### Response
### Successful Response
```json
{
"code": 0,
"data": true,
"message": ""
}
```
### Response for parsing documents which does not exist.
```json
{
"code": 101,
"message": "This document 'imagination.txt' cannot be found!"
}
```
### Response for parsing documents in the nonexistent dataset.
```json
{
"code": 102,
"message": "This dataset 'imagination' cannot be found!"
}
```
### Response for parsing documents, one of which is empty.
```json
{
"code": 0,
"data": true,
"message": "Empty data in the document: empty.txt; "
}
```
## Show the parsing status of the document
This method shows the parsing status of the document for a specific user.
### Request
#### Request URI
| Method | Request URI |
|--------|-------------------------------------------------------|
| GET | `/dataset/{dataset_id}/documents/status` |
#### Request parameter
| Name | Type | Required | Description |
|--------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------|
| `dataset_id` | string | Yes | The ID of the dataset. Call ['GET' /dataset](#create-dataset) to retrieve the ID. |
| `document_id` | string | Yes | The ID of the document. Call ['GET' /document](#list-documents) to retrieve the ID. |
### Response
### Successful Response
```json
{
"code": 0,
"data": {
"progress": 0.0,
"status": "RUNNING"
},
"message": "success"
}
```
### Response for showing the parsing status of a document which does not exist.
```json
{
"code": 102,
"message": "This document: 'imagination.txt' is not a valid document."
}
```
### Response for showing the parsing status of a document in the nonexistent dataset.
```json
{
"code": 102,
"message": "This dataset 'imagination' cannot be found!"
}
```

3
sdk/python/test/test_document.py
View File

@ -555,7 +555,6 @@ class TestFile(TestSdk):
"illegal_parameter": "0" "illegal_parameter": "0"
} }
update_res = ragflow.update_file(created_res_id, doc_id, **params) update_res = ragflow.update_file(created_res_id, doc_id, **params)
assert (update_res["code"] == RetCode.ARGUMENT_ERROR and assert (update_res["code"] == RetCode.ARGUMENT_ERROR and
update_res["message"] == "illegal_parameter is an illegal parameter.") update_res["message"] == "illegal_parameter is an illegal parameter.")
@ -969,7 +968,7 @@ class TestFile(TestSdk):
assert res["code"] == RetCode.SUCCESS and res["message"] == "" assert res["code"] == RetCode.SUCCESS and res["message"] == ""
# show status # show status
status_res = ragflow.show_parsing_status(created_res_id, doc_id) status_res = ragflow.show_parsing_status(created_res_id, doc_id)
assert status_res["code"] == RetCode.SUCCESS and status_res["data"]["status"] == "1" assert status_res["code"] == RetCode.SUCCESS and status_res["data"]["status"] == "RUNNING"
def test_show_status_nonexistent_document(self): def test_show_status_nonexistent_document(self):
""" """