From 571498ff866201aed11c21873e7192344ee22554 Mon Sep 17 00:00:00 2001 From: RAGFlow Curator Date: Thu, 23 Oct 2025 11:34:43 +0000 Subject: [PATCH] Synchronize documentation. --- website/docs/configurations.md | 4 +- website/docs/develop/build_docker_image.mdx | 2 +- website/docs/faq.mdx | 34 +- website/docs/guides/chat/start_chat.md | 2 +- .../dataset/configure_knowledge_base.md | 4 +- .../docs/guides/dataset/select_pdf_parser.md | 23 + website/docs/guides/manage_files.md | 2 +- .../docs/guides/manage_users_and_services.md | 2 +- website/docs/guides/tracing.mdx | 2 +- website/docs/guides/upgrade_ragflow.mdx | 12 +- website/docs/quickstart.mdx | 12 +- website/docs/references/glossary.mdx | 2 +- website/docs/release_notes.md | 21 +- .../version-v0.21.1/_category_.json | 8 + .../version-v0.21.1/configurations.md | 229 + .../contribution/_category_.json | 8 + .../contribution/contributing.md | 57 + .../version-v0.21.1/develop/_category_.json | 8 + .../develop/acquire_ragflow_api_key.md | 18 + .../develop/build_docker_image.mdx | 92 + .../develop/launch_ragflow_from_source.md | 145 + .../develop/mcp/_category_.json | 8 + .../develop/mcp/launch_mcp_server.md | 212 + .../develop/mcp/mcp_client_example.md | 241 + .../version-v0.21.1/develop/mcp/mcp_tools.md | 12 + .../develop/switch_doc_engine.md | 34 + .../versioned_docs/version-v0.21.1/faq.mdx | 536 +++ .../version-v0.21.1/guides/_category_.json | 8 + .../guides/agent/_category_.json | 8 + .../agent_component_reference/_category_.json | 8 + .../agent/agent_component_reference/agent.mdx | 233 + .../await_response.mdx | 57 + .../agent/agent_component_reference/begin.mdx | 80 + .../agent_component_reference/categorize.mdx | 109 + .../chunker_title.md | 40 + .../chunker_token.md | 43 + .../agent/agent_component_reference/code.mdx | 205 + .../agent_component_reference/execute_sql.md | 79 + .../agent_component_reference/indexer.md | 29 + .../agent_component_reference/iteration.mdx | 65 + .../agent_component_reference/message.mdx | 21 + .../agent/agent_component_reference/parser.md | 17 + .../agent_component_reference/retrieval.mdx | 145 + .../agent_component_reference/switch.mdx | 50 + .../text_processing.mdx | 38 + .../agent_component_reference/transformer.md | 80 + .../guides/agent/agent_introduction.md | 51 + .../agent/best_practices/_category_.json | 8 + .../accelerate_agent_question_answering.md | 58 + .../guides/agent/embed_agent_into_webpage.md | 15 + .../guides/agent/sandbox_quickstart.md | 116 + .../version-v0.21.1/guides/ai_search.md | 31 + .../guides/chat/_category_.json | 8 + .../chat/best_practices/_category_.json | 8 + .../accelerate_question_answering.mdx | 48 + .../guides/chat/implement_deep_research.md | 28 + .../guides/chat/set_chat_variables.md | 110 + .../version-v0.21.1/guides/chat/start_chat.md | 116 + .../guides/dataset/_category_.json | 8 + .../dataset/autokeyword_autoquestion.mdx | 72 + .../dataset/best_practices/_category_.json | 8 + .../accelerate_doc_indexing.mdx | 19 + .../dataset/configure_knowledge_base.md | 152 + .../dataset/construct_knowledge_graph.md | 102 + .../guides/dataset/enable_excel2html.md | 42 + .../guides/dataset/enable_raptor.md | 93 + .../dataset/extract_table_of_contents.md | 39 + .../guides/dataset/run_retrieval_test.md | 95 + .../guides/dataset/select_pdf_parser.md | 76 + .../guides/dataset/set_metadata.md | 32 + .../guides/dataset/set_page_rank.md | 39 + .../guides/dataset/use_tag_sets.md | 103 + .../version-v0.21.1/guides/manage_files.md | 90 + .../guides/manage_users_and_services.md | 390 ++ .../migration/migrate_from_docker_compose.md | 108 + .../guides/models/_category_.json | 8 + .../guides/models/deploy_local_llm.mdx | 353 ++ .../guides/models/llm_api_key_setup.md | 48 + .../guides/run_health_check.md | 109 + .../guides/team/_category_.json | 8 + .../guides/team/join_or_leave_team.md | 37 + .../guides/team/manage_team_members.md | 42 + .../guides/team/share_agents.md | 19 + .../guides/team/share_chat_assistant.md | 8 + .../guides/team/share_knowledge_bases.md | 18 + .../guides/team/share_model.md | 8 + .../version-v0.21.1/guides/tracing.mdx | 72 + .../guides/upgrade_ragflow.mdx | 123 + .../version-v0.21.1/quickstart.mdx | 372 ++ .../references/_category_.json | 8 + .../version-v0.21.1/references/glossary.mdx | 26 + .../references/http_api_reference.md | 4236 +++++++++++++++++ .../references/python_api_reference.md | 1962 ++++++++ .../references/supported_models.mdx | 81 + .../version-v0.21.1/release_notes.md | 758 +++ .../version-v0.21.1-sidebars.json | 3 + website/versions.json | 2 +- 97 files changed, 13381 insertions(+), 30 deletions(-) create mode 100644 website/versioned_docs/version-v0.21.1/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/configurations.md create mode 100644 website/versioned_docs/version-v0.21.1/contribution/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/contribution/contributing.md create mode 100644 website/versioned_docs/version-v0.21.1/develop/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/develop/acquire_ragflow_api_key.md create mode 100644 website/versioned_docs/version-v0.21.1/develop/build_docker_image.mdx create mode 100644 website/versioned_docs/version-v0.21.1/develop/launch_ragflow_from_source.md create mode 100644 website/versioned_docs/version-v0.21.1/develop/mcp/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/develop/mcp/launch_mcp_server.md create mode 100644 website/versioned_docs/version-v0.21.1/develop/mcp/mcp_client_example.md create mode 100644 website/versioned_docs/version-v0.21.1/develop/mcp/mcp_tools.md create mode 100644 website/versioned_docs/version-v0.21.1/develop/switch_doc_engine.md create mode 100644 website/versioned_docs/version-v0.21.1/faq.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/agent.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/await_response.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/begin.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/categorize.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_title.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_token.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/code.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/execute_sql.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/indexer.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/iteration.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/message.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/parser.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/retrieval.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/switch.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/text_processing.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/transformer.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/agent_introduction.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/best_practices/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/best_practices/accelerate_agent_question_answering.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/embed_agent_into_webpage.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/agent/sandbox_quickstart.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/ai_search.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/chat/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/chat/best_practices/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/chat/best_practices/accelerate_question_answering.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/chat/implement_deep_research.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/chat/set_chat_variables.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/chat/start_chat.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/autokeyword_autoquestion.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/accelerate_doc_indexing.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/configure_knowledge_base.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/construct_knowledge_graph.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/enable_excel2html.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/enable_raptor.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/extract_table_of_contents.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/run_retrieval_test.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/select_pdf_parser.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/set_metadata.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/set_page_rank.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/dataset/use_tag_sets.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/manage_files.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/manage_users_and_services.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/migration/migrate_from_docker_compose.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/models/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/models/deploy_local_llm.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/models/llm_api_key_setup.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/run_health_check.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/team/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/guides/team/join_or_leave_team.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/team/manage_team_members.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/team/share_agents.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/team/share_chat_assistant.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/team/share_knowledge_bases.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/team/share_model.md create mode 100644 website/versioned_docs/version-v0.21.1/guides/tracing.mdx create mode 100644 website/versioned_docs/version-v0.21.1/guides/upgrade_ragflow.mdx create mode 100644 website/versioned_docs/version-v0.21.1/quickstart.mdx create mode 100644 website/versioned_docs/version-v0.21.1/references/_category_.json create mode 100644 website/versioned_docs/version-v0.21.1/references/glossary.mdx create mode 100644 website/versioned_docs/version-v0.21.1/references/http_api_reference.md create mode 100644 website/versioned_docs/version-v0.21.1/references/python_api_reference.md create mode 100644 website/versioned_docs/version-v0.21.1/references/supported_models.mdx create mode 100644 website/versioned_docs/version-v0.21.1/release_notes.md create mode 100644 website/versioned_sidebars/version-v0.21.1-sidebars.json diff --git a/website/docs/configurations.md b/website/docs/configurations.md index e09e6ff..973bdbc 100644 --- a/website/docs/configurations.md +++ b/website/docs/configurations.md @@ -99,8 +99,8 @@ RAGFlow utilizes MinIO as its object storage solution, leveraging its scalabilit - `RAGFLOW-IMAGE` The Docker image edition. Available editions: - - `infiniflow/ragflow:v0.21.0-slim` (default): The RAGFlow Docker image without embedding models. - - `infiniflow/ragflow:v0.21.0`: The RAGFlow Docker image with embedding models including: + - `infiniflow/ragflow:v0.21.1-slim` (default): The RAGFlow Docker image without embedding models. + - `infiniflow/ragflow:v0.21.1`: The RAGFlow Docker image with embedding models including: - Built-in embedding models: - `BAAI/bge-large-zh-v1.5` - `maidalun1020/bce-embedding-base_v1` diff --git a/website/docs/develop/build_docker_image.mdx b/website/docs/develop/build_docker_image.mdx index 47009a9..16b5e86 100644 --- a/website/docs/develop/build_docker_image.mdx +++ b/website/docs/develop/build_docker_image.mdx @@ -77,7 +77,7 @@ After building the infiniflow/ragflow:nightly-slim image, you are ready to launc 1. Edit Docker Compose Configuration -Open the `docker/.env` file. Find the `RAGFLOW_IMAGE` setting and change the image reference from `infiniflow/ragflow:v0.21.0-slim` to `infiniflow/ragflow:nightly-slim` to use the pre-built image. +Open the `docker/.env` file. Find the `RAGFLOW_IMAGE` setting and change the image reference from `infiniflow/ragflow:v0.21.1-slim` to `infiniflow/ragflow:nightly-slim` to use the pre-built image. 2. Launch the Service diff --git a/website/docs/faq.mdx b/website/docs/faq.mdx index ff3a17a..cee1179 100644 --- a/website/docs/faq.mdx +++ b/website/docs/faq.mdx @@ -30,17 +30,17 @@ The "garbage in garbage out" status quo remains unchanged despite the fact that Each RAGFlow release is available in two editions: -- **Slim edition**: excludes built-in embedding models and is identified by a **-slim** suffix added to the version name. Example: `infiniflow/ragflow:v0.21.0-slim` -- **Full edition**: includes built-in embedding models and has no suffix added to the version name. Example: `infiniflow/ragflow:v0.21.0` +- **Slim edition**: excludes built-in embedding models and is identified by a **-slim** suffix added to the version name. Example: `infiniflow/ragflow:v0.21.1-slim` +- **Full edition**: includes built-in embedding models and has no suffix added to the version name. Example: `infiniflow/ragflow:v0.21.1` --- ### Which embedding models can be deployed locally? -RAGFlow offers two Docker image editions, `v0.21.0-slim` and `v0.21.0`: +RAGFlow offers two Docker image editions, `v0.21.1-slim` and `v0.21.1`: -- `infiniflow/ragflow:v0.21.0-slim` (default): The RAGFlow Docker image without embedding models. -- `infiniflow/ragflow:v0.21.0`: The RAGFlow Docker image with the following built-in embedding models: +- `infiniflow/ragflow:v0.21.1-slim` (default): The RAGFlow Docker image without embedding models. +- `infiniflow/ragflow:v0.21.1`: The RAGFlow Docker image with the following built-in embedding models: - `BAAI/bge-large-zh-v1.5` - `maidalun1020/bce-embedding-base_v1` @@ -510,3 +510,27 @@ See [here](./guides/agent/best_practices/accelerate_agent_question_answering.md) --- +### How to use MinerU to parse PDF documents? + +MinerU PDF document parsing is available starting from v0.21.1. To use this feature, follow these steps: + +1. Before deploying ragflow-server, update your **docker/.env** file: + - Enable `HF_ENDPOINT=https://hf-mirror.com` + - Add a MinerU entry: `MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru` + +2. Start the ragflow-server and run the following commands inside the container: + +```bash +mkdir uv_tools +cd uv_tools +uv venv .venv +source .venv/bin/activate +uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple +``` + +3. Restart the ragflow-server. +4. In the web UI, navigate to the **Configuration** page of your dataset. Click **Built-in** in the **Ingestion pipeline** section, select a chunking method from the **Built-in** dropdown, which supports PDF parsing, and slect **MinerU** in **PDF parser**. +5. If you use a custom ingestion pipeline instead, you must also complete the first three steps before selecting **MinerU** in the **Parsing method** section of the **Parser** component. + + + diff --git a/website/docs/guides/chat/start_chat.md b/website/docs/guides/chat/start_chat.md index 99b0cf6..e3581aa 100644 --- a/website/docs/guides/chat/start_chat.md +++ b/website/docs/guides/chat/start_chat.md @@ -48,7 +48,7 @@ You start an AI conversation by creating an assistant. - If no target language is selected, the system will search only in the language of your query, which may cause relevant information in other languages to be missed. - **Variable** refers to the variables (keys) to be used in the system prompt. `{knowledge}` is a reserved variable. Click **Add** to add more variables for the system prompt. - If you are uncertain about the logic behind **Variable**, leave it *as-is*. - - As of v0.21.0, if you add custom variables here, the only way you can pass in their values is to call: + - As of v0.21.1, if you add custom variables here, the only way you can pass in their values is to call: - HTTP method [Converse with chat assistant](../../references/http_api_reference.md#converse-with-chat-assistant), or - Python method [Converse with chat assistant](../../references/python_api_reference.md#converse-with-chat-assistant). diff --git a/website/docs/guides/dataset/configure_knowledge_base.md b/website/docs/guides/dataset/configure_knowledge_base.md index a57ca03..ef54831 100644 --- a/website/docs/guides/dataset/configure_knowledge_base.md +++ b/website/docs/guides/dataset/configure_knowledge_base.md @@ -59,7 +59,7 @@ You can also change a file's chunking method on the **Files** page. ![change chunking method](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/change_chunking_method.jpg)
- From v0.21.0 onward, RAGFlow supports ingestion pipeline for customized data ingestion and cleansing workflows. + From v0.21.1 onward, RAGFlow supports ingestion pipeline for customized data ingestion and cleansing workflows. To use a customized data pipeline: @@ -138,7 +138,7 @@ See [Run retrieval test](./run_retrieval_test.md) for details. ## Search for dataset -As of RAGFlow v0.21.0, the search feature is still in a rudimentary form, supporting only dataset search by name. +As of RAGFlow v0.21.1, the search feature is still in a rudimentary form, supporting only dataset search by name. ![search dataset](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/search_datasets.jpg) diff --git a/website/docs/guides/dataset/select_pdf_parser.md b/website/docs/guides/dataset/select_pdf_parser.md index b9af551..1781d76 100644 --- a/website/docs/guides/dataset/select_pdf_parser.md +++ b/website/docs/guides/dataset/select_pdf_parser.md @@ -35,8 +35,31 @@ RAGFlow isn't one-size-fits-all. It is built for flexibility and supports deeper - DeepDoc: (Default) The default visual model performing OCR, TSR, and DLR tasks on PDFs, which can be time-consuming. - Naive: Skip OCR, TSR, and DLR tasks if *all* your PDFs are plain text. + - MinerU: An experimental feature. - A third-party visual model provided by a specific model provider. +:::danger IMPORTANG +MinerU PDF document parsing is available starting from v0.21.1. To use this feature, follow these steps: + +1. Before deploying ragflow-server, update your **docker/.env** file: + - Enable `HF_ENDPOINT=https://hf-mirror.com` + - Add a MinerU entry: `MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru` + +2. Start the ragflow-server and run the following commands inside the container: + +```bash +mkdir uv_tools +cd uv_tools +uv venv .venv +source .venv/bin/activate +uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple +``` + +3. Restart the ragflow-server. +4. In the web UI, navigate to the **Configuration** page of your dataset. Click **Built-in** in the **Ingestion pipeline** section, select a chunking method from the **Built-in** dropdown, which supports PDF parsing, and slect **MinerU** in **PDF parser**. +5. If you use a custom ingestion pipeline instead, you must also complete the first three steps before selecting **MinerU** in the **Parsing method** section of the **Parser** component. +::: + :::caution WARNING Third-party visual models are marked **Experimental**, because we have not fully tested these models for the aforementioned data extraction tasks. ::: diff --git a/website/docs/guides/manage_files.md b/website/docs/guides/manage_files.md index 3a587b8..127eaf5 100644 --- a/website/docs/guides/manage_files.md +++ b/website/docs/guides/manage_files.md @@ -87,4 +87,4 @@ RAGFlow's file management allows you to download an uploaded file: ![download_file](https://github.com/infiniflow/ragflow/assets/93570324/cf3b297f-7d9b-4522-bf5f-4f45743e4ed5) -> As of RAGFlow v0.21.0, bulk download is not supported, nor can you download an entire folder. +> As of RAGFlow v0.21.1, bulk download is not supported, nor can you download an entire folder. diff --git a/website/docs/guides/manage_users_and_services.md b/website/docs/guides/manage_users_and_services.md index f964430..02e569a 100644 --- a/website/docs/guides/manage_users_and_services.md +++ b/website/docs/guides/manage_users_and_services.md @@ -46,7 +46,7 @@ The Admin CLI and Admin Service form a client-server architectural suite for RAG 2. Install ragflow-cli. ```bash - pip install ragflow-cli==0.21.0 + pip install ragflow-cli==0.21.1 ``` 3. Launch the CLI client: diff --git a/website/docs/guides/tracing.mdx b/website/docs/guides/tracing.mdx index a96aed0..37e5243 100644 --- a/website/docs/guides/tracing.mdx +++ b/website/docs/guides/tracing.mdx @@ -18,7 +18,7 @@ RAGFlow ships with a built-in [Langfuse](https://langfuse.com) integration so th Langfuse stores traces, spans and prompt payloads in a purpose-built observability backend and offers filtering and visualisations on top. :::info NOTE -• RAGFlow **≥ 0.21.0** (contains the Langfuse connector) +• RAGFlow **≥ 0.21.1** (contains the Langfuse connector) • A Langfuse workspace (cloud or self-hosted) with a _Project Public Key_ and _Secret Key_ ::: diff --git a/website/docs/guides/upgrade_ragflow.mdx b/website/docs/guides/upgrade_ragflow.mdx index 950b6f7..166efde 100644 --- a/website/docs/guides/upgrade_ragflow.mdx +++ b/website/docs/guides/upgrade_ragflow.mdx @@ -66,10 +66,10 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag git clone https://github.com/infiniflow/ragflow.git ``` -2. Switch to the latest, officially published release, e.g., `v0.21.0`: +2. Switch to the latest, officially published release, e.g., `v0.21.1`: ```bash - git checkout -f v0.21.0 + git checkout -f v0.21.1 ``` 3. Update **ragflow/docker/.env**: @@ -83,14 +83,14 @@ To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker imag ```bash -RAGFLOW_IMAGE=infiniflow/ragflow:v0.21.0-slim +RAGFLOW_IMAGE=infiniflow/ragflow:v0.21.1-slim ``` ```bash -RAGFLOW_IMAGE=infiniflow/ragflow:v0.21.0 +RAGFLOW_IMAGE=infiniflow/ragflow:v0.21.1 ``` @@ -114,10 +114,10 @@ No, you do not need to. Upgrading RAGFlow in itself will *not* remove your uploa 1. From an environment with Internet access, pull the required Docker image. 2. Save the Docker image to a **.tar** file. ```bash - docker save -o ragflow.v0.21.0.tar infiniflow/ragflow:v0.21.0 + docker save -o ragflow.v0.21.1.tar infiniflow/ragflow:v0.21.1 ``` 3. Copy the **.tar** file to the target server. 4. Load the **.tar** file into Docker: ```bash - docker load -i ragflow.v0.21.0.tar + docker load -i ragflow.v0.21.1.tar ``` diff --git a/website/docs/quickstart.mdx b/website/docs/quickstart.mdx index 3d52f62..3d1ccf9 100644 --- a/website/docs/quickstart.mdx +++ b/website/docs/quickstart.mdx @@ -44,7 +44,7 @@ This section provides instructions on setting up the RAGFlow server on Linux. If `vm.max_map_count`. This value sets the maximum number of memory map areas a process may have. Its default value is 65530. While most applications require fewer than a thousand maps, reducing this value can result in abnormal behaviors, and the system will throw out-of-memory errors when a process reaches the limitation. - RAGFlow v0.21.0 uses Elasticsearch or [Infinity](https://github.com/infiniflow/infinity) for multiple recall. Setting the value of `vm.max_map_count` correctly is crucial to the proper functioning of the Elasticsearch component. + RAGFlow v0.21.1 uses Elasticsearch or [Infinity](https://github.com/infiniflow/infinity) for multiple recall. Setting the value of `vm.max_map_count` correctly is crucial to the proper functioning of the Elasticsearch component. :80`. + +:::tip NOTE +Updates to the above configurations require a reboot of all containers to take effect: + +```bash +docker compose -f docker/docker-compose.yml up -d +``` + +::: + +## Docker Compose + +- **docker-compose.yml** + Sets up environment for RAGFlow and its dependencies. +- **docker-compose-base.yml** + Sets up environment for RAGFlow's dependencies: Elasticsearch/[Infinity](https://github.com/infiniflow/infinity), MySQL, MinIO, and Redis. + +:::danger IMPORTANT +We do not actively maintain **docker-compose-CN-oc9.yml**, **docker-compose-gpu-CN-oc9.yml**, or **docker-compose-gpu.yml**, so use them at your own risk. However, you are welcome to file a pull request to improve any of them. +::: + +## Docker environment variables + +The [.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env) file contains important environment variables for Docker. + +### Elasticsearch + +- `STACK_VERSION` + The version of Elasticsearch. Defaults to `8.11.3` +- `ES_PORT` + The port used to expose the Elasticsearch service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `1200`. +- `ELASTIC_PASSWORD` + The password for Elasticsearch. + +### Kibana + +- `KIBANA_PORT` + The port used to expose the Kibana service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `6601`. +- `KIBANA_USER` + The username for Kibana. Defaults to `rag_flow`. +- `KIBANA_PASSWORD` + The password for Kibana. Defaults to `infini_rag_flow`. + +### Resource management + +- `MEM_LIMIT` + The maximum amount of the memory, in bytes, that *a specific* Docker container can use while running. Defaults to `8073741824`. + +### MySQL + +- `MYSQL_PASSWORD` + The password for MySQL. +- `MYSQL_PORT` + The port used to expose the MySQL service to the host machine, allowing **external** access to the MySQL database running inside the Docker container. Defaults to `5455`. + +### MinIO + +RAGFlow utilizes MinIO as its object storage solution, leveraging its scalability to store and manage all uploaded files. + +- `MINIO_CONSOLE_PORT` + The port used to expose the MinIO console interface to the host machine, allowing **external** access to the web-based console running inside the Docker container. Defaults to `9001` +- `MINIO_PORT` + The port used to expose the MinIO API service to the host machine, allowing **external** access to the MinIO object storage service running inside the Docker container. Defaults to `9000`. +- `MINIO_USER` + The username for MinIO. +- `MINIO_PASSWORD` + The password for MinIO. + +### Redis + +- `REDIS_PORT` + The port used to expose the Redis service to the host machine, allowing **external** access to the Redis service running inside the Docker container. Defaults to `6379`. +- `REDIS_PASSWORD` + The password for Redis. + +### RAGFlow + +- `SVR_HTTP_PORT` + The port used to expose RAGFlow's HTTP API service to the host machine, allowing **external** access to the service running inside the Docker container. Defaults to `9380`. +- `RAGFLOW-IMAGE` + The Docker image edition. Available editions: + + - `infiniflow/ragflow:v0.21.1-slim` (default): The RAGFlow Docker image without embedding models. + - `infiniflow/ragflow:v0.21.1`: The RAGFlow Docker image with embedding models including: + - Built-in embedding models: + - `BAAI/bge-large-zh-v1.5` + - `maidalun1020/bce-embedding-base_v1` + + +:::tip NOTE +If you cannot download the RAGFlow Docker image, try the following mirrors. + +- For the `nightly-slim` edition: + - `RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly-slim` or, + - `RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:nightly-slim`. +- For the `nightly` edition: + - `RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:nightly` or, + - `RAGFLOW_IMAGE=registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow:nightly`. +::: + +### Timezone + +- `TIMEZONE` + The local time zone. Defaults to `'Asia/Shanghai'`. + +### Hugging Face mirror site + +- `HF_ENDPOINT` + The mirror site for huggingface.co. It is disabled by default. You can uncomment this line if you have limited access to the primary Hugging Face domain. + +### MacOS + +- `MACOS` + Optimizations for macOS. It is disabled by default. You can uncomment this line if your OS is macOS. + +### User registration + +- `REGISTER_ENABLED` + - `1`: (Default) Enable user registration. + - `0`: Disable user registration. + +## Service configuration + +[service_conf.yaml.template](https://github.com/infiniflow/ragflow/blob/main/docker/service_conf.yaml.template) specifies the system-level configuration for RAGFlow and is used by its API server and task executor. + +### `ragflow` + +- `host`: The API server's IP address inside the Docker container. Defaults to `0.0.0.0`. +- `port`: The API server's serving port inside the Docker container. Defaults to `9380`. + +### `mysql` + +- `name`: The MySQL database name. Defaults to `rag_flow`. +- `user`: The username for MySQL. +- `password`: The password for MySQL. +- `port`: The MySQL serving port inside the Docker container. Defaults to `3306`. +- `max_connections`: The maximum number of concurrent connections to the MySQL database. Defaults to `100`. +- `stale_timeout`: Timeout in seconds. + +### `minio` + +- `user`: The username for MinIO. +- `password`: The password for MinIO. +- `host`: The MinIO serving IP *and* port inside the Docker container. Defaults to `minio:9000`. + +### `oauth` + +The OAuth configuration for signing up or signing in to RAGFlow using a third-party account. + +- ``: Custom channel ID. + - `type`: Authentication type, options include `oauth2`, `oidc`, `github`. Default is `oauth2`, when `issuer` parameter is provided, defaults to `oidc`. + - `icon`: Icon ID, options include `github`, `sso`, default is `sso`. + - `display_name`: Channel name, defaults to the Title Case format of the channel ID. + - `client_id`: Required, unique identifier assigned to the client application. + - `client_secret`: Required, secret key for the client application, used for communication with the authentication server. + - `authorization_url`: Base URL for obtaining user authorization. + - `token_url`: URL for exchanging authorization code and obtaining access token. + - `userinfo_url`: URL for obtaining user information (username, email, etc.). + - `issuer`: Base URL of the identity provider. OIDC clients can dynamically obtain the identity provider's metadata (`authorization_url`, `token_url`, `userinfo_url`) through `issuer`. + - `scope`: Requested permission scope, a space-separated string. For example, `openid profile email`. + - `redirect_uri`: Required, URI to which the authorization server redirects during the authentication flow to return results. Must match the callback URI registered with the authentication server. Format: `https://your-app.com/v1/user/oauth/callback/`. For local configuration, you can directly use `http://127.0.0.1:80/v1/user/oauth/callback/`. + +:::tip NOTE +The following are best practices for configuring various third-party authentication methods. You can configure one or multiple third-party authentication methods for Ragflow: +```yaml +oauth: + oauth2: + display_name: "OAuth2" + client_id: "your_client_id" + client_secret: "your_client_secret" + authorization_url: "https://your-oauth-provider.com/oauth/authorize" + token_url: "https://your-oauth-provider.com/oauth/token" + userinfo_url: "https://your-oauth-provider.com/oauth/userinfo" + redirect_uri: "https://your-app.com/v1/user/oauth/callback/oauth2" + + oidc: + display_name: "OIDC" + client_id: "your_client_id" + client_secret: "your_client_secret" + issuer: "https://your-oauth-provider.com/oidc" + scope: "openid email profile" + redirect_uri: "https://your-app.com/v1/user/oauth/callback/oidc" + + github: + # https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app + type: "github" + icon: "github" + display_name: "Github" + client_id: "your_client_id" + client_secret: "your_client_secret" + redirect_uri: "https://your-app.com/v1/user/oauth/callback/github" +``` +::: + +### `user_default_llm` + +The default LLM to use for a new RAGFlow user. It is disabled by default. To enable this feature, uncomment the corresponding lines in **service_conf.yaml.template**. + +- `factory`: The LLM supplier. Available options: + - `"OpenAI"` + - `"DeepSeek"` + - `"Moonshot"` + - `"Tongyi-Qianwen"` + - `"VolcEngine"` + - `"ZHIPU-AI"` +- `api_key`: The API key for the specified LLM. You will need to apply for your model API key online. + +:::tip NOTE +If you do not set the default LLM here, configure the default LLM on the **Settings** page in the RAGFlow UI. +::: \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/contribution/_category_.json b/website/versioned_docs/version-v0.21.1/contribution/_category_.json new file mode 100644 index 0000000..594fe20 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/contribution/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Contribution", + "position": 8, + "link": { + "type": "generated-index", + "description": "Miscellaneous contribution guides." + } +} diff --git a/website/versioned_docs/version-v0.21.1/contribution/contributing.md b/website/versioned_docs/version-v0.21.1/contribution/contributing.md new file mode 100644 index 0000000..5d1ec19 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/contribution/contributing.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 1 +slug: /contributing +--- + +# Contribution guidelines + +General guidelines for RAGFlow's community contributors. + +--- + +This document offers guidelines and major considerations for submitting your contributions to RAGFlow. + +- To report a bug, file a [GitHub issue](https://github.com/infiniflow/ragflow/issues/new/choose) with us. +- For further questions, you can explore existing discussions or initiate a new one in [Discussions](https://github.com/orgs/infiniflow/discussions). + +## What you can contribute + +The list below mentions some contributions you can make, but it is not a complete list. + +- Proposing or implementing new features +- Fixing a bug +- Adding test cases or demos +- Posting a blog or tutorial +- Updates to existing documents, codes, or annotations. +- Suggesting more user-friendly error codes + +## File a pull request (PR) + +### General workflow + +1. Fork our GitHub repository. +2. Clone your fork to your local machine: +`git clone git@github.com:/ragflow.git` +3. Create a local branch: +`git checkout -b my-branch` +4. Provide sufficient information in your commit message +`git commit -m 'Provide sufficient info in your commit message'` +5. Commit changes to your local branch, and push to GitHub: (include necessary commit message) +`git push origin my-branch.` +6. Submit a pull request for review. + +### Before filing a PR + +- Consider splitting a large PR into multiple smaller, standalone PRs to keep a traceable development history. +- Ensure that your PR addresses just one issue, or keep any unrelated changes small. +- Add test cases when contributing new features. They demonstrate that your code functions correctly and protect against potential issues from future changes. + +### Describing your PR + +- Ensure that your PR title is concise and clear, providing all the required information. +- Refer to a corresponding GitHub issue in your PR description if applicable. +- Include sufficient design details for *breaking changes* or *API changes* in your description. + +### Reviewing & merging a PR + +Ensure that your PR passes all Continuous Integration (CI) tests before merging it. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/develop/_category_.json b/website/versioned_docs/version-v0.21.1/develop/_category_.json new file mode 100644 index 0000000..036bc99 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/develop/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Developers", + "position": 4, + "link": { + "type": "generated-index", + "description": "Guides for hardcore developers" + } +} diff --git a/website/versioned_docs/version-v0.21.1/develop/acquire_ragflow_api_key.md b/website/versioned_docs/version-v0.21.1/develop/acquire_ragflow_api_key.md new file mode 100644 index 0000000..4dc4520 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/develop/acquire_ragflow_api_key.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 4 +slug: /acquire_ragflow_api_key +--- + +# Acquire RAGFlow API key + +An API key is required for the RAGFlow server to authenticate your HTTP/Python or MCP requests. This documents provides instructions on obtaining a RAGFlow API key. + +1. Click your avatar in the top right corner of the RAGFlow UI to access the configuration page. +2. Click **API** to switch to the **API** page. +3. Obtain a RAGFlow API key: + +![ragflow_api_key](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/ragflow_api_key.jpg) + +:::tip NOTE +See the [RAGFlow HTTP API reference](../references/http_api_reference.md) or the [RAGFlow Python API reference](../references/python_api_reference.md) for a complete reference of RAGFlow's HTTP or Python APIs. +::: \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/develop/build_docker_image.mdx b/website/versioned_docs/version-v0.21.1/develop/build_docker_image.mdx new file mode 100644 index 0000000..16b5e86 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/develop/build_docker_image.mdx @@ -0,0 +1,92 @@ +--- +sidebar_position: 1 +slug: /build_docker_image +--- + +# Build RAGFlow Docker image +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +A guide explaining how to build a RAGFlow Docker image from its source code. By following this guide, you'll be able to create a local Docker image that can be used for development, debugging, or testing purposes. + +## Target Audience + +- Developers who have added new features or modified the existing code and require a Docker image to view and debug their changes. +- Developers seeking to build a RAGFlow Docker image for an ARM64 platform. +- Testers aiming to explore the latest features of RAGFlow in a Docker image. + +## Prerequisites + +- CPU ≥ 4 cores +- RAM ≥ 16 GB +- Disk ≥ 50 GB +- Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1 + +## Build a Docker image + + + + +This image is approximately 2 GB in size and relies on external LLM and embedding services. + +:::danger IMPORTANT +- While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. However, you can build an image yourself on a `linux/arm64` or `darwin/arm64` host machine as well. +- For ARM64 platforms, please upgrade the `xgboost` version in **pyproject.toml** to `1.6.0` and ensure **unixODBC** is properly installed. +::: + +```bash +git clone https://github.com/infiniflow/ragflow.git +cd ragflow/ +uv run download_deps.py +docker build -f Dockerfile.deps -t infiniflow/ragflow_deps . +docker build --build-arg LIGHTEN=1 -f Dockerfile -t infiniflow/ragflow:nightly-slim . +``` + + + + + +This image is approximately 9 GB in size. As it includes embedding models, it relies on external LLM services only. + +:::danger IMPORTANT +- While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. However, you can build an image yourself on a `linux/arm64` or `darwin/arm64` host machine as well. +- For ARM64 platforms, please upgrade the `xgboost` version in **pyproject.toml** to `1.6.0` and ensure **unixODBC** is properly installed. +::: + +```bash +git clone https://github.com/infiniflow/ragflow.git +cd ragflow/ +uv run download_deps.py +docker build -f Dockerfile.deps -t infiniflow/ragflow_deps . +docker build -f Dockerfile -t infiniflow/ragflow:nightly . +``` + + + + +## Launch a RAGFlow Service from Docker for MacOS + +After building the infiniflow/ragflow:nightly-slim image, you are ready to launch a fully-functional RAGFlow service with all the required components, such as Elasticsearch, MySQL, MinIO, Redis, and more. + +## Example: Apple M2 Pro (Sequoia) + +1. Edit Docker Compose Configuration + +Open the `docker/.env` file. Find the `RAGFLOW_IMAGE` setting and change the image reference from `infiniflow/ragflow:v0.21.1-slim` to `infiniflow/ragflow:nightly-slim` to use the pre-built image. + + +2. Launch the Service + +```bash +cd docker +$ docker compose -f docker-compose-macos.yml up -d +``` + +3. Access the RAGFlow Service + +Once the setup is complete, open your web browser and navigate to http://127.0.0.1 or your server's \; (the default port is \ = 80). You will be directed to the RAGFlow welcome page. Enjoy!🍻 \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/develop/launch_ragflow_from_source.md b/website/versioned_docs/version-v0.21.1/develop/launch_ragflow_from_source.md new file mode 100644 index 0000000..b81e14e --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/develop/launch_ragflow_from_source.md @@ -0,0 +1,145 @@ +--- +sidebar_position: 2 +slug: /launch_ragflow_from_source +--- + +# Launch service from source + +A guide explaining how to set up a RAGFlow service from its source code. By following this guide, you'll be able to debug using the source code. + +## Target audience + +Developers who have added new features or modified existing code and wish to debug using the source code, *provided that* their machine has the target deployment environment set up. + +## Prerequisites + +- CPU ≥ 4 cores +- RAM ≥ 16 GB +- Disk ≥ 50 GB +- Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1 + +:::tip NOTE +If you have not installed Docker on your local machine (Windows, Mac, or Linux), see the [Install Docker Engine](https://docs.docker.com/engine/install/) guide. +::: + +## Launch a service from source + +To launch a RAGFlow service from source code: + +### Clone the RAGFlow repository + +```bash +git clone https://github.com/infiniflow/ragflow.git +cd ragflow/ +``` + +### Install Python dependencies + +1. Install uv: + + ```bash + pipx install uv + ``` + +2. Install Python dependencies: + - slim: + ```bash + uv sync --python 3.10 # install RAGFlow dependent python modules + ``` + - full: + ```bash + uv sync --python 3.10 --all-extras # install RAGFlow dependent python modules + ``` + *A virtual environment named `.venv` is created, and all Python dependencies are installed into the new environment.* + +### Launch third-party services + +The following command launches the 'base' services (MinIO, Elasticsearch, Redis, and MySQL) using Docker Compose: + +```bash +docker compose -f docker/docker-compose-base.yml up -d +``` + +### Update `host` and `port` Settings for Third-party Services + +1. Add the following line to `/etc/hosts` to resolve all hosts specified in **docker/service_conf.yaml.template** to `127.0.0.1`: + + ``` + 127.0.0.1 es01 infinity mysql minio redis + ``` + +2. In **docker/service_conf.yaml.template**, update mysql port to `5455` and es port to `1200`, as specified in **docker/.env**. + +### Launch the RAGFlow backend service + +1. Comment out the `nginx` line in **docker/entrypoint.sh**. + + ``` + # /usr/sbin/nginx + ``` + +2. Activate the Python virtual environment: + + ```bash + source .venv/bin/activate + export PYTHONPATH=$(pwd) + ``` + +3. **Optional:** If you cannot access HuggingFace, set the HF_ENDPOINT environment variable to use a mirror site: + + ```bash + export HF_ENDPOINT=https://hf-mirror.com + ``` + +4. Check the configuration in **conf/service_conf.yaml**, ensuring all hosts and ports are correctly set. + +5. Run the **entrypoint.sh** script to launch the backend service: + + ```shell + JEMALLOC_PATH=$(pkg-config --variable=libdir jemalloc)/libjemalloc.so; + LD_PRELOAD=$JEMALLOC_PATH python rag/svr/task_executor.py 1; + ``` + ```shell + python api/ragflow_server.py; + ``` + +### Launch the RAGFlow frontend service + +1. Navigate to the `web` directory and install the frontend dependencies: + + ```bash + cd web + npm install + ``` + +2. Update `proxy.target` in **.umirc.ts** to `http://127.0.0.1:9380`: + + ```bash + vim .umirc.ts + ``` + +3. Start up the RAGFlow frontend service: + + ```bash + npm run dev + ``` + + *The following message appears, showing the IP address and port number of your frontend service:* + + ![](https://github.com/user-attachments/assets/0daf462c-a24d-4496-a66f-92533534e187) + +### Access the RAGFlow service + +In your web browser, enter `http://127.0.0.1:/`, ensuring the port number matches that shown in the screenshot above. + +### Stop the RAGFlow service when the development is done + +1. Stop the RAGFlow frontend service: + ```bash + pkill npm + ``` + +2. Stop the RAGFlow backend service: + ```bash + pkill -f "docker/entrypoint.sh" + ``` diff --git a/website/versioned_docs/version-v0.21.1/develop/mcp/_category_.json b/website/versioned_docs/version-v0.21.1/develop/mcp/_category_.json new file mode 100644 index 0000000..d2f129c --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/develop/mcp/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "MCP", + "position": 40, + "link": { + "type": "generated-index", + "description": "Guides and references on accessing RAGFlow's datasets via MCP." + } +} diff --git a/website/versioned_docs/version-v0.21.1/develop/mcp/launch_mcp_server.md b/website/versioned_docs/version-v0.21.1/develop/mcp/launch_mcp_server.md new file mode 100644 index 0000000..3df5284 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/develop/mcp/launch_mcp_server.md @@ -0,0 +1,212 @@ +--- +sidebar_position: 1 +slug: /launch_mcp_server +--- + +# Launch RAGFlow MCP server + +Launch an MCP server from source or via Docker. + +--- + +A RAGFlow Model Context Protocol (MCP) server is designed as an independent component to complement the RAGFlow server. Note that an MCP server must operate alongside a properly functioning RAGFlow server. + +An MCP server can start up in either self-host mode (default) or host mode: + +- **Self-host mode**: + When launching an MCP server in self-host mode, you must provide an API key to authenticate the MCP server with the RAGFlow server. In this mode, the MCP server can access *only* the datasets of a specified tenant on the RAGFlow server. +- **Host mode**: + In host mode, each MCP client can access their own datasets on the RAGFlow server. However, each client request must include a valid API key to authenticate the client with the RAGFlow server. + +Once a connection is established, an MCP server communicates with its client in MCP HTTP+SSE (Server-Sent Events) mode, unidirectionally pushing responses from the RAGFlow server to its client in real time. + +## Prerequisites + +1. Ensure RAGFlow is upgraded to v0.18.0 or later. +2. Have your RAGFlow API key ready. See [Acquire a RAGFlow API key](../acquire_ragflow_api_key.md). + +:::tip INFO +If you wish to try out our MCP server without upgrading RAGFlow, community contributor [yiminghub2024](https://github.com/yiminghub2024) 👏 shares their recommended steps [here](#launch-an-mcp-server-without-upgrading-ragflow). +::: + +## Launch an MCP server + +You can start an MCP server either from source code or via Docker. + +### Launch from source code + +1. Ensure that a RAGFlow server v0.18.0+ is properly running. +2. Launch the MCP server: + + +```bash +# Launch the MCP server to work in self-host mode, run either of the following +uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --api-key=ragflow-xxxxx +# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --mode=self-host --api-key=ragflow-xxxxx + +# To launch the MCP server to work in host mode, run the following instead: +# uv run mcp/server/server.py --host=127.0.0.1 --port=9382 --base-url=http://127.0.0.1:9380 --mode=host +``` + +Where: + +- `host`: The MCP server's host address. +- `port`: The MCP server's listening port. +- `base_url`: The address of the running RAGFlow server. +- `mode`: The launch mode. + - `self-host`: (default) self-host mode. + - `host`: host mode. +- `api_key`: Required in self-host mode to authenticate the MCP server with the RAGFlow server. See [here](../acquire_ragflow_api_key.md) for instructions on acquiring an API key. + +### Transports + +The RAGFlow MCP server supports two transports: the legacy SSE transport (served at `/sse`), introduced on November 5, 2024 and deprecated on March 26, 2025, and the streamable-HTTP transport (served at `/mcp`). The legacy SSE transport and the streamable HTTP transport with JSON responses are enabled by default. To disable either transport, use the flags `--no-transport-sse-enabled` or `--no-transport-streamable-http-enabled`. To disable JSON responses for the streamable HTTP transport, use the `--no-json-response` flag. + +### Launch from Docker + +#### 1. Enable MCP server + +The MCP server is designed as an optional component that complements the RAGFlow server and disabled by default. To enable MCP server: + +1. Navigate to **docker/docker-compose.yml**. +2. Uncomment the `services.ragflow.command` section as shown below: + +```yaml {6-13} + services: + ragflow: + ... + image: ${RAGFLOW_IMAGE} + # Example configuration to set up an MCP server: + command: + - --enable-mcpserver + - --mcp-host=0.0.0.0 + - --mcp-port=9382 + - --mcp-base-url=http://127.0.0.1:9380 + - --mcp-script-path=/ragflow/mcp/server/server.py + - --mcp-mode=self-host + - --mcp-host-api-key=ragflow-xxxxxxx + # Optional transport flags for the RAGFlow MCP server. + # If you set `mcp-mode` to `host`, you must add the --no-transport-streamable-http-enabled flag, because the streamable-HTTP transport is not yet supported in host mode. + # The legacy SSE transport and the streamable-HTTP transport with JSON responses are enabled by default. + # To disable a specific transport or JSON responses for the streamable-HTTP transport, use the corresponding flag(s): + # - --no-transport-sse-enabled # Disables the legacy SSE endpoint (/sse) + # - --no-transport-streamable-http-enabled # Disables the streamable-HTTP transport (served at the /mcp endpoint) + # - --no-json-response # Disables JSON responses for the streamable-HTTP transport +``` + +Where: + +- `mcp-host`: The MCP server's host address. +- `mcp-port`: The MCP server's listening port. +- `mcp-base-url`: The address of the running RAGFlow server. +- `mcp-script-path`: The file path to the MCP server’s main script. +- `mcp-mode`: The launch mode. + - `self-host`: (default) self-host mode. + - `host`: host mode. +- `mcp-host-api_key`: Required in self-host mode to authenticate the MCP server with the RAGFlow server. See [here](../acquire_ragflow_api_key.md) for instructions on acquiring an API key. + +:::tip INFO +If you set `mcp-mode` to `host`, you must add the `--no-transport-streamable-http-enabled` flag, because the streamable-HTTP transport is not yet supported in host mode. +::: + +#### 2. Launch a RAGFlow server with an MCP server + +Run `docker compose -f docker-compose.yml up` to launch the RAGFlow server together with the MCP server. + +*The following ASCII art confirms a successful launch:* + +```bash + ragflow-server | Starting MCP Server on 0.0.0.0:9382 with base URL http://127.0.0.1:9380... + ragflow-server | Starting 1 task executor(s) on host 'dd0b5e07e76f'... + ragflow-server | 2025-04-18 15:41:18,816 INFO 27 ragflow_server log path: /ragflow/logs/ragflow_server.log, log levels: {'peewee': 'WARNING', 'pdfminer': 'WARNING', 'root': 'INFO'} + ragflow-server | + ragflow-server | __ __ ____ ____ ____ _____ ______ _______ ____ + ragflow-server | | \/ |/ ___| _ \ / ___|| ____| _ \ \ / / ____| _ \ + ragflow-server | | |\/| | | | |_) | \___ \| _| | |_) \ \ / /| _| | |_) | + ragflow-server | | | | | |___| __/ ___) | |___| _ < \ V / | |___| _ < + ragflow-server | |_| |_|\____|_| |____/|_____|_| \_\ \_/ |_____|_| \_\ + ragflow-server | + ragflow-server | MCP launch mode: self-host + ragflow-server | MCP host: 0.0.0.0 + ragflow-server | MCP port: 9382 + ragflow-server | MCP base_url: http://127.0.0.1:9380 + ragflow-server | INFO: Started server process [26] + ragflow-server | INFO: Waiting for application startup. + ragflow-server | INFO: Application startup complete. + ragflow-server | INFO: Uvicorn running on http://0.0.0.0:9382 (Press CTRL+C to quit) + ragflow-server | 2025-04-18 15:41:20,469 INFO 27 found 0 gpus + ragflow-server | 2025-04-18 15:41:23,263 INFO 27 init database on cluster mode successfully + ragflow-server | 2025-04-18 15:41:25,318 INFO 27 load_model /ragflow/rag/res/deepdoc/det.onnx uses CPU + ragflow-server | 2025-04-18 15:41:25,367 INFO 27 load_model /ragflow/rag/res/deepdoc/rec.onnx uses CPU + ragflow-server | ____ ___ ______ ______ __ + ragflow-server | / __ \ / | / ____// ____// /____ _ __ + ragflow-server | / /_/ // /| | / / __ / /_ / // __ \| | /| / / + ragflow-server | / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / + ragflow-server | /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ + ragflow-server | + ragflow-server | + ragflow-server | 2025-04-18 15:41:29,088 INFO 27 RAGFlow version: v0.18.0-285-gb2c299fa full + ragflow-server | 2025-04-18 15:41:29,088 INFO 27 project base: /ragflow + ragflow-server | 2025-04-18 15:41:29,088 INFO 27 Current configs, from /ragflow/conf/service_conf.yaml: + ragflow-server | ragflow: {'host': '0.0.0.0', 'http_port': 9380} + ... + ragflow-server | * Running on all addresses (0.0.0.0) + ragflow-server | * Running on http://127.0.0.1:9380 + ragflow-server | * Running on http://172.19.0.6:9380 + ragflow-server | ______ __ ______ __ + ragflow-server | /_ __/___ ______/ /__ / ____/ _____ _______ __/ /_____ _____ + ragflow-server | / / / __ `/ ___/ //_/ / __/ | |/_/ _ \/ ___/ / / / __/ __ \/ ___/ + ragflow-server | / / / /_/ (__ ) ,< / /____> + +## General features + +--- + +### What sets RAGFlow apart from other RAG products? + +The "garbage in garbage out" status quo remains unchanged despite the fact that LLMs have advanced Natural Language Processing (NLP) significantly. In its response, RAGFlow introduces two unique features compared to other Retrieval-Augmented Generation (RAG) products. + +- Fine-grained document parsing: Document parsing involves images and tables, with the flexibility for you to intervene as needed. +- Traceable answers with reduced hallucinations: You can trust RAGFlow's responses as you can view the citations and references supporting them. + +--- + +### Differences between RAGFlow full edition and RAGFlow slim edition? + +Each RAGFlow release is available in two editions: + +- **Slim edition**: excludes built-in embedding models and is identified by a **-slim** suffix added to the version name. Example: `infiniflow/ragflow:v0.21.1-slim` +- **Full edition**: includes built-in embedding models and has no suffix added to the version name. Example: `infiniflow/ragflow:v0.21.1` + +--- + +### Which embedding models can be deployed locally? + +RAGFlow offers two Docker image editions, `v0.21.1-slim` and `v0.21.1`: + +- `infiniflow/ragflow:v0.21.1-slim` (default): The RAGFlow Docker image without embedding models. +- `infiniflow/ragflow:v0.21.1`: The RAGFlow Docker image with the following built-in embedding models: + - `BAAI/bge-large-zh-v1.5` + - `maidalun1020/bce-embedding-base_v1` + +--- + +### Where to find the version of RAGFlow? How to interpret it? + +You can find the RAGFlow version number on the **System** page of the UI: + +![Image](https://github.com/user-attachments/assets/20cf7213-2537-4e18-a88c-4dadf6228c6b) + +If you build RAGFlow from source, the version number is also in the system log: + +``` + ____ ___ ______ ______ __ + / __ \ / | / ____// ____// /____ _ __ + / /_/ // /| | / / __ / /_ / // __ \| | /| / / + / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / + /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ + +2025-02-18 10:10:43,835 INFO 1445658 RAGFlow version: v0.15.0-50-g6daae7f2 full +``` + +Where: + +- `v0.15.0`: The officially published release. +- `50`: The number of git commits since the official release. +- `g6daae7f2`: `g` is the prefix, and `6daae7f2` is the first seven characters of the current commit ID. +- `full`/`slim`: The RAGFlow edition. + - `full`: The full RAGFlow edition. + - `slim`: The RAGFlow edition without embedding models and Python packages. + +--- + +### Why not use other open-source vector databases as the document engine? + +Currently, only Elasticsearch and [Infinity](https://github.com/infiniflow/infinity) meet the hybrid search requirements of RAGFlow. Most open-source vector databases have limited support for full-text search, and sparse embedding is not an alternative to full-text search. Additionally, these vector databases lack critical features essential to RAGFlow, such as phrase search and advanced ranking capabilities. + +These limitations led us to develop [Infinity](https://github.com/infiniflow/infinity), the AI-native database, from the ground up. + +--- + +### Differences between demo.ragflow.io and a locally deployed open-source RAGFlow service? + +demo.ragflow.io demonstrates the capabilities of RAGFlow Enterprise. Its DeepDoc models are pre-trained using proprietary data and it offers much more sophisticated team permission controls. Essentially, demo.ragflow.io serves as a preview of RAGFlow's forthcoming SaaS (Software as a Service) offering. + +You can deploy an open-source RAGFlow service and call it from a Python client or through RESTful APIs. However, this is not supported on demo.ragflow.io. + +--- + +### Why does it take longer for RAGFlow to parse a document than LangChain? + +We put painstaking effort into document pre-processing tasks like layout analysis, table structure recognition, and OCR (Optical Character Recognition) using our vision models. This contributes to the additional time required. + +--- + +### Why does RAGFlow require more resources than other projects? + +RAGFlow has a number of built-in models for document structure parsing, which account for the additional computational resources. + +--- + +### Which architectures or devices does RAGFlow support? + +We officially support x86 CPU and nvidia GPU. While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. If you are on an ARM platform, follow [this guide](./develop/build_docker_image.mdx) to build a RAGFlow Docker image. + +--- + +### Do you offer an API for integration with third-party applications? + +The corresponding APIs are now available. See the [RAGFlow HTTP API Reference](./references/http_api_reference.md) or the [RAGFlow Python API Reference](./references/python_api_reference.md) for more information. + +--- + +### Do you support stream output? + +Yes, we do. Stream output is enabled by default in the chat assistant and agent. Note that you cannot disable stream output via RAGFlow's UI. To disable stream output in responses, use RAGFlow's Python or RESTful APIs: + +Python: + +- [Create chat completion](./references/python_api_reference.md#create-chat-completion) +- [Converse with chat assistant](./references/python_api_reference.md#converse-with-chat-assistant) +- [Converse with agent](./references/python_api_reference.md#converse-with-agent) + +RESTful: + +- [Create chat completion](./references/http_api_reference.md#create-chat-completion) +- [Converse with chat assistant](./references/http_api_reference.md#converse-with-chat-assistant) +- [Converse with agent](./references/http_api_reference.md#converse-with-agent) + +--- + +### Do you support sharing dialogue through URL? + +No, this feature is not supported. + +--- + +### Do you support multiple rounds of dialogues, referencing previous dialogues as context for the current query? + +Yes, we support enhancing user queries based on existing context of an ongoing conversation: + +1. On the **Chat** page, hover over the desired assistant and select **Edit**. +2. In the **Chat Configuration** popup, click the **Prompt engine** tab. +3. Switch on **Multi-turn optimization** to enable this feature. + +--- + +### Key differences between AI search and chat? + +- **AI search**: This is a single-turn AI conversation using a predefined retrieval strategy (a hybrid search of weighted keyword similarity and weighted vector similarity) and the system's default chat model. It does not involve advanced RAG strategies like knowledge graph, auto-keyword, or auto-question. Retrieved chunks will be listed below the chat model's response. +- **AI chat**: This is a multi-turn AI conversation where you can define your retrieval strategy (a weighted reranking score can be used to replace the weighted vector similarity in a hybrid search) and choose your chat model. In an AI chat, you can configure advanced RAG strategies, such as knowledge graphs, auto-keyword, and auto-question, for your specific case. Retrieved chunks are not displayed along with the answer. + +When debugging your chat assistant, you can use AI search as a reference to verify your model settings and retrieval strategy. + +--- + +## Troubleshooting + +--- + +### How to build the RAGFlow image from scratch? + +See [Build a RAGFlow Docker image](./develop/build_docker_image.mdx). + +### Cannot access https://huggingface.co + +A locally deployed RAGflow downloads OCR and embedding modules from [Huggingface website](https://huggingface.co) by default. If your machine is unable to access this site, the following error occurs and PDF parsing fails: + +``` +FileNotFoundError: [Errno 2] No such file or directory: '/root/.cache/huggingface/hub/models--InfiniFlow--deepdoc/snapshots/be0c1e50eef6047b412d1800aa89aba4d275f997/ocr.res' +``` + +To fix this issue, use https://hf-mirror.com instead: + +1. Stop all containers and remove all related resources: + + ```bash + cd ragflow/docker/ + docker compose down + ``` + +2. Uncomment the following line in **ragflow/docker/.env**: + + ``` + # HF_ENDPOINT=https://hf-mirror.com + ``` + +3. Start up the server: + + ```bash + docker compose up -d + ``` + +--- + +### `MaxRetryError: HTTPSConnectionPool(host='hf-mirror.com', port=443)` + +This error suggests that you do not have Internet access or are unable to connect to hf-mirror.com. Try the following: + +1. Manually download the resource files from [huggingface.co/InfiniFlow/deepdoc](https://huggingface.co/InfiniFlow/deepdoc) to your local folder **~/deepdoc**. +2. Add a volumes to **docker-compose.yml**, for example: + + ``` + - ~/deepdoc:/ragflow/rag/res/deepdoc + ``` + +--- + +### `WARNING: can't find /raglof/rag/res/borker.tm` + +Ignore this warning and continue. All system warnings can be ignored. + +--- + +### `network anomaly There is an abnormality in your network and you cannot connect to the server.` + +![anomaly](https://github.com/infiniflow/ragflow/assets/93570324/beb7ad10-92e4-4a58-8886-bfb7cbd09e5d) + +You will not log in to RAGFlow unless the server is fully initialized. Run `docker logs -f ragflow-server`. + +*The server is successfully initialized, if your system displays the following:* + +``` + ____ ___ ______ ______ __ + / __ \ / | / ____// ____// /____ _ __ + / /_/ // /| | / / __ / /_ / // __ \| | /| / / + / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / + /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ + + * Running on all addresses (0.0.0.0) + * Running on http://127.0.0.1:9380 + * Running on http://x.x.x.x:9380 + INFO:werkzeug:Press CTRL+C to quit +``` + +--- + +### `Realtime synonym is disabled, since no redis connection` + +Ignore this warning and continue. All system warnings can be ignored. + +![](https://github.com/infiniflow/ragflow/assets/93570324/ef5a6194-084a-4fe3-bdd5-1c025b40865c) + +--- + +### Why does my document parsing stall at under one percent? + +![stall](https://github.com/infiniflow/ragflow/assets/93570324/3589cc25-c733-47d5-bbfc-fedb74a3da50) + +Click the red cross beside the 'parsing status' bar, then restart the parsing process to see if the issue remains. If the issue persists and your RAGFlow is deployed locally, try the following: + +1. Check the log of your RAGFlow server to see if it is running properly: + + ```bash + docker logs -f ragflow-server + ``` + +2. Check if the **task_executor.py** process exists. +3. Check if your RAGFlow server can access hf-mirror.com or huggingface.com. + +--- + +### Why does my pdf parsing stall near completion, while the log does not show any error? + +Click the red cross beside the 'parsing status' bar, then restart the parsing process to see if the issue remains. If the issue persists and your RAGFlow is deployed locally, the parsing process is likely killed due to insufficient RAM. Try increasing your memory allocation by increasing the `MEM_LIMIT` value in **docker/.env**. + +:::note +Ensure that you restart up your RAGFlow server for your changes to take effect! + +```bash +docker compose stop +``` + +```bash +docker compose up -d +``` + +::: + +![nearcompletion](https://github.com/infiniflow/ragflow/assets/93570324/563974c3-f8bb-4ec8-b241-adcda8929cbb) + +--- + +### `Index failure` + +An index failure usually indicates an unavailable Elasticsearch service. + +--- + +### How to check the log of RAGFlow? + +```bash +tail -f ragflow/docker/ragflow-logs/*.log +``` + +--- + +### How to check the status of each component in RAGFlow? + +1. Check the status of the Elasticsearch Docker container: + + ```bash + $ docker ps + ``` + + *The following is an example result:* + + ```bash + 5bc45806b680 infiniflow/ragflow:latest "./entrypoint.sh" 11 hours ago Up 11 hours 0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:9380->9380/tcp, :::9380->9380/tcp ragflow-server + 91220e3285dd docker.elastic.co/elasticsearch/elasticsearch:8.11.3 "/bin/tini -- /usr/l…" 11 hours ago Up 11 hours (healthy) 9300/tcp, 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp ragflow-es-01 + d8c86f06c56b mysql:5.7.18 "docker-entrypoint.s…" 7 days ago Up 16 seconds (healthy) 0.0.0.0:3306->3306/tcp, :::3306->3306/tcp ragflow-mysql + cd29bcb254bc quay.io/minio/minio:RELEASE.2023-12-20T01-00-02Z "/usr/bin/docker-ent…" 2 weeks ago Up 11 hours 0.0.0.0:9001->9001/tcp, :::9001->9001/tcp, 0.0.0.0:9000->9000/tcp, :::9000->9000/tcp ragflow-minio + ``` + +2. Follow [this document](./guides/run_health_check.md) to check the health status of the Elasticsearch service. + +:::danger IMPORTANT +The status of a Docker container status does not necessarily reflect the status of the service. You may find that your services are unhealthy even when the corresponding Docker containers are up running. Possible reasons for this include network failures, incorrect port numbers, or DNS issues. +::: + +--- + +### `Exception: Can't connect to ES cluster` + +1. Check the status of the Elasticsearch Docker container: + + ```bash + $ docker ps + ``` + + *The status of a healthy Elasticsearch component should look as follows:* + + ``` + 91220e3285dd docker.elastic.co/elasticsearch/elasticsearch:8.11.3 "/bin/tini -- /usr/l…" 11 hours ago Up 11 hours (healthy) 9300/tcp, 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp ragflow-es-01 + ``` + +2. Follow [this document](./guides/run_health_check.md) to check the health status of the Elasticsearch service. + +:::danger IMPORTANT +The status of a Docker container status does not necessarily reflect the status of the service. You may find that your services are unhealthy even when the corresponding Docker containers are up running. Possible reasons for this include network failures, incorrect port numbers, or DNS issues. +::: + +3. If your container keeps restarting, ensure `vm.max_map_count` >= 262144 as per [this README](https://github.com/infiniflow/ragflow?tab=readme-ov-file#-start-up-the-server). Updating the `vm.max_map_count` value in **/etc/sysctl.conf** is required, if you wish to keep your change permanent. Note that this configuration works only for Linux. + +--- + +### Can't start ES container and get `Elasticsearch did not exit normally` + +This is because you forgot to update the `vm.max_map_count` value in **/etc/sysctl.conf** and your change to this value was reset after a system reboot. + +--- + +### `{"data":null,"code":100,"message":""}` + +Your IP address or port number may be incorrect. If you are using the default configurations, enter `http://` (**NOT 9380, AND NO PORT NUMBER REQUIRED!**) in your browser. This should work. + +--- + +### `Ollama - Mistral instance running at 127.0.0.1:11434 but cannot add Ollama as model in RagFlow` + +A correct Ollama IP address and port is crucial to adding models to Ollama: + +- If you are on demo.ragflow.io, ensure that the server hosting Ollama has a publicly accessible IP address. Note that 127.0.0.1 is not a publicly accessible IP address. +- If you deploy RAGFlow locally, ensure that Ollama and RAGFlow are in the same LAN and can communicate with each other. + +See [Deploy a local LLM](./guides/models/deploy_local_llm.mdx) for more information. + +--- + +### Do you offer examples of using DeepDoc to parse PDF or other files? + +Yes, we do. See the Python files under the **rag/app** folder. + +--- + +### `FileNotFoundError: [Errno 2] No such file or directory` + +1. Check the status of the MinIO Docker container: + + ```bash + $ docker ps + ``` + + *The status of a healthy Elasticsearch component should look as follows:* + + ```bash + cd29bcb254bc quay.io/minio/minio:RELEASE.2023-12-20T01-00-02Z "/usr/bin/docker-ent…" 2 weeks ago Up 11 hours 0.0.0.0:9001->9001/tcp, :::9001->9001/tcp, 0.0.0.0:9000->9000/tcp, :::9000->9000/tcp ragflow-minio + ``` + +2. Follow [this document](./guides/run_health_check.md) to check the health status of the Elasticsearch service. + +:::danger IMPORTANT +The status of a Docker container status does not necessarily reflect the status of the service. You may find that your services are unhealthy even when the corresponding Docker containers are up running. Possible reasons for this include network failures, incorrect port numbers, or DNS issues. +::: + +--- + +## Usage + +--- + +### How to run RAGFlow with a locally deployed LLM? + +You can use Ollama or Xinference to deploy local LLM. See [here](./guides/models/deploy_local_llm.mdx) for more information. + +--- + +### How to add an LLM that is not supported? + +If your model is not currently supported but has APIs compatible with those of OpenAI, click **OpenAI-API-Compatible** on the **Model providers** page to configure your model: + +![openai-api-compatible](https://github.com/user-attachments/assets/b1e964f2-b86e-41af-8528-fd8a96dc5f6f) + +--- + +### How to integrate RAGFlow with Ollama? + +- If RAGFlow is locally deployed, ensure that your RAGFlow and Ollama are in the same LAN. +- If you are using our online demo, ensure that the IP address of your Ollama server is public and accessible. + +See [here](./guides/models/deploy_local_llm.mdx) for more information. + +--- + +### How to change the file size limit? + +For a locally deployed RAGFlow: the total file size limit per upload is 1GB, with a batch upload limit of 32 files. There is no cap on the total number of files per account. To update this 1GB file size limit: + +- In **docker/.env**, upcomment `# MAX_CONTENT_LENGTH=1073741824`, adjust the value as needed, and note that `1073741824` represents 1GB in bytes. +- If you update the value of `MAX_CONTENT_LENGTH` in **docker/.env**, ensure that you update `client_max_body_size` in **nginx/nginx.conf** accordingly. + +:::tip NOTE +It is not recommended to manually change the 32-file batch upload limit. However, if you use RAGFlow's HTTP API or Python SDK to upload files, the 32-file batch upload limit is automatically removed. +::: + +--- + +### `Error: Range of input length should be [1, 30000]` + +This error occurs because there are too many chunks matching your search criteria. Try reducing the **TopN** and increasing **Similarity threshold** to fix this issue: + +1. Click **Chat** in the middle top of the page. +2. Right-click the desired conversation > **Edit** > **Prompt engine** +3. Reduce the **TopN** and/or raise **Similarity threshold**. +4. Click **OK** to confirm your changes. + +![topn](https://github.com/infiniflow/ragflow/assets/93570324/7ec72ab3-0dd2-4cff-af44-e2663b67b2fc) + +--- + +### How to get an API key for integration with third-party applications? + +See [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md). + +--- + +### How to upgrade RAGFlow? + +See [Upgrade RAGFlow](./guides/upgrade_ragflow.mdx) for more information. + +--- + +### How to switch the document engine to Infinity? + +To switch your document engine from Elasticsearch to [Infinity](https://github.com/infiniflow/infinity): + +1. Stop all running containers: + + ```bash + $ docker compose -f docker/docker-compose.yml down -v + ``` +:::caution WARNING +`-v` will delete all Docker container volumes, and the existing data will be cleared. +::: + +2. In **docker/.env**, set `DOC_ENGINE=${DOC_ENGINE:-infinity}` +3. Restart your Docker image: + + ```bash + $ docker compose -f docker-compose.yml up -d + ``` + +--- + +### Where are my uploaded files stored in RAGFlow's image? + +All uploaded files are stored in Minio, RAGFlow's object storage solution. For instance, if you upload your file directly to a dataset, it is located at `/filename`. + +--- + +### How to tune batch size for document parsing and embedding? + +You can control the batch size for document parsing and embedding by setting the environment variables `DOC_BULK_SIZE` and `EMBEDDING_BATCH_SIZE`. Increasing these values may improve throughput for large-scale data processing, but will also increase memory usage. Adjust them according to your hardware resources. + +--- + +### How to accelerate the question-answering speed of my chat assistant? + +See [here](./guides/chat/best_practices/accelerate_question_answering.mdx). + +--- + +### How to accelerate the question-answering speed of my Agent? + +See [here](./guides/agent/best_practices/accelerate_agent_question_answering.md). + +--- + +### How to use MinerU to parse PDF documents? + +MinerU PDF document parsing is available starting from v0.21.1. To use this feature, follow these steps: + +1. Before deploying ragflow-server, update your **docker/.env** file: + - Enable `HF_ENDPOINT=https://hf-mirror.com` + - Add a MinerU entry: `MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru` + +2. Start the ragflow-server and run the following commands inside the container: + +```bash +mkdir uv_tools +cd uv_tools +uv venv .venv +source .venv/bin/activate +uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple +``` + +3. Restart the ragflow-server. +4. In the web UI, navigate to the **Configuration** page of your dataset. Click **Built-in** in the **Ingestion pipeline** section, select a chunking method from the **Built-in** dropdown, which supports PDF parsing, and slect **MinerU** in **PDF parser**. +5. If you use a custom ingestion pipeline instead, you must also complete the first three steps before selecting **MinerU** in the **Parsing method** section of the **Parser** component. + + + diff --git a/website/versioned_docs/version-v0.21.1/guides/_category_.json b/website/versioned_docs/version-v0.21.1/guides/_category_.json new file mode 100644 index 0000000..895506b --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Guides", + "position": 3, + "link": { + "type": "generated-index", + "description": "Guides for RAGFlow users and developers." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/_category_.json b/website/versioned_docs/version-v0.21.1/guides/agent/_category_.json new file mode 100644 index 0000000..020ba1d --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Agents", + "position": 3, + "link": { + "type": "generated-index", + "description": "RAGFlow v0.8.0 introduces an agent mechanism, featuring a no-code workflow editor on the front end and a comprehensive graph-based task orchestration framework on the backend." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/_category_.json b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/_category_.json new file mode 100644 index 0000000..7548ec8 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Agent Components", + "position": 20, + "link": { + "type": "generated-index", + "description": "A complete reference for RAGFlow's agent components." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/agent.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/agent.mdx new file mode 100644 index 0000000..dd358f0 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/agent.mdx @@ -0,0 +1,233 @@ +--- +sidebar_position: 2 +slug: /agent_component +--- + +# Agent component + +The component equipped with reasoning, tool usage, and multi-agent collaboration capabilities. + +--- + +An **Agent** component fine-tunes the LLM and sets its prompt. From v0.20.5 onwards, an **Agent** component is able to work independently and with the following capabilities: + +- Autonomous reasoning with reflection and adjustment based on environmental feedback. +- Use of tools or subagents to complete tasks. + +## Scenarios + +An **Agent** component is essential when you need the LLM to assist with summarizing, translating, or controlling various tasks. + +## Prerequisites + +1. Ensure you have a chat model properly configured: + +![Set default models](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/set_default_models.jpg) + +2. If your Agent involves dataset retrieval, ensure you [have properly configured your target dataset(s)](../../dataset/configure_knowledge_base.md). + +## Quickstart + +### 1. Click on an **Agent** component to show its configuration panel + +The corresponding configuration panel appears to the right of the canvas. Use this panel to define and fine-tune the **Agent** component's behavior. + +### 2. Select your model + +Click **Model**, and select a chat model from the dropdown menu. + +:::tip NOTE +If no model appears, check if your have added a chat model on the **Model providers** page. +::: + +### 3. Update system prompt (Optional) + +The system prompt typically defines your model's role. You can either keep the system prompt as is or customize it to override the default. + + +### 4. Update user prompt + +The user prompt typically defines your model's task. You will find the `sys.query` variable auto-populated. Type `/` or click **(x)** to view or add variables. + +In this quickstart, we assume your **Agent** component is used standalone (without tools or sub-Agents below), then you may also need to specify retrieved chunks using the `formalized_content` variable: + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/standalone_user_prompt_variable.jpg) + +### 5. Skip Tools and Agent + +The **+ Add tools** and **+ Add agent** sections are used *only* when you need to configure your **Agent** component as a planner (with tools or sub-Agents beneath). In this quickstart, we assume your **Agent** component is used standalone (without tools or sub-Agents beneath). + +### 6. Choose the next component + +When necessary, click the **+** button on the **Agent** component to choose the next component in the worflow from the dropdown list. + +## Connect to an MCP server as a client + +:::danger IMPORTANT +In this section, we assume your **Agent** will be configured as a planner, with a Tavily tool beneath it. +::: + +### 1. Navigate to the MCP configuration page + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/mcp_page.jpg) + +### 2. Configure your Tavily MCP server + +Update your MCP server's name, URL (including the API key), server type, and other necessary settings. When configured correctly, the available tools will be displayed. + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/edit_mcp_server.jpg) + +### 3. Navigate to your Agent's editing page + +### 4. Connect to your MCP server + +1. Click **+ Add tools**: + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/add_tools.jpg) + +2. Click **MCP** to show the available MCP servers. + +3. Select your MCP server: + + *The target MCP server appears below your Agent component, and your Agent will autonomously decide when to invoke the available tools it offers.* + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/choose_tavily_mcp_server.jpg) + +### 5. Update system prompt to specify trigger conditions (Optional) + +To ensure reliable tool calls, you may specify within the system prompt which tasks should trigger each tool call. + +### 6. View the availabe tools of your MCP server + +On the canvas, click the newly-populated Tavily server to view and select its available tools: + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/tavily_mcp_server.jpg) + + +## Configurations + +### Model + +Click the dropdown menu of **Model** to show the model configuration window. + +- **Model**: The chat model to use. + - Ensure you set the chat model correctly on the **Model providers** page. + - You can use different models for different components to increase flexibility or improve overall performance. +- **Creavity**: A shortcut to **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty** settings, indicating the freedom level of the model. From **Improvise**, **Precise**, to **Balance**, each preset configuration corresponds to a unique combination of **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**. + This parameter has three options: + - **Improvise**: Produces more creative responses. + - **Precise**: (Default) Produces more conservative responses. + - **Balance**: A middle ground between **Improvise** and **Precise**. +- **Temperature**: The randomness level of the model's output. + Defaults to 0.1. + - Lower values lead to more deterministic and predictable outputs. + - Higher values lead to more creative and varied outputs. + - A temperature of zero results in the same output for the same prompt. +- **Top P**: Nucleus sampling. + - Reduces the likelihood of generating repetitive or unnatural text by setting a threshold *P* and restricting the sampling to tokens with a cumulative probability exceeding *P*. + - Defaults to 0.3. +- **Presence penalty**: Encourages the model to include a more diverse range of tokens in the response. + - A higher **presence penalty** value results in the model being more likely to generate tokens not yet been included in the generated text. + - Defaults to 0.4. +- **Frequency penalty**: Discourages the model from repeating the same words or phrases too frequently in the generated text. + - A higher **frequency penalty** value results in the model being more conservative in its use of repeated tokens. + - Defaults to 0.7. +- **Max tokens**: + This sets the maximum length of the model's output, measured in the number of tokens (words or pieces of words). It is disabled by default, allowing the model to determine the number of tokens in its responses. + +:::tip NOTE +- It is not necessary to stick with the same model for all components. If a specific model is not performing well for a particular task, consider using a different one. +- If you are uncertain about the mechanism behind **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**, simply choose one of the three options of **Creavity**. +::: + +### System prompt + +Typically, you use the system prompt to describe the task for the LLM, specify how it should respond, and outline other miscellaneous requirements. We do not plan to elaborate on this topic, as it can be as extensive as prompt engineering. However, please be aware that the system prompt is often used in conjunction with keys (variables), which serve as various data inputs for the LLM. + +An **Agent** component relies on keys (variables) to specify its data inputs. Its immediate upstream component is *not* necessarily its data input, and the arrows in the workflow indicate *only* the processing sequence. Keys in a **Agent** component are used in conjunction with the system prompt to specify data inputs for the LLM. Use a forward slash `/` or the **(x)** button to show the keys to use. + +#### Advanced usage + +From v0.20.5 onwards, four framework-level prompt blocks are available in the **System prompt** field, enabling you to customize and *override* prompts at the framework level. Type `/` or click **(x)** to view them; they appear under the **Framework** entry in the dropdown menu. + +- `task_analysis` prompt block + - This block is responsible for analyzing tasks — either a user task or a task assigned by the lead Agent when the **Agent** component is acting as a Sub-Agent. + - Reference design: [analyze_task_system.md](https://github.com/infiniflow/ragflow/blob/main/rag/prompts/analyze_task_system.md) and [analyze_task_user.md](https://github.com/infiniflow/ragflow/blob/main/rag/prompts/analyze_task_user.md) + - Available *only* when this **Agent** component is acting as a planner, with either tools or sub-Agents under it. + - Input variables: + - `agent_prompt`: The system prompt. + - `task`: The user prompt for either a lead Agent or a sub-Agent. The lead Agent's user prompt is defined by the user, while a sub-Agent's user prompt is defined by the lead Agent when delegating tasks. + - `tool_desc`: A description of the tools and sub_Agents that can be called. + - `context`: The operational context, which stores interactions between the Agent, tools, and sub-agents; initially empty. +- `plan_generation` prompt block + - This block creates a plan for the **Agent** component to execute next, based on the task analysis results. + - Reference design: [next_step.md](https://github.com/infiniflow/ragflow/blob/main/rag/prompts/next_step.md) + - Available *only* when this **Agent** component is acting as a planner, with either tools or sub-Agents under it. + - Input variables: + - `task_analysis`: The analysis result of the current task. + - `desc`: A description of the tools or sub-Agents currently being called. + - `today`: The date of today. +- `reflection` prompt block + - This block enables the **Agent** component to reflect, improving task accuracy and efficiency. + - Reference design: [reflect.md](https://github.com/infiniflow/ragflow/blob/main/rag/prompts/reflect.md) + - Available *only* when this **Agent** component is acting as a planner, with either tools or sub-Agents under it. + - Input variables: + - `goal`: The goal of the current task. It is the user prompt for either a lead Agent or a sub-Agent. The lead Agent's user prompt is defined by the user, while a sub-Agent's user prompt is defined by the lead Agent. + - `tool_calls`: The history of tool calling + - `call.name`：The name of the tool called. + - `call.result`：The result of tool calling +- `citation_guidelines` prompt block + - Reference design: [citation_prompt.md](https://github.com/infiniflow/ragflow/blob/main/rag/prompts/citation_prompt.md) + +*The screenshots below show the framework prompt blocks available to an **Agent** component, both as a standalone and as a planner (with a Tavily tool below):* + +![standalone](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/standalone_agent_framework_block.jpg) + +![planner](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/planner_agent_framework_blocks.jpg) + +### User prompt + +The user-defined prompt. Defaults to `sys.query`, the user query. As a general rule, when using the **Agent** component as a standalone module (not as a planner), you usually need to specify the corresponding **Retrieval** component’s output variable (`formalized_content`) here as part of the input to the LLM. + + +### Tools + +You can use an **Agent** component as a collaborator that reasons and reflects with the aid of other tools; for instance, **Retrieval** can serve as one such tool for an **Agent**. + +### Agent + +You use an **Agent** component as a collaborator that reasons and reflects with the aid of subagents or other tools, forming a multi-agent system. + +### Message window size + +An integer specifying the number of previous dialogue rounds to input into the LLM. For example, if it is set to 12, the tokens from the last 12 dialogue rounds will be fed to the LLM. This feature consumes additional tokens. + +:::tip IMPORTANT +This feature is used for multi-turn dialogue *only*. +::: + +### Max retries + +Defines the maximum number of attempts the agent will make to retry a failed task or operation before stopping or reporting failure. + +### Delay after error + +The waiting period in seconds that the agent observes before retrying a failed task, helping to prevent immediate repeated attempts and allowing system conditions to improve. Defaults to 1 second. + +### Max reflection rounds + +Defines the maximum number reflection rounds of the selected chat model. Defaults to 1 round. + +:::tip NOTE +Increasing this value will significantly extend your agent's response time. +::: + +### Output + +The global variable name for the output of the **Agent** component, which can be referenced by other components in the workflow. + +## Frequently asked questions + +### Why does it take so long for my Agent to respond? + +See [here](../best_practices/accelerate_agent_question_answering.md) for details. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/await_response.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/await_response.mdx new file mode 100644 index 0000000..973e1df --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/await_response.mdx @@ -0,0 +1,57 @@ +--- +sidebar_position: 5 +slug: /await_response +--- + +# Await response component + +A component that halts the workflow and awaits user input. + +--- + +An **Await response** component halts the workflow, initiating a conversation and collecting key information via predefined forms. + +## Scenarios + +An **Await response** component is essential where you need to display the agent's responses or require user-computer interaction. + +## Configurations + +### Guiding question + +Whether to show the message defined in the **Message** field. + +### Message + +The static message to send out. + +Click **+ Add message** to add message options. When multiple messages are supplied, the **Message** component randomly selects one to send. + +### Input + +You can define global variables within the **Await response** component, which can be either mandatory or optional. Once set, users will need to provide values for these variables when engaging with the agent. Click **+** to add a global variable, each with the following attributes: + +- **Name**: _Required_ + A descriptive name providing additional details about the variable. +- **Type**: _Required_ + The type of the variable: + - **Single-line text**: Accepts a single line of text without line breaks. + - **Paragraph text**: Accepts multiple lines of text, including line breaks. + - **Dropdown options**: Requires the user to select a value for this variable from a dropdown menu. And you are required to set _at least_ one option for the dropdown menu. + - **file upload**: Requires the user to upload one or multiple files. + - **Number**: Accepts a number as input. + - **Boolean**: Requires the user to toggle between on and off. +- **Key**: _Required_ + The unique variable name. +- **Optional**: A toggle indicating whether the variable is optional. + +:::tip NOTE +To pass in parameters from a client, call: + +- HTTP method [Converse with agent](../../../references/http_api_reference.md#converse-with-agent), or +- Python method [Converse with agent](../../../references/python_api_reference.md#converse-with-agent). + ::: + +:::danger IMPORTANT +If you set the key type as **file**, ensure the token count of the uploaded file does not exceed your model provider's maximum token limit; otherwise, the plain text in your file will be truncated and incomplete. +::: \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/begin.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/begin.mdx new file mode 100644 index 0000000..597d939 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/begin.mdx @@ -0,0 +1,80 @@ +--- +sidebar_position: 1 +slug: /begin_component +--- + +# Begin component + +The starting component in a workflow. + +--- + +The **Begin** component sets an opening greeting or accepts inputs from the user. It is automatically populated onto the canvas when you create an agent, whether from a template or from scratch (from a blank template). There should be only one **Begin** component in the workflow. + +## Scenarios + +A **Begin** component is essential in all cases. Every agent includes a **Begin** component, which cannot be deleted. + +## Configurations + +Click the component to display its **Configuration** window. Here, you can set an opening greeting and the input parameters (global variables) for the agent. + +### Mode + +Mode defines how the workflow is triggered. + +- Conversational: The agent is triggered from a conversation. +- Task: The agent starts without a conversation. + +### Opening greeting + +**Conversational mode only.** + +An agent in conversational mode begins with an opening greeting. It is the agent's first message to the user in conversational mode, which can be a welcoming remark or an instruction to guide the user forward. + +### Global variables + +You can define global variables within the **Begin** component, which can be either mandatory or optional. Once set, users will need to provide values for these variables when engaging with the agent. Click **+ Add variable** to add a global variable, each with the following attributes: + +- **Name**: _Required_ + A descriptive name providing additional details about the variable. +- **Type**: _Required_ + The type of the variable: + - **Single-line text**: Accepts a single line of text without line breaks. + - **Paragraph text**: Accepts multiple lines of text, including line breaks. + - **Dropdown options**: Requires the user to select a value for this variable from a dropdown menu. And you are required to set _at least_ one option for the dropdown menu. + - **file upload**: Requires the user to upload one or multiple files. + - **Number**: Accepts a number as input. + - **Boolean**: Requires the user to toggle between on and off. +- **Key**: _Required_ + The unique variable name. +- **Optional**: A toggle indicating whether the variable is optional. + +:::tip NOTE +To pass in parameters from a client, call: + +- HTTP method [Converse with agent](../../../references/http_api_reference.md#converse-with-agent), or +- Python method [Converse with agent](../../../references/python_api_reference.md#converse-with-agent). + ::: + +:::danger IMPORTANT +If you set the key type as **file**, ensure the token count of the uploaded file does not exceed your model provider's maximum token limit; otherwise, the plain text in your file will be truncated and incomplete. +::: + +:::note +You can tune document parsing and embedding efficiency by setting the environment variables `DOC_BULK_SIZE` and `EMBEDDING_BATCH_SIZE`. +::: + +## Frequently asked questions + +### Is the uploaded file in a dataset? + +No. Files uploaded to an agent as input are not stored in a dataset and hence will not be processed using RAGFlow's built-in OCR, DLR or TSR models, or chunked using RAGFlow's built-in chunking methods. + +### File size limit for an uploaded file + +There is no _specific_ file size limit for a file uploaded to an agent. However, note that model providers typically have a default or explicit maximum token setting, which can range from 8196 to 128k: The plain text part of the uploaded file will be passed in as the key value, but if the file's token count exceeds this limit, the string will be truncated and incomplete. + +:::tip NOTE +The variables `MAX_CONTENT_LENGTH` in `/docker/.env` and `client_max_body_size` in `/docker/nginx/nginx.conf` set the file size limit for each upload to a dataset or **File Management**. These settings DO NOT apply in this scenario. +::: diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/categorize.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/categorize.mdx new file mode 100644 index 0000000..39cc7c4 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/categorize.mdx @@ -0,0 +1,109 @@ +--- +sidebar_position: 8 +slug: /categorize_component +--- + +# Categorize component + +A component that classifies user inputs and applies strategies accordingly. + +--- + +A **Categorize** component is usually the downstream of the **Interact** component. + +## Scenarios + +A **Categorize** component is essential when you need the LLM to help you identify user intentions and apply appropriate processing strategies. + +## Configurations + +### Query variables + +*Mandatory* + +Select the source for categorization. + +The **Categorize** component relies on query variables to specify its data inputs (queries). All global variables defined before the **Categorize** component are available in the dropdown list. + + +### Input + +The **Categorize** component relies on input variables to specify its data inputs (queries). Click **+ Add variable** in the **Input** section to add the desired input variables. There are two types of input variables: **Reference** and **Text**. + +- **Reference**: Uses a component's output or a user input as the data source. You are required to select from the dropdown menu: + - A component ID under **Component Output**, or + - A global variable under **Begin input**, which is defined in the **Begin** component. +- **Text**: Uses fixed text as the query. You are required to enter static text. + +### Model + +Click the dropdown menu of **Model** to show the model configuration window. + +- **Model**: The chat model to use. + - Ensure you set the chat model correctly on the **Model providers** page. + - You can use different models for different components to increase flexibility or improve overall performance. +- **Creavity**: A shortcut to **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty** settings, indicating the freedom level of the model. From **Improvise**, **Precise**, to **Balance**, each preset configuration corresponds to a unique combination of **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**. + This parameter has three options: + - **Improvise**: Produces more creative responses. + - **Precise**: (Default) Produces more conservative responses. + - **Balance**: A middle ground between **Improvise** and **Precise**. +- **Temperature**: The randomness level of the model's output. + Defaults to 0.1. + - Lower values lead to more deterministic and predictable outputs. + - Higher values lead to more creative and varied outputs. + - A temperature of zero results in the same output for the same prompt. +- **Top P**: Nucleus sampling. + - Reduces the likelihood of generating repetitive or unnatural text by setting a threshold *P* and restricting the sampling to tokens with a cumulative probability exceeding *P*. + - Defaults to 0.3. +- **Presence penalty**: Encourages the model to include a more diverse range of tokens in the response. + - A higher **presence penalty** value results in the model being more likely to generate tokens not yet been included in the generated text. + - Defaults to 0.4. +- **Frequency penalty**: Discourages the model from repeating the same words or phrases too frequently in the generated text. + - A higher **frequency penalty** value results in the model being more conservative in its use of repeated tokens. + - Defaults to 0.7. +- **Max tokens**: + This sets the maximum length of the model's output, measured in the number of tokens (words or pieces of words). It is disabled by default, allowing the model to determine the number of tokens in its responses. + +:::tip NOTE +- It is not necessary to stick with the same model for all components. If a specific model is not performing well for a particular task, consider using a different one. +- If you are uncertain about the mechanism behind **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**, simply choose one of the three options of **Creavity**. +::: + +### Message window size + +An integer specifying the number of previous dialogue rounds to input into the LLM. For example, if it is set to 12, the tokens from the last 12 dialogue rounds will be fed to the LLM. This feature consumes additional tokens. + +Defaults to 1. + +:::tip IMPORTANT +This feature is used for multi-turn dialogue *only*. If your **Categorize** component is not part of a multi-turn dialogue (i.e., it is not in a loop), leave this field as-is. +::: + +### Category name + +A **Categorize** component must have at least two categories. This field sets the name of the category. Click **+ Add Item** to include the intended categories. + +:::tip NOTE +You will notice that the category name is auto-populated. No worries. Each category is assigned a random name upon creation. Feel free to change it to a name that is understandable to the LLM. +::: + +#### Description + +Description of this category. + +You can input criteria, situation, or information that may help the LLM determine which inputs belong in this category. + +#### Examples + +Additional examples that may help the LLM determine which inputs belong in this category. + +:::danger IMPORTANT +Examples are more helpful than the description if you want the LLM to classify particular cases into this category. +::: + +Once a new category is added, navigate to the **Categorize** component on the canvas, find the **+** button next to the case, and click it to specify the downstream component(s). + + +#### Output + +The global variable name for the output of the component, which can be referenced by other components in the workflow. Defaults to `category_name`. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_title.md b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_title.md new file mode 100644 index 0000000..27b8a97 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_title.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 31 +slug: /chunker_title_component +--- + +# Title chunker component + +A component that splits texts into chunks by heading level. + +--- + +A **Token chunker** component is a text splitter that uses specified heading level as delimiter to define chunk boundaries and create chunks. + +## Scenario + +A **Title chunker** component is optional, usually placed immediately after **Parser**. + +:::caution WARNING +Placing a **Title chunker** after a **Token chunker** is invalid and will cause an error. Please note that this restriction is not currently system-enforced and requires your attention. +::: + +## Configurations + +### Hierarchy + +Specifies the heading level to define chunk boundaries: + +- H1 +- H2 +- H3 (Default) +- H4 + +Click **+ Add** to add heading levels here or update the corresponding **Regular Expressions** fields for custom heading patterns. + +### Output + +The global variable name for the output of the **Title chunker** component, which can be referenced by subsequent components in the ingestion pipeline. + +- Default: `chunks` +- Type: `Array` \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_token.md b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_token.md new file mode 100644 index 0000000..d93f0ea --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/chunker_token.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 32 +slug: /chunker_token_component +--- + +# Token chunker component + +A component that splits texts into chunks, respecting a maximum token limit and using delimiters to find optimal breakpoints. + +--- + +A **Token chunker** component is a text splitter that creates chunks by respecting a recommended maximum token length, using delimiters to ensure logical chunk breakpoints. It splits long texts into appropriately-sized, semantically related chunks. + + +## Scenario + +A **Token chunker** component is optional, usually placed immediately after **Parser** or **Title chunker**. + +## Configurations + +### Recommended chunk size + +The recommended maximum token limit for each created chunk. The **Token chunker** component creates chunks at specified delimiters. If this token limit is reached before a delimiter, a chunk is created at that point. + +### Overlapped percent (%) + +This defines the overlap percentage between chunks. An appropriate degree of overlap ensures semantic coherence without creating excessive, redundant tokens for the LLM. + +- Default: 0 +- Maximum: 30% + + +### Delimiters + +Defaults to `\n`. Click the right-hand **Recycle bin** button to remove it, or click **+ Add** to add a delimiter. + + +### Output + +The global variable name for the output of the **Token chunker** component, which can be referenced by subsequent components in the ingestion pipeline. + +- Default: `chunks` +- Type: `Array` \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/code.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/code.mdx new file mode 100644 index 0000000..3d90496 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/code.mdx @@ -0,0 +1,205 @@ +--- +sidebar_position: 13 +slug: /code_component +--- + +# Code component + +A component that enables users to integrate Python or JavaScript codes into their Agent for dynamic data processing. + +--- + +## Scenarios + +A **Code** component is essential when you need to integrate complex code logic (Python or JavaScript) into your Agent for dynamic data processing. + +## Prerequisites + +### 1. Ensure gVisor is properly installed + +We use gVisor to isolate code execution from the host system. Please follow [the official installation guide](https://gvisor.dev/docs/user_guide/install/) to install gVisor, ensuring your operating system is compatible before proceeding. + +### 2. Ensure Sandbox is properly installed + +RAGFlow Sandbox is a secure, pluggable code execution backend. It serves as the code executor for the **Code** component. Please follow the [instructions here](https://github.com/infiniflow/ragflow/tree/main/sandbox) to install RAGFlow Sandbox. + +:::tip NOTE +If your RAGFlow Sandbox is not working, please be sure to consult the [Troubleshooting](#troubleshooting) section in this document. We assure you that it addresses 99.99% of the issues! +::: + +### 3. (Optional) Install necessary dependencies + +If you need to import your own Python or JavaScript packages into Sandbox, please follow the commands provided in the [How to import my own Python or JavaScript packages into Sandbox?](#how-to-import-my-own-python-or-javascript-packages-into-sandbox) section to install the additional dependencies. + +### 4. Enable Sandbox-specific settings in RAGFlow + +Ensure all Sandbox-specific settings are enabled in **ragflow/docker/.env**. + +### 5. Restart the service after making changes + +Any changes to the configuration or environment *require* a full service restart to take effect. + +## Configurations + +### Input + +You can specify multiple input sources for the **Code** component. Click **+ Add variable** in the **Input variables** section to include the desired input variables. + +### Code + +This field allows you to enter and edit your source code. + +:::danger IMPORTANT +If your code implementation includes defined variables, whether input or output variables, ensure they are also specified in the corresponding **Input** or **Output** sections. +::: + +#### A Python code example + +```Python + def main(arg1: str, arg2: str) -> dict: + return { + "result": arg1 + arg2, + } +``` + +#### A JavaScript code example + +```JavaScript + + const axios = require('axios'); + async function main(args) { + try { + const response = await axios.get('https://github.com/infiniflow/ragflow'); + console.log('Body:', response.data); + } catch (error) { + console.error('Error:', error.message); + } + } +``` + +### Return values + +You define the output variable(s) of the **Code** component here. + +:::danger IMPORTANT +If you define output variables here, ensure they are also defined in your code implementation; otherwise, their values will be `null`. The following are two examples: + + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/set_object_output.jpg) + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/set_nested_object_output.png) +::: + +### Output + +The defined output variable(s) will be auto-populated here. + +## Troubleshooting + +### `HTTPConnectionPool(host='sandbox-executor-manager', port=9385): Read timed out.` + +**Root cause** + +- You did not properly install gVisor and `runsc` was not recognized as a valid Docker runtime. +- You did not pull the required base images for the runners and no runner was started. + +**Solution** + +For the gVisor issue: + +1. Install [gVisor](https://gvisor.dev/docs/user_guide/install/). +2. Restart Docker. +3. Run the following to double check: + + ```bash + docker run --rm --runtime=runsc hello-world + ``` + +For the base image issue, pull the required base images: + +```bash +docker pull infiniflow/sandbox-base-nodejs:latest +docker pull infiniflow/sandbox-base-python:latest +``` + +### `HTTPConnectionPool(host='none', port=9385): Max retries exceeded.` + +**Root cause** + +`sandbox-executor-manager` is not mapped in `/etc/hosts`. + +**Solution** + +Add a new entry to `/etc/hosts`: + +`127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager` + +### `Container pool is busy` + +**Root cause** + +All runners are currently in use, executing tasks. + +**Solution** + +Please try again shortly or increase the pool size in the configuration to improve availability and reduce waiting times. + + +## Frequently asked questions + +### How to import my own Python or JavaScript packages into Sandbox? + +To import your Python packages, update **sandbox_base_image/python/requirements.txt** to install the required dependencies. For example, to add the `openpyxl` package, proceed with the following command lines: + +```bash {4,6} +(ragflow) ➜ ragflow/sandbox main ✓ pwd # make sure you are in the right directory +/home/infiniflow/workspace/ragflow/sandbox + +(ragflow) ➜ ragflow/sandbox main ✓ echo "openpyxl" >> sandbox_base_image/python/requirements.txt # add the package to the requirements.txt file + +(ragflow) ➜ ragflow/sandbox main ✗ cat sandbox_base_image/python/requirements.txt # make sure the package is added +numpy +pandas +requests +openpyxl # here it is + +(ragflow) ➜ ragflow/sandbox main ✗ make # rebuild the docker image, this command will rebuild the iamge and start the service immediately. To build image only, using `make build` instead. + +(ragflow) ➜ ragflow/sandbox main ✗ docker exec -it sandbox_python_0 /bin/bash # entering container to check if the package is installed + + +# in the container +nobody@ffd8a7dd19da:/workspace$ python # launch python shell +Python 3.11.13 (main, Aug 12 2025, 22:46:03) [GCC 12.2.0] on linux +Type "help", "copyright", "credits" or "license" for more information. +>>> import openpyxl # import the package to verify installation +>>> +# That's okay! +``` + +To import your JavaScript packages, navigate to `sandbox_base_image/nodejs` and use `npm` to install the required packages. For example, to add the `lodash` package, run the following commands: + +```bash +(ragflow) ➜ ragflow/sandbox main ✓ pwd +/home/infiniflow/workspace/ragflow/sandbox + +(ragflow) ➜ ragflow/sandbox main ✓ cd sandbox_base_image/nodejs + +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ npm install lodash + +(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ cd ../.. # go back to sandbox root directory + +(ragflow) ➜ ragflow/sandbox main ✗ make # rebuild the docker image, this command will rebuild the iamge and start the service immediately. To build image only, using `make build` instead. + +(ragflow) ➜ ragflow/sandbox main ✗ docker exec -it sandbox_nodejs_0 /bin/bash # entering container to check if the package is installed + +# in the container +nobody@dd4bbcabef63:/workspace$ npm list lodash # verify via npm list +/workspace +`-- lodash@4.17.21 extraneous + +nobody@dd4bbcabef63:/workspace$ ls node_modules | grep lodash # or verify via listing node_modules +lodash + +# That's okay! +``` diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/execute_sql.md b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/execute_sql.md new file mode 100644 index 0000000..f74bc32 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/execute_sql.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 25 +slug: /execute_sql +--- + +# Execute SQL tool + +A tool that execute SQL queries on a specified relational database. + +--- + +The **Execute SQL** tool enables you to connect to a relational database and run SQL queries, whether entered directly or generated by the system’s Text2SQL capability via an **Agent** component. + +## Prerequisites + +- A database instance properly configured and running. +- The database must be one of the following types: + - MySQL + - PostgreSQL + - MariaDB + - Microsoft SQL Server + +## Examples + +You can pair an **Agent** component with the **Execute SQL** tool, with the **Agent** generating SQL statements and the **Execute SQL** tool handling database connection and query execution. An example of this setup can be found in the **SQL Assistant** Agent template shown below: + +![](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/exeSQL.jpg) + +## Configurations + +### SQL statement + +This text input field allows you to write static SQL queries, such as `SELECT * FROM my_table`, and dynamic SQL queries using variables. + +:::tip NOTE +Click **(x)** or type `/` to insert variables. +::: + +For dynamic SQL queries, you can include variables in your SQL queries, such as `SELECT * FROM /sys.query`; if an **Agent** component is paired with the **Execute SQL** tool to generate SQL tasks (see the [Examples](#examples) section), you can directly insert that **Agent**'s output, `content`, into this field. + +### Database type + +The supported database type. Currently the following database types are available: + +- MySQL +- PostreSQL +- MariaDB +- Microsoft SQL Server (Myssql) + +### Database + +Appears only when you select **Split** as method. + +### Username + +The username with access privileges to the database. + +### Host + +The IP address of the database server. + +### Port + +The port number on which the database server is listening. + +### Password + +The password for the database user. + +### Max records + +The maximum number of records returned by the SQL query to control response size and improve efficiency. Defaults to `1024`. + +### Output + +The **Execute SQL** tool provides two output variables: + +- `formalized_content`: A string. If you reference this variable in a **Message** component, the returned records are displayed as a table. +- `json`: An object array. If you reference this variable in a **Message** component, the returned records will be presented as key-value pairs. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/indexer.md b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/indexer.md new file mode 100644 index 0000000..5bc2d92 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/indexer.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 40 +slug: /indexer_component +--- + +# Indexer component + +A component that defines how chunks are indexed. + +--- + +An **Indexer** component indexes chunks and configures their storage formats in the document engine. + +## Scenario + +An **Indexer** component is the mandatory ending component for all ingestion pipelines. + +## Configurations + +### Search method + +This setting configures how chunks are stored in the document engine: as full-text, embeddings, or both. + +### Filename embedding weight + +This setting defines the filename's contribution to the final embedding, which is a weighted combination of both the chunk content and the filename. Essentially, a higher value gives the filename more influence in the final *composite* embedding. + +- 0.1: Filename contributes 10% (chunk content 90%) +- 0.5 (maximum): Filename contributes 50% (chunk content 90%) \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/iteration.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/iteration.mdx new file mode 100644 index 0000000..9d4907d --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/iteration.mdx @@ -0,0 +1,65 @@ +--- +sidebar_position: 7 +slug: /iteration_component +--- + +# Iteration component + +A component that splits text input into text segments and iterates a predefined workflow for each one. + +--- + +An **Interaction** component can divide text input into text segments and apply its built-in component workflow to each segment. + + +## Scenario + +An **Iteration** component is essential when a workflow loop is required and the loop count is *not* fixed but depends on number of segments created from the output of specific agent components. + +- If, for instance, you plan to feed several paragraphs into an LLM for content generation, each with its own focus, and feeding them to the LLM all at once could create confusion or contradictions, then you can use an **Iteration** component, which encapsulates a **Generate** component, to repeat the content generation process for each paragraph. +- Another example: If you wish to use the LLM to translate a lengthy paper into a target language without exceeding its token limit, consider using an **Iteration** component, which encapsulates a **Generate** component, to break the paper into smaller pieces and repeat the translation process for each one. + +## Internal components + +### IterationItem + +Each **Iteration** component includes an internal **IterationItem** component. The **IterationItem** component serves as both the starting point and input node of the workflow within the **Iteration** component. It manages the loop of the workflow for all text segments created from the input. + +:::tip NOTE +The **IterationItem** component is visible *only* to the components encapsulated by the current **Iteration** components. +::: + +### Build an internal workflow + +You are allowed to pull other components into the **Iteration** component to build an internal workflow, and these "added internal components" are no longer visible to components outside of the current **Iteration** component. + +:::danger IMPORTANT +To reference the created text segments from an added internal component, simply add a **Reference** variable that equals **IterationItem** within the **Input** section of that internal component. There is no need to reference the corresponding external component, as the **IterationItem** component manages the loop of the workflow for all created text segments. +::: + +:::tip NOTE +An added internal component can reference an external component when necessary. +::: + +## Configurations + +### Input + +The **Iteration** component uses input variables to specify its data inputs, namely the texts to be segmented. You are allowed to specify multiple input sources for the **Iteration** component. Click **+ Add variable** in the **Input** section to include the desired input variables. There are two types of input variables: **Reference** and **Text**. + +- **Reference**: Uses a component's output or a user input as the data source. You are required to select from the dropdown menu: + - A component ID under **Component Output**, or + - A global variable under **Begin input**, which is defined in the **Begin** component. +- **Text**: Uses fixed text as the query. You are required to enter static text. + +### Delimiter + +The delimiter to use to split the text input into segments: + +- Comma (Default) +- Line break +- Tab +- Underline +- Forward slash +- Dash +- Semicolon \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/message.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/message.mdx new file mode 100644 index 0000000..9e12ba5 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/message.mdx @@ -0,0 +1,21 @@ +--- +sidebar_position: 4 +slug: /message_component +--- + +# Message component + +A component that sends out a static or dynamic message. + +--- + +As the final component of the workflow, a Message component returns the workflow’s ultimate data output accompanied by predefined message content. The system selects one message at random if multiple messages are provided. + +## Configurations + +### Messages + +The message to send out. Click `(x)` or type `/` to quickly insert variables. + +Click **+ Add message** to add message options. When multiple messages are supplied, the **Message** component randomly selects one to send. + diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/parser.md b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/parser.md new file mode 100644 index 0000000..95e23cb --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/parser.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 30 +slug: /parser_component +--- + +# Parser component + +A component that sets the parsing rules for your dataset. + +--- + +A **Parser** component defines how various file types should be parsed, including parsing methods for PDFs , fields to parse for Emails, and OCR methods for images. + + +## Scenario + +A **Parser** component is auto-populated on the ingestion pipeline canvas and required in all ingestion pipeline workflows. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/retrieval.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/retrieval.mdx new file mode 100644 index 0000000..a2215a2 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/retrieval.mdx @@ -0,0 +1,145 @@ +--- +sidebar_position: 3 +slug: /retrieval_component +--- + +# Retrieval component + +A component that retrieves information from specified datasets. + +## Scenarios + +A **Retrieval** component is essential in most RAG scenarios, where information is extracted from designated datasets before being sent to the LLM for content generation. A **Retrieval** component can operate either as a standalone workflow module or as a tool for an **Agent** component. In the latter role, the **Agent** component has autonomous control over when to invoke it for query and retrieval. + +The following screenshot shows a reference design using the **Retrieval** component, where the component serves as a tool for an **Agent** component. You can find it from the **Report Agent Using Knowledge Base** Agent template. + +![retrieval_reference_design](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/retrieval_reference_design.jpg) + +## Prerequisites + +Ensure you [have properly configured your target dataset(s)](../../dataset/configure_knowledge_base.md). + +## Quickstart + +### 1. Click on a **Retrieval** component to show its configuration panel + +The corresponding configuration panel appears to the right of the canvas. Use this panel to define and fine-tune the **Retrieval** component's search behavior. + +### 2. Input query variable(s) + +The **Retrieval** component depends on query variables to specify its queries. + +:::caution IMPORTANT +- If you use the **Retrieval** component as a standalone workflow module, input query variables in the **Input Variables** text box. +- If it is used as a tool for an **Agent** component, input the query variables in the **Agent** component's **User prompt** field. +::: + +By default, you can use `sys.query`, which is the user query and the default output of the **Begin** component. All global variables defined before the **Retrieval** component can also be used as query statements. Use the `(x)` button or type `/` to show all the available query variables. + +### 3. Select dataset(s) to query + +You can specify one or multiple datasets to retrieve data from. If selecting mutiple, ensure they use the same embedding model. + +### 4. Expand **Advanced Settings** to configure the retrieval method + +By default, a combination of weighted keyword similarity and weighted vector cosine similarity is used for retrieval. If a rerank model is selected, a combination of weighted keyword similarity and weighted reranking score will be used instead. + +As a starter, you can skip this step to stay with the default retrieval method. + +:::caution WARNING +Using a rerank model will *significantly* increase the system's response time. If you must use a rerank model, ensure you use a SaaS reranker; if you prefer a locally deployed rerank model, ensure you start RAGFlow with **docker-compose-gpu.yml**. +::: + +### 5. Enable cross-language search + +If your user query is different from the languages of the datasets, you can select the target languages in the **Cross-language search** dropdown menu. The model will then translates queries to ensure accurate matching of semantic meaning across languages. + + +### 6. Test retrieval results + +Click the **Run** button on the top of canvas to test the retrieval results. + +### 7. Choose the next component + +When necessary, click the **+** button on the **Retrieval** component to choose the next component in the worflow from the dropdown list. + + +## Configurations + +### Query variables + +*Mandatory* + +Select the query source for retrieval. Defaults to `sys.query`, which is the default output of the **Begin** component. + +The **Retrieval** component relies on query variables to specify its queries. All global variables defined before the **Retrieval** component can also be used as queries. Use the `(x)` button or type `/` to show all the available query variables. + +### Knowledge bases + +Select the dataset(s) to retrieve data from. + +- If no dataset is selected, meaning conversations with the agent will not be based on any dataset, ensure that the **Empty response** field is left blank to avoid an error. +- If you select multiple datasets, you must ensure that the datasets you select use the same embedding model; otherwise, an error message would occur. + +### Similarity threshold + +RAGFlow employs a combination of weighted keyword similarity and weighted vector cosine similarity during retrieval. This parameter sets the threshold for similarities between the user query and chunks stored in the datasets. Any chunk with a similarity score below this threshold will be excluded from the results. + +Defaults to 0.2. + +### Vector similarity weight + +This parameter sets the weight of vector similarity in the composite similarity score. The total of the two weights must equal 1.0. Its default value is 0.3, which means the weight of keyword similarity in a combined search is 1 - 0.3 = 0.7. + +### Top N + +This parameter selects the "Top N" chunks from retrieved ones and feed them to the LLM. + +Defaults to 8. + + +### Rerank model + +*Optional* + +If a rerank model is selected, a combination of weighted keyword similarity and weighted reranking score will be used for retrieval. + +:::caution WARNING +Using a rerank model will *significantly* increase the system's response time. +::: + +### Empty response + +- Set this as a response if no results are retrieved from the dataset(s) for your query, or +- Leave this field blank to allow the chat model to improvise when nothing is found. + +:::caution WARNING +If you do not specify a dataset, you must leave this field blank; otherwise, an error would occur. +::: + +### Cross-language search + +Select one or more languages for cross‑language search. If no language is selected, the system searches with the original query. + +### Use knowledge graph + +:::caution IMPORTANT +Before enabling this feature, ensure you have properly [constructed a knowledge graph from each target dataset](../../dataset/construct_knowledge_graph.md). +::: + +Whether to use knowledge graph(s) in the specified dataset(s) during retrieval for multi-hop question answering. When enabled, this would involve iterative searches across entity, relationship, and community report chunks, greatly increasing retrieval time. + +### Output + +The global variable name for the output of the **Retrieval** component, which can be referenced by other components in the workflow. + + +## Frequently asked questions + +### How to reduce response time? + +Go through the checklist below for best performance: + +- Leave the **Rerank model** field empty. +- If you must use a rerank model, ensure you use a SaaS reranker; if you prefer a locally deployed rerank model, ensure you start RAGFlow with **docker-compose-gpu.yml**. +- Disable **Use knowledge graph**. diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/switch.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/switch.mdx new file mode 100644 index 0000000..1840e66 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/switch.mdx @@ -0,0 +1,50 @@ +--- +sidebar_position: 6 +slug: /switch_component +--- + +# Switch component + +A component that evaluates whether specified conditions are met and directs the follow of execution accordingly. + +--- + +A **Switch** component evaluates conditions based on the output of specific components, directing the flow of execution accordingly to enable complex branching logic. + +## Scenarios + +A **Switch** component is essential for condition-based direction of execution flow. While it shares similarities with the [Categorize](./categorize.mdx) component, which is also used in multi-pronged strategies, the key distinction lies in their approach: the evaluation of the **Switch** component is rule-based, whereas the **Categorize** component involves AI and uses an LLM for decision-making. + +## Configurations + +### Case n + +A **Switch** component must have at least one case, each with multiple specified conditions. When multiple conditions are specified for a case, you must set the logical relationship between them to either AND or OR. + +Once a new case is added, navigate to the **Switch** component on the canvas, find the **+** button next to the case, and click it to specify the downstream component(s). + + +#### Condition + +Evaluates whether the output of specific components meets certain conditions + +:::danger IMPORTANT +When you have added multiple conditions for a specific case, a **Logical operator** field appears, requiring you to set the logical relationship between these conditions as either AND or OR. +::: + +- **Operator**: The operator required to form a conditional expression. + - Equals (default) + - Not equal + - Greater than + - Greater equal + - Less than + - Less equal + - Contains + - Not contains + - Starts with + - Ends with + - Is empty + - Not empty +- **Value**: A single value, which can be an integer, float, or string. + - Delimiters, multiple values, or expressions are *not* supported. + diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/text_processing.mdx b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/text_processing.mdx new file mode 100644 index 0000000..626ae67 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/text_processing.mdx @@ -0,0 +1,38 @@ +--- +sidebar_position: 15 +slug: /text_processing +--- + +# Text processing component + +A component that merges or splits texts. + +--- + +A **Text processing** component merges or splits texts. + +## Configurations + +### Method + +- Split: Split the text +- Merge: Merge the text + +### Split_ref + +Appears only when you select **Split** as method. + +The variable to be split. Type `/` to quickly insert variables. + +### Script + +Template for the merge. Appears only when you select **Merge** as method. Type `/` to quickly insert variables. + +### Delimiters + +The delimiter(s) used to split or merge the text. + +### Output + +The global variable name for the output of the component, which can be referenced by other components in the workflow. + diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/transformer.md b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/transformer.md new file mode 100644 index 0000000..ab21f60 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_component_reference/transformer.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 37 +slug: /transformer_component +--- + +# Transformer component + +A component that uses an LLM to extract insights from the chunks. + +--- + +A **Transformer** component indexes chunks and configures their storage formats in the document engine. It *typically* precedes the **Indexer** in the ingestion pipeline, but you can also chain multiple **Transformer** components in sequence. + +## Scenario + +A **Transformer** component is essential when you need the LLM to extract new information, such as keywords, questions, metadata, and summaries, from the original chunks. + +## Configurations + +### Model + +Click the dropdown menu of **Model** to show the model configuration window. + +- **Model**: The chat model to use. + - Ensure you set the chat model correctly on the **Model providers** page. + - You can use different models for different components to increase flexibility or improve overall performance. +- **Creavity**: A shortcut to **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty** settings, indicating the freedom level of the model. From **Improvise**, **Precise**, to **Balance**, each preset configuration corresponds to a unique combination of **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**. + This parameter has three options: + - **Improvise**: Produces more creative responses. + - **Precise**: (Default) Produces more conservative responses. + - **Balance**: A middle ground between **Improvise** and **Precise**. +- **Temperature**: The randomness level of the model's output. + Defaults to 0.1. + - Lower values lead to more deterministic and predictable outputs. + - Higher values lead to more creative and varied outputs. + - A temperature of zero results in the same output for the same prompt. +- **Top P**: Nucleus sampling. + - Reduces the likelihood of generating repetitive or unnatural text by setting a threshold *P* and restricting the sampling to tokens with a cumulative probability exceeding *P*. + - Defaults to 0.3. +- **Presence penalty**: Encourages the model to include a more diverse range of tokens in the response. + - A higher **presence penalty** value results in the model being more likely to generate tokens not yet been included in the generated text. + - Defaults to 0.4. +- **Frequency penalty**: Discourages the model from repeating the same words or phrases too frequently in the generated text. + - A higher **frequency penalty** value results in the model being more conservative in its use of repeated tokens. + - Defaults to 0.7. +- **Max tokens**: + This sets the maximum length of the model's output, measured in the number of tokens (words or pieces of words). It is disabled by default, allowing the model to determine the number of tokens in its responses. + +:::tip NOTE +- It is not necessary to stick with the same model for all components. If a specific model is not performing well for a particular task, consider using a different one. +- If you are uncertain about the mechanism behind **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**, simply choose one of the three options of **Creativity**. +::: + +### Result destination + +Select the type of output to be generated by the LLM: + +- Summary +- Keywords +- Questions +- Metadata + +### System prompt + +Typically, you use the system prompt to describe the task for the LLM, specify how it should respond, and outline other miscellaneous requirements. We do not plan to elaborate on this topic, as it can be as extensive as prompt engineering. + +:::tip NOTE +The system prompt here automatically updates to match your selected **Result destination**. +::: + +### User prompt + +The user-defined prompt. For example, you can type `/` or click **(x)** to insert variables of preceding components in the ingestion pipeline as the LLM's input. + +### Output + +The global variable name for the output of the **Transformer** component, which can be referenced by subsequent **Transformer** components in the ingestion pipeline. + +- Default: `chunks` +- Type: `Array` \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/agent_introduction.md b/website/versioned_docs/version-v0.21.1/guides/agent/agent_introduction.md new file mode 100644 index 0000000..fa21a78 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/agent_introduction.md @@ -0,0 +1,51 @@ +--- +sidebar_position: 1 +slug: /agent_introduction +--- + +# Introduction to agents + +Key concepts, basic operations, a quick view of the agent editor. + +--- + +:::danger DEPRECATED! +A new version is coming soon. +::: + +## Key concepts + +Agents and RAG are complementary techniques, each enhancing the other’s capabilities in business applications. RAGFlow v0.8.0 introduces an agent mechanism, featuring a no-code workflow editor on the front end and a comprehensive graph-based task orchestration framework on the back end. This mechanism is built on top of RAGFlow's existing RAG solutions and aims to orchestrate search technologies such as query intent classification, conversation leading, and query rewriting to: + +- Provide higher retrievals and, +- Accommodate more complex scenarios. + +## Create an agent + +:::tip NOTE + +Before proceeding, ensure that: + +1. You have properly set the LLM to use. See the guides on [Configure your API key](../models/llm_api_key_setup.md) or [Deploy a local LLM](../models/deploy_local_llm.mdx) for more information. +2. You have a dataset configured and the corresponding files properly parsed. See the guide on [Configure a dataset](../dataset/configure_knowledge_base.md) for more information. + +::: + +Click the **Agent** tab in the middle top of the page to show the **Agent** page. As shown in the screenshot below, the cards on this page represent the created agents, which you can continue to edit. + +![Agent_list](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/agent_list.jpg) + +We also provide templates catered to different business scenarios. You can either generate your agent from one of our agent templates or create one from scratch: + +1. Click **+ Create agent** to show the **agent template** page: + + ![agent_template](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/agent_template_list.jpg) + +2. To create an agent from scratch, click **Create Agent**. Alternatively, to create an agent from one of our templates, click the desired card, such as **Deep Research**, name your agent in the pop-up dialogue, and click **OK** to confirm. + + *You are now taken to the **no-code workflow editor** page.* + + ![add_component](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/add_component.jpg) + +3. Click the **+** button on the **Begin** component to select the desired components in your workflow. +4. Click **Save** to apply changes to your agent. diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/best_practices/_category_.json b/website/versioned_docs/version-v0.21.1/guides/agent/best_practices/_category_.json new file mode 100644 index 0000000..c788383 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/best_practices/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Best practices", + "position": 30, + "link": { + "type": "generated-index", + "description": "Best practices on Agent configuration." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/best_practices/accelerate_agent_question_answering.md b/website/versioned_docs/version-v0.21.1/guides/agent/best_practices/accelerate_agent_question_answering.md new file mode 100644 index 0000000..c069377 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/best_practices/accelerate_agent_question_answering.md @@ -0,0 +1,58 @@ +--- +sidebar_position: 1 +slug: /accelerate_agent_question_answering +--- + +# Accelerate answering + +A checklist to speed up question answering. + +--- + +Please note that some of your settings may consume a significant amount of time. If you often find that your question answering is time-consuming, here is a checklist to consider: + +## Balance task complexity with an Agent’s performance and speed? + +An Agent’s response time generally depends on many factors, e.g., the LLM’s capabilities and the prompt, the latter reflecting task complexity. When using an Agent, you should always balance task demands with the LLM’s ability. + +- For simple tasks, such as retrieval, rewriting, formatting, or structured data extraction, use concise prompts, remove planning or reasoning instructions, enforce output length limits, and select smaller or Turbo-class models. This significantly reduces latency and cost with minimal impact on quality. + +- For complex tasks, like multi-step reasoning, cross-document synthesis, or tool-based workflows, maintain or enhance prompts that include planning, reflection, and verification steps. + +- In multi-Agent orchestration systems, delegate simple subtasks to sub-Agents using smaller, faster models, and reserve more powerful models for the lead Agent to handle complexity and uncertainty. + +:::tip KEY INSIGHT +Focus on minimizing output tokens — through summarization, bullet points, or explicit length limits — as this has far greater impact on reducing latency than optimizing input size. +::: + +## Disable Reasoning + +Disabling the **Reasoning** toggle will reduce the LLM's thinking time. For a model like Qwen3, you also need to add `/no_think` to the system prompt to disable reasoning. + +## Disable Rerank model + +- Leaving the **Rerank model** field empty (in the corresponding **Retrieval** component) will significantly decrease retrieval time. +- When using a rerank model, ensure you have a GPU for acceleration; otherwise, the reranking process will be *prohibitively* slow. + +:::tip NOTE +Please note that rerank models are essential in certain scenarios. There is always a trade-off between speed and performance; you must weigh the pros against cons for your specific case. +::: + +## Check the time taken for each task + +Click the light bulb icon above the *current* dialogue and scroll down the popup window to view the time taken for each task: + + + +| Item name | Description | +| ----------------- | --------------------------------------------------------------------------------------------- | +| Total | Total time spent on this conversation round, including chunk retrieval and answer generation. | +| Check LLM | Time to validate the specified LLM. | +| Create retriever | Time to create a chunk retriever. | +| Bind embedding | Time to initialize an embedding model instance. | +| Bind LLM | Time to initialize an LLM instance. | +| Tune question | Time to optimize the user query using the context of the mult-turn conversation. | +| Bind reranker | Time to initialize an reranker model instance for chunk retrieval. | +| Generate keywords | Time to extract keywords from the user query. | +| Retrieval | Time to retrieve the chunks. | +| Generate answer | Time to generate the answer. | diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/embed_agent_into_webpage.md b/website/versioned_docs/version-v0.21.1/guides/agent/embed_agent_into_webpage.md new file mode 100644 index 0000000..1b532c4 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/embed_agent_into_webpage.md @@ -0,0 +1,15 @@ +--- +sidebar_position: 3 +slug: /embed_agent_into_webpage +--- + +# Embed agent into webpage + +You can use iframe to embed an agent into a third-party webpage. + +1. Before proceeding, you must [acquire an API key](../models/llm_api_key_setup.md); otherwise, an error message would appear. +2. On the **Agent** page, click an intended agent to access its editing page. +3. Click **Management > Embed into webpage** on the top right corner of the canvas to show the **iframe** window: +4. Copy the iframe and embed it into your webpage. + +![Embed_agent](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/embed_agent_into_webpage.jpg) \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/agent/sandbox_quickstart.md b/website/versioned_docs/version-v0.21.1/guides/agent/sandbox_quickstart.md new file mode 100644 index 0000000..1e1b9e2 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/agent/sandbox_quickstart.md @@ -0,0 +1,116 @@ +--- +sidebar_position: 20 +slug: /sandbox_quickstart +--- + +# Sandbox quickstart + +A secure, pluggable code execution backend designed for RAGFlow and other applications requiring isolated code execution environments. + +## Features: + +- Seamless RAGFlow Integration — Works out-of-the-box with the code component of RAGFlow. +- High Security — Uses gVisor for syscall-level sandboxing to isolate execution. +- Customisable Sandboxing — Modify seccomp profiles easily to tailor syscall restrictions. +- Pluggable Runtime Support — Extendable to support any programming language runtime. +- Developer Friendly — Quick setup with a convenient Makefile. + +## Architecture + +The architecture consists of isolated Docker base images for each supported language runtime, managed by the executor manager service. The executor manager orchestrates sandboxed code execution using gVisor for syscall interception and optional seccomp profiles for enhanced syscall filtering. + +## Prerequisites + +- Linux distribution compatible with gVisor. +- gVisor installed and configured. +- Docker version 24.0.0 or higher. +- Docker Compose version 2.26.1 or higher (similar to RAGFlow requirements). +- uv package and project manager installed. +- (Optional) GNU Make for simplified command-line management. + +## Build Docker base images + +The sandbox uses isolated base images for secure containerised execution environments. + +Build the base images manually: + +```bash +docker build -t sandbox-base-python:latest ./sandbox_base_image/python +docker build -t sandbox-base-nodejs:latest ./sandbox_base_image/nodejs +``` + +Alternatively, build all base images at once using the Makefile: + +```bash +make build +``` + +Next, build the executor manager image: + +```bash +docker build -t sandbox-executor-manager:latest ./executor_manager +``` + +## Running with RAGFlow + +1. Verify that gVisor is properly installed and operational. + +2. Configure the .env file located at docker/.env: + +- Uncomment sandbox-related environment variables. +- Enable the sandbox profile at the bottom of the file. + +3. Add the following entry to your /etc/hosts file to resolve the executor manager service: + +```bash +127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager +``` + +4. Start the RAGFlow service as usual. + +## Running standalone + +### Manual setup + +1. Initialize the environment variables: + +```bash +cp .env.example .env +``` + +2. Launch the sandbox services with Docker Compose: + +```bash +docker compose -f docker-compose.yml up +``` + +3. Test the sandbox setup: + +```bash +source .venv/bin/activate +export PYTHONPATH=$(pwd) +uv pip install -r executor_manager/requirements.txt +uv run tests/sandbox_security_tests_full.py +``` + +### Using Makefile + +Run all setup, build, launch, and tests with a single command: + +```bash +make +``` + +### Monitoring + +To follow logs of the executor manager container: + +```bash +docker logs -f sandbox-executor-manager +``` + +Or use the Makefile shortcut: + +```bash +make logs +``` \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/ai_search.md b/website/versioned_docs/version-v0.21.1/guides/ai_search.md new file mode 100644 index 0000000..6bd5336 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/ai_search.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 2 +slug: /ai_search +--- + +# Search + +Conduct an AI search. + +--- + +An AI search is a single-turn AI conversation using a predefined retrieval strategy (a hybrid search of weighted keyword similarity and weighted vector similarity) and the system's default chat model. It does not involve advanced RAG strategies like knowledge graph, auto-keyword, or auto-question. The related chunks are listed below the chat model's response in descending order based on their similarity scores. + +![Create search app](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/create_search_app.jpg) + +![Search view](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/search_view.jpg) + +:::tip NOTE +When debugging your chat assistant, you can use AI search as a reference to verify your model settings and retrieval strategy. +::: + +## Prerequisites + +- Ensure that you have configured the system's default models on the **Model providers** page. +- Ensure that the intended datasets are properly configured and the intended documents have finished file parsing. + +## Frequently asked questions + +### Key difference between an AI search and an AI chat? + +A chat is a multi-turn AI conversation where you can define your retrieval strategy (a weighted reranking score can be used to replace the weighted vector similarity in a hybrid search) and choose your chat model. In an AI chat, you can configure advanced RAG strategies, such as knowledge graphs, auto-keyword, and auto-question, for your specific case. Retrieved chunks are not displayed along with the answer. diff --git a/website/versioned_docs/version-v0.21.1/guides/chat/_category_.json b/website/versioned_docs/version-v0.21.1/guides/chat/_category_.json new file mode 100644 index 0000000..4b33e0c --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/chat/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Chat", + "position": 1, + "link": { + "type": "generated-index", + "description": "Chat-specific guides." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/chat/best_practices/_category_.json b/website/versioned_docs/version-v0.21.1/guides/chat/best_practices/_category_.json new file mode 100644 index 0000000..e92bb79 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/chat/best_practices/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Best practices", + "position": 7, + "link": { + "type": "generated-index", + "description": "Best practices on chat assistant configuration." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/chat/best_practices/accelerate_question_answering.mdx b/website/versioned_docs/version-v0.21.1/guides/chat/best_practices/accelerate_question_answering.mdx new file mode 100644 index 0000000..e404c1c --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/chat/best_practices/accelerate_question_answering.mdx @@ -0,0 +1,48 @@ +--- +sidebar_position: 1 +slug: /accelerate_question_answering +--- + +# Accelerate answering +import APITable from '@site/src/components/APITable'; + +A checklist to speed up question answering for your chat assistant. + +--- + +Please note that some of your settings may consume a significant amount of time. If you often find that your question answering is time-consuming, here is a checklist to consider: + +- Disabling **Multi-turn optimization** will reduce the time required to get an answer from the LLM. +- Leaving the **Rerank model** field empty will significantly decrease retrieval time. +- Disabling the **Reasoning** toggle will reduce the LLM's thinking time. For a model like Qwen3, you also need to add `/no_think` to the system prompt to disable reasoning. +- When using a rerank model, ensure you have a GPU for acceleration; otherwise, the reranking process will be *prohibitively* slow. + +:::tip NOTE +Please note that rerank models are essential in certain scenarios. There is always a trade-off between speed and performance; you must weigh the pros against cons for your specific case. +::: + +- Disabling **Keyword analysis** will reduce the time to receive an answer from the LLM. +- When chatting with your chat assistant, click the light bulb icon above the *current* dialogue and scroll down the popup window to view the time taken for each task: + ![enlighten](https://github.com/user-attachments/assets/fedfa2ee-21a7-451b-be66-20125619923c) + + +```mdx-code-block + +``` + +| Item name | Description | +| ----------------- | --------------------------------------------------------------------------------------------- | +| Total | Total time spent on this conversation round, including chunk retrieval and answer generation. | +| Check LLM | Time to validate the specified LLM. | +| Create retriever | Time to create a chunk retriever. | +| Bind embedding | Time to initialize an embedding model instance. | +| Bind LLM | Time to initialize an LLM instance. | +| Tune question | Time to optimize the user query using the context of the mult-turn conversation. | +| Bind reranker | Time to initialize an reranker model instance for chunk retrieval. | +| Generate keywords | Time to extract keywords from the user query. | +| Retrieval | Time to retrieve the chunks. | +| Generate answer | Time to generate the answer. | + +```mdx-code-block + +``` \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/chat/implement_deep_research.md b/website/versioned_docs/version-v0.21.1/guides/chat/implement_deep_research.md new file mode 100644 index 0000000..b5edd2d --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/chat/implement_deep_research.md @@ -0,0 +1,28 @@ +--- +sidebar_position: 3 +slug: /implement_deep_research +--- + +# Implement deep research + +Implements deep research for agentic reasoning. + +--- + +From v0.17.0 onward, RAGFlow supports integrating agentic reasoning in an AI chat. The following diagram illustrates the workflow of RAGFlow's deep research: + +![Image](https://github.com/user-attachments/assets/f65d4759-4f09-4d9d-9549-c0e1fe907525) + +To activate this feature: + +1. Enable the **Reasoning** toggle in **Chat setting**. + +![chat_reasoning](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_reasoning.jpg) + +2. Enter the correct Tavily API key to leverage Tavily-based web search: + +![chat_tavily](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_tavily.jpg) + +*The following is a screenshot of a conversation that integrates Deep Research:* + +![Image](https://github.com/user-attachments/assets/165b88ff-1f5d-4fb8-90e2-c836b25e32e9) \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/chat/set_chat_variables.md b/website/versioned_docs/version-v0.21.1/guides/chat/set_chat_variables.md new file mode 100644 index 0000000..89e7862 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/chat/set_chat_variables.md @@ -0,0 +1,110 @@ +--- +sidebar_position: 4 +slug: /set_chat_variables +--- + +# Set variables + +Set variables to be used together with the system prompt for your LLM. + +--- + +When configuring the system prompt for a chat model, variables play an important role in enhancing flexibility and reusability. With variables, you can dynamically adjust the system prompt to be sent to your model. In the context of RAGFlow, if you have defined variables in **Chat setting**, except for the system's reserved variable `{knowledge}`, you are required to pass in values for them from RAGFlow's [HTTP API](../../references/http_api_reference.md#converse-with-chat-assistant) or through its [Python SDK](../../references/python_api_reference.md#converse-with-chat-assistant). + +:::danger IMPORTANT +In RAGFlow, variables are closely linked with the system prompt. When you add a variable in the **Variable** section, include it in the system prompt. Conversely, when deleting a variable, ensure it is removed from the system prompt; otherwise, an error would occur. +::: + +## Where to set variables + +![set_variables](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_variables.jpg) + +## 1. Manage variables + +In the **Variable** section, you add, remove, or update variables. + +### `{knowledge}` - a reserved variable + +`{knowledge}` is the system's reserved variable, representing the chunks retrieved from the dataset(s) specified by **Knowledge bases** under the **Assistant settings** tab. If your chat assistant is associated with certain datasets, you can keep it as is. + +:::info NOTE +It currently makes no difference whether `{knowledge}` is set as optional or mandatory, but please note this design will be updated in due course. +::: + +From v0.17.0 onward, you can start an AI chat without specifying datasets. In this case, we recommend removing the `{knowledge}` variable to prevent unnecessary reference and keeping the **Empty response** field empty to avoid errors. + +### Custom variables + +Besides `{knowledge}`, you can also define your own variables to pair with the system prompt. To use these custom variables, you must pass in their values through RAGFlow's official APIs. The **Optional** toggle determines whether these variables are required in the corresponding APIs: + +- **Disabled** (Default): The variable is mandatory and must be provided. +- **Enabled**: The variable is optional and can be omitted if not needed. + +## 2. Update system prompt + +After you add or remove variables in the **Variable** section, ensure your changes are reflected in the system prompt to avoid inconsistencies or errors. Here's an example: + +``` +You are an intelligent assistant. Please answer the question by summarizing chunks from the specified dataset(s)... + +Your answers should follow a professional and {style} style. + +... + +Here is the dataset: +{knowledge} +The above is the dataset. +``` + +:::tip NOTE +If you have removed `{knowledge}`, ensure that you thoroughly review and update the entire system prompt to achieve optimal results. +::: + +## APIs + +The *only* way to pass in values for the custom variables defined in the **Chat Configuration** dialogue is to call RAGFlow's [HTTP API](../../references/http_api_reference.md#converse-with-chat-assistant) or through its [Python SDK](../../references/python_api_reference.md#converse-with-chat-assistant). + +### HTTP API + +See [Converse with chat assistant](../../references/http_api_reference.md#converse-with-chat-assistant). Here's an example: + +```json {9} +curl --request POST \ + --url http://{address}/api/v1/chats/{chat_id}/completions \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data-binary ' + { + "question": "xxxxxxxxx", + "stream": true, + "style":"hilarious" + }' +``` + +### Python API + +See [Converse with chat assistant](../../references/python_api_reference.md#converse-with-chat-assistant). Here's an example: + +```python {18} +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +assistant = rag_object.list_chats(name="Miss R") +assistant = assistant[0] +session = assistant.create_session() + +print("\n==================== Miss R =====================\n") +print("Hello. What can I do for you?") + +while True: + question = input("\n==================== User =====================\n> ") + style = input("Please enter your preferred style (e.g., formal, informal, hilarious): ") + + print("\n==================== Miss R =====================\n") + + cont = "" + for ans in session.ask(question, stream=True, style=style): + print(ans.content[len(cont):], end='', flush=True) + cont = ans.content +``` + diff --git a/website/versioned_docs/version-v0.21.1/guides/chat/start_chat.md b/website/versioned_docs/version-v0.21.1/guides/chat/start_chat.md new file mode 100644 index 0000000..e3581aa --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/chat/start_chat.md @@ -0,0 +1,116 @@ +--- +sidebar_position: 1 +slug: /start_chat +--- + +# Start AI chat + +Initiate an AI-powered chat with a configured chat assistant. + +--- + +Knowledge base, hallucination-free chat, and file management are the three pillars of RAGFlow. Chats in RAGFlow are based on a particular dataset or multiple datasets. Once you have created your dataset, finished file parsing, and [run a retrieval test](../dataset/run_retrieval_test.md), you can go ahead and start an AI conversation. + +## Start an AI chat + +You start an AI conversation by creating an assistant. + +1. Click the **Chat** tab in the middle top of the page **>** **Create an assistant** to show the **Chat Configuration** dialogue *of your next dialogue*. + + > RAGFlow offers you the flexibility of choosing a different chat model for each dialogue, while allowing you to set the default models in **System Model Settings**. + +2. Update Assistant-specific settings: + + - **Assistant name** is the name of your chat assistant. Each assistant corresponds to a dialogue with a unique combination of datasets, prompts, hybrid search configurations, and large model settings. + - **Empty response**: + - If you wish to *confine* RAGFlow's answers to your datasets, leave a response here. Then, when it doesn't retrieve an answer, it *uniformly* responds with what you set here. + - If you wish RAGFlow to *improvise* when it doesn't retrieve an answer from your datasets, leave it blank, which may give rise to hallucinations. + - **Show quote**: This is a key feature of RAGFlow and enabled by default. RAGFlow does not work like a black box. Instead, it clearly shows the sources of information that its responses are based on. + - Select the corresponding datasets. You can select one or multiple datasets, but ensure that they use the same embedding model, otherwise an error would occur. + +3. Update Prompt-specific settings: + + - In **System**, you fill in the prompts for your LLM, you can also leave the default prompt as-is for the beginning. + - **Similarity threshold** sets the similarity "bar" for each chunk of text. The default is 0.2. Text chunks with lower similarity scores are filtered out of the final response. + - **Vector similarity weight** is set to 0.3 by default. RAGFlow uses a hybrid score system to evaluate the relevance of different text chunks. This value sets the weight assigned to the vector similarity component in the hybrid score. + - If **Rerank model** is left empty, the hybrid score system uses keyword similarity and vector similarity, and the default weight assigned to the keyword similarity component is 1-0.3=0.7. + - If **Rerank model** is selected, the hybrid score system uses keyword similarity and reranker score, and the default weight assigned to the reranker score is 1-0.7=0.3. + - **Top N** determines the *maximum* number of chunks to feed to the LLM. In other words, even if more chunks are retrieved, only the top N chunks are provided as input. + - **Multi-turn optimization** enhances user queries using existing context in a multi-round conversation. It is enabled by default. When enabled, it will consume additional LLM tokens and significantly increase the time to generate answers. + - **Use knowledge graph** indicates whether to use knowledge graph(s) in the specified dataset(s) during retrieval for multi-hop question answering. When enabled, this would involve iterative searches across entity, relationship, and community report chunks, greatly increasing retrieval time. + - **Reasoning** indicates whether to generate answers through reasoning processes like Deepseek-R1/OpenAI o1. Once enabled, the chat model autonomously integrates Deep Research during question answering when encountering an unknown topic. This involves the chat model dynamically searching external knowledge and generating final answers through reasoning. + - **Rerank model** sets the reranker model to use. It is left empty by default. + - If **Rerank model** is left empty, the hybrid score system uses keyword similarity and vector similarity, and the default weight assigned to the vector similarity component is 1-0.7=0.3. + - If **Rerank model** is selected, the hybrid score system uses keyword similarity and reranker score, and the default weight assigned to the reranker score is 1-0.7=0.3. + - [Cross-language search](../../references/glossary.mdx#cross-language-search): Optional + Select one or more target languages from the dropdown menu. The system’s default chat model will then translate your query into the selected target language(s). This translation ensures accurate semantic matching across languages, allowing you to retrieve relevant results regardless of language differences. + - When selecting target languages, please ensure that these languages are present in the dataset to guarantee an effective search. + - If no target language is selected, the system will search only in the language of your query, which may cause relevant information in other languages to be missed. + - **Variable** refers to the variables (keys) to be used in the system prompt. `{knowledge}` is a reserved variable. Click **Add** to add more variables for the system prompt. + - If you are uncertain about the logic behind **Variable**, leave it *as-is*. + - As of v0.21.1, if you add custom variables here, the only way you can pass in their values is to call: + - HTTP method [Converse with chat assistant](../../references/http_api_reference.md#converse-with-chat-assistant), or + - Python method [Converse with chat assistant](../../references/python_api_reference.md#converse-with-chat-assistant). + +4. Update Model-specific Settings: + + - In **Model**: you select the chat model. Though you have selected the default chat model in **System Model Settings**, RAGFlow allows you to choose an alternative chat model for your dialogue. + - **Creavity**: A shortcut to **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty** settings, indicating the freedom level of the model. From **Improvise**, **Precise**, to **Balance**, each preset configuration corresponds to a unique combination of **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**. + This parameter has three options: + - **Improvise**: Produces more creative responses. + - **Precise**: (Default) Produces more conservative responses. + - **Balance**: A middle ground between **Improvise** and **Precise**. + - **Temperature**: The randomness level of the model's output. + Defaults to 0.1. + - Lower values lead to more deterministic and predictable outputs. + - Higher values lead to more creative and varied outputs. + - A temperature of zero results in the same output for the same prompt. + - **Top P**: Nucleus sampling. + - Reduces the likelihood of generating repetitive or unnatural text by setting a threshold *P* and restricting the sampling to tokens with a cumulative probability exceeding *P*. + - Defaults to 0.3. + - **Presence penalty**: Encourages the model to include a more diverse range of tokens in the response. + - A higher **presence penalty** value results in the model being more likely to generate tokens not yet been included in the generated text. + - Defaults to 0.4. + - **Frequency penalty**: Discourages the model from repeating the same words or phrases too frequently in the generated text. + - A higher **frequency penalty** value results in the model being more conservative in its use of repeated tokens. + - Defaults to 0.7. + +5. Now, let's start the show: + + ![chat_thermal_solution](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_thermal_solution.jpg) + +:::tip NOTE + +1. Click the light bulb icon above the answer to view the expanded system prompt: + +![prompt_display](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/prompt_display.jpg) + + *The light bulb icon is available only for the current dialogue.* + +2. Scroll down the expanded prompt to view the time consumed for each task: + +![time_elapsed](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/time_elapsed.jpg) +::: + +## Update settings of an existing chat assistant + +![chat_setting](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_setting.jpg) + +## Integrate chat capabilities into your application or webpage + +RAGFlow offers HTTP and Python APIs for you to integrate RAGFlow's capabilities into your applications. Read the following documents for more information: + +- [Acquire a RAGFlow API key](../../develop/acquire_ragflow_api_key.md) +- [HTTP API reference](../../references/http_api_reference.md) +- [Python API reference](../../references/python_api_reference.md) + +You can use iframe to embed the created chat assistant into a third-party webpage: + +1. Before proceeding, you must [acquire an API key](../../develop/acquire_ragflow_api_key.md); otherwise, an error message would appear. +2. Hover over an intended chat assistant **>** **Edit** to show the **iframe** window: + + ![chat-embed](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/embed_chat_into_webpage.jpg) + +3. Copy the iframe and embed it into your webpage. + +![chat-embed](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/embedded_chat_app.jpg) diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/_category_.json b/website/versioned_docs/version-v0.21.1/guides/dataset/_category_.json new file mode 100644 index 0000000..4c454f5 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Datasets", + "position": 0, + "link": { + "type": "generated-index", + "description": "Guides on configuring a dataset." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/autokeyword_autoquestion.mdx b/website/versioned_docs/version-v0.21.1/guides/dataset/autokeyword_autoquestion.mdx new file mode 100644 index 0000000..f61e503 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/autokeyword_autoquestion.mdx @@ -0,0 +1,72 @@ +--- +sidebar_position: 3 +slug: /autokeyword_autoquestion +--- + +# Auto-keyword Auto-question +import APITable from '@site/src/components/APITable'; + +Use a chat model to generate keywords or questions from each chunk in the dataset. + +--- + +When selecting a chunking method, you can also enable auto-keyword or auto-question generation to increase retrieval rates. This feature uses a chat model to produce a specified number of keywords and questions from each created chunk, generating an "additional layer of information" from the original content. + +:::caution WARNING +Enabling this feature increases document indexing time and uses extra tokens, as all created chunks will be sent to the chat model for keyword or question generation. +::: + +## What is Auto-keyword? + +Auto-keyword refers to the auto-keyword generation feature of RAGFlow. It uses a chat model to generate a set of keywords or synonyms from each chunk to correct errors and enhance retrieval accuracy. This feature is implemented as a slider under **Page rank** on the **Configuration** page of your dataset. + +**Values**: + +- 0: (Default) Disabled. +- Between 3 and 5 (inclusive): Recommended if you have chunks of approximately 1,000 characters. +- 30 (maximum) + +:::tip NOTE +- If your chunk size increases, you can increase the value accordingly. Please note, as the value increases, the marginal benefit decreases. +- An Auto-keyword value must be an integer. If you set it to a non-integer, say 1.7, it will be rounded down to the nearest integer, which in this case is 1. +::: + +## What is Auto-question? + +Auto-question is a feature of RAGFlow that automatically generates questions from chunks of data using a chat model. These questions (e.g. who, what, and why) also help correct errors and improve the matching of user queries. The feature usually works with FAQ retrieval scenarios involving product manuals or policy documents. And you can find this feature as a slider under **Page rank** on the **Configuration** page of your dataset. + +**Values**: + +- 0: (Default) Disabled. +- 1 or 2: Recommended if you have chunks of approximately 1,000 characters. +- 10 (maximum) + +:::tip NOTE +- If your chunk size increases, you can increase the value accordingly. Please note, as the value increases, the marginal benefit decreases. +- An Auto-question value must be an integer. If you set it to a non-integer, say 1.7, it will be rounded down to the nearest integer, which in this case is 1. +::: + +## Tips from the community + +The Auto-keyword or Auto-question values relate closely to the chunking size in your dataset. However, if you are new to this feature and unsure which value(s) to start with, the following are some value settings we gathered from our community. While they may not be accurate, they provide a starting point at the very least. + +```mdx-code-block + +``` + +| Use cases or typical scenarios | Document volume/length | Auto_keyword (0–30) | Auto_question (0–10) | +|---------------------------------------------------------------------|---------------------------------|----------------------------|----------------------------| +| Internal process guidance for employee handbook | Small, under 10 pages | 0 | 0 | +| Customer service FAQs | Medium, 10–100 pages | 3–7 | 1–3 | +| Technical whitepapers: Development standards, protocol details | Large, over 100 pages | 2–4 | 1–2 | +| Contracts / Regulations / Legal clause retrieval | Large, over 50 pages | 2–5 | 0–1 | +| Multi-repository layered new documents + old archive | Many | Adjust as appropriate |Adjust as appropriate | +| Social media comment pool: multilingual & mixed spelling | Very large volume of short text | 8–12 | 0 | +| Operational logs for troubleshooting | Very large volume of short text | 3–6 | 0 | +| Marketing asset library: multilingual product descriptions | Medium | 6–10 | 1–2 | +| Training courses / eBooks | Large | 2–5 | 1–2 | +| Maintenance manual: equipment diagrams + steps | Medium | 3–7 | 1–2 | + +```mdx-code-block + +``` diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/_category_.json b/website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/_category_.json new file mode 100644 index 0000000..f55fe00 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Best practices", + "position": 11, + "link": { + "type": "generated-index", + "description": "Best practices on configuring a dataset." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/accelerate_doc_indexing.mdx b/website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/accelerate_doc_indexing.mdx new file mode 100644 index 0000000..d705797 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/best_practices/accelerate_doc_indexing.mdx @@ -0,0 +1,19 @@ +--- +sidebar_position: 1 +slug: /accelerate_doc_indexing +--- + +# Accelerate indexing +import APITable from '@site/src/components/APITable'; + +A checklist to speed up document parsing and indexing. + +--- + +Please note that some of your settings may consume a significant amount of time. If you often find that document parsing is time-consuming, here is a checklist to consider: + +- Use GPU to reduce embedding time. +- On the configuration page of your dataset, switch off **Use RAPTOR to enhance retrieval**. +- Extracting knowledge graph (GraphRAG) is time-consuming. +- Disable **Auto-keyword** and **Auto-question** on the configuration page of your dataset, as both depend on the LLM. +- **v0.17.0+:** If all PDFs in your dataset are plain text and do not require GPU-intensive processes like OCR (Optical Character Recognition), TSR (Table Structure Recognition), or DLA (Document Layout Analysis), you can choose **Naive** over **DeepDoc** or other time-consuming large model options in the **Document parser** dropdown. This will substantially reduce document parsing time. diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/configure_knowledge_base.md b/website/versioned_docs/version-v0.21.1/guides/dataset/configure_knowledge_base.md new file mode 100644 index 0000000..ef54831 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/configure_knowledge_base.md @@ -0,0 +1,152 @@ +--- +sidebar_position: -10 +slug: /configure_knowledge_base +--- + +# Configure dataset + +Most of RAGFlow's chat assistants and Agents are based on datasets. Each of RAGFlow's datasets serves as a knowledge source, *parsing* files uploaded from your local machine and file references generated in **File Management** into the real 'knowledge' for future AI chats. This guide demonstrates some basic usages of the dataset feature, covering the following topics: + +- Create a dataset +- Configure a dataset +- Search for a dataset +- Delete a dataset + +## Create dataset + +With multiple datasets, you can build more flexible, diversified question answering. To create your first dataset: + +![create dataset](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/create_knowledge_base.jpg) + +_Each time a dataset is created, a folder with the same name is generated in the **root/.knowledgebase** directory._ + +## Configure dataset + +The following screenshot shows the configuration page of a dataset. A proper configuration of your dataset is crucial for future AI chats. For example, choosing the wrong embedding model or chunking method would cause unexpected semantic loss or mismatched answers in chats. + +![dataset configuration](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/configure_knowledge_base.jpg) + +This section covers the following topics: + +- Select chunking method +- Select embedding model +- Upload file +- Parse file +- Intervene with file parsing results +- Run retrieval testing + +### Select chunking method + +RAGFlow offers multiple built-in chunking template to facilitate chunking files of different layouts and ensure semantic integrity. From the **Built-in** chunking method dropdown under **Parse type**, you can choose the default template that suits the layouts and formats of your files. The following table shows the descriptions and the compatible file formats of each supported chunk template: + +| **Template** | Description | File format | +|--------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| +| General | Files are consecutively chunked based on a preset chunk token number. | MD, MDX, DOCX, XLSX, XLS (Excel 97-2003), PPT, PDF, TXT, JPEG, JPG, PNG, TIF, GIF, CSV, JSON, EML, HTML | +| Q&A | | XLSX, XLS (Excel 97-2003), CSV/TXT | +| Resume | Enterprise edition only. You can also try it out on demo.ragflow.io. | DOCX, PDF, TXT | +| Manual | | PDF | +| Table | | XLSX, XLS (Excel 97-2003), CSV/TXT | +| Paper | | PDF | +| Book | | DOCX, PDF, TXT | +| Laws | | DOCX, PDF, TXT | +| Presentation | | PDF, PPTX | +| Picture | | JPEG, JPG, PNG, TIF, GIF | +| One | Each document is chunked in its entirety (as one). | DOCX, XLSX, XLS (Excel 97-2003), PDF, TXT | +| Tag | The dataset functions as a tag set for the others. | XLSX, CSV/TXT | + +You can also change a file's chunking method on the **Files** page. + +![change chunking method](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/change_chunking_method.jpg) + +
+ From v0.21.1 onward, RAGFlow supports ingestion pipeline for customized data ingestion and cleansing workflows. + + To use a customized data pipeline: + + 1. On the **Agent** page, click **+ Create agent** > **Create from blank**. + 2. Select **Ingestion pipeline** and name your data pipeline in the popup, then click **Save** to show the data pipeline canvas. + 3. After updating your data pipeline, click **Save** on the top right of the canvas. + 4. Navigate to the **Configuration** page of your dataset, select **Choose pipeline** in **Ingestion pipeline**. + + *Your saved data pipeline will appear in the dropdown menu below.* + +
+ +### Select embedding model + +An embedding model converts chunks into embeddings. It cannot be changed once the dataset has chunks. To switch to a different embedding model, you must delete all existing chunks in the dataset. The obvious reason is that we *must* ensure that files in a specific dataset are converted to embeddings using the *same* embedding model (ensure that they are compared in the same embedding space). + +The following embedding models can be deployed locally: + +- BAAI/bge-large-zh-v1.5 +- maidalun1020/bce-embedding-base_v1 + +:::danger IMPORTANT +These two embedding models are optimized specifically for English and Chinese, so performance may be compromised if you use them to embed documents in other languages. +::: + +### Upload file + +- RAGFlow's **File Management** allows you to link a file to multiple datasets, in which case each target dataset holds a reference to the file. +- In **Knowledge Base**, you are also given the option of uploading a single file or a folder of files (bulk upload) from your local machine to a dataset, in which case the dataset holds file copies. + +While uploading files directly to a dataset seems more convenient, we *highly* recommend uploading files to **File Management** and then linking them to the target datasets. This way, you can avoid permanently deleting files uploaded to the dataset. + +### Parse file + +File parsing is a crucial topic in dataset configuration. The meaning of file parsing in RAGFlow is twofold: chunking files based on file layout and building embedding and full-text (keyword) indexes on these chunks. After having selected the chunking method and embedding model, you can start parsing a file: + +![parse file](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/parse_file.jpg) + +- As shown above, RAGFlow allows you to use a different chunking method for a particular file, offering flexibility beyond the default method. +- As shown above, RAGFlow allows you to enable or disable individual files, offering finer control over dataset-based AI chats. + +### Intervene with file parsing results + +RAGFlow features visibility and explainability, allowing you to view the chunking results and intervene where necessary. To do so: + +1. Click on the file that completes file parsing to view the chunking results: + + _You are taken to the **Chunk** page:_ + + ![chunks](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/file_chunks.jpg) + +2. Hover over each snapshot for a quick view of each chunk. + +3. Double-click the chunked texts to add keywords, questions, tags, or make *manual* changes where necessary: + + ![update chunk](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/add_keyword_question.jpg) + +:::caution NOTE +You can add keywords to a file chunk to increase its ranking for queries containing those keywords. This action increases its keyword weight and can improve its position in search list. +::: + +4. In Retrieval testing, ask a quick question in **Test text** to double-check if your configurations work: + + _As you can tell from the following, RAGFlow responds with truthful citations._ + + ![retrieval test](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/retrieval_test.jpg) + +### Run retrieval testing + +RAGFlow uses multiple recall of both full-text search and vector search in its chats. Prior to setting up an AI chat, consider adjusting the following parameters to ensure that the intended information always turns up in answers: + +- Similarity threshold: Chunks with similarities below the threshold will be filtered. By default, it is set to 0.2. +- Vector similarity weight: The percentage by which vector similarity contributes to the overall score. By default, it is set to 0.3. + +See [Run retrieval test](./run_retrieval_test.md) for details. + +## Search for dataset + +As of RAGFlow v0.21.1, the search feature is still in a rudimentary form, supporting only dataset search by name. + +![search dataset](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/search_datasets.jpg) + +## Delete dataset + +You are allowed to delete a dataset. Hover your mouse over the three dot of the intended dataset card and the **Delete** option appears. Once you delete a dataset, the associated folder under **root/.knowledge** directory is AUTOMATICALLY REMOVED. The consequence is: + +- The files uploaded directly to the dataset are gone; +- The file references, which you created from within **File Management**, are gone, but the associated files still exist in **File Management**. + +![delete dataset](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/delete_datasets.jpg) diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/construct_knowledge_graph.md b/website/versioned_docs/version-v0.21.1/guides/dataset/construct_knowledge_graph.md new file mode 100644 index 0000000..23ee6bf --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/construct_knowledge_graph.md @@ -0,0 +1,102 @@ +--- +sidebar_position: 8 +slug: /construct_knowledge_graph +--- + +# Construct knowledge graph + +Generate a knowledge graph for your dataset. + +--- + +To enhance multi-hop question-answering, RAGFlow adds a knowledge graph construction step between data extraction and indexing, as illustrated below. This step creates additional chunks from existing ones generated by your specified chunking method. + +![Image](https://github.com/user-attachments/assets/1ec21d8e-f255-4d65-9918-69b72dfa142b) + +From v0.16.0 onward, RAGFlow supports constructing a knowledge graph on a dataset, allowing you to construct a *unified* graph across multiple files within your dataset. When a newly uploaded file starts parsing, the generated graph will automatically update. + +:::danger WARNING +Constructing a knowledge graph requires significant memory, computational resources, and tokens. +::: + +## Scenarios + +Knowledge graphs are especially useful for multi-hop question-answering involving *nested* logic. They outperform traditional extraction approaches when you are performing question answering on books or works with complex entities and relationships. + +:::tip NOTE +RAPTOR (Recursive Abstractive Processing for Tree Organized Retrieval) can also be used for multi-hop question-answering tasks. See [Enable RAPTOR](./enable_raptor.md) for details. You may use either approach or both, but ensure you understand the memory, computational, and token costs involved. +::: + +## Prerequisites + +The system's default chat model is used to generate knowledge graph. Before proceeding, ensure that you have a chat model properly configured: + +![Set default models](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/set_default_models.jpg) + +## Configurations + +### Entity types (*Required*) + +The types of the entities to extract from your dataset. The default types are: **organization**, **person**, **event**, and **category**. Add or remove types to suit your specific dataset. + +### Method + +The method to use to construct knowledge graph: + +- **General**: Use prompts provided by [GraphRAG](https://github.com/microsoft/graphrag) to extract entities and relationships. +- **Light**: (Default) Use prompts provided by [LightRAG](https://github.com/HKUDS/LightRAG) to extract entities and relationships. This option consumes fewer tokens, less memory, and fewer computational resources. + +### Entity resolution + +Whether to enable entity resolution. You can think of this as an entity deduplication switch. When enabled, the LLM will combine similar entities - e.g., '2025' and 'the year of 2025', or 'IT' and 'Information Technology' - to construct a more effective graph. + +- (Default) Disable entity resolution. +- Enable entity resolution. This option consumes more tokens. + +### Community reports + +In a knowledge graph, a community is a cluster of entities linked by relationships. You can have the LLM generate an abstract for each community, known as a community report. See [here](https://www.microsoft.com/en-us/research/blog/graphrag-improving-global-search-via-dynamic-community-selection/) for more information. This indicates whether to generate community reports: + +- Generate community reports. This option consumes more tokens. +- (Default) Do not generate community reports. + +## Quickstart + +1. Navigate to the **Configuration** page of your dataset and update: + + - Entity types: *Required* - Specifies the entity types in the knowledge graph to generate. You don't have to stick with the default, but you need to customize them for your documents. + - Method: *Optional* + - Entity resolution: *Optional* + - Community reports: *Optional* + *The default knowledge graph configurations for your dataset are now set.* + +2. Navigate to the **Files** page of your dataset, click the **Generate** button on the top right corner of the page, then select **Knowledge graph** from the dropdown to initiate the knowledge graph generation process. + + *You can click the pause button in the dropdown to halt the build process when necessary.* + +3. Go back to the **Configuration** page: + + *Once a knowledge graph is generated, the **Knowledge graph** field changes from `Not generated` to `Generated at a specific timestamp`. You can delete it by clicking the recycle bin button to the right of the field.* + +4. To use the created knowledge graph, do either of the following: + + - In the **Chat setting** panel of your chat app, switch on the **Use knowledge graph** toggle. + - If you are using an agent, click the **Retrieval** agent component to specify the dataset(s) and switch on the **Use knowledge graph** toggle. + +## Frequently asked questions + +### Does the knowledge graph automatically update when I remove a related file? + +Nope. The knowledge graph does *not* update *until* you regenerate a knowledge graph for your dataset. + +### How to remove a generated knowledge graph? + +On the **Configuration** page of your dataset, find the **Knoweledge graph** field and click the recycle bin button to the right of the field. + +### Where is the created knowledge graph stored? + +All chunks of the created knowledge graph are stored in RAGFlow's document engine: either Elasticsearch or [Infinity](https://github.com/infiniflow/infinity). + +### How to export a created knowledge graph? + +Nope. Exporting a created knowledge graph is not supported. If you still consider this feature essential, please [raise an issue](https://github.com/infiniflow/ragflow/issues) explaining your use case and its importance. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/enable_excel2html.md b/website/versioned_docs/version-v0.21.1/guides/dataset/enable_excel2html.md new file mode 100644 index 0000000..d809042 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/enable_excel2html.md @@ -0,0 +1,42 @@ +--- +sidebar_position: 4 +slug: /enable_excel2html +--- + +# Enable Excel2HTML + +Convert complex Excel spreadsheets into HTML tables. + +--- + +When using the **General** chunking method, you can enable the **Excel to HTML** toggle to convert spreadsheet files into HTML tables. If it is disabled, spreadsheet tables will be represented as key-value pairs. For complex tables that cannot be simply represented this way, you must enable this feature. + +:::caution WARNING +The feature is disabled by default. If your dataset contains spreadsheets with complex tables and you do not enable this feature, RAGFlow will not throw an error but your tables are likely to be garbled. +::: + +## Scenarios + +Works with complex tables that cannot be represented as key-value pairs. Examples include spreadsheet tables with multiple columns, tables with merged cells, or multiple tables within one sheet. In such cases, consider converting these spreadsheet tables into HTML tables. + +## Considerations + +- The Excel2HTML feature applies only to spreadsheet files (XLSX or XLS (Excel 97-2003)). +- This feature is associated with the **General** chunking method. In other words, it is available *only when* you select the **General** chunking method. +- When this feature is enabled, spreadsheet tables with more than 12 rows will be split into chunks of 12 rows each. + +## Procedure + +1. On your dataset's **Configuration** page, select **General** as the chunking method. + + _The **Excel to HTML** toggle appears._ + +2. Enable **Excel to HTML** if your dataset contains complex spreadsheet tables that cannot be represented as key-value pairs. +3. Leave **Excel to HTML** disabled if your dataset has no spreadsheet tables or if its spreadsheet tables can be represented as key-value pairs. +4. If question-answering regarding complex tables is unsatisfactory, check if **Excel to HTML** is enabled. + +## Frequently asked questions + +### Should I enable this feature for PDFs with complex tables? + +Nope. This feature applies to spreadsheet files only. Enabling **Excel to HTML** does not affect your PDFs. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/enable_raptor.md b/website/versioned_docs/version-v0.21.1/guides/dataset/enable_raptor.md new file mode 100644 index 0000000..aab4cd7 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/enable_raptor.md @@ -0,0 +1,93 @@ +--- +sidebar_position: 7 +slug: /enable_raptor +--- + +# Enable RAPTOR + +A recursive abstractive method used in long-context knowledge retrieval and summarization, balancing broad semantic understanding with fine details. + +--- + +RAPTOR (Recursive Abstractive Processing for Tree Organized Retrieval) is an enhanced document preprocessing technique introduced in a [2024 paper](https://arxiv.org/html/2401.18059v1). Designed to tackle multi-hop question-answering issues, RAPTOR performs recursive clustering and summarization of document chunks to build a hierarchical tree structure. This enables more context-aware retrieval across lengthy documents. RAGFlow v0.6.0 integrates RAPTOR for document clustering as part of its data preprocessing pipeline between data extraction and indexing, as illustrated below. + +![document_clustering](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/document_clustering_as_preprocessing.jpg) + +Our tests with this new approach demonstrate state-of-the-art (SOTA) results on question-answering tasks requiring complex, multi-step reasoning. By combining RAPTOR retrieval with our built-in chunking methods and/or other retrieval-augmented generation (RAG) approaches, you can further improve your question-answering accuracy. + +:::danger WARNING +Enabling RAPTOR requires significant memory, computational resources, and tokens. +::: + +## Basic principles + +After the original documents are divided into chunks, the chunks are clustered by semantic similarity rather than by their original order in the text. Clusters are then summarized into higher-level chunks by your system's default chat model. This process is applied recursively, forming a tree structure with various levels of summarization from the bottom up. As illustrated in the figure below, the initial chunks form the leaf nodes (shown in blue) and are recursively summarized into a root node (shown in orange). + +![raptor](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/clustering_and_summarizing.jpg) + +The recursive clustering and summarization capture a broad understanding (by the root node) as well as fine details (by the leaf nodes) necessary for multi-hop question-answering. + +## Scenarios + +For multi-hop question-answering tasks involving complex, multi-step reasoning, a semantic gap often exists between the question and its answer. As a result, searching with the question often fails to retrieve the relevant chunks that contribute to the correct answer. RAPTOR addresses this challenge by providing the chat model with richer and more context-aware and relevant chunks to summarize, enabling a holistic understanding without losing granular details. + +:::tip NOTE +Knowledge graphs can also be used for multi-hop question-answering tasks. See [Construct knowledge graph](./construct_knowledge_graph.md) for details. You may use either approach or both, but ensure you understand the memory, computational, and token costs involved. +::: + +## Prerequisites + +The system's default chat model is used to summarize clustered content. Before proceeding, ensure that you have a chat model properly configured: + +![Set default models](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/set_default_models.jpg) + +## Configurations + +The RAPTOR feature is disabled by default. To enable it, manually switch on the **Use RAPTOR to enhance retrieval** toggle on your dataset's **Configuration** page. + +### Prompt + +The following prompt will be applied *recursively* for cluster summarization, with `{cluster_content}` serving as an internal parameter. We recommend that you keep it as-is for now. The design will be updated in due course. + +``` +Please summarize the following paragraphs... Paragraphs as following: + {cluster_content} +The above is the content you need to summarize. +``` + +### Max token + +The maximum number of tokens per generated summary chunk. Defaults to 256, with a maximum limit of 2048. + +### Threshold + +In RAPTOR, chunks are clustered by their semantic similarity. The **Threshold** parameter sets the minimum similarity required for chunks to be grouped together. + +It defaults to 0.1, with a maximum limit of 1. A higher **Threshold** means fewer chunks in each cluster, while a lower one means more. + +### Max cluster + +The maximum number of clusters to create. Defaults to 64, with a maximum limit of 1024. + +### Random seed + +A random seed. Click **+** to change the seed value. + +## Quickstart + +1. Navigate to the **Configuration** page of your dataset and update: + + - Prompt: *Optional* - We recommend that you keep it as-is until you understand the mechanism behind. + - Max token: *Optional* + - Threshold: *Optional* + - Max cluster: *Optional* + +2. Navigate to the **Files** page of your dataset, click the **Generate** button on the top right corner of the page, then select **RAPTOR** from the dropdown to initiate the RAPTOR build process. + + *You can click the pause button in the dropdown to halt the build process when necessary.* + +3. Go back to the **Configuration** page: + + *The **RAPTOR** field changes from `Not generated` to `Generated at a specific timestamp` when a RAPTOR hierarchical tree structure is generated. You can delete it by clicking the recycle bin button to the right of the field.* + +4. Once a RAPTOR hierarchical tree structure is generated, your chat assistant and **Retrieval** agent component will use it for retrieval as a default. diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/extract_table_of_contents.md b/website/versioned_docs/version-v0.21.1/guides/dataset/extract_table_of_contents.md new file mode 100644 index 0000000..58e9206 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/extract_table_of_contents.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 4 +slug: /enable_table_of_contents +--- + +# Extract table of contents + +Extract table of contents (TOC) from documents to provide long context RAG and improve retrieval. + +--- + +During indexing, this technique uses LLM to extract and generate chapter information, which is added to each chunk to provide sufficient global context. At the retrieval stage, it first uses the chunks matched by search, then supplements missing chunks based on the table of contents structure. This addresses issues caused by chunk fragmentation and insufficient context, improving answer quality. + +:::danger WARNING +Enabling TOC extraction requires significant memory, computational resources, and tokens. +::: + +## Prerequisites + +The system's default chat model is used to summarize clustered content. Before proceeding, ensure that you have a chat model properly configured: + +![Set default models](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/set_default_models.jpg) + +## Quickstart + +1. Navigate to the **Configuration** page. + +2. Enable **TOC Enhance**. + +3. To use this technique during retrieval, do either of the following: + + - In the **Chat setting** panel of your chat app, switch on the **TOC Enhance** toggle. + - If you are using an agent, click the **Retrieval** agent component to specify the dataset(s) and switch on the **TOC Enhance** toggle. + +## Frequently asked questions + +### Will previously parsed files be searched using the TOC enhancement feature once I enable `TOC Enhance`? + +No. Only files parsed after you enable **TOC Enhance** will be searched using the TOC enhancement feature. To apply this feature to files parsed before enabling **TOC Enhance**, you must reparse them. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/run_retrieval_test.md b/website/versioned_docs/version-v0.21.1/guides/dataset/run_retrieval_test.md new file mode 100644 index 0000000..87bd298 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/run_retrieval_test.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 10 +slug: /run_retrieval_test +--- + +# Run retrieval test + +Conduct a retrieval test on your dataset to check whether the intended chunks can be retrieved. + +--- + +After your files are uploaded and parsed, it is recommended that you run a retrieval test before proceeding with the chat assistant configuration. Running a retrieval test is *not* an unnecessary or superfluous step at all! Just like fine-tuning a precision instrument, RAGFlow requires careful tuning to deliver optimal question answering performance. Your dataset settings, chat assistant configurations, and the specified large and small models can all significantly impact the final results. Running a retrieval test verifies whether the intended chunks can be recovered, allowing you to quickly identify areas for improvement or pinpoint any issue that needs addressing. For instance, when debugging your question answering system, if you know that the correct chunks can be retrieved, you can focus your efforts elsewhere. For example, in issue [#5627](https://github.com/infiniflow/ragflow/issues/5627), the problem was found to be due to the LLM's limitations. + +During a retrieval test, chunks created from your specified chunking method are retrieved using a hybrid search. This search combines weighted keyword similarity with either weighted vector cosine similarity or a weighted reranking score, depending on your settings: + +- If no rerank model is selected, weighted keyword similarity will be combined with weighted vector cosine similarity. +- If a rerank model is selected, weighted keyword similarity will be combined with weighted vector reranking score. + +In contrast, chunks created from [knowledge graph construction](./construct_knowledge_graph.md) are retrieved solely using vector cosine similarity. + +## Prerequisites + +- Your files are uploaded and successfully parsed before running a retrieval test. +- A knowledge graph must be successfully built before enabling **Use knowledge graph**. + +## Configurations + +### Similarity threshold + +This sets the bar for retrieving chunks: chunks with similarities below the threshold will be filtered out. By default, the threshold is set to 0.2. This means that only chunks with hybrid similarity score of 20 or higher will be retrieved. + +### Vector similarity weight + +This sets the weight of vector similarity in the composite similarity score, whether used with vector cosine similarity or a reranking score. By default, it is set to 0.3, making the weight of the other component 0.7 (1 - 0.3). + +### Rerank model + +- If left empty, RAGFlow will use a combination of weighted keyword similarity and weighted vector cosine similarity. +- If a rerank model is selected, weighted keyword similarity will be combined with weighted vector reranking score. + +:::danger IMPORTANT +Using a rerank model will significantly increase the time to receive a response. +::: + +### Use knowledge graph + +In a knowledge graph, an entity description, a relationship description, or a community report each exists as an independent chunk. This switch indicates whether to add these chunks to the retrieval. + +The switch is disabled by default. When enabled, RAGFlow performs the following during a retrieval test: + +1. Extract entities and entity types from your query using the LLM. +2. Retrieve top N entities from the graph based on their PageRank values, using the extracted entity types. +3. Find similar entities and their N-hop relationships from the graph using the embeddings of the extracted query entities. +4. Retrieve similar relationships from the graph using the query embedding. +5. Rank these retrieved entities and relationships by multiplying each one's PageRank value with its similarity score to the query, returning the top n as the final retrieval. +6. Retrieve the report for the community involving the most entities in the final retrieval. + *The retrieved entity descriptions, relationship descriptions, and the top 1 community report are sent to the LLM for content generation.* + +:::danger IMPORTANT +Using a knowledge graph in a retrieval test will significantly increase the time to receive a response. +::: + +### Cross-language search + +To perform a [cross-language search](../../references/glossary.mdx#cross-language-search), select one or more target languages from the dropdown menu. The system’s default chat model will then translate your query entered in the Test text field into the selected target language(s). This translation ensures accurate semantic matching across languages, allowing you to retrieve relevant results regardless of language differences. + +:::tip NOTE +- When selecting target languages, please ensure that these languages are present in the dataset to guarantee an effective search. +- If no target language is selected, the system will search only in the language of your query, which may cause relevant information in other languages to be missed. +::: + +### Test text + +This field is where you put in your testing query. + +## Procedure + +1. Navigate to the **Retrieval testing** page of your dataset, enter your query in **Test text**, and click **Testing** to run the test. +2. If the results are unsatisfactory, tune the options listed in the Configuration section and rerun the test. + + *The following is a screenshot of a retrieval test conducted without using knowledge graph. It demonstrates a hybrid search combining weighted keyword similarity and weighted vector cosine similarity. The overall hybrid similarity score is 28.56, calculated as 25.17 (term similarity score) x 0.7 + 36.49 (vector similarity score) x 0.3:* + ![Image](https://github.com/user-attachments/assets/541554d4-3f3e-44e1-954b-0ae77d7372c6) + + *The following is a screenshot of a retrieval test conducted using a knowledge graph. It shows that only vector similarity is used for knowledge graph-generated chunks:* + ![Image](https://github.com/user-attachments/assets/30a03091-0f7b-4058-901a-f4dc5ca5aa6b) + +:::caution WARNING +If you have adjusted the default settings, such as keyword similarity weight or similarity threshold, to achieve the optimal results, be aware that these changes will not be automatically saved. You must apply them to your chat assistant settings or the **Retrieval** agent component settings. +::: + +## Frequently asked questions + +### Is an LLM used when the Use Knowledge Graph switch is enabled? + +Yes, your LLM will be involved to analyze your query and extract the related entities and relationship from the knowledge graph. This also explains why additional tokens and time will be consumed. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/select_pdf_parser.md b/website/versioned_docs/version-v0.21.1/guides/dataset/select_pdf_parser.md new file mode 100644 index 0000000..1781d76 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/select_pdf_parser.md @@ -0,0 +1,76 @@ +--- +sidebar_position: -4 +slug: /select_pdf_parser +--- + +# Select PDF parser + +Select a visual model for parsing your PDFs. + +--- + +RAGFlow isn't one-size-fits-all. It is built for flexibility and supports deeper customization to accommodate more complex use cases. From v0.17.0 onwards, RAGFlow decouples DeepDoc-specific data extraction tasks from chunking methods **for PDF files**. This separation enables you to autonomously select a visual model for OCR (Optical Character Recognition), TSR (Table Structure Recognition), and DLR (Document Layout Recognition) tasks that balances speed and performance to suit your specific use cases. If your PDFs contain only plain text, you can opt to skip these tasks by selecting the **Naive** option, to reduce the overall parsing time. + +![data extraction](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/data_extraction.jpg) + +## Prerequisites + +- The PDF parser dropdown menu appears only when you select a chunking method compatible with PDFs, including: + - **General** + - **Manual** + - **Paper** + - **Book** + - **Laws** + - **Presentation** + - **One** +- To use a third-party visual model for parsing PDFs, ensure you have set a default img2txt model under **Set default models** on the **Model providers** page. + +## Quickstart + +1. On your dataset's **Configuration** page, select a chunking method, say **General**. + + _The **PDF parser** dropdown menu appears._ + +2. Select the option that works best with your scenario: + + - DeepDoc: (Default) The default visual model performing OCR, TSR, and DLR tasks on PDFs, which can be time-consuming. + - Naive: Skip OCR, TSR, and DLR tasks if *all* your PDFs are plain text. + - MinerU: An experimental feature. + - A third-party visual model provided by a specific model provider. + +:::danger IMPORTANG +MinerU PDF document parsing is available starting from v0.21.1. To use this feature, follow these steps: + +1. Before deploying ragflow-server, update your **docker/.env** file: + - Enable `HF_ENDPOINT=https://hf-mirror.com` + - Add a MinerU entry: `MINERU_EXECUTABLE=/ragflow/uv_tools/.venv/bin/mineru` + +2. Start the ragflow-server and run the following commands inside the container: + +```bash +mkdir uv_tools +cd uv_tools +uv venv .venv +source .venv/bin/activate +uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple +``` + +3. Restart the ragflow-server. +4. In the web UI, navigate to the **Configuration** page of your dataset. Click **Built-in** in the **Ingestion pipeline** section, select a chunking method from the **Built-in** dropdown, which supports PDF parsing, and slect **MinerU** in **PDF parser**. +5. If you use a custom ingestion pipeline instead, you must also complete the first three steps before selecting **MinerU** in the **Parsing method** section of the **Parser** component. +::: + +:::caution WARNING +Third-party visual models are marked **Experimental**, because we have not fully tested these models for the aforementioned data extraction tasks. +::: + +## Frequently asked questions + +### When should I select DeepDoc or a third-party visual model as the PDF parser? + +Use a visual model to extract data if your PDFs contain formatted or image-based text rather than plain text. DeepDoc is the default visual model but can be time-consuming. You can also choose a lightweight or high-performance img2txt model depending on your needs and hardware capabilities. + +### Can I select a visual model to parse my DOCX files? + +No, you cannot. This dropdown menu is for PDFs only. To use this feature, convert your DOCX files to PDF first. + diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/set_metadata.md b/website/versioned_docs/version-v0.21.1/guides/dataset/set_metadata.md new file mode 100644 index 0000000..15491ad --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/set_metadata.md @@ -0,0 +1,32 @@ +--- +sidebar_position: -7 +slug: /set_metada +--- + +# Set metadata + +Add metadata to an uploaded file + +--- + +On the **Dataset** page of your dataset, you can add metadata to any uploaded file. This approach enables you to 'tag' additional information like URL, author, date, and more to an existing file. In an AI-powered chat, such information will be sent to the LLM with the retrieved chunks for content generation. + +For example, if you have a dataset of HTML files and want the LLM to cite the source URL when responding to your query, add a `"url"` parameter to each file's metadata. + +![Set metadata](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/set_metadata.jpg) + +:::tip NOTE +Ensure that your metadata is in JSON format; otherwise, your updates will not be applied. +::: + +![Input metadata](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/input_metadata.jpg) + +## Related APIs + +[Retrieve chunks](../../references/http_api_reference.md#retrieve-chunks) + +## Frequently asked questions + +### Can I set metadata for multiple documents at once? + +No, you must set metadata *individually* for each document, as RAGFlow does not support batch setting of metadata. If you still consider this feature essential, please [raise an issue](https://github.com/infiniflow/ragflow/issues) explaining your use case and its importance. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/set_page_rank.md b/website/versioned_docs/version-v0.21.1/guides/dataset/set_page_rank.md new file mode 100644 index 0000000..5df848a --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/set_page_rank.md @@ -0,0 +1,39 @@ +--- +sidebar_position: -2 +slug: /set_page_rank +--- + +# Set page rank + +Create a step-retrieval strategy using page rank. + +--- + +## Scenario + +In an AI-powered chat, you can configure a chat assistant or an agent to respond using knowledge retrieved from multiple specified datasets (datasets), provided that they employ the same embedding model. In situations where you prefer information from certain dataset(s) to take precedence or to be retrieved first, you can use RAGFlow's page rank feature to increase the ranking of chunks from these datasets. For example, if you have configured a chat assistant to draw from two datasets, dataset A for 2024 news and dataset B for 2023 news, but wish to prioritize news from year 2024, this feature is particularly useful. + +:::info NOTE +It is important to note that this 'page rank' feature operates at the level of the entire dataset rather than on individual files or documents. +::: + +## Configuration + +On the **Configuration** page of your dataset, drag the slider under **Page rank** to set the page rank value for your dataset. You are also allowed to input the intended page rank value in the field next to the slider. + +:::info NOTE +The page rank value must be an integer. Range: [0,100] + +- 0: Disabled (Default) +- A specific value: enabled +::: + +:::tip NOTE +If you set the page rank value to a non-integer, say 1.7, it will be rounded down to the nearest integer, which in this case is 1. +::: + +## Scoring mechanism + +If you configure a chat assistant's **similarity threshold** to 0.2, only chunks with a hybrid score greater than 0.2 x 100 = 20 will be retrieved and sent to the chat model for content generation. This initial filtering step is crucial for narrowing down relevant information. + +If you have assigned a page rank of 1 to dataset A (2024 news) and 0 to dataset B (2023 news), the final hybrid scores of the retrieved chunks will be adjusted accordingly. A chunk retrieved from dataset A with an initial score of 50 will receive a boost of 1 x 100 = 100 points, resulting in a final score of 50 + 1 x 100 = 150. In this way, chunks retrieved from dataset A will always precede chunks from dataset B. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/dataset/use_tag_sets.md b/website/versioned_docs/version-v0.21.1/guides/dataset/use_tag_sets.md new file mode 100644 index 0000000..35af071 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/dataset/use_tag_sets.md @@ -0,0 +1,103 @@ +--- +sidebar_position: 6 +slug: /use_tag_sets +--- + +# Use tag set + +Use a tag set to auto-tag chunks in your datasets. + +--- + +Retrieval accuracy is the touchstone for a production-ready RAG framework. In addition to retrieval-enhancing approaches like auto-keyword, auto-question, and knowledge graph, RAGFlow introduces an auto-tagging feature to address semantic gaps. The auto-tagging feature automatically maps tags in the user-defined tag sets to relevant chunks within your dataset based on similarity with each chunk. This automation mechanism allows you to apply an additional "layer" of domain-specific knowledge to existing datasets, which is particularly useful when dealing with a large number of chunks. + +To use this feature, ensure you have at least one properly configured tag set, specify the tag set(s) on the **Configuration** page of your dataset, and then re-parse your documents to initiate the auto-tagging process. During this process, each chunk in your dataset is compared with every entry in the specified tag set(s), and tags are automatically applied based on similarity. + +## Scenarios + +Auto-tagging applies in situations where chunks are so similar to each other that the intended chunks cannot be distinguished from the rest. For example, when you have a few chunks about iPhone and a majority about iPhone case or iPhone accessaries, it becomes difficult to retrieve those chunks about iPhone without additional information. + +## 1. Create tag set + +You can consider a tag set as a closed set, and the tags to attach to the chunks in your dataset are *exclusively* from the specified tag set. You use a tag set to "inform" RAGFlow which chunks to tag and which tags to apply. + +### Prepare a tag table file + +A tag set can comprise one or multiple table files in XLSX, CSV, or TXT formats. Each table file in the tag set contains two columns, **Description** and **Tag**: + +- The first column provides descriptions of the tags listed in the second column. These descriptions can be example chunks or example queries. Similarity will be calculated between each entry in this column and every chunk in your dataset. +- The **Tag** column includes tags to pair with the description entries. Multiple tags should be separated by a comma (,). + +:::tip NOTE +As a rule of thumb, consider including the following entries in your tag table: + +- Descriptions of intended chunks, along with their corresponding tags. +- User queries that fail to retrieve the correct responses using other methods, ensuring their tags match the intended chunks in your dataset. +::: + +### Create a tag set + +:::danger IMPORTANT +A tag set is *not* involved in document indexing or retrieval. Do not specify a tag set when configuring your chat assistant or agent. +::: + +1. Click **+ Create dataset** to create a dataset. +2. Navigate to the **Configuration** page of the created dataset, select **Built-in** in **Ingestion pipeline**, then choose **Tag** as the default chunking method from the **Built-in** drop-down menu. +3. Go back to the **Files** page and upload and parse your table file in XLSX, CSV, or TXT formats. + _A tag cloud appears under the **Tag view** section, indicating the tag set is created:_ + ![Image](https://github.com/user-attachments/assets/abefbcbf-c130-4abe-95e1-267b0d2a0505) +4. Click the **Table** tab to view the tag frequency table: + ![Image](https://github.com/user-attachments/assets/af91d10c-5ea5-491f-ab21-3803d5ebf59f) + +## 2. Tag chunks + +Once a tag set is created, you can apply it to your dataset: + +1. Navigate to the **Configuration** page of your dataset. +2. Select the tag set from the **Tag sets** dropdown and click **Save** to confirm. + +:::tip NOTE +If the tag set is missing from the dropdown, check that it has been created or configured correctly. +::: + +3. Re-parse your documents to start the auto-tagging process. + _In an AI chat scenario using auto-tagged datasets, each query will be tagged using the corresponding tag set(s) and chunks with these tags will have a higher chance to be retrieved._ + +## 3. Update tag set + +Creating a tag set is *not* for once and for all. Oftentimes, you may find it necessary to update or delete existing tags or add new entries. + +- You can update the existing tag set in the tag frequency table. +- To add new entries, you can add and parse new table files in XLSX, CSV, or TXT formats. + +### Update tag set in tag frequency table + +1. Navigate to the **Configuration** page in your tag set. +2. Click the **Table** tab under **Tag view** to view the tag frequncy table, where you can update tag names or delete tags. + +:::danger IMPORTANT +When a tag set is updated, you must re-parse the documents in your dataset so that their tags can be updated accordingly. +::: + +### Add new table files + +1. Navigate to the **Configuration** page in your tag set. +2. Navigate to the **Dataset** page and upload and parse your table file in XLSX, CSV, or TXT formats. + +:::danger IMPORTANT +If you add new table files to your tag set, it is at your own discretion whether to re-parse your documents in your datasets. +::: + +## Frequently asked questions + +### Can I reference more than one tag set? + +Yes, you can. Usually one tag set suffices. When using multiple tag sets, ensure they are independent of each other; otherwise, consider merging your tag sets. + +### Difference between a tag set and a standard dataset? + +A standard dataset is a dataset. It will be searched by RAGFlow's document engine and the retrieved chunks will be fed to the LLM. In contrast, a tag set is used solely to attach tags to chunks within your dataset. It does not directly participate in the retrieval process, and you should not choose a tag set when selecting datasets for your chat assistant or agent. + +### Difference between auto-tag and auto-keyword? + +Both features enhance retrieval in RAGFlow. The auto-keyword feature relies on the LLM and consumes a significant number of tokens, whereas the auto-tag feature is based on vector similarity and predefined tag set(s). You can view the keywords applied in the auto-keyword feature as an open set, as they are generated by the LLM. In contrast, a tag set can be considered a user-defined close set, requiring upload tag set(s) in specified formats before use. diff --git a/website/versioned_docs/version-v0.21.1/guides/manage_files.md b/website/versioned_docs/version-v0.21.1/guides/manage_files.md new file mode 100644 index 0000000..127eaf5 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/manage_files.md @@ -0,0 +1,90 @@ +--- +sidebar_position: 6 +slug: /manage_files +--- + +# Files + +RAGFlow's file management allows you to upload files individually or in bulk. You can then link an uploaded file to multiple target datasets. This guide showcases some basic usages of the file management feature. + +:::info IMPORTANT +Compared to uploading files directly to various datasets, uploading them to RAGFlow's file management and then linking them to different datasets is *not* an unnecessary step, particularly when you want to delete some parsed files or an entire dataset but retain the original files. +::: + +## Create folder + +RAGFlow's file management allows you to establish your file system with nested folder structures. To create a folder in the root directory of RAGFlow: + +![create new folder](https://github.com/infiniflow/ragflow/assets/93570324/3a37a5f4-43a6-426d-a62a-e5cd2ff7a533) + +:::caution NOTE +Each dataset in RAGFlow has a corresponding folder under the **root/.knowledgebase** directory. You are not allowed to create a subfolder within it. +::: + +## Upload file + +RAGFlow's file management supports file uploads from your local machine, allowing both individual and bulk uploads: + +![upload file](https://github.com/infiniflow/ragflow/assets/93570324/5d7ded14-ce2b-4703-8567-9356a978f45c) + +![bulk upload](https://github.com/infiniflow/ragflow/assets/93570324/def0db55-824c-4236-b809-a98d8c8674e3) + +## Preview file + +RAGFlow's file management supports previewing files in the following formats: + +- Documents (PDF, DOCS) +- Tables (XLSX) +- Pictures (JPEG, JPG, PNG, TIF, GIF) + +![preview](https://github.com/infiniflow/ragflow/assets/93570324/2e931362-8bbf-482c-ac86-b68b09d331bc) + +## Link file to datasets + +RAGFlow's file management allows you to *link* an uploaded file to multiple datasets, creating a file reference in each target dataset. Therefore, deleting a file in your file management will AUTOMATICALLY REMOVE all related file references across the datasets. + +![link knowledgebase](https://github.com/infiniflow/ragflow/assets/93570324/6c6b8db4-3269-4e35-9434-6089887e3e3f) + +You can link your file to one dataset or multiple datasets at one time: + +![link multiple kb](https://github.com/infiniflow/ragflow/assets/93570324/6c508803-fb1f-435d-b688-683066fd7fff) + +## Move file to a specific folder + +![move files](https://github.com/user-attachments/assets/3a2db469-6811-4ea0-be80-403b61ffe257) + +## Search files or folders + +**File Management** only supports file name and folder name filtering in the current directory (files or folders in the child directory will not be retrieved). + +![search file](https://github.com/infiniflow/ragflow/assets/93570324/77ffc2e5-bd80-4ed1-841f-068e664efffe) + +## Rename file or folder + +RAGFlow's file management allows you to rename a file or folder: + +![rename_file](https://github.com/infiniflow/ragflow/assets/93570324/5abb0704-d9e9-4b43-9ed4-5750ccee011f) + + +## Delete files or folders + +RAGFlow's file management allows you to delete files or folders individually or in bulk. + +To delete a file or folder: + +![delete file](https://github.com/infiniflow/ragflow/assets/93570324/85872728-125d-45e9-a0ee-21e9d4cedb8b) + +To bulk delete files or folders: + +![bulk delete](https://github.com/infiniflow/ragflow/assets/93570324/519b99ab-ec7f-4c8a-8cea-e0b6dcb3cb46) + +> - You are not allowed to delete the **root/.knowledgebase** folder. +> - Deleting files that have been linked to datasets will **AUTOMATICALLY REMOVE** all associated file references across the datasets. + +## Download uploaded file + +RAGFlow's file management allows you to download an uploaded file: + +![download_file](https://github.com/infiniflow/ragflow/assets/93570324/cf3b297f-7d9b-4522-bf5f-4f45743e4ed5) + +> As of RAGFlow v0.21.1, bulk download is not supported, nor can you download an entire folder. diff --git a/website/versioned_docs/version-v0.21.1/guides/manage_users_and_services.md b/website/versioned_docs/version-v0.21.1/guides/manage_users_and_services.md new file mode 100644 index 0000000..02e569a --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/manage_users_and_services.md @@ -0,0 +1,390 @@ +--- +sidebar_position: 6 +slug: /manage_users_and_services +--- + + +# Admin CLI and Admin Service + + + +The Admin CLI and Admin Service form a client-server architectural suite for RAGflow system administration. The Admin CLI serves as an interactive command-line interface that receives instructions and displays execution results from the Admin Service in real-time. This duo enables real-time monitoring of system operational status, supporting visibility into RAGflow Server services and dependent components including MySQL, Elasticsearch, Redis, and MinIO. In administrator mode, they provide user management capabilities that allow viewing users and performing critical operations—such as user creation, password updates, activation status changes, and comprehensive user data deletion—even when corresponding web interface functionalities are disabled. + + + +## Starting the Admin Service + +### Launching from source code + +1. Before start Admin Service, please make sure RAGFlow system is already started. + +2. Launch from source code: + + ```bash + python admin/server/admin_server.py + ``` + + The service will start and listen for incoming connections from the CLI on the configured port. + +### Using docker image + +1. Before startup, please configure the `docker_compose.yml` file to enable admin server: + + ```bash + command: + - --enable-adminserver + ``` + +2. Start the containers, the service will start and listen for incoming connections from the CLI on the configured port. + + + +## Using the Admin CLI + +1. Ensure the Admin Service is running. + +2. Install ragflow-cli. + + ```bash + pip install ragflow-cli==0.21.1 + ``` + +3. Launch the CLI client: + + ```bash + ragflow-cli -h 127.0.0.1 -p 9381 + ``` + + You will be prompted to enter the superuser's password to log in. + The default password is admin. + + **Parameters:** + + - -h: RAGFlow admin server host address + + - -p: RAGFlow admin server port + + + +## Supported Commands + +Commands are case-insensitive and must be terminated with a semicolon(;). + +### Service manage commands + + `LIST SERVICES;` + +- Lists all available services within the RAGFlow system. + +- [Example](#example-list-services) + +`SHOW SERVICE ;` + +- Shows detailed status information for the service identified by **id**. +- [Example](#example-show-service) + +### User Management Commands + +`LIST USERS;` + +- Lists all users known to the system. +- [Example](#example-list-users) + +`SHOW USER ;` + +- Shows details and permissions for the user specified by **email**. The username must be enclosed in single or double quotes. +- [Example](#example-show-user) + +`CREATE USER ;` + +- Create user by username and password. The username and password must be enclosed in single or double quotes. +- [Example](#example-create-user) + +`DROP USER ;` + +- Removes the specified user from the system. Use with caution. +- [Example](#example-drop-user) + +`ALTER USER PASSWORD ;` + +- Changes the password for the specified user. +- [Example](#example-alter-user-password) + +`ALTER USER ACTIVE ;` + +- Changes the user to active or inactive. +- [Example](#example-alter-user-active) + +### Data and Agent Commands + +`LIST DATASETS OF ;` + +- Lists the datasets associated with the specified user. +- [Example](#example-list-datasets-of-user) + +`LIST AGENTS OF ;` + +- Lists the agents associated with the specified user. +- [Example](#example-list-agents-of-user) + +### Meta-Commands + +- \? or \help + Shows help information for the available commands. +- \q or \quit + Exits the CLI application. +- [Example](#example-meta-commands) + +### Examples + + + +- List all available services. + +``` +admin> list services; +command: list services; +Listing all services ++-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+ +| extra | host | id | name | port | service_type | status | ++-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+ +| {} | 0.0.0.0 | 0 | ragflow_0 | 9380 | ragflow_server | Timeout | +| {'meta_type': 'mysql', 'password': 'infini_rag_flow', 'username': 'root'} | localhost | 1 | mysql | 5455 | meta_data | Alive | +| {'password': 'infini_rag_flow', 'store_type': 'minio', 'user': 'rag_flow'} | localhost | 2 | minio | 9000 | file_store | Alive | +| {'password': 'infini_rag_flow', 'retrieval_type': 'elasticsearch', 'username': 'elastic'} | localhost | 3 | elasticsearch | 1200 | retrieval | Alive | +| {'db_name': 'default_db', 'retrieval_type': 'infinity'} | localhost | 4 | infinity | 23817 | retrieval | Timeout | +| {'database': 1, 'mq_type': 'redis', 'password': 'infini_rag_flow'} | localhost | 5 | redis | 6379 | message_queue | Alive | ++-------------------------------------------------------------------------------------------+-----------+----+---------------+-------+----------------+---------+ + +``` + + + +- Show ragflow_server. + +``` +admin> show service 0; +command: show service 0; +Showing service: 0 +Service ragflow_0 is alive. Detail: +Confirm elapsed: 26.0 ms. +``` + +- Show mysql. + +``` +admin> show service 1; +command: show service 1; +Showing service: 1 +Service mysql is alive. Detail: ++---------+----------+------------------+------+------------------+------------------------+-------+-----------------+ +| command | db | host | id | info | state | time | user | ++---------+----------+------------------+------+------------------+------------------------+-------+-----------------+ +| Daemon | None | localhost | 5 | None | Waiting on empty queue | 16111 | event_scheduler | +| Sleep | rag_flow | 172.18.0.1:40046 | 1610 | None | | 2 | root | +| Query | rag_flow | 172.18.0.1:35882 | 1629 | SHOW PROCESSLIST | init | 0 | root | ++---------+----------+------------------+------+------------------+------------------------+-------+-----------------+ +``` + +- Show minio. + +``` +admin> show service 2; +command: show service 2; +Showing service: 2 +Service minio is alive. Detail: +Confirm elapsed: 2.1 ms. +``` + +- Show elasticsearch. + +``` +admin> show service 3; +command: show service 3; +Showing service: 3 +Service elasticsearch is alive. Detail: ++----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+ +| cluster_name | docs | docs_deleted | indices | indices_shards | jvm_heap_max | jvm_heap_used | jvm_versions | mappings_deduplicated_fields | mappings_deduplicated_size | mappings_fields | nodes | nodes_version | os_mem | os_mem_used | os_mem_used_percent | status | store_size | total_dataset_size | ++----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+ +| docker-cluster | 717 | 86 | 37 | 42 | 3.76 GB | 1.74 GB | 21.0.1+12-29 | 6575 | 48.0 KB | 8521 | 1 | ['8.11.3'] | 7.52 GB | 4.55 GB | 61 | green | 4.60 MB | 4.60 MB | ++----------------+------+--------------+---------+----------------+--------------+---------------+--------------+------------------------------+----------------------------+-----------------+-------+---------------+---------+-------------+---------------------+--------+------------+--------------------+ +``` + +- Show infinity. + +``` +admin> show service 4; +command: show service 4; +Showing service: 4 +Fail to show service, code: 500, message: Infinity is not in use. +``` + +- Show redis. + +``` +admin> show service 5; +command: show service 5; +Showing service: 5 +Service redis is alive. Detail: ++-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+ +| blocked_clients | connected_clients | instantaneous_ops_per_sec | mem_fragmentation_ratio | redis_version | server_mode | total_commands_processed | total_system_memory | used_memory | ++-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+ +| 0 | 2 | 1 | 10.41 | 7.2.4 | standalone | 10446 | 30.84G | 1.10M | ++-----------------+-------------------+---------------------------+-------------------------+---------------+-------------+--------------------------+---------------------+-------------+ +``` + + + +- List all user. + +``` +admin> list users; +command: list users; +Listing all users ++-------------------------------+----------------------+-----------+----------+ +| create_date | email | is_active | nickname | ++-------------------------------+----------------------+-----------+----------+ +| Mon, 22 Sep 2025 10:59:04 GMT | admin@ragflow.io | 1 | admin | +| Sun, 14 Sep 2025 17:36:27 GMT | lynn_inf@hotmail.com | 1 | Lynn | ++-------------------------------+----------------------+-----------+----------+ +``` + + + +- Show specified user. + +``` +admin> show user "admin@ragflow.io"; +command: show user "admin@ragflow.io"; +Showing user: admin@ragflow.io ++-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+ +| create_date | email | is_active | is_anonymous | is_authenticated | is_superuser | language | last_login_time | login_channel | status | update_date | ++-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+ +| Mon, 22 Sep 2025 10:59:04 GMT | admin@ragflow.io | 1 | 0 | 1 | True | Chinese | None | None | 1 | Mon, 22 Sep 2025 10:59:04 GMT | ++-------------------------------+------------------+-----------+--------------+------------------+--------------+----------+-----------------+---------------+--------+-------------------------------+ +``` + + + +- Create new user. + +``` +admin> create user "example@ragflow.io" "psw"; +command: create user "example@ragflow.io" "psw"; +Create user: example@ragflow.io, password: psw, role: user ++----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+ +| access_token | email | id | is_superuser | login_channel | nickname | ++----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+ +| 5cdc6d1e9df111f099b543aee592c6bf | example@ragflow.io | 5cdc6ca69df111f099b543aee592c6bf | False | password | | ++----------------------------------+--------------------+----------------------------------+--------------+---------------+----------+ +``` + + + +- Alter user password. + +``` +admin> alter user password "example@ragflow.io" "newpsw"; +command: alter user password "example@ragflow.io" "newpsw"; +Alter user: example@ragflow.io, password: newpsw +Password updated successfully! +``` + + + +- Alter user active, turn off. + +``` +admin> alter user active "example@ragflow.io" off; +command: alter user active "example@ragflow.io" off; +Alter user example@ragflow.io activate status, turn off. +Turn off user activate status successfully! +``` + + + +- Drop user. + +``` +admin> Drop user "example@ragflow.io"; +command: Drop user "example@ragflow.io"; +Drop user: example@ragflow.io +Successfully deleted user. Details: +Start to delete owned tenant. +- Deleted 2 tenant-LLM records. +- Deleted 0 langfuse records. +- Deleted 1 tenant. +- Deleted 1 user-tenant records. +- Deleted 1 user. +Delete done! +``` + +Delete user's data at the same time. + + + +- List the specified user's dataset. + +``` +admin> list datasets of "lynn_inf@hotmail.com"; +command: list datasets of "lynn_inf@hotmail.com"; +Listing all datasets of user: lynn_inf@hotmail.com ++-----------+-------------------------------+---------+----------+---------------+------------+--------+-----------+-------------------------------+ +| chunk_num | create_date | doc_num | language | name | permission | status | token_num | update_date | ++-----------+-------------------------------+---------+----------+---------------+------------+--------+-----------+-------------------------------+ +| 29 | Mon, 15 Sep 2025 11:56:59 GMT | 12 | Chinese | test_dataset | me | 1 | 12896 | Fri, 19 Sep 2025 17:50:58 GMT | +| 4 | Sun, 28 Sep 2025 11:49:31 GMT | 6 | Chinese | dataset_share | team | 1 | 1121 | Sun, 28 Sep 2025 14:41:03 GMT | ++-----------+-------------------------------+---------+----------+---------------+------------+--------+-----------+-------------------------------+ +``` + + + +- List the specified user's agents. + +``` +admin> list agents of "lynn_inf@hotmail.com"; +command: list agents of "lynn_inf@hotmail.com"; +Listing all agents of user: lynn_inf@hotmail.com ++-----------------+-------------+------------+-----------------+ +| canvas_category | canvas_type | permission | title | ++-----------------+-------------+------------+-----------------+ +| agent | None | team | research_helper | ++-----------------+-------------+------------+-----------------+ +``` + + + +- Show help information. + +``` +admin> \help +command: \help + +Commands: + LIST SERVICES + SHOW SERVICE + STARTUP SERVICE + SHUTDOWN SERVICE + RESTART SERVICE + LIST USERS + SHOW USER + DROP USER + CREATE USER + ALTER USER PASSWORD + ALTER USER ACTIVE + LIST DATASETS OF + LIST AGENTS OF + +Meta Commands: + \?, \h, \help Show this help + \q, \quit, \exit Quit the CLI +``` + +- Exit + +``` +admin> \q +command: \q +Goodbye! +``` + diff --git a/website/versioned_docs/version-v0.21.1/guides/migration/migrate_from_docker_compose.md b/website/versioned_docs/version-v0.21.1/guides/migration/migrate_from_docker_compose.md new file mode 100644 index 0000000..a8d36ea --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/migration/migrate_from_docker_compose.md @@ -0,0 +1,108 @@ +# Data Migration Guide + +A common scenario is processing large datasets on a powerful instance (e.g., with a GPU) and then migrating the entire RAGFlow service to a different production environment (e.g., a CPU-only server). This guide explains how to safely back up and restore your data using our provided migration script. + +## Identifying Your Data + +By default, RAGFlow uses Docker volumes to store all persistent data, including your database, uploaded files, and search indexes. You can see these volumes by running: + +```bash +docker volume ls +``` + +The output will look similar to this: + +```text +DRIVER VOLUME NAME +local docker_esdata01 +local docker_minio_data +local docker_mysql_data +local docker_redis_data +``` + +These volumes contain all the data you need to migrate. + +## Step 1: Stop RAGFlow Services + +Before starting the migration, you must stop all running RAGFlow services on the **source machine**. Navigate to the project's root directory and run: + +```bash +docker-compose -f docker/docker-compose.yml down +``` + +**Important:** Do **not** use the `-v` flag (e.g., `docker-compose down -v`), as this will delete all your data volumes. The migration script includes a check and will prevent you from running it if services are active. + +## Step 2: Back Up Your Data + +We provide a convenient script to package all your data volumes into a single backup folder. + +For a quick reference of the script's commands and options, you can run: +```bash +bash docker/migration.sh help +``` + +To create a backup, run the following command from the project's root directory: + +```bash +bash docker/migration.sh backup +``` + +This will create a `backup/` folder in your project root containing compressed archives of your data volumes. + +You can also specify a custom name for your backup folder: + +```bash +bash docker/migration.sh backup my_ragflow_backup +``` + +This will create a folder named `my_ragflow_backup/` instead. + +## Step 3: Transfer the Backup Folder + +Copy the entire backup folder (e.g., `backup/` or `my_ragflow_backup/`) from your source machine to the RAGFlow project directory on your **target machine**. You can use tools like `scp`, `rsync`, or a physical drive for the transfer. + +## Step 4: Restore Your Data + +On the **target machine**, ensure that RAGFlow services are not running. Then, use the migration script to restore your data from the backup folder. + +If your backup folder is named `backup/`, run: + +```bash +bash docker/migration.sh restore +``` + +If you used a custom name, specify it in the command: + +```bash +bash docker/migration.sh restore my_ragflow_backup +``` + +The script will automatically create the necessary Docker volumes and unpack the data. + +**Note:** If the script detects that Docker volumes with the same names already exist on the target machine, it will warn you that restoring will overwrite the existing data and ask for confirmation before proceeding. + +## Step 5: Start RAGFlow Services + +Once the restore process is complete, you can start the RAGFlow services on your new machine: + +```bash +docker-compose -f docker/docker-compose.yml up -d +``` + +**Note:** If you already have build an service by docker-compose before, you may need to backup your data for target machine like this guide above and run like: + +```bash +# Please backup by `sh docker/migration.sh backup backup_dir_name` before you do the following line. +# !!! this line -v flag will delete the original docker volume +docker-compose -f docker/docker-compose.yml down -v +docker-compose -f docker/docker-compose.yml up -d +``` + +Your RAGFlow instance is now running with all the data from your original machine. + + + + + + + diff --git a/website/versioned_docs/version-v0.21.1/guides/models/_category_.json b/website/versioned_docs/version-v0.21.1/guides/models/_category_.json new file mode 100644 index 0000000..8536f8e --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/models/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Models", + "position": -1, + "link": { + "type": "generated-index", + "description": "Guides on model settings." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/models/deploy_local_llm.mdx b/website/versioned_docs/version-v0.21.1/guides/models/deploy_local_llm.mdx new file mode 100644 index 0000000..6553e7c --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/models/deploy_local_llm.mdx @@ -0,0 +1,353 @@ +--- +sidebar_position: 2 +slug: /deploy_local_llm +--- + +# Deploy local models +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Deploy and run local models using Ollama, Xinference, or other frameworks. + +--- + +RAGFlow supports deploying models locally using Ollama, Xinference, IPEX-LLM, or jina. If you have locally deployed models to leverage or wish to enable GPU or CUDA for inference acceleration, you can bind Ollama or Xinference into RAGFlow and use either of them as a local "server" for interacting with your local models. + +RAGFlow seamlessly integrates with Ollama and Xinference, without the need for further environment configurations. You can use them to deploy two types of local models in RAGFlow: chat models and embedding models. + +:::tip NOTE +This user guide does not intend to cover much of the installation or configuration details of Ollama or Xinference; its focus is on configurations inside RAGFlow. For the most current information, you may need to check out the official site of Ollama or Xinference. +::: + +## Deploy local models using Ollama + +[Ollama](https://github.com/ollama/ollama) enables you to run open-source large language models that you deployed locally. It bundles model weights, configurations, and data into a single package, defined by a Modelfile, and optimizes setup and configurations, including GPU usage. + +:::note +- For information about downloading Ollama, see [here](https://github.com/ollama/ollama?tab=readme-ov-file#ollama). +- For a complete list of supported models and variants, see the [Ollama model library](https://ollama.com/library). +::: + +### 1. Deploy Ollama using Docker + +Ollama can be [installed from binaries](https://ollama.com/download) or [deployed with Docker](https://hub.docker.com/r/ollama/ollama). Here are the instructions to deploy with Docker: + +```bash +$ sudo docker run --name ollama -p 11434:11434 ollama/ollama +> time=2024-12-02T02:20:21.360Z level=INFO source=routes.go:1248 msg="Listening on [::]:11434 (version 0.4.6)" +> time=2024-12-02T02:20:21.360Z level=INFO source=common.go:49 msg="Dynamic LLM libraries" runners="[cpu cpu_avx cpu_avx2 cuda_v11 cuda_v12]" +``` + +Ensure Ollama is listening on all IP address: +```bash +$ sudo ss -tunlp | grep 11434 +> tcp LISTEN 0 4096 0.0.0.0:11434 0.0.0.0:* users:(("docker-proxy",pid=794507,fd=4)) +> tcp LISTEN 0 4096 [::]:11434 [::]:* users:(("docker-proxy",pid=794513,fd=4)) +``` + +Pull models as you need. We recommend that you start with `llama3.2` (a 3B chat model) and `bge-m3` (a 567M embedding model): +```bash +$ sudo docker exec ollama ollama pull llama3.2 +> pulling dde5aa3fc5ff... 100% ▕████████████████▏ 2.0 GB +> success +``` + +```bash +$ sudo docker exec ollama ollama pull bge-m3 +> pulling daec91ffb5dd... 100% ▕████████████████▏ 1.2 GB +> success +``` + +### 2. Find Ollama URL and ensure it is accessible + +- If RAGFlow runs in Docker, the localhost is mapped within the RAGFlow Docker container as `host.docker.internal`. If Ollama runs on the same host machine, the right URL to use for Ollama would be `http://host.docker.internal:11434/' and you should check that Ollama is accessible from inside the RAGFlow container with: +```bash +$ sudo docker exec -it ragflow-server bash +$ curl http://host.docker.internal:11434/ +> Ollama is running +``` + +- If RAGFlow is launched from source code and Ollama runs on the same host machine as RAGFlow, check if Ollama is accessible from RAGFlow's host machine: +```bash +$ curl http://localhost:11434/ +> Ollama is running +``` + +- If RAGFlow and Ollama run on different machines, check if Ollama is accessible from RAGFlow's host machine: +```bash +$ curl http://${IP_OF_OLLAMA_MACHINE}:11434/ +> Ollama is running +``` + +### 3. Add Ollama + +In RAGFlow, click on your logo on the top right of the page **>** **Model providers** and add Ollama to RAGFlow: + +![add ollama](https://github.com/infiniflow/ragflow/assets/93570324/10635088-028b-4b3d-add9-5c5a6e626814) + + +### 4. Complete basic Ollama settings + +In the popup window, complete basic settings for Ollama: + +1. Ensure that your model name and type match those been pulled at step 1 (Deploy Ollama using Docker). For example, (`llama3.2` and `chat`) or (`bge-m3` and `embedding`). +2. Put in the Ollama base URL, i.e. `http://host.docker.internal:11434`, `http://localhost:11434` or `http://${IP_OF_OLLAMA_MACHINE}:11434`. +3. OPTIONAL: Switch on the toggle under **Does it support Vision?** if your model includes an image-to-text model. + + +:::caution WARNING +Improper base URL settings will trigger the following error: +```bash +Max retries exceeded with url: /api/chat (Caused by NewConnectionError(': Failed to establish a new connection: [Errno 111] Connection refused')) +``` +::: + +### 5. Update System Model Settings + +Click on your logo **>** **Model providers** **>** **System Model Settings** to update your model: + +- *You should now be able to find **llama3.2** from the dropdown list under **Chat model**, and **bge-m3** from the dropdown list under **Embedding model**.* +- _If your local model is an embedding model, you should find it under **Embedding model**._ + +### 6. Update Chat Configuration + +Update your model(s) accordingly in **Chat Configuration**. + +## Deploy a local model using Xinference + +Xorbits Inference ([Xinference](https://github.com/xorbitsai/inference)) enables you to unleash the full potential of cutting-edge AI models. + +:::note +- For information about installing Xinference Ollama, see [here](https://inference.readthedocs.io/en/latest/getting_started/). +- For a complete list of supported models, see the [Builtin Models](https://inference.readthedocs.io/en/latest/models/builtin/). +::: + +To deploy a local model, e.g., **Mistral**, using Xinference: + +### 1. Check firewall settings + +Ensure that your host machine's firewall allows inbound connections on port 9997. + +### 2. Start an Xinference instance + +```bash +$ xinference-local --host 0.0.0.0 --port 9997 +``` + +### 3. Launch your local model + +Launch your local model (**Mistral**), ensuring that you replace `${quantization}` with your chosen quantization method: + +```bash +$ xinference launch -u mistral --model-name mistral-v0.1 --size-in-billions 7 --model-format pytorch --quantization ${quantization} +``` +### 4. Add Xinference + +In RAGFlow, click on your logo on the top right of the page **>** **Model providers** and add Xinference to RAGFlow: + +![add xinference](https://github.com/infiniflow/ragflow/assets/93570324/10635088-028b-4b3d-add9-5c5a6e626814) + +### 5. Complete basic Xinference settings + +Enter an accessible base URL, such as `http://:9997/v1`. +> For rerank model, please use the `http://:9997/v1/rerank` as the base URL. + +### 6. Update System Model Settings + +Click on your logo **>** **Model providers** **>** **System Model Settings** to update your model. + +*You should now be able to find **mistral** from the dropdown list under **Chat model**.* + +> If your local model is an embedding model, you should find your local model under **Embedding model**. + +### 7. Update Chat Configuration + +Update your chat model accordingly in **Chat Configuration**: + +> If your local model is an embedding model, update it on the configuration page of your dataset. + +## Deploy a local model using IPEX-LLM + +[IPEX-LLM](https://github.com/intel-analytics/ipex-llm) is a PyTorch library for running LLMs on local Intel CPUs or GPUs (including iGPU or discrete GPUs like Arc, Flex, and Max) with low latency. It supports Ollama on Linux and Windows systems. + +To deploy a local model, e.g., **Qwen2**, using IPEX-LLM-accelerated Ollama: + +### 1. Check firewall settings + +Ensure that your host machine's firewall allows inbound connections on port 11434. For example: + +```bash +sudo ufw allow 11434/tcp +``` + +### 2. Launch Ollama service using IPEX-LLM + +#### 2.1 Install IPEX-LLM for Ollama + +:::tip NOTE +IPEX-LLM's supports Ollama on Linux and Windows systems. +::: + +For detailed information about installing IPEX-LLM for Ollama, see [Run llama.cpp with IPEX-LLM on Intel GPU Guide](https://github.com/intel-analytics/ipex-llm/blob/main/docs/mddocs/Quickstart/llama_cpp_quickstart.md): +- [Prerequisites](https://github.com/intel-analytics/ipex-llm/blob/main/docs/mddocs/Quickstart/llama_cpp_quickstart.md#0-prerequisites) +- [Install IPEX-LLM cpp with Ollama binaries](https://github.com/intel-analytics/ipex-llm/blob/main/docs/mddocs/Quickstart/llama_cpp_quickstart.md#1-install-ipex-llm-for-llamacpp) + +*After the installation, you should have created a Conda environment, e.g., `llm-cpp`, for running Ollama commands with IPEX-LLM.* + +#### 2.2 Initialize Ollama + +1. Activate the `llm-cpp` Conda environment and initialize Ollama: + + + + + ```bash + conda activate llm-cpp + init-ollama + ``` + + + + Run these commands with *administrator privileges in Miniforge Prompt*: + + ```cmd + conda activate llm-cpp + init-ollama.bat + ``` + + + +2. If the installed `ipex-llm[cpp]` requires an upgrade to the Ollama binary files, remove the old binary files and reinitialize Ollama using `init-ollama` (Linux) or `init-ollama.bat` (Windows). + + *A symbolic link to Ollama appears in your current directory, and you can use this executable file following standard Ollama commands.* + +#### 2.3 Launch Ollama service + +1. Set the environment variable `OLLAMA_NUM_GPU` to `999` to ensure that all layers of your model run on the Intel GPU; otherwise, some layers may default to CPU. +2. For optimal performance on Intel Arc™ A-Series Graphics with Linux OS (Kernel 6.2), set the following environment variable before launching the Ollama service: + + ```bash + export SYCL_PI_LEVEL_ZERO_USE_IMMEDIATE_COMMANDLISTS=1 + ``` +3. Launch the Ollama service: + + + + + ```bash + export OLLAMA_NUM_GPU=999 + export no_proxy=localhost,127.0.0.1 + export ZES_ENABLE_SYSMAN=1 + source /opt/intel/oneapi/setvars.sh + export SYCL_CACHE_PERSISTENT=1 + + ./ollama serve + ``` + + + + + Run the following command *in Miniforge Prompt*: + + ```cmd + set OLLAMA_NUM_GPU=999 + set no_proxy=localhost,127.0.0.1 + set ZES_ENABLE_SYSMAN=1 + set SYCL_CACHE_PERSISTENT=1 + + ollama serve + ``` + + + + +:::tip NOTE +To enable the Ollama service to accept connections from all IP addresses, use `OLLAMA_HOST=0.0.0.0 ./ollama serve` rather than simply `./ollama serve`. +::: + +*The console displays messages similar to the following:* + +![](https://llm-assets.readthedocs.io/en/latest/_images/ollama_serve.png) + +### 3. Pull and Run Ollama model + +#### 3.1 Pull Ollama model + +With the Ollama service running, open a new terminal and run `./ollama pull ` (Linux) or `ollama.exe pull ` (Windows) to pull the desired model. e.g., `qwen2:latest`: + +![](https://llm-assets.readthedocs.io/en/latest/_images/ollama_pull.png) + +#### 3.2 Run Ollama model + + + + + ```bash + ./ollama run qwen2:latest + ``` + + + + ```cmd + ollama run qwen2:latest + ``` + + + + +### 4. Configure RAGflow + +To enable IPEX-LLM accelerated Ollama in RAGFlow, you must also complete the configurations in RAGFlow. The steps are identical to those outlined in the *Deploy a local model using Ollama* section: + +1. [Add Ollama](#4-add-ollama) +2. [Complete basic Ollama settings](#5-complete-basic-ollama-settings) +3. [Update System Model Settings](#6-update-system-model-settings) +4. [Update Chat Configuration](#7-update-chat-configuration) + +## Deploy a local model using jina + +To deploy a local model, e.g., **gpt2**, using jina: + +### 1. Check firewall settings + +Ensure that your host machine's firewall allows inbound connections on port 12345. + +```bash +sudo ufw allow 12345/tcp +``` + +### 2. Install jina package + +```bash +pip install jina +``` + +### 3. Deploy a local model + +Step 1: Navigate to the **rag/svr** directory. + +```bash +cd rag/svr +``` + +Step 2: Run **jina_server.py**, specifying either the model's name or its local directory: + +```bash +python jina_server.py --model_name gpt2 +``` +> The script only supports models downloaded from Hugging Face. diff --git a/website/versioned_docs/version-v0.21.1/guides/models/llm_api_key_setup.md b/website/versioned_docs/version-v0.21.1/guides/models/llm_api_key_setup.md new file mode 100644 index 0000000..f61d71c --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/models/llm_api_key_setup.md @@ -0,0 +1,48 @@ +--- +sidebar_position: 1 +slug: /llm_api_key_setup +--- + +# Configure model API key + +An API key is required for RAGFlow to interact with an online AI model. This guide provides information about setting your model API key in RAGFlow. + +## Get model API key + +RAGFlow supports most mainstream LLMs. Please refer to [Supported Models](../../references/supported_models.mdx) for a complete list of supported models. You will need to apply for your model API key online. Note that most LLM providers grant newly-created accounts trial credit, which will expire in a couple of months, or a promotional amount of free quota. + +:::note +If you find your online LLM is not on the list, don't feel disheartened. The list is expanding, and you can [file a feature request](https://github.com/infiniflow/ragflow/issues/new?assignees=&labels=feature+request&projects=&template=feature_request.yml&title=%5BFeature+Request%5D%3A+) with us! Alternatively, if you have customized or locally-deployed models, you can [bind them to RAGFlow using Ollama, Xinference, or LocalAI](./deploy_local_llm.mdx). +::: + +## Configure model API key + +You have two options for configuring your model API key: + +- Configure it in **service_conf.yaml.template** before starting RAGFlow. +- Configure it on the **Model providers** page after logging into RAGFlow. + +### Configure model API key before starting up RAGFlow + +1. Navigate to **./docker/ragflow**. +2. Find entry **user_default_llm**: + - Update `factory` with your chosen LLM. + - Update `api_key` with yours. + - Update `base_url` if you use a proxy to connect to the remote service. +3. Reboot your system for your changes to take effect. +4. Log into RAGFlow. + _After logging into RAGFlow, you will find your chosen model appears under **Added models** on the **Model providers** page._ + +### Configure model API key after logging into RAGFlow + +:::caution WARNING +After logging into RAGFlow, configuring your model API key through the **service_conf.yaml.template** file will no longer take effect. +::: + +After logging into RAGFlow, you can *only* configure API Key on the **Model providers** page: + +1. Click on your logo on the top right of the page **>** **Model providers**. +2. Find your model card under **Models to be added** and click **Add the model**. +3. Paste your model API key. +4. Fill in your base URL if you use a proxy to connect to the remote service. +5. Click **OK** to confirm your changes. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/run_health_check.md b/website/versioned_docs/version-v0.21.1/guides/run_health_check.md new file mode 100644 index 0000000..5ed7cfd --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/run_health_check.md @@ -0,0 +1,109 @@ +--- +sidebar_position: 8 +slug: /run_health_check +--- + +# Monitoring + +Double-check the health status of RAGFlow's dependencies. + +--- + +The operation of RAGFlow depends on four services: + +- **Elasticsearch** (default) or [Infinity](https://github.com/infiniflow/infinity) as the document engine +- **MySQL** +- **Redis** +- **MinIO** for object storage + +If an exception or error occurs related to any of the above services, such as `Exception: Can't connect to ES cluster`, refer to this document to check their health status. + +You can also click you avatar in the top right corner of the page **>** System to view the visualized health status of RAGFlow's core services. The following screenshot shows that all services are 'green' (running healthily). The task executor displays the *cumulative* number of completed and failed document parsing tasks from the past 30 minutes: + +![system_status_page](https://github.com/user-attachments/assets/b0c1a11e-93e3-4947-b17a-1bfb4cdab6e4) + +Services with a yellow or red light are not running properly. The following is a screenshot of the system page after running `docker stop ragflow-es-10`: + +![es_failed](https://github.com/user-attachments/assets/06056540-49f5-48bf-9cc9-a7086bc75790) + +You can click on a specific 30-second time interval to view the details of completed and failed tasks: + +![done_tasks](https://github.com/user-attachments/assets/49b25ec4-03af-48cf-b2e5-c892f6eaa261) + +![done_vs_failed](https://github.com/user-attachments/assets/eaa928d0-a31c-4072-adea-046091e04599) + +## API Health Check + +In addition to checking the system dependencies from the **avatar > System** page in the UI, you can directly query the backend health check endpoint: + +```bash +http://IP_OF_YOUR_MACHINE/v1/system/healthz +``` + +Here `` refers to the actual port of your backend service (e.g., `7897`, `9222`, etc.). + +Key points: +- **No login required** (no `@login_required` decorator) +- Returns results in JSON format +- If all dependencies are healthy → HTTP **200 OK** +- If any dependency fails → HTTP **500 Internal Server Error** + +### Example 1: All services healthy (HTTP 200) + +```bash +http://127.0.0.1/v1/system/healthz +``` + +Response: + +```http +HTTP/1.1 200 OK +Content-Type: application/json +Content-Length: 120 + +{ + "db": "ok", + "redis": "ok", + "doc_engine": "ok", + "storage": "ok", + "status": "ok" +} +``` + +Explanation: +- Database (MySQL/Postgres), Redis, document engine (Elasticsearch/Infinity), and object storage (MinIO) are all healthy. +- The `status` field returns `"ok"`. + +### Example 2: One service unhealthy (HTTP 500) + +For example, if Redis is down: + +Response: + +```http +HTTP/1.1 500 INTERNAL SERVER ERROR +Content-Type: application/json +Content-Length: 300 + +{ + "db": "ok", + "redis": "nok", + "doc_engine": "ok", + "storage": "ok", + "status": "nok", + "_meta": { + "redis": { + "elapsed": "5.2", + "error": "Lost connection!" + } + } +} +``` + +Explanation: +- `redis` is marked as `"nok"`, with detailed error info under `_meta.redis.error`. +- The overall `status` is `"nok"`, so the endpoint returns 500. + +--- + +This endpoint allows you to monitor RAGFlow’s core dependencies programmatically in scripts or external monitoring systems, without relying on the frontend UI. diff --git a/website/versioned_docs/version-v0.21.1/guides/team/_category_.json b/website/versioned_docs/version-v0.21.1/guides/team/_category_.json new file mode 100644 index 0000000..37bbf13 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/team/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Team", + "position": 4, + "link": { + "type": "generated-index", + "description": "Team-specific guides." + } +} diff --git a/website/versioned_docs/version-v0.21.1/guides/team/join_or_leave_team.md b/website/versioned_docs/version-v0.21.1/guides/team/join_or_leave_team.md new file mode 100644 index 0000000..93255ef --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/team/join_or_leave_team.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 3 +slug: /join_or_leave_team +--- + +# Join or leave a team + +Accept an invite to join a team, decline an invite, or leave a team. + +--- + +Once you join a team, you can do the following: + +- Upload documents to the team owner's shared datasets. +- Parse documents in the team owner's shared datasets. +- Use the team owner's shared Agents. + +:::tip NOTE +You cannot invite users to a team unless you are its owner. +::: + +## Prerequisites + +1. Ensure that your Email address that received the team invitation is associated with a RAGFlow user account. +2. The team owner should share his datasets by setting their **Permission** to **Team**. + +## Accept or decline team invite + +1. You will be notified on the top right corner of your system page when you receive an invitation to join a team. + +2. Click on your avatar in the top right corner of the page, then select **Team** in the left-hand panel to access the **Team** page. + +_On the **Team** page, you can view the information about members of your team and the teams you have joined._ + +_After accepting the team invite, you should be able to view and update the team owner's datasets whose **Permissions** is set to **Team**._ + +## Leave a joined team \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/team/manage_team_members.md b/website/versioned_docs/version-v0.21.1/guides/team/manage_team_members.md new file mode 100644 index 0000000..edd8289 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/team/manage_team_members.md @@ -0,0 +1,42 @@ +--- +sidebar_position: 2 +slug: /manage_team_members +--- + +# Manage team members + +Invite or remove team members. + +--- + +By default, each RAGFlow user is assigned a single team named after their name. RAGFlow allows you to invite RAGFlow users to your team. Your team members can help you: + +- Upload documents to your shared datasets. +- Parse documents in your shared datasets. +- Use your shared Agents. + +:::tip NOTE +- Your team members are currently *not* allowed to invite users to your team, and only you, the team owner, is permitted to do so. +- Sharing added models with team members is only available in RAGFlow's Enterprise edition. +::: + +## Prerequisites + +1. Ensure that the invited team member is a RAGFlow user and that the Email address used is associated with a RAGFlow user account. +2. To allow your team members to view and update your dataset, ensure that you set **Permissions** on its **Configuration** page from **Only me** to **Team**. + +## Invite team members + +Click on your avatar in the top right corner of the page, then select **Team** in the left-hand panel to access the **Team** page. + +![team_view](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/team_view.jpg) + +_On the **Team** page, you can view the information about members of your team and the teams you have joined._ + +You are, by default, the owner of your own team and the only person permitted to invite users to join your team or remove team members. + +![invite_user](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/invite_user.jpg) + +## Remove team members + +![delete_invite](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/delete_invite.jpg) \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/team/share_agents.md b/website/versioned_docs/version-v0.21.1/guides/team/share_agents.md new file mode 100644 index 0000000..f6be1a7 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/team/share_agents.md @@ -0,0 +1,19 @@ +--- +sidebar_position: 6 +slug: /share_agent +--- + +# Share Agent + +Share an Agent with your team members. + +--- + +When ready, you may share your Agents with your team members so that they can use them. Please note that your Agents are not shared automatically; you must manually enable sharing by selecting the corresponding **Permissions** radio button: + +1. Click the intended Agent to open its editing canvas. +2. Click **Management** > **Settings** to show the **Agent settings** dialogue. +3. Change **Permissions** from **Only me** to **Team**. +4. Click **Save** to apply your changes. + +*When completed, your team members will see your shared Agents.* \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/team/share_chat_assistant.md b/website/versioned_docs/version-v0.21.1/guides/team/share_chat_assistant.md new file mode 100644 index 0000000..f8f172e --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/team/share_chat_assistant.md @@ -0,0 +1,8 @@ +--- +sidebar_position: 5 +slug: /share_chat_assistant +--- + +# Share chat assistant + +Sharing chat assistant is currently exclusive to RAGFlow Enterprise, but will be made available in due course. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/team/share_knowledge_bases.md b/website/versioned_docs/version-v0.21.1/guides/team/share_knowledge_bases.md new file mode 100644 index 0000000..4eeccd2 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/team/share_knowledge_bases.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 4 +slug: /share_datasets +--- + +# Share dataset + +Share a dataset with team members. + +--- + +When ready, you may share your datasets with your team members so that they can upload and parse files in them. Please note that your datasets are not shared automatically; you must manually enable sharing by selecting the appropriate **Permissions** radio button: + +1. Navigate to the dataset's **Configuration** page. +2. Change **Permissions** from **Only me** to **Team**. +3. Click **Save** to apply your changes. + +*Once completed, your team members will see your shared datasets.* \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/team/share_model.md b/website/versioned_docs/version-v0.21.1/guides/team/share_model.md new file mode 100644 index 0000000..459641f --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/team/share_model.md @@ -0,0 +1,8 @@ +--- +sidebar_position: 7 +slug: /share_model +--- + +# Share models + +Sharing models is currently exclusive to RAGFlow Enterprise. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/guides/tracing.mdx b/website/versioned_docs/version-v0.21.1/guides/tracing.mdx new file mode 100644 index 0000000..37e5243 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/tracing.mdx @@ -0,0 +1,72 @@ +--- +sidebar_position: 9 +slug: /tracing +--- + +# Tracing + +Observability & Tracing with Langfuse. + +--- + +:::info KUDOS +This document is contributed by our community contributor [jannikmaierhoefer](https://github.com/jannikmaierhoefer). 👏 +::: + +RAGFlow ships with a built-in [Langfuse](https://langfuse.com) integration so that you can **inspect and debug every retrieval and generation step** of your RAG pipelines in near real-time. + +Langfuse stores traces, spans and prompt payloads in a purpose-built observability backend and offers filtering and visualisations on top. + +:::info NOTE +• RAGFlow **≥ 0.21.1** (contains the Langfuse connector) +• A Langfuse workspace (cloud or self-hosted) with a _Project Public Key_ and _Secret Key_ +::: + +--- + +## 1. Collect your Langfuse credentials + +1. Sign in to your Langfuse dashboard. +2. Open **Settings ▸ Projects** and either create a new project or select an existing one. +3. Copy the **Public Key** and **Secret Key**. +4. Note the Langfuse **host** (e.g. `https://cloud.langfuse.com`). Use the base URL of your own installation if you self-host. + +> The keys are _project-scoped_: one pair of keys is enough for all environments that should write into the same project. + +--- + +## 2. Add the keys to RAGFlow + +RAGFlow stores the credentials _per tenant_. You can configure them either via the web UI or the HTTP API. + +1. Log in to RAGFlow and click your avatar in the top-right corner. +2. Select **API ▸ Scroll down to the bottom ▸ Langfuse Configuration**. +3. Fill in you Langfuse **Host**, **Public Key** and **Secret Key**. +4. Click **Save**. + +![Example RAGFlow trace in Langfuse](https://langfuse.com/images/docs/ragflow/ragflow-configuration.gif) + +Once saved, RAGFlow starts emitting traces automatically – no code change required. + +--- + +## 3. Run a pipeline and watch the traces + +1. Execute any chat or retrieval pipeline in RAGFlow (e.g. the Quickstart demo). +2. Open your Langfuse project ▸ **Traces**. +3. Filter by **name ~ `ragflow-*`** (RAGFlow prefixes each trace with `ragflow-`). + +For every user request you will see: + +• a **trace** representing the overall request +• **spans** for retrieval, ranking and generation steps +• the complete **prompts**, **retrieved documents** and **LLM responses** as metadata + +![Example RAGFlow trace in Langfuse](https://langfuse.com/images/docs/ragflow/ragflow-trace-frame.png) + +([Example trace in Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/0bde9629-4251-4386-b583-26101b8e7561?timestamp=2025-05-09T19%3A15%3A37.797Z&display=details&observation=823997d8-ac40-40f3-8e7b-8aa6753b499e)) + +:::tip NOTE +Use Langfuse's diff view to compare prompt versions or drill down into long-running retrievals to identify bottlenecks. +::: + diff --git a/website/versioned_docs/version-v0.21.1/guides/upgrade_ragflow.mdx b/website/versioned_docs/version-v0.21.1/guides/upgrade_ragflow.mdx new file mode 100644 index 0000000..166efde --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/guides/upgrade_ragflow.mdx @@ -0,0 +1,123 @@ +--- +sidebar_position: 11 +slug: /upgrade_ragflow +--- + +# Upgrading +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Upgrade RAGFlow to `nightly-slim`/`nightly` or the latest, published release. + +:::info NOTE +Upgrading RAGFlow in itself will *not* remove your uploaded/historical data. However, be aware that `docker compose -f docker/docker-compose.yml down -v` will remove Docker container volumes, resulting in data loss. +::: + +## Upgrade RAGFlow to `nightly-slim`/`nightly`, the most recent, tested Docker image + +`nightly-slim` refers to the RAGFlow Docker image *without* embedding models, while `nightly` refers to the RAGFlow Docker image with embedding models. For details on their differences, see [ragflow/docker/.env](https://github.com/infiniflow/ragflow/blob/main/docker/.env). + +To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker image: + +1. Clone the repo + + ```bash + git clone https://github.com/infiniflow/ragflow.git + ``` + +2. Update **ragflow/docker/.env**: + + + + +```bash +RAGFLOW_IMAGE=infiniflow/ragflow:nightly-slim +``` + + + + +```bash +RAGFLOW_IMAGE=infiniflow/ragflow:nightly +``` + + + + +3. Update RAGFlow image and restart RAGFlow: + + ```bash + docker compose -f docker/docker-compose.yml pull + docker compose -f docker/docker-compose.yml up -d + ``` + +## Upgrade RAGFlow to the most recent, officially published release + +To upgrade RAGFlow, you must upgrade **both** your code **and** your Docker image: + +1. Clone the repo + + ```bash + git clone https://github.com/infiniflow/ragflow.git + ``` + +2. Switch to the latest, officially published release, e.g., `v0.21.1`: + + ```bash + git checkout -f v0.21.1 + ``` + +3. Update **ragflow/docker/.env**: + + + + +```bash +RAGFLOW_IMAGE=infiniflow/ragflow:v0.21.1-slim +``` + + + + +```bash +RAGFLOW_IMAGE=infiniflow/ragflow:v0.21.1 +``` + + + + +4. Update the RAGFlow image and restart RAGFlow: + + ```bash + docker compose -f docker/docker-compose.yml pull + docker compose -f docker/docker-compose.yml up -d + ``` + +## Frequently asked questions + +### Do I need to back up my datasets before upgrading RAGFlow? + +No, you do not need to. Upgrading RAGFlow in itself will *not* remove your uploaded data or dataset settings. However, be aware that `docker compose -f docker/docker-compose.yml down -v` will remove Docker container volumes, resulting in data loss. + +### Upgrade RAGFlow in an offline environment (without Internet access) + +1. From an environment with Internet access, pull the required Docker image. +2. Save the Docker image to a **.tar** file. + ```bash + docker save -o ragflow.v0.21.1.tar infiniflow/ragflow:v0.21.1 + ``` +3. Copy the **.tar** file to the target server. +4. Load the **.tar** file into Docker: + ```bash + docker load -i ragflow.v0.21.1.tar + ``` diff --git a/website/versioned_docs/version-v0.21.1/quickstart.mdx b/website/versioned_docs/version-v0.21.1/quickstart.mdx new file mode 100644 index 0000000..3d1ccf9 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/quickstart.mdx @@ -0,0 +1,372 @@ +--- +sidebar_position: 0 +slug: / +--- + +# Get started +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import APITable from '@site/src/components/APITable'; + +RAGFlow is an open-source RAG (Retrieval-Augmented Generation) engine based on deep document understanding. When integrated with LLMs, it is capable of providing truthful question-answering capabilities, backed by well-founded citations from various complex formatted data. + +This quick start guide describes a general process from: + +- Starting up a local RAGFlow server, +- Creating a dataset, +- Intervening with file parsing, to +- Establishing an AI chat based on your datasets. + +:::danger IMPORTANT +We officially support x86 CPU and Nvidia GPU, and this document offers instructions on deploying RAGFlow using Docker on x86 platforms. While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. + +If you are on an ARM platform, follow [this guide](./develop/build_docker_image.mdx) to build a RAGFlow Docker image. +::: + +## Prerequisites + +- CPU ≥ 4 cores (x86); +- RAM ≥ 16 GB; +- Disk ≥ 50 GB; +- Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1. +- [gVisor](https://gvisor.dev/docs/user_guide/install/): Required only if you intend to use the code executor ([sandbox](https://github.com/infiniflow/ragflow/tree/main/sandbox)) feature of RAGFlow. + +:::tip NOTE +If you have not installed Docker on your local machine (Windows, Mac, or Linux), see [Install Docker Engine](https://docs.docker.com/engine/install/). +::: + +## Start up the server + +This section provides instructions on setting up the RAGFlow server on Linux. If you are on a different operating system, no worries. Most steps are alike. + +
+ 1. Ensure vm.max_map_count ≥ 262144: + + `vm.max_map_count`. This value sets the maximum number of memory map areas a process may have. Its default value is 65530. While most applications require fewer than a thousand maps, reducing this value can result in abnormal behaviors, and the system will throw out-of-memory errors when a process reaches the limitation. + + RAGFlow v0.21.1 uses Elasticsearch or [Infinity](https://github.com/infiniflow/infinity) for multiple recall. Setting the value of `vm.max_map_count` correctly is crucial to the proper functioning of the Elasticsearch component. + + + + 1.1. Check the value of `vm.max_map_count`: + + ```bash + $ sysctl vm.max_map_count + ``` + + 1.2. Reset `vm.max_map_count` to a value at least 262144 if it is not. + + ```bash + $ sudo sysctl -w vm.max_map_count=262144 + ``` + + :::caution WARNING + This change will be reset after a system reboot. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception. + ::: + + 1.3. To ensure your change remains permanent, add or update the `vm.max_map_count` value in **/etc/sysctl.conf** accordingly: + + ```bash + vm.max_map_count=262144 + ``` + + + If you are on macOS with Docker Desktop, run the following command to update `vm.max_map_count`: + + ```bash + docker run --rm --privileged --pid=host alpine sysctl -w vm.max_map_count=262144 + ``` + + :::caution WARNING + This change will be reset after a system reboot. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception. + ::: + + To make your change persistent, create a file with proper settings: + + 1.1. Create a file: + + ```shell + sudo nano /Library/LaunchDaemons/com.user.vmmaxmap.plist + ``` + + 1.2. Open the file: + + ```shell + sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist + ``` + + 1.3. Add settings: + + ```xml + + + + + Label + com.user.vmmaxmap + ProgramArguments + + /usr/sbin/sysctl + -w + vm.max_map_count=262144 + + RunAtLoad + + + + ``` + + 1.4. After saving the file, load the new daemon: + + ```shell + sudo launchctl load /Library/LaunchDaemons/com.user.vmmaxmap.plist + ``` + + :::note + If the above steps do not work, consider using [this workaround](https://github.com/docker/for-mac/issues/7047#issuecomment-1791912053), which employs a container and does not require manual editing of the macOS settings. + ::: + + + + + #### If you are on Windows with Docker Desktop, then you *must* use docker-machine to set `vm.max_map_count`: + + ```bash + $ docker-machine ssh + $ sudo sysctl -w vm.max_map_count=262144 + ``` + #### If you are on Windows with Docker Desktop WSL 2 backend, then use docker-desktop to set `vm.max_map_count`: + + 1.1. Run the following in WSL: + ```bash + $ wsl -d docker-desktop -u root + $ sysctl -w vm.max_map_count=262144 + ``` + + :::caution WARNING + This change will be reset after you restart Docker. If you forget to update the value the next time you start up the server, you may get a `Can't connect to ES cluster` exception. + ::: + + 1.2. If you prefer not to run those commands every time you restart Docker, you can update your `%USERPROFILE%.wslconfig` as follows to keep your change permanent and global for all WSL distributions: + + ```bash + [wsl2] + kernelCommandLine = "sysctl.vm.max_map_count=262144" + ``` + *This causes all WSL2 virtual machines to have that setting assigned when they start.* + + :::note + If you are on Windows 11 or Windows 10 version 22H2, and have installed the Microsoft Store version of WSL, you can also update the **/etc/sysctl.conf** within the docker-desktop WSL distribution to keep your change permanent: + + ```bash + $ wsl -d docker-desktop -u root + $ vi /etc/sysctl.conf + ``` + + ```bash + # Append a line, which reads: + vm.max_map_count = 262144 + ``` + ::: + + + +
+ +2. Clone the repo: + + ```bash + $ git clone https://github.com/infiniflow/ragflow.git + $ cd ragflow/docker + $ git checkout -f v0.21.1 + ``` + +3. Use the pre-built Docker images and start up the server: + + :::tip NOTE + The command below downloads the `v0.21.1-slim` edition of the RAGFlow Docker image. Refer to the following table for descriptions of different RAGFlow editions. To download a RAGFlow edition different from `v0.21.1-slim`, update the `RAGFLOW_IMAGE` variable accordingly in **docker/.env** before using `docker compose` to start the server. For example: set `RAGFLOW_IMAGE=infiniflow/ragflow:v0.21.1` for the full edition `v0.21.1`. + ::: + + ```bash + # Use CPU for embedding and DeepDoc tasks: + $ docker compose -f docker-compose.yml up -d + + # To use GPU to accelerate embedding and DeepDoc tasks: + # docker compose -f docker-compose-gpu.yml up -d + ``` + +```mdx-code-block + +``` + +| RAGFlow image tag | Image size (GB) | Has embedding models and Python packages? | Stable? | +| ------------------- | --------------- | ----------------------------------------- | ------------------------ | +| `v0.21.1` | ≈9 | :heavy_check_mark: | Stable release | +| `v0.21.1-slim` | ≈2 | ❌ | Stable release | +| `nightly` | ≈9 | :heavy_check_mark: | *Unstable* nightly build | +| `nightly-slim` | ≈2 | ❌ | *Unstable* nightly build | + +```mdx-code-block + +``` + +:::danger IMPORTANT +The embedding models included in `v0.21.1` and `nightly` are: + +- BAAI/bge-large-zh-v1.5 +- maidalun1020/bce-embedding-base_v1 + +These two embedding models are optimized specifically for English and Chinese, so performance will be compromised if you use them to embed documents in other languages. +::: + +:::tip NOTE +The image size shown refers to the size of the *downloaded* Docker image, which is compressed. When Docker runs the image, it unpacks it, resulting in significantly greater disk usage. For example, a slim edition image will expand to around 7 GB once unpacked. +::: + +4. Check the server status after having the server up and running: + + ```bash + $ docker logs -f ragflow-server + ``` + + _The following output confirms a successful launch of the system:_ + + ```bash + ____ ___ ______ ______ __ + / __ \ / | / ____// ____// /____ _ __ + / /_/ // /| | / / __ / /_ / // __ \| | /| / / + / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ / + /_/ |_|/_/ |_|\____//_/ /_/ \____/ |__/|__/ + + * Running on all addresses (0.0.0.0) + ``` + +:::danger IMPORTANT +If you skip this confirmation step and directly log in to RAGFlow, your browser may prompt a `network anomaly` error because, at that moment, your RAGFlow may not be fully initialized. +::: + +5. In your web browser, enter the IP address of your server and log in to RAGFlow. + +:::caution WARNING +With the default settings, you only need to enter `http://IP_OF_YOUR_MACHINE` (**sans** port number) as the default HTTP serving port `80` can be omitted when using the default configurations. +::: + +## Configure LLMs + +RAGFlow is a RAG engine and needs to work with an LLM to offer grounded, hallucination-free question-answering capabilities. RAGFlow supports most mainstream LLMs. For a complete list of supported models, please refer to [Supported Models](./references/supported_models.mdx). + +:::note +RAGFlow also supports deploying LLMs locally using Ollama, Xinference, or LocalAI, but this part is not covered in this quick start guide. +::: + +To add and configure an LLM: + +1. Click on your logo on the top right of the page **>** **Model providers**. + +2. Click on the desired LLM and update the API key accordingly. + +3. Click **System Model Settings** to select the default models: + + - Chat model, + - Embedding model, + - Image-to-text model, + - and more. + +> Some models, such as the image-to-text model **qwen-vl-max**, are subsidiary to a specific LLM. And you may need to update your API key to access these models. + +## Create your first dataset + +You are allowed to upload files to a dataset in RAGFlow and parse them into datasets. A dataset is virtually a collection of datasets. Question answering in RAGFlow can be based on a particular dataset or multiple datasets. File formats that RAGFlow supports include documents (PDF, DOC, DOCX, TXT, MD, MDX), tables (CSV, XLSX, XLS), pictures (JPEG, JPG, PNG, TIF, GIF), and slides (PPT, PPTX). + +To create your first dataset: + +1. Click the **Dataset** tab in the top middle of the page **>** **Create dataset**. + +2. Input the name of your dataset and click **OK** to confirm your changes. + + _You are taken to the **Configuration** page of your dataset._ + + ![dataset configuration](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/configure_knowledge_base.jpg) + +3. RAGFlow offers multiple chunk templates that cater to different document layouts and file formats. Select the embedding model and chunking method (template) for your dataset. + +:::danger IMPORTANT +Once you have selected an embedding model and used it to parse a file, you are no longer allowed to change it. The obvious reason is that we must ensure that all files in a specific dataset are parsed using the *same* embedding model (ensure that they are being compared in the same embedding space). +::: + + _You are taken to the **Dataset** page of your dataset._ + +4. Click **+ Add file** **>** **Local files** to start uploading a particular file to the dataset. + +5. In the uploaded file entry, click the play button to start file parsing: + + ![parse file](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/parse_file.jpg) + +:::caution NOTE +- If your file parsing gets stuck at below 1%, see [this FAQ](./faq.mdx#why-does-my-document-parsing-stall-at-under-one-percent). +- If your file parsing gets stuck at near completion, see [this FAQ](./faq.mdx#why-does-my-pdf-parsing-stall-near-completion-while-the-log-does-not-show-any-error) +::: + +## Intervene with file parsing + +RAGFlow features visibility and explainability, allowing you to view the chunking results and intervene where necessary. To do so: + +1. Click on the file that completes file parsing to view the chunking results: + + _You are taken to the **Chunk** page:_ + + ![chunks](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/file_chunks.jpg) + +2. Hover over each snapshot for a quick view of each chunk. + +3. Double click the chunked texts to add keywords or make *manual* changes where necessary: + + ![update chunk](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/add_keyword_question.jpg) + +:::caution NOTE +You can add keywords or questions to a file chunk to improve its ranking for queries containing those keywords. This action increases its keyword weight and can improve its position in search list. +::: + +4. In Retrieval testing, ask a quick question in **Test text** to double check if your configurations work: + + _As you can tell from the following, RAGFlow responds with truthful citations._ + + ![retrieval test](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/retrieval_test.jpg) + +## Set up an AI chat + +Conversations in RAGFlow are based on a particular dataset or multiple datasets. Once you have created your dataset and finished file parsing, you can go ahead and start an AI conversation. + +1. Click the **Chat** tab in the middle top of the page **>** **Create chat** to create a chat assistant. +2. Click the created chat app to enter its configuration page. + > RAGFlow offer the flexibility of choosing a different chat model for each dialogue, while allowing you to set the default models in **System Model Settings**. + +2. Update **Chat setting** on the right of the configuration page: + + - Name your assistant and specify your datasets. + - **Empty response**: + - If you wish to *confine* RAGFlow's answers to your datasets, leave a response here. Then when it doesn't retrieve an answer, it *uniformly* responds with what you set here. + - If you wish RAGFlow to *improvise* when it doesn't retrieve an answer from your datasets, leave it blank, which may give rise to hallucinations. + +3. Update **System prompt** or leave it as is for the beginning. + +4. Select a chat model in the **Model** dropdown list. + +5. Now, let's start the show: + + ![chat_thermal_solution](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/chat_thermal_solution.jpg) + + +:::tip NOTE +RAGFlow also offers HTTP and Python APIs for you to integrate RAGFlow's capabilities into your applications. Read the following documents for more information: + +- [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md) +- [HTTP API reference](./references/http_api_reference.md) +- [Python API reference](./references/python_api_reference.md) +::: diff --git a/website/versioned_docs/version-v0.21.1/references/_category_.json b/website/versioned_docs/version-v0.21.1/references/_category_.json new file mode 100644 index 0000000..fec5335 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/references/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "References", + "position": 6, + "link": { + "type": "generated-index", + "description": "Miscellaneous References" + } +} diff --git a/website/versioned_docs/version-v0.21.1/references/glossary.mdx b/website/versioned_docs/version-v0.21.1/references/glossary.mdx new file mode 100644 index 0000000..0f8d7ce --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/references/glossary.mdx @@ -0,0 +1,26 @@ +--- +sidebar_position: 0 +slug: /glossary +--- + +# Glossary + +Definitions of key terms and basic concepts related to RAGFlow. + +--- + +import TOCInline from '@theme/TOCInline'; + + + +--- + +## C + +### Cross-language search + +Cross-language search (also known as cross-lingual retrieval) is a feature introduced in version 0.21.1. It enables users to submit queries in one language (for example, English) and retrieve relevant documents written in other languages such as Chinese or Spanish. This feature is enabled by the system’s default chat model, which translates queries to ensure accurate matching of semantic meaning across languages. + +By enabling cross-language search, users can effortlessly access a broader range of information regardless of language barriers, significantly enhancing the system’s usability and inclusiveness. + +This feature is available in the retrieval test and chat assistant settings. See [Run retrieval test](../guides/dataset/run_retrieval_test.md) and [Start AI chat](../guides/chat/start_chat.md) for further details. \ No newline at end of file diff --git a/website/versioned_docs/version-v0.21.1/references/http_api_reference.md b/website/versioned_docs/version-v0.21.1/references/http_api_reference.md new file mode 100644 index 0000000..51e2cc0 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/references/http_api_reference.md @@ -0,0 +1,4236 @@ +--- +sidebar_position: 4 +slug: /http_api_reference +--- + +# HTTP API + +A complete reference for RAGFlow's RESTful API. Before proceeding, please ensure you [have your RAGFlow API key ready for authentication](https://ragflow.io/docs/dev/acquire_ragflow_api_key). + +--- + +## ERROR CODES + +--- + +| Code | Message | Description | +| ---- | --------------------- | -------------------------- | +| 400 | Bad Request | Invalid request parameters | +| 401 | Unauthorized | Unauthorized access | +| 403 | Forbidden | Access denied | +| 404 | Not Found | Resource not found | +| 500 | Internal Server Error | Server internal error | +| 1001 | Invalid Chunk ID | Invalid Chunk ID | +| 1002 | Chunk Update Failed | Chunk update failed | + +--- + +## OpenAI-Compatible API + +--- + +### Create chat completion + +**POST** `/api/v1/chats_openai/{chat_id}/chat/completions` + +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). + +#### Request + +- Method: POST +- URL: `/api/v1/chats_openai/{chat_id}/chat/completions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"model"`: `string` + - `"messages"`: `object list` + - `"stream"`: `boolean` + +##### Request example + +```bash +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 + }' +``` + +##### Request Parameters + +- `model` (*Body parameter*) `string`, *Required* + The model used to generate the response. The server will parse this automatically, so you can set it to any value for now. + +- `messages` (*Body parameter*) `list[object]`, *Required* + 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. + +#### Response + +Stream: + +```json +data:{ + "id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", + "choices": [ + { + "delta": { + "content": "Hello! It seems like you're just greeting me. If you have a specific", + "role": "assistant", + "function_call": null, + "tool_calls": null, + "reasoning_content": null + }, + "finish_reason": null, + "index": 0, + "logprobs": null + } + ], + "created": 1755084508, + "model": "model", + "object": "chat.completion.chunk", + "system_fingerprint": "", + "usage": null +} + +data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " question or need information, feel free to ask, and I'll do my best", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null} + +data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": " to assist you based on the knowledge base provided.", "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": null, "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": null} + +data:{"id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", "choices": [{"delta": {"content": null, "role": "assistant", "function_call": null, "tool_calls": null, "reasoning_content": null}, "finish_reason": "stop", "index": 0, "logprobs": null}], "created": 1755084508, "model": "model", "object": "chat.completion.chunk", "system_fingerprint": "", "usage": {"prompt_tokens": 5, "completion_tokens": 188, "total_tokens": 193}} + +data:[DONE] +``` + +Non-stream: + +```json +{ + "choices": [ + { + "finish_reason": "stop", + "index": 0, + "logprobs": null, + "message": { + "content": "Hello! I'm your smart assistant. What can I do for you?", + "role": "assistant" + } + } + ], + "created": 1755084403, + "id": "chatcmpl-3b0397f277f511f0b47f729e3aa55728", + "model": "model", + "object": "chat.completion", + "usage": { + "completion_tokens": 55, + "completion_tokens_details": { + "accepted_prediction_tokens": 55, + "reasoning_tokens": 5, + "rejected_prediction_tokens": 0 + }, + "prompt_tokens": 5, + "total_tokens": 60 + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The last content of this conversation is not from user." +} +``` + +--- + +### Create agent completion + +**POST** `/api/v1/agents_openai/{agent_id}/chat/completions` + +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). + +#### Request + +- Method: POST +- URL: `/api/v1/agents_openai/{agent_id}/chat/completions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"model"`: `string` + - `"messages"`: `object list` + - `"stream"`: `boolean` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/agents_openai/{agent_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 + }' +``` + +##### Request Parameters + +- `model` (*Body parameter*) `string`, *Required* + The model used to generate the response. The server will parse this automatically, so you can set it to any value for now. + +- `messages` (*Body parameter*) `list[object]`, *Required* + 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. + +- `session_id` (*Body parameter*) `string` + Agent session id. + +#### Response + +Stream: + +```json +... + +data: { + "id": "c39f6f9c83d911f0858253708ecb6573", + "object": "chat.completion.chunk", + "model": "d1f79142831f11f09cc51795b9eb07c0", + "choices": [ + { + "delta": { + "content": " terminal" + }, + "finish_reason": null, + "index": 0 + } + ] +} + +data: { + "id": "c39f6f9c83d911f0858253708ecb6573", + "object": "chat.completion.chunk", + "model": "d1f79142831f11f09cc51795b9eb07c0", + "choices": [ + { + "delta": { + "content": "." + }, + "finish_reason": null, + "index": 0 + } + ] +} + +data: { + "id": "c39f6f9c83d911f0858253708ecb6573", + "object": "chat.completion.chunk", + "model": "d1f79142831f11f09cc51795b9eb07c0", + "choices": [ + { + "delta": { + "content": "", + "reference": { + "chunks": { + "20": { + "id": "4b8935ac0a22deb1", + "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.", + "document_id": "4bdd2ff65e1511f0907f09f583941b45", + "document_name": "INSTALL22.md", + "dataset_id": "456ce60c5e1511f0907f09f583941b45", + "image_id": "", + "positions": [ + [ + 12, + 11, + 11, + 11, + 11 + ] + ], + "url": null, + "similarity": 0.5697155305154673, + "vector_similarity": 0.7323851005515574, + "term_similarity": 0.5000000005, + "doc_type": "" + } + }, + "doc_aggs": { + "INSTALL22.md": { + "doc_name": "INSTALL22.md", + "doc_id": "4bdd2ff65e1511f0907f09f583941b45", + "count": 3 + }, + "INSTALL.md": { + "doc_name": "INSTALL.md", + "doc_id": "4bd7fdd85e1511f0907f09f583941b45", + "count": 2 + }, + "INSTALL(1).md": { + "doc_name": "INSTALL(1).md", + "doc_id": "4bdfb42e5e1511f0907f09f583941b45", + "count": 2 + }, + "INSTALL3.md": { + "doc_name": "INSTALL3.md", + "doc_id": "4bdab5825e1511f0907f09f583941b45", + "count": 1 + } + } + } + }, + "finish_reason": null, + "index": 0 + } + ] +} + +data: [DONE] +``` + +Non-stream: + +```json +{ + "choices": [ + { + "finish_reason": "stop", + "index": 0, + "logprobs": null, + "message": { + "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For Windows:\n1. **Download from GitHub**: \n - Visit the [Neovim releases page](https://github.com/neovim/neovim/releases)\n - Download the latest Windows installer (nvim-win64.msi)\n - Run the installer and follow the prompts\n\n2. **Using winget** (Windows Package Manager):\n...", + "reference": { + "chunks": { + "20": { + "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.", + "dataset_id": "456ce60c5e1511f0907f09f583941b45", + "doc_type": "", + "document_id": "4bdd2ff65e1511f0907f09f583941b45", + "document_name": "INSTALL22.md", + "id": "4b8935ac0a22deb1", + "image_id": "", + "positions": [ + [ + 12, + 11, + 11, + 11, + 11 + ] + ], + "similarity": 0.5697155305154673, + "term_similarity": 0.5000000005, + "url": null, + "vector_similarity": 0.7323851005515574 + } + }, + "doc_aggs": { + "INSTALL(1).md": { + "count": 2, + "doc_id": "4bdfb42e5e1511f0907f09f583941b45", + "doc_name": "INSTALL(1).md" + }, + "INSTALL.md": { + "count": 2, + "doc_id": "4bd7fdd85e1511f0907f09f583941b45", + "doc_name": "INSTALL.md" + }, + "INSTALL22.md": { + "count": 3, + "doc_id": "4bdd2ff65e1511f0907f09f583941b45", + "doc_name": "INSTALL22.md" + }, + "INSTALL3.md": { + "count": 1, + "doc_id": "4bdab5825e1511f0907f09f583941b45", + "doc_name": "INSTALL3.md" + } + } + }, + "role": "assistant" + } + } + ], + "created": null, + "id": "c39f6f9c83d911f0858253708ecb6573", + "model": "d1f79142831f11f09cc51795b9eb07c0", + "object": "chat.completion", + "param": null, + "usage": { + "completion_tokens": 415, + "completion_tokens_details": { + "accepted_prediction_tokens": 0, + "reasoning_tokens": 0, + "rejected_prediction_tokens": 0 + }, + "prompt_tokens": 6, + "total_tokens": 421 + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The last content of this conversation is not from user." +} +``` + +## DATASET MANAGEMENT + +--- + +### Create dataset + +**POST** `/api/v1/datasets` + +Creates a dataset. + +#### Request + +- Method: POST +- URL: `/api/v1/datasets` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name"`: `string` + - `"avatar"`: `string` + - `"description"`: `string` + - `"embedding_model"`: `string` + - `"permission"`: `string` + - `"chunk_method"`: `string` + - `"parser_config"`: `object` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/datasets \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "name": "test_1" + }' +``` + +##### Request parameters + +- `"name"`: (*Body parameter*), `string`, *Required* + The unique name of the dataset to create. It must adhere to the following requirements: + - Basic Multilingual Plane (BMP) only + - Maximum 128 characters + - Case-insensitive + +- `"avatar"`: (*Body parameter*), `string` + Base64 encoding of the avatar. + - Maximum 65535 characters + +- `"description"`: (*Body parameter*), `string` + A brief description of the dataset to create. + - Maximum 65535 characters + +- `"embedding_model"`: (*Body parameter*), `string` + The name of the embedding model to use. For example: `"BAAI/bge-large-zh-v1.5@BAAI"` + - Maximum 255 characters + - Must follow `model_name@model_factory` format + +- `"permission"`: (*Body parameter*), `string` + Specifies who can access the dataset to create. Available options: + - `"me"`: (Default) Only you can manage the dataset. + - `"team"`: All team members can manage the dataset. + +- `"chunk_method"`: (*Body parameter*), `enum` + The chunking method of the dataset to create. Available options: + - `"naive"`: General (default) + - `"book"`: Book + - `"email"`: Email + - `"laws"`: Laws + - `"manual"`: Manual + - `"one"`: One + - `"paper"`: Paper + - `"picture"`: Picture + - `"presentation"`: Presentation + - `"qa"`: Q&A + - `"table"`: Table + - `"tag"`: Tag + +- `"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: + - `"auto_keywords"`: `int` + - Defaults to `0` + - Minimum: `0` + - Maximum: `32` + - `"auto_questions"`: `int` + - Defaults to `0` + - Minimum: `0` + - Maximum: `10` + - `"chunk_token_num"`: `int` + - Defaults to `512` + - Minimum: `1` + - Maximum: `2048` + - `"delimiter"`: `string` + - Defaults to `"\n"`. + - `"html4excel"`: `bool` Indicates whether to convert Excel documents into HTML format. + - Defaults to `false` + - `"layout_recognize"`: `string` + - Defaults to `DeepDOC` + - `"tag_kb_ids"`: `array` refer to [Use tag set](https://ragflow.io/docs/dev/use_tag_sets) + - Must include a list of dataset IDs, where each dataset is parsed using the ​​Tag Chunking Method + - `"task_page_size"`: `int` For PDF only. + - Defaults to `12` + - Minimum: `1` + - `"raptor"`: `object` RAPTOR-specific settings. + - Defaults to: `{"use_raptor": false}` + - `"graphrag"`: `object` GRAPHRAG-specific settings. + - Defaults to: `{"use_graphrag": false}` + - If `"chunk_method"` is `"qa"`, `"manuel"`, `"paper"`, `"book"`, `"laws"`, or `"presentation"`, the `"parser_config"` object contains the following attribute: + - `"raptor"`: `object` RAPTOR-specific settings. + - Defaults to: `{"use_raptor": false}`. + - If `"chunk_method"` is `"table"`, `"picture"`, `"one"`, or `"email"`, `"parser_config"` is an empty JSON object. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "avatar": null, + "chunk_count": 0, + "chunk_method": "naive", + "create_date": "Mon, 28 Apr 2025 18:40:41 GMT", + "create_time": 1745836841611, + "created_by": "3af81804241d11f0a6a79f24fc270c7f", + "description": null, + "document_count": 0, + "embedding_model": "BAAI/bge-large-zh-v1.5@BAAI", + "id": "3b4de7d4241d11f0a6a79f24fc270c7f", + "language": "English", + "name": "RAGFlow example", + "pagerank": 0, + "parser_config": { + "chunk_token_num": 128, + "delimiter": "\\n!?;。；！？", + "html4excel": false, + "layout_recognize": "DeepDOC", + "raptor": { + "use_raptor": false + } + }, + "permission": "me", + "similarity_threshold": 0.2, + "status": "1", + "tenant_id": "3af81804241d11f0a6a79f24fc270c7f", + "token_num": 0, + "update_date": "Mon, 28 Apr 2025 18:40:41 GMT", + "update_time": 1745836841611, + "vector_similarity_weight": 0.3, + }, +} +``` + +Failure: + +```json +{ + "code": 101, + "message": "Dataset name 'RAGFlow example' already exists" +} +``` + +--- + +### Delete datasets + +**DELETE** `/api/v1/datasets` + +Deletes datasets by ID. + +#### Request + +- Method: DELETE +- URL: `/api/v1/datasets` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` + - Body: + - `"ids"`: `list[string]` or `null` + +##### Request example + +```bash +curl --request DELETE \ + --url http://{address}/api/v1/datasets \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "ids": ["d94a8dc02c9711f0930f7fbc369eab6d", "e94a8dc02c9711f0930f7fbc369eab6e"] + }' +``` + +##### Request parameters + +- `"ids"`: (*Body parameter*), `list[string]` or `null`, *Required* + Specifies the datasets to delete: + - If `null`, all datasets will be deleted. + - If an array of IDs, only the specified datasets will be deleted. + - If an empty array, no datasets will be deleted. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "You don't own the dataset." +} +``` + +--- + +### Update dataset + +**PUT** `/api/v1/datasets/{dataset_id}` + +Updates configurations for a specified dataset. + +#### Request + +- Method: PUT +- URL: `/api/v1/datasets/{dataset_id}` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name"`: `string` + - `"avatar"`: `string` + - `"description"`: `string` + - `"embedding_model"`: `string` + - `"permission"`: `string` + - `"chunk_method"`: `string` + - `"pagerank"`: `int` + - `"parser_config"`: `object` + +##### Request example + +```bash +curl --request PUT \ + --url http://{address}/api/v1/datasets/{dataset_id} \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data ' + { + "name": "updated_dataset" + }' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The ID of the dataset to update. +- `"name"`: (*Body parameter*), `string` + The revised name of the dataset. + - Basic Multilingual Plane (BMP) only + - Maximum 128 characters + - Case-insensitive +- `"avatar"`: (*Body parameter*), `string` + The updated base64 encoding of the avatar. + - Maximum 65535 characters +- `"embedding_model"`: (*Body parameter*), `string` + The updated embedding model name. + - Ensure that `"chunk_count"` is `0` before updating `"embedding_model"`. + - Maximum 255 characters + - Must follow `model_name@model_factory` format +- `"permission"`: (*Body parameter*), `string` + The updated dataset permission. Available options: + - `"me"`: (Default) Only you can manage the dataset. + - `"team"`: All team members can manage the dataset. +- `"pagerank"`: (*Body parameter*), `int` + refer to [Set page rank](https://ragflow.io/docs/dev/set_page_rank) + - Default: `0` + - Minimum: `0` + - Maximum: `100` +- `"chunk_method"`: (*Body parameter*), `enum` + The chunking method for the dataset. Available options: + - `"naive"`: General (default) + - `"book"`: Book + - `"email"`: Email + - `"laws"`: Laws + - `"manual"`: Manual + - `"one"`: One + - `"paper"`: Paper + - `"picture"`: Picture + - `"presentation"`: Presentation + - `"qa"`: Q&A + - `"table"`: Table + - `"tag"`: Tag +- `"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: + - `"auto_keywords"`: `int` + - Defaults to `0` + - Minimum: `0` + - Maximum: `32` + - `"auto_questions"`: `int` + - Defaults to `0` + - Minimum: `0` + - Maximum: `10` + - `"chunk_token_num"`: `int` + - Defaults to `512` + - Minimum: `1` + - Maximum: `2048` + - `"delimiter"`: `string` + - Defaults to `"\n"`. + - `"html4excel"`: `bool` Indicates whether to convert Excel documents into HTML format. + - Defaults to `false` + - `"layout_recognize"`: `string` + - Defaults to `DeepDOC` + - `"tag_kb_ids"`: `array` refer to [Use tag set](https://ragflow.io/docs/dev/use_tag_sets) + - Must include a list of dataset IDs, where each dataset is parsed using the ​​Tag Chunking Method + - `"task_page_size"`: `int` For PDF only. + - Defaults to `12` + - Minimum: `1` + - `"raptor"`: `object` RAPTOR-specific settings. + - Defaults to: `{"use_raptor": false}` + - `"graphrag"`: `object` GRAPHRAG-specific settings. + - Defaults to: `{"use_graphrag": false}` + - If `"chunk_method"` is `"qa"`, `"manuel"`, `"paper"`, `"book"`, `"laws"`, or `"presentation"`, the `"parser_config"` object contains the following attribute: + - `"raptor"`: `object` RAPTOR-specific settings. + - Defaults to: `{"use_raptor": false}`. + - If `"chunk_method"` is `"table"`, `"picture"`, `"one"`, or `"email"`, `"parser_config"` is an empty JSON object. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "Can't change tenant_id." +} +``` + +--- + +### List datasets + +**GET** `/api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}` + +Lists datasets. + +#### Request + +- Method: GET +- URL: `/api/v1/datasets?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={dataset_name}&id={dataset_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +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 ' +``` + +##### Request parameters + +- `page`: (*Filter parameter*) + Specifies the page on which the datasets will be displayed. Defaults to `1`. +- `page_size`: (*Filter parameter*) + The number of datasets on each page. Defaults to `30`. +- `orderby`: (*Filter parameter*) + The field by which datasets should be sorted. Available options: + - `create_time` (default) + - `update_time` +- `desc`: (*Filter parameter*) + Indicates whether the retrieved datasets should be sorted in descending order. Defaults to `true`. +- `name`: (*Filter parameter*) + The name of the dataset to retrieve. +- `id`: (*Filter parameter*) + The ID of the dataset to retrieve. + +#### Response + +Success: + +```json +{ + "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": "naive", + "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 + } + ], + "total": 1 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The dataset doesn't exist" +} +``` + + --- + +### Get knowledge graph + +**GET** `/api/v1/datasets/{dataset_id}/knowledge_graph` + +Retrieves the knowledge graph of a specified dataset. + +#### Request + +- Method: GET +- URL: `/api/v1/datasets/{dataset_id}/knowledge_graph` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The ID of the target dataset. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "graph": { + "directed": false, + "edges": [ + { + "description": "The notice is a document issued to convey risk warnings and operational alerts.The notice is a specific instance of a notification document issued under the risk warning framework.", + "keywords": ["9", "8"], + "source": "notice", + "source_id": ["8a46cdfe4b5c11f0a5281a58e595aa1c"], + "src_id": "xxx", + "target": "xxx", + "tgt_id": "xxx", + "weight": 17.0 + } + ], + "graph": { + "source_id": ["8a46cdfe4b5c11f0a5281a58e595aa1c", "8a7eb6424b5c11f0a5281a58e595aa1c"] + }, + "multigraph": false, + "nodes": [ + { + "description": "xxx", + "entity_name": "xxx", + "entity_type": "ORGANIZATION", + "id": "xxx", + "pagerank": 0.10804906590624092, + "rank": 3, + "source_id": ["8a7eb6424b5c11f0a5281a58e595aa1c"] + } + ] + }, + "mind_map": {} + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The dataset doesn't exist" +} +``` + +--- + +### Delete knowledge graph + +**DELETE** `/api/v1/datasets/{dataset_id}/knowledge_graph` + +Removes the knowledge graph of a specified dataset. + +#### Request + +- Method: DELETE +- URL: `/api/v1/datasets/{dataset_id}/knowledge_graph` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request DELETE \ + --url http://{address}/api/v1/datasets/{dataset_id}/knowledge_graph \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The ID of the target dataset. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": true +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The dataset doesn't exist" +} +``` + +--- + +## FILE MANAGEMENT WITHIN DATASET + +--- + +### Upload documents + +**POST** `/api/v1/datasets/{dataset_id}/documents` + +Uploads documents to a specified dataset. + +#### Request + +- Method: POST +- URL: `/api/v1/datasets/{dataset_id}/documents` +- Headers: + - `'Content-Type: multipart/form-data'` + - `'Authorization: Bearer '` +- Form: + - `'file=@{FILE_PATH}'` + +##### Request example + +```bash +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' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The ID of the dataset to which the documents will be uploaded. +- `'file'`: (*Body parameter*) + A document to upload. + +#### Response + +Success: + +```json +{ + "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": { + "use_raptor": false + } + }, + "run": "UNSTART", + "size": 17966, + "thumbnail": "", + "type": "doc" + } + ] +} +``` + +Failure: + +```json +{ + "code": 101, + "message": "No file part!" +} +``` + +--- + +### Update document + +**PUT** `/api/v1/datasets/{dataset_id}/documents/{document_id}` + +Updates configurations for a specified document. + +#### Request + +- Method: PUT +- URL: `/api/v1/datasets/{dataset_id}/documents/{document_id}` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name"`:`string` + - `"meta_fields"`:`object` + - `"chunk_method"`:`string` + - `"parser_config"`:`object` + +##### Request example + +```bash +curl --request PUT \ + --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data ' + { + "name": "manual.txt", + "chunk_method": "manual", + "parser_config": {"chunk_token_num": 128} + }' + +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The ID of the associated dataset. +- `document_id`: (*Path parameter*) + The ID of the document to update. +- `"name"`: (*Body parameter*), `string` +- `"meta_fields"`: (*Body parameter*), `dict[str, Any]` The meta fields of the document. +- `"chunk_method"`: (*Body parameter*), `string` + The parsing method to apply to the document: + - `"naive"`: General + - `"manual`: Manual + - `"qa"`: Q&A + - `"table"`: Table + - `"paper"`: Paper + - `"book"`: Book + - `"laws"`: Laws + - `"presentation"`: Presentation + - `"picture"`: Picture + - `"one"`: One + - `"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_num"`: Defaults to `256`. + - `"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. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The dataset does not have the document." +} +``` + +--- + +### Download document + +**GET** `/api/v1/datasets/{dataset_id}/documents/{document_id}` + +Downloads a document from a specified dataset. + +#### Request + +- Method: GET +- URL: `/api/v1/datasets/{dataset_id}/documents/{document_id}` +- Headers: + - `'Authorization: Bearer '` +- Output: + - `'{PATH_TO_THE_FILE}'` + +##### Request example + +```bash +curl --request GET \ + --url http://{address}/api/v1/datasets/{dataset_id}/documents/{document_id} \ + --header 'Authorization: Bearer ' \ + --output ./ragflow.txt +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `documents_id`: (*Path parameter*) + The ID of the document to download. + +#### Response + +Success: + +```json +This is a test to verify the file download feature. +``` + +Failure: + +```json +{ + "code": 102, + "message": "You do not own the dataset 7898da028a0511efbf750242ac1220005." +} +``` + +--- + +### List documents + +**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}&create_time_from={timestamp}&create_time_to={timestamp}&suffix={file_suffix}&run={run_status}` + +Lists documents in a specified dataset. + +#### Request + +- Method: 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}&create_time_from={timestamp}&create_time_to={timestamp}&suffix={file_suffix}&run={run_status}` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` + +##### Request examples + +**A basic request with pagination:** +```bash +curl --request GET \ + --url http://{address}/api/v1/datasets/{dataset_id}/documents?page=1&page_size=10 \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `keywords`: (*Filter parameter*), `string` + The keywords used to match document titles. +- `page`: (*Filter parameter*), `integer` + Specifies the page on which the documents will be displayed. Defaults to `1`. +- `page_size`: (*Filter parameter*), `integer` + The maximum number of documents on each page. Defaults to `30`. +- `orderby`: (*Filter parameter*), `string` + The field by which documents should be sorted. Available options: + - `create_time` (default) + - `update_time` +- `desc`: (*Filter parameter*), `boolean` + Indicates whether the retrieved documents should be sorted in descending order. Defaults to `true`. +- `id`: (*Filter parameter*), `string` + The ID of the document to retrieve. +- `create_time_from`: (*Filter parameter*), `integer` + Unix timestamp for filtering documents created after this time. 0 means no filter. Defaults to `0`. +- `create_time_to`: (*Filter parameter*), `integer` + Unix timestamp for filtering documents created before this time. 0 means no filter. Defaults to `0`. +- `suffix`: (*Filter parameter*), `array[string]` + Filter by file suffix. Supports multiple values, e.g., `pdf`, `txt`, and `docx`. Defaults to all suffixes. +- `run`: (*Filter parameter*), `array[string]` + Filter by document processing status. Supports numeric, text, and mixed formats: + - Numeric format: `["0", "1", "2", "3", "4"]` + - Text format: `[UNSTART, RUNNING, CANCEL, DONE, FAIL]` + - Mixed format: `[UNSTART, 1, DONE]` (mixing numeric and text formats) + - Status mapping: + - `0` / `UNSTART`: Document not yet processed + - `1` / `RUNNING`: Document is currently being processed + - `2` / `CANCEL`: Document processing was cancelled + - `3` / `DONE`: Document processing completed successfully + - `4` / `FAIL`: Document processing failed + Defaults to all statuses. + +##### Usage examples + +**A request with multiple filtering parameters** + +```bash +curl --request GET \ + --url 'http://{address}/api/v1/datasets/{dataset_id}/documents?suffix=pdf&run=DONE&page=1&page_size=10' \ + --header 'Authorization: Bearer ' +``` + +#### Response + +Success: + +```json +{ + "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_duration": 0.0, + "progress": 0.0, + "progress_msg": "", + "run": "UNSTART", + "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_datasets": 1 + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "You don't own the dataset 7898da028a0511efbf750242ac1220005. " +} +``` + +--- + +### Delete documents + +**DELETE** `/api/v1/datasets/{dataset_id}/documents` + +Deletes documents by ID. + +#### Request + +- Method: DELETE +- URL: `/api/v1/datasets/{dataset_id}/documents` +- Headers: + - `'Content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"ids"`: `list[string]` + +##### Request example + +```bash +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"] + }' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `"ids"`: (*Body parameter*), `list[string]` + The IDs of the documents to delete. If it is not specified, all documents in the specified dataset will be deleted. + +#### Response + +Success: + +```json +{ + "code": 0 +}. +``` + +Failure: + +```json +{ + "code": 102, + "message": "You do not own the dataset 7898da028a0511efbf750242ac1220005." +} +``` + +--- + +### Parse documents + +**POST** `/api/v1/datasets/{dataset_id}/chunks` + +Parses documents in a specified dataset. + +#### Request + +- Method: POST +- URL: `/api/v1/datasets/{dataset_id}/chunks` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"document_ids"`: `list[string]` + +##### Request example + +```bash +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"] + }' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The dataset ID. +- `"document_ids"`: (*Body parameter*), `list[string]`, *Required* + The IDs of the documents to parse. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "`document_ids` is required" +} +``` + +--- + +### Stop parsing documents + +**DELETE** `/api/v1/datasets/{dataset_id}/chunks` + +Stops parsing specified documents. + +#### Request + +- Method: DELETE +- URL: `/api/v1/datasets/{dataset_id}/chunks` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"document_ids"`: `list[string]` + +##### Request example + +```bash +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"] + }' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `"document_ids"`: (*Body parameter*), `list[string]`, *Required* + The IDs of the documents for which the parsing should be stopped. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "`document_ids` is required" +} +``` + +--- + +## CHUNK MANAGEMENT WITHIN DATASET + +--- + +### Add chunk + +**POST** `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks` + +Adds a chunk to a specified document in a specified dataset. + +#### Request + +- Method: POST +- URL: `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"content"`: `string` + - `"important_keywords"`: `list[string]` + +##### Request example + +```bash +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": "" + }' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `document_ids`: (*Path parameter*) + The associated document ID. +- `"content"`: (*Body parameter*), `string`, *Required* + The text content of the chunk. +- `"important_keywords`(*Body parameter*), `list[string]` + The key terms or phrases to tag with the chunk. +- `"questions"`(*Body parameter*), `list[string]` + If there is a given question, the embedded chunks will be based on them + +#### Response + +Success: + +```json +{ + "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": [] + } + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "`content` is required" +} +``` + +--- + +### List chunks + +**GET** `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={id}` + +Lists chunks in a specified document. + +#### Request + +- Method: GET +- URL: `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks?keywords={keywords}&page={page}&page_size={page_size}&id={chunk_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +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 ' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `document_id`: (*Path parameter*) + The associated document ID. +- `keywords`(*Filter parameter*), `string` + The keywords used to match chunk content. +- `page`(*Filter parameter*), `integer` + Specifies the page on which the chunks will be displayed. Defaults to `1`. +- `page_size`(*Filter parameter*), `integer` + The maximum number of chunks on each page. Defaults to `1024`. +- `id`(*Filter parameter*), `string` + The ID of the chunk to retrieve. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "chunks": [ + { + "available": true, + "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": { + "use_raptor": false + } + }, + "process_begin_at": "Thu, 24 Oct 2024 09:56:44 GMT", + "process_duration": 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 + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "You don't own the document 5c5999ec7be811ef9cab0242ac12000e5." +} +``` + +--- + +### Delete chunks + +**DELETE** `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks` + +Deletes chunks by ID. + +#### Request + +- Method: DELETE +- URL: `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"chunk_ids"`: `list[string]` + +##### Request example + +```bash +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"] + }' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `document_ids`: (*Path parameter*) + The associated document ID. +- `"chunk_ids"`: (*Body parameter*), `list[string]` + The IDs of the chunks to delete. If it is not specified, all chunks of the specified document will be deleted. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "`chunk_ids` is required" +} +``` + +--- + +### Update chunk + +**PUT** `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}` + +Updates content or configurations for a specified chunk. + +#### Request + +- Method: PUT +- URL: `/api/v1/datasets/{dataset_id}/documents/{document_id}/chunks/{chunk_id}` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"content"`: `string` + - `"important_keywords"`: `list[string]` + - `"available"`: `boolean` + +##### Request example + +```bash +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": [] + }' +``` + +##### Request parameters + +- `dataset_id`: (*Path parameter*) + The associated dataset ID. +- `document_ids`: (*Path parameter*) + The associated document ID. +- `chunk_id`: (*Path parameter*) + The ID of the chunk to update. +- `"content"`: (*Body parameter*), `string` + The text content of the chunk. +- `"important_keywords"`: (*Body parameter*), `list[string]` + A list of key terms or phrases to tag with the chunk. +- `"available"`: (*Body parameter*) `boolean` + The chunk's availability status in the dataset. Value options: + - `true`: Available (default) + - `false`: Unavailable + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "Can't find this chunk 29a2d9987e16ba331fb4d7d30d99b71d2" +} +``` + +--- + +### Retrieve chunks + +**POST** `/api/v1/retrieval` + +Retrieves chunks from specified datasets. + +#### Request + +- Method: POST +- URL: `/api/v1/retrieval` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"question"`: `string` + - `"dataset_ids"`: `list[string]` + - `"document_ids"`: `list[string]` + - `"page"`: `integer` + - `"page_size"`: `integer` + - `"similarity_threshold"`: `float` + - `"vector_similarity_weight"`: `float` + - `"top_k"`: `integer` + - `"rerank_id"`: `string` + - `"keyword"`: `boolean` + - `"highlight"`: `boolean` + - `"cross_languages"`: `list[string]` + - `"metadata_condition"`: `object` + +##### Request example + +```bash +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"], + "metadata_condition": { + "conditions": [ + { + "name": "author", + "comparison_operator": "=", + "value": "Toby" + }, + { + "name": "url", + "comparison_operator": "not contains", + "value": "amd" + } + ] + } + }' +``` + +##### Request parameter + +- `"question"`: (*Body parameter*), `string`, *Required* + The user query or query keywords. +- `"dataset_ids"`: (*Body parameter*) `list[string]` + The IDs of the datasets to search. If you do not set this argument, ensure that you set `"document_ids"`. +- `"document_ids"`: (*Body parameter*), `list[string]` + 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`. +- `"similarity_threshold"`: (*Body parameter*) + The minimum similarity score. Defaults to `0.2`. +- `"vector_similarity_weight"`: (*Body parameter*), `float` + 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: + - `true`: Enable keyword-based matching. + - `false`: Disable keyword-based matching (default). +- `"highlight"`: (*Body parameter*), `boolean` + Specifies whether to enable highlighting of matched terms in the results: + - `true`: Enable highlighting of matched terms. + - `false`: Disable highlighting of matched terms (default). +- `"cross_languages"`: (*Body parameter*) `list[string]` + The languages that should be translated into, in order to achieve keywords retrievals in different languages. +- `"metadata_condition"`: (*Body parameter*), `object` + The metadata condition used for filtering chunks: + - `"conditions"`: (*Body parameter*), `array` + A list of metadata filter conditions. + - `"name"`: `string` - The metadata field name to filter by, e.g., `"author"`, `"company"`, `"url"`. Ensure this parameter before use. See [Set metadata](../guides/dataset/set_metadata.md) for details. + - `comparison_operator`: `string` - The comparison operator. Can be one of: + - `"contains"` + - `"not contains"` + - `"start with"` + - `"empty"` + - `"not empty"` + - `"="` + - `"≠"` + - `">"` + - `"<"` + - `"≥"` + - `"≤"` + - `"value"`: `string` - The value to compare. + + +#### Response + +Success: + +```json +{ + "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 + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "`datasets` is required." +} +``` + +--- + +## CHAT ASSISTANT MANAGEMENT + +--- + +### Create chat assistant + +**POST** `/api/v1/chats` + +Creates a chat assistant. + +#### Request + +- Method: POST +- URL: `/api/v1/chats` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name"`: `string` + - `"avatar"`: `string` + - `"dataset_ids"`: `list[string]` + - `"llm"`: `object` + - `"prompt"`: `object` + +##### Request example + +```shell +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" +}' +``` + +##### Request parameters + +- `"name"`: (*Body parameter*), `string`, *Required* + The name of the chat assistant. +- `"avatar"`: (*Body parameter*), `string` + Base64 encoding of the avatar. +- `"dataset_ids"`: (*Body parameter*), `list[string]` + The IDs of the associated datasets. +- `"llm"`: (*Body parameter*), `object` + 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.4`. + - `"frequency penalty"`: `float` + Similar to the presence penalty, this reduces the model’s tendency to repeat the same words frequently. Defaults to `0.7`. +- `"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 `6`. + - `"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, + "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. + +#### Request + +- Method: PUT +- URL: `/api/v1/chats/{chat_id}` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name"`: `string` + - `"avatar"`: `string` + - `"dataset_ids"`: `list[string]` + - `"llm"`: `object` + - `"prompt"`: `object` + +##### Request example + +```bash +curl --request PUT \ + --url http://{address}/api/v1/chats/{chat_id} \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data ' + { + "name":"Test" + }' +``` + +#### Parameters + +- `chat_id`: (*Path parameter*) + The ID of the chat assistant to update. +- `"name"`: (*Body parameter*), `string`, *Required* + The revised name of the chat assistant. +- `"avatar"`: (*Body parameter*), `string` + Base64 encoding of the avatar. +- `"dataset_ids"`: (*Body parameter*), `list[string]` + The IDs of the associated datasets. +- `"llm"`: (*Body parameter*), `object` + 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`. +- `"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 '` +- Body: + - `"ids"`: `list[string]` + +##### Request example + +```bash +curl --request DELETE \ + --url http://{address}/api/v1/chats \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --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. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "ids are required" +} +``` + +--- + +### List chat assistants + +**GET** `/api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id}` + +Lists chat assistants. + +#### Request + +- Method: GET +- URL: `/api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url http://{address}/api/v1/chats?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={chat_name}&id={chat_id} \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `page`: (*Filter parameter*), `integer` + Specifies the page on which the chat assistants will be displayed. Defaults to `1`. +- `page_size`: (*Filter parameter*), `integer` + The number of chat assistants on each page. Defaults to `30`. +- `orderby`: (*Filter parameter*), `string` + The attribute by which the results are sorted. Available options: + - `create_time` (default) + - `update_time` +- `desc`: (*Filter parameter*), `boolean` + Indicates whether the retrieved chat assistants should be sorted in descending order. Defaults to `true`. +- `id`: (*Filter parameter*), `string` + The ID of the chat assistant to retrieve. +- `name`: (*Filter parameter*), `string` + The name of the chat assistant to retrieve. + +#### Response + +Success: + +```json +{ + "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, + "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 + } + ] +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The chat doesn't exist" +} +``` + +--- + +## SESSION MANAGEMENT + +--- + +### Create session with chat assistant + +**POST** `/api/v1/chats/{chat_id}/sessions` + +Creates a session with a chat assistant. + +#### Request + +- Method: POST +- URL: `/api/v1/chats/{chat_id}/sessions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name"`: `string` + - `"user_id"`: `string` (optional) + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/chats/{chat_id}/sessions \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data ' + { + "name": "new session" + }' +``` + +##### Request parameters + +- `chat_id`: (*Path parameter*) + The ID of the associated chat assistant. +- `"name"`: (*Body parameter*), `string` + The name of the chat session to create. +- `"user_id"`: (*Body parameter*), `string` + Optional user-defined ID. + +#### Response + +Success: + +```json +{ + "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 + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "Name cannot be empty." +} +``` + +--- + +### Update chat assistant's session + +**PUT** `/api/v1/chats/{chat_id}/sessions/{session_id}` + +Updates a session of a specified chat assistant. + +#### Request + +- Method: PUT +- URL: `/api/v1/chats/{chat_id}/sessions/{session_id}` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"name`: `string` + - `"user_id`: `string` (optional) + +##### Request example + +```bash +curl --request PUT \ + --url http://{address}/api/v1/chats/{chat_id}/sessions/{session_id} \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data ' + { + "name": "" + }' +``` + +##### 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` + The revised name of the session. +- `"user_id"`: (*Body parameter*), `string` + Optional user-defined ID. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "Name cannot be empty." +} +``` + +--- + +### List chat assistant's sessions + +**GET** `/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}` + +Lists sessions associated with a specified chat assistant. + +#### Request + +- Method: GET +- URL: `/api/v1/chats/{chat_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={session_name}&id={session_id}&user_id={user_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +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 ' +``` + +##### Request Parameters + +- `chat_id`: (*Path parameter*) + The ID of the associated chat assistant. +- `page`: (*Filter parameter*), `integer` + Specifies the page on which the sessions will be displayed. Defaults to `1`. +- `page_size`: (*Filter parameter*), `integer` + The number of sessions on each page. Defaults to `30`. +- `orderby`: (*Filter parameter*), `string` + The field by which sessions should be sorted. Available options: + - `create_time` (default) + - `update_time` +- `desc`: (*Filter parameter*), `boolean` + Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `true`. +- `name`: (*Filter parameter*) `string` + The name of the chat session to retrieve. +- `id`: (*Filter parameter*), `string` + The ID of the chat session to retrieve. +- `user_id`: (*Filter parameter*), `string` + The optional user-defined ID passed in when creating session. + +#### Response + +Success: + +```json +{ + "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 + } + ] +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The session doesn't exist" +} +``` + +--- + +### Delete chat assistant's sessions + +**DELETE** `/api/v1/chats/{chat_id}/sessions` + +Deletes sessions of a chat assistant by ID. + +#### Request + +- Method: DELETE +- URL: `/api/v1/chats/{chat_id}/sessions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"ids"`: `list[string]` + +##### Request example + +```bash +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"] + }' +``` + +##### Request Parameters + +- `chat_id`: (*Path parameter*) + The ID of the associated chat assistant. +- `"ids"`: (*Body Parameter*), `list[string]` + The IDs of the sessions to delete. If it is not specified, all sessions associated with the specified chat assistant will be deleted. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The chat doesn't own the session" +} +``` + +--- + +### Converse with chat assistant + +**POST** `/api/v1/chats/{chat_id}/completions` + +Asks a specified chat assistant a question to start an AI-powered conversation. + +:::tip NOTE + +- In streaming mode, not all responses include a reference, as this depends on the system's judgement. +- In streaming mode, the last message is an empty message: + + ```json + data: + { + "code": 0, + "data": true + } + ``` + +::: + +#### Request + +- Method: POST +- URL: `/api/v1/chats/{chat_id}/completions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"question"`: `string` + - `"stream"`: `boolean` + - `"session_id"`: `string` (optional) + - `"user_id`: `string` (optional) + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/chats/{chat_id}/completions \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data-binary ' + { + }' +``` + +```bash +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" + }' +``` + +##### Request Parameters + +- `chat_id`: (*Path parameter*) + The ID of the associated chat assistant. +- `"question"`: (*Body Parameter*), `string`, *Required* + The question to start an AI-powered conversation. +- `"stream"`: (*Body Parameter*), `boolean` + 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.", + "reference": { + "total": 1, + "chunks": [ + { + "id": "faf26c791128f2d5e821f822671063bd", + "content": "xxxxxxxx", + "document_id": "dd58f58e888511ef89c90242ac120006", + "document_name": "1.txt", + "dataset_id": "8e83e57a884611ef9d760242ac120006", + "image_id": "", + "url": null, + "similarity": 0.7, + "vector_similarity": 0.0, + "term_similarity": 1.0, + "doc_type": [], + "positions": [ + "" + ] + } + ], + "doc_aggs": [ + { + "doc_name": "1.txt", + "doc_id": "dd58f58e888511ef89c90242ac120006", + "count": 1 + } + ] + }, + "prompt": "xxxxxxxxxxx", + "created_at": 1755055623.6401553, + "id": "a84c5dd4-97b4-4624-8c3b-974012c8000d", + "session_id": "82b0ab2a9c1911ef9d870242ac120006" + } +} +data:{ + "code": 0, + "data": true +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "Please input your question." +} +``` + +--- + +### Create session with agent + +:::danger DEPRECATED +This method is deprecated and not recommended. You can still call it but be mindful that calling `Converse with agent` will automatically generate a session ID for the associated agent. +::: + +**POST** `/api/v1/agents/{agent_id}/sessions` + +Creates a session with an agent. + +#### Request + +- Method: POST +- URL: `/api/v1/agents/{agent_id}/sessions?user_id={user_id}` +- Headers: + - `'content-Type: application/json' + - `'Authorization: Bearer '` +- Body: + - the required parameters:`str` + - other parameters: + The variables specified in the **Begin** component. + +##### Request example + +If the **Begin** component in your agent does not take required parameters: + +```bash +curl --request POST \ + --url http://{address}/api/v1/agents/{agent_id}/sessions \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + }' +``` + +##### Request parameters + +- `agent_id`: (*Path parameter*) + The ID of the associated agent. +- `user_id`: (*Filter parameter*) + The optional user-defined ID for parsing docs (especially images) when creating a session while uploading files. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": { + "agent_id": "dbb4ed366e8611f09690a55a6daec4ef", + "dsl": { + "components": { + "Message:EightyJobsAsk": { + "downstream": [], + "obj": { + "component_name": "Message", + "params": { + "content": [ + "{begin@var1}{begin@var2}" + ], + "debug_inputs": {}, + "delay_after_error": 2.0, + "description": "", + "exception_default_value": null, + "exception_goto": null, + "exception_method": null, + "inputs": {}, + "max_retries": 0, + "message_history_window_size": 22, + "outputs": { + "content": { + "type": "str", + "value": null + } + }, + "stream": true + } + }, + "upstream": [ + "begin" + ] + }, + "begin": { + "downstream": [ + "Message:EightyJobsAsk" + ], + "obj": { + "component_name": "Begin", + "params": { + "debug_inputs": {}, + "delay_after_error": 2.0, + "description": "", + "enablePrologue": true, + "enable_tips": true, + "exception_default_value": null, + "exception_goto": null, + "exception_method": null, + "inputs": { + "var1": { + "name": "var1", + "optional": false, + "options": [], + "type": "line", + "value": null + }, + "var2": { + "name": "var2", + "optional": false, + "options": [], + "type": "line", + "value": null + } + }, + "max_retries": 0, + "message_history_window_size": 22, + "mode": "conversational", + "outputs": {}, + "prologue": "Hi! I'm your assistant. What can I do for you?", + "tips": "Please fill in the form" + } + }, + "upstream": [] + } + }, + "globals": { + "sys.conversation_turns": 0, + "sys.files": [], + "sys.query": "", + "sys.user_id": "" + }, + "graph": { + "edges": [ + { + "data": { + "isHovered": false + }, + "id": "xy-edge__beginstart-Message:EightyJobsAskend", + "markerEnd": "logo", + "source": "begin", + "sourceHandle": "start", + "style": { + "stroke": "rgba(151, 154, 171, 1)", + "strokeWidth": 1 + }, + "target": "Message:EightyJobsAsk", + "targetHandle": "end", + "type": "buttonEdge", + "zIndex": 1001 + } + ], + "nodes": [ + { + "data": { + "form": { + "enablePrologue": true, + "inputs": { + "var1": { + "name": "var1", + "optional": false, + "options": [], + "type": "line" + }, + "var2": { + "name": "var2", + "optional": false, + "options": [], + "type": "line" + } + }, + "mode": "conversational", + "prologue": "Hi! I'm your assistant. What can I do for you?" + }, + "label": "Begin", + "name": "begin" + }, + "dragging": false, + "id": "begin", + "measured": { + "height": 112, + "width": 200 + }, + "position": { + "x": 270.64098070942583, + "y": -56.320928437811176 + }, + "selected": false, + "sourcePosition": "left", + "targetPosition": "right", + "type": "beginNode" + }, + { + "data": { + "form": { + "content": [ + "{begin@var1}{begin@var2}" + ] + }, + "label": "Message", + "name": "Message_0" + }, + "dragging": false, + "id": "Message:EightyJobsAsk", + "measured": { + "height": 57, + "width": 200 + }, + "position": { + "x": 279.5, + "y": 190 + }, + "selected": true, + "sourcePosition": "right", + "targetPosition": "left", + "type": "messageNode" + } + ] + }, + "history": [], + "memory": [], + "messages": [], + "path": [], + "retrieval": [], + "task_id": "dbb4ed366e8611f09690a55a6daec4ef" + }, + "id": "0b02fe80780e11f084adcfdc3ed1d902", + "message": [ + { + "content": "Hi! I'm your assistant. What can I do for you?", + "role": "assistant" + } + ], + "source": "agent", + "user_id": "c3fb861af27a11efa69751e139332ced" + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "Agent not found." +} +``` + +--- + +### Converse with agent + +**POST** `/api/v1/agents/{agent_id}/completions` + +Asks a specified agent a question to start an AI-powered conversation. + +:::tip NOTE + +- In streaming mode, not all responses include a reference, as this depends on the system's judgement. +- In streaming mode, the last message is an empty message: + + ``` + [DONE] + ``` + +::: + +#### Request + +- Method: POST +- URL: `/api/v1/agents/{agent_id}/completions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"question"`: `string` + - `"stream"`: `boolean` + - `"session_id"`: `string` (optional) + - `"inputs"`: `object` (optional) + - `"user_id"`: `string` (optional) + +:::info IMPORTANT +You can include custom parameters in the request body, but first ensure they are defined in the [Begin](../guides/agent/agent_component_reference/begin.mdx) component. +::: + +##### Request example + +- If the **Begin** component does not take parameters: + +```bash +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": false, + }' +``` + +- If the **Begin** component takes parameters, include their values in the body of `"inputs"` as follows: + +```bash +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": false, + "inputs": { + "line_var": { + "type": "line", + "value": "I am line_var" + }, + "int_var": { + "type": "integer", + "value": 1 + }, + "paragraph_var": { + "type": "paragraph", + "value": "a\nb\nc" + }, + "option_var": { + "type": "options", + "value": "option 2" + }, + "boolean_var": { + "type": "boolean", + "value": true + } + } + }' +``` + +The following code will execute the completion process + +```bash +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" + }' +``` + +##### Request Parameters + +- `agent_id`: (*Path parameter*), `string` + The ID of the associated agent. +- `"question"`: (*Body Parameter*), `string`, *Required* + The question to start an AI-powered conversation. +- `"stream"`: (*Body Parameter*), `boolean` + Indicates whether to output responses in a streaming way: + - `true`: Enable streaming (default). + - `false`: Disable streaming. +- `"session_id"`: (*Body Parameter*) + The ID of the session. If it is not provided, a new session will be generated. +- `"inputs"`: (*Body Parameter*) + Variables specified in the **Begin** component. +- `"user_id"`: (*Body parameter*), `string` + The optional user-defined ID. Valid *only* when no `session_id` is provided. + +:::tip NOTE +For now, this method does *not* support a file type input/variable. As a workaround, use the following to upload a file to an agent: +`http://{address}/v1/canvas/upload/{agent_id}` +*You will get a corresponding file ID from its response body.* +::: + +#### Response + +success without `session_id` provided and with no variables specified in the **Begin** component: + +Stream: + +```json +... + +data: { + "event": "message", + "message_id": "cecdcb0e83dc11f0858253708ecb6573", + "created_at": 1756364483, + "task_id": "d1f79142831f11f09cc51795b9eb07c0", + "data": { + "content": " themes" + }, + "session_id": "cd097ca083dc11f0858253708ecb6573" +} + +data: { + "event": "message", + "message_id": "cecdcb0e83dc11f0858253708ecb6573", + "created_at": 1756364483, + "task_id": "d1f79142831f11f09cc51795b9eb07c0", + "data": { + "content": "." + }, + "session_id": "cd097ca083dc11f0858253708ecb6573" +} + +data: { + "event": "message_end", + "message_id": "cecdcb0e83dc11f0858253708ecb6573", + "created_at": 1756364483, + "task_id": "d1f79142831f11f09cc51795b9eb07c0", + "data": { + "reference": { + "chunks": { + "20": { + "id": "4b8935ac0a22deb1", + "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.", + "document_id": "4bdd2ff65e1511f0907f09f583941b45", + "document_name": "INSTALL22.md", + "dataset_id": "456ce60c5e1511f0907f09f583941b45", + "image_id": "", + "positions": [ + [ + 12, + 11, + 11, + 11, + 11 + ] + ], + "url": null, + "similarity": 0.5705525104787287, + "vector_similarity": 0.7351750337624289, + "term_similarity": 0.5000000005, + "doc_type": "" + } + }, + "doc_aggs": { + "INSTALL22.md": { + "doc_name": "INSTALL22.md", + "doc_id": "4bdd2ff65e1511f0907f09f583941b45", + "count": 3 + }, + "INSTALL.md": { + "doc_name": "INSTALL.md", + "doc_id": "4bd7fdd85e1511f0907f09f583941b45", + "count": 2 + }, + "INSTALL(1).md": { + "doc_name": "INSTALL(1).md", + "doc_id": "4bdfb42e5e1511f0907f09f583941b45", + "count": 2 + }, + "INSTALL3.md": { + "doc_name": "INSTALL3.md", + "doc_id": "4bdab5825e1511f0907f09f583941b45", + "count": 1 + } + } + } + }, + "session_id": "cd097ca083dc11f0858253708ecb6573" +} + +data:[DONE] +``` + +Non-stream: + +```json +{ + "code": 0, + "data": { + "created_at": 1756363177, + "data": { + "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For macOS:\nUsing Homebrew:\n```bash\nbrew install neovim\n```\n\n### For Linux (Debian/Ubuntu):\n```bash\nsudo apt update\nsudo apt install neovim\n```\n\nFor other Linux distributions, you can use their respective package managers or build from source.\n\n### For Windows:\n1. Download the latest Windows installer from the official Neovim GitHub releases page\n2. Run the installer and follow the prompts\n3. Add Neovim to your PATH if not done automatically\n\n### From source (Unix-like systems):\n```bash\ngit clone https://github.com/neovim/neovim.git\ncd neovim\nmake CMAKE_BUILD_TYPE=Release\nsudo make install\n```\n\nAfter installation, you can verify it by running `nvim --version` in your terminal.", + "created_at": 18129.044975627, + "elapsed_time": 10.0157331670016, + "inputs": { + "var1": { + "value": "I am var1" + }, + "var2": { + "value": "I am var2" + } + }, + "outputs": { + "_created_time": 18129.502422278, + "_elapsed_time": 0.00013378599760471843, + "content": "\nTo install Neovim, the process varies depending on your operating system:\n\n### For macOS:\nUsing Homebrew:\n```bash\nbrew install neovim\n```\n\n### For Linux (Debian/Ubuntu):\n```bash\nsudo apt update\nsudo apt install neovim\n```\n\nFor other Linux distributions, you can use their respective package managers or build from source.\n\n### For Windows:\n1. Download the latest Windows installer from the official Neovim GitHub releases page\n2. Run the installer and follow the prompts\n3. Add Neovim to your PATH if not done automatically\n\n### From source (Unix-like systems):\n```bash\ngit clone https://github.com/neovim/neovim.git\ncd neovim\nmake CMAKE_BUILD_TYPE=Release\nsudo make install\n```\n\nAfter installation, you can verify it by running `nvim --version` in your terminal." + }, + "reference": { + "chunks": { + "20": { + "content": "```cd /usr/ports/editors/neovim/ && make install```## Android[Termux](https://github.com/termux/termux-app) offers a Neovim package.", + "dataset_id": "456ce60c5e1511f0907f09f583941b45", + "doc_type": "", + "document_id": "4bdd2ff65e1511f0907f09f583941b45", + "document_name": "INSTALL22.md", + "id": "4b8935ac0a22deb1", + "image_id": "", + "positions": [ + [ + 12, + 11, + 11, + 11, + 11 + ] + ], + "similarity": 0.5705525104787287, + "term_similarity": 0.5000000005, + "url": null, + "vector_similarity": 0.7351750337624289 + } + }, + "doc_aggs": { + "INSTALL(1).md": { + "count": 2, + "doc_id": "4bdfb42e5e1511f0907f09f583941b45", + "doc_name": "INSTALL(1).md" + }, + "INSTALL.md": { + "count": 2, + "doc_id": "4bd7fdd85e1511f0907f09f583941b45", + "doc_name": "INSTALL.md" + }, + "INSTALL22.md": { + "count": 3, + "doc_id": "4bdd2ff65e1511f0907f09f583941b45", + "doc_name": "INSTALL22.md" + }, + "INSTALL3.md": { + "count": 1, + "doc_id": "4bdab5825e1511f0907f09f583941b45", + "doc_name": "INSTALL3.md" + } + } + } + }, + "event": "workflow_finished", + "message_id": "c4692a2683d911f0858253708ecb6573", + "session_id": "c39f6f9c83d911f0858253708ecb6573", + "task_id": "d1f79142831f11f09cc51795b9eb07c0" + } +} +``` + +Success without `session_id` provided and with variables specified in the **Begin** component: + +Stream: + +```json +data:{ + "event": "message", + "message_id": "0e273472783711f0806e1a6272e682d8", + "created_at": 1755083830, + "task_id": "99ee29d6783511f09c921a6272e682d8", + "data": { + "content": "Hello" + }, + "session_id": "0e0d1542783711f0806e1a6272e682d8" +} + +data:{ + "event": "message", + "message_id": "0e273472783711f0806e1a6272e682d8", + "created_at": 1755083830, + "task_id": "99ee29d6783511f09c921a6272e682d8", + "data": { + "content": "!" + }, + "session_id": "0e0d1542783711f0806e1a6272e682d8" +} + +data:{ + "event": "message", + "message_id": "0e273472783711f0806e1a6272e682d8", + "created_at": 1755083830, + "task_id": "99ee29d6783511f09c921a6272e682d8", + "data": { + "content": " How" + }, + "session_id": "0e0d1542783711f0806e1a6272e682d8" +} + +... + +data:[DONE] +``` + +Non-stream: + +```json +{ + "code": 0, + "data": { + "created_at": 1755083779, + "data": { + "created_at": 547400.868004651, + "elapsed_time": 3.5037803899031132, + "inputs": { + "boolean_var": { + "type": "boolean", + "value": true + }, + "int_var": { + "type": "integer", + "value": 1 + }, + "line_var": { + "type": "line", + "value": "I am line_var" + }, + "option_var": { + "type": "options", + "value": "option 2" + }, + "paragraph_var": { + "type": "paragraph", + "value": "a\nb\nc" + } + }, + "outputs": { + "_created_time": 547400.869271305, + "_elapsed_time": 0.0001251999055966735, + "content": "Hello there! How can I assist you today?" + } + }, + "event": "workflow_finished", + "message_id": "effdad8c783611f089261a6272e682d8", + "session_id": "efe523b6783611f089261a6272e682d8", + "task_id": "99ee29d6783511f09c921a6272e682d8" + } +} +``` + +Success with variables specified in the **Begin** component: + +Stream: + +```json +data:{ + "event": "message", + "message_id": "5b62e790783711f0bc531a6272e682d8", + "created_at": 1755083960, + "task_id": "99ee29d6783511f09c921a6272e682d8", + "data": { + "content": "Hello" + }, + "session_id": "979e450c781d11f095cb729e3aa55728" +} + +data:{ + "event": "message", + "message_id": "5b62e790783711f0bc531a6272e682d8", + "created_at": 1755083960, + "task_id": "99ee29d6783511f09c921a6272e682d8", + "data": { + "content": "!" + }, + "session_id": "979e450c781d11f095cb729e3aa55728" +} + +data:{ + "event": "message", + "message_id": "5b62e790783711f0bc531a6272e682d8", + "created_at": 1755083960, + "task_id": "99ee29d6783511f09c921a6272e682d8", + "data": { + "content": " You" + }, + "session_id": "979e450c781d11f095cb729e3aa55728" +} + +... + +data:[DONE] +``` + +Non-stream: + +```json +{ + "code": 0, + "data": { + "created_at": 1755084029, + "data": { + "created_at": 547650.750818867, + "elapsed_time": 1.6227330720284954, + "inputs": {}, + "outputs": { + "_created_time": 547650.752800839, + "_elapsed_time": 9.628792759031057e-05, + "content": "Hello! It appears you've sent another \"Hello\" without additional context. I'm here and ready to respond to any requests or questions you may have. Is there something specific you'd like to discuss or learn about?" + } + }, + "event": "workflow_finished", + "message_id": "84eec534783711f08db41a6272e682d8", + "session_id": "979e450c781d11f095cb729e3aa55728", + "task_id": "99ee29d6783511f09c921a6272e682d8" + } +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "`question` is required." +} +``` + +--- + +### List agent sessions + +**GET** `/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}&user_id={user_id}&dsl={dsl}` + +Lists sessions associated with a specified agent. + +#### Request + +- Method: GET +- URL: `/api/v1/agents/{agent_id}/sessions?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&id={session_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +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 ' +``` + +##### Request Parameters + +- `agent_id`: (*Path parameter*) + The ID of the associated agent. +- `page`: (*Filter parameter*), `integer` + Specifies the page on which the sessions will be displayed. Defaults to `1`. +- `page_size`: (*Filter parameter*), `integer` + The number of sessions on each page. Defaults to `30`. +- `orderby`: (*Filter parameter*), `string` + The field by which sessions should be sorted. Available options: + - `create_time` (default) + - `update_time` +- `desc`: (*Filter parameter*), `boolean` + Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `true`. +- `id`: (*Filter parameter*), `string` + The ID of the agent session to retrieve. +- `user_id`: (*Filter parameter*), `string` + The optional user-defined ID passed in when creating session. +- `dsl`: (*Filter parameter*), `boolean` + Indicates whether to include the dsl field of the sessions in the response. Defaults to `true`. + +#### Response + +Success: + +```json +{ + "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", + "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, + "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": "" + }] +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "You don't own the agent ccd2f856b12311ef94ca0242ac1200052." +} +``` + +--- + +### Delete agent's sessions + +**DELETE** `/api/v1/agents/{agent_id}/sessions` + +Deletes sessions of a agent by ID. + +#### Request + +- Method: DELETE +- URL: `/api/v1/agents/{agent_id}/sessions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"ids"`: `list[string]` + +##### Request example + +```bash +curl --request DELETE \ + --url http://{address}/api/v1/agents/{agent_id}/sessions \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data ' + { + "ids": ["test_1", "test_2"] + }' +``` + +##### Request Parameters + +- `agent_id`: (*Path parameter*) + The ID of the associated agent. +- `"ids"`: (*Body Parameter*), `list[string]` + The IDs of the sessions to delete. If it is not specified, all sessions associated with the specified agent will be deleted. + +#### Response + +Success: + +```json +{ + "code": 0 +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The agent doesn't own the session cbd31e52f73911ef93b232903b842af6" +} +``` + +--- + +### Generate related questions + +**POST** `/api/v1/sessions/related_questions` + +Generates five to ten alternative question strings from the user's original query to retrieve more relevant search results. + +This operation requires a `Bearer Login Token`, which typically expires with in 24 hours. You can find the it in the Request Headers in your browser easily as shown below: + +![Image](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/login_token.jpg) + +:::tip NOTE +The chat model autonomously determines the number of questions to generate based on the instruction, typically between five and ten. +::: + +#### Request + +- Method: POST +- URL: `/api/v1/sessions/related_questions` +- Headers: + - `'content-Type: application/json'` + - `'Authorization: Bearer '` +- Body: + - `"question"`: `string` + - `"industry"`: `string` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/sessions/related_questions \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data ' + { + "question": "What are the key advantages of Neovim over Vim?", + "industry": "software_development" + }' +``` + +##### Request Parameters + +- `"question"`: (*Body Parameter*), `string` + The original user question. +- `"industry"`: (*Body Parameter*), `string` + Industry of the question. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": [ + "What makes Neovim superior to Vim in terms of features?", + "How do the benefits of Neovim compare to those of Vim?", + "What advantages does Neovim offer that are not present in Vim?", + "In what ways does Neovim outperform Vim in functionality?", + "What are the most significant improvements in Neovim compared to Vim?", + "What unique advantages does Neovim bring to the table over Vim?", + "How does the user experience in Neovim differ from Vim in terms of benefits?", + "What are the top reasons to switch from Vim to Neovim?", + "What features of Neovim are considered more advanced than those in Vim?" + ], + "message": "success" +} +``` + +Failure: + +```json +{ + "code": 401, + "data": null, + "message": "" +} +``` + +--- + +## AGENT MANAGEMENT + +--- + +### List agents + +**GET** `/api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&name={agent_name}&id={agent_id}` + +Lists agents. + +#### Request + +- Method: GET +- URL: `/api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&title={agent_name}&id={agent_id}` +- Headers: + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request GET \ + --url http://{address}/api/v1/agents?page={page}&page_size={page_size}&orderby={orderby}&desc={desc}&title={agent_name}&id={agent_id} \ + --header 'Authorization: Bearer ' +``` + +##### Request parameters + +- `page`: (*Filter parameter*), `integer` + Specifies the page on which the agents will be displayed. Defaults to `1`. +- `page_size`: (*Filter parameter*), `integer` + The number of agents on each page. Defaults to `30`. +- `orderby`: (*Filter parameter*), `string` + The attribute by which the results are sorted. Available options: + - `create_time` (default) + - `update_time` +- `desc`: (*Filter parameter*), `boolean` + Indicates whether the retrieved agents should be sorted in descending order. Defaults to `true`. +- `id`: (*Filter parameter*), `string` + The ID of the agent to retrieve. +- `title`: (*Filter parameter*), `string` + The name of the agent to retrieve. + +#### Response + +Success: + +```json +{ + "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" + } + ] +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "The agent doesn't exist." +} +``` + +--- + +### Create agent + +**POST** `/api/v1/agents` + +Create an agent. + +#### Request + +- Method: POST +- URL: `/api/v1/agents` +- Headers: + - `'Content-Type: application/json` + - `'Authorization: Bearer '` +- Body: + - `"title"`: `string` + - `"description"`: `string` + - `"dsl"`: `object` + +##### Request example + +```bash +curl --request POST \ + --url http://{address}/api/v1/agents \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "title": "Test Agent", + "description": "A test agent", + "dsl": { + // ... Canvas DSL here ... + } + }' +``` + +##### Request parameters + +- `title`: (*Body parameter*), `string`, *Required* + The title of the agent. +- `description`: (*Body parameter*), `string` + The description of the agent. Defaults to `None`. +- `dsl`: (*Body parameter*), `object`, *Required* + The canvas DSL object of the agent. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": true, + "message": "success" +} +``` + +Failure: + +```json +{ + "code": 102, + "message": "Agent with title test already exists." +} +``` + +--- + +### Update agent + +**PUT** `/api/v1/agents/{agent_id}` + +Update an agent by id. + +#### Request + +- Method: PUT +- URL: `/api/v1/agents/{agent_id}` +- Headers: + - `'Content-Type: application/json` + - `'Authorization: Bearer '` +- Body: + - `"title"`: `string` + - `"description"`: `string` + - `"dsl"`: `object` + +##### Request example + +```bash +curl --request PUT \ + --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{ + "title": "Test Agent", + "description": "A test agent", + "dsl": { + // ... Canvas DSL here ... + } + }' +``` + +##### Request parameters + +- `agent_id`: (*Path parameter*), `string` + The id of the agent to be updated. +- `title`: (*Body parameter*), `string` + The title of the agent. +- `description`: (*Body parameter*), `string` + The description of the agent. +- `dsl`: (*Body parameter*), `object` + The canvas DSL object of the agent. + +Only specify the parameter you want to change in the request body. If a parameter does not exist or is `None`, it won't be updated. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": true, + "message": "success" +} +``` + +Failure: + +```json +{ + "code": 103, + "message": "Only owner of canvas authorized for this operation." +} +``` + +--- + +### Delete agent + +**DELETE** `/api/v1/agents/{agent_id}` + +Delete an agent by id. + +#### Request + +- Method: DELETE +- URL: `/api/v1/agents/{agent_id}` +- Headers: + - `'Content-Type: application/json` + - `'Authorization: Bearer '` + +##### Request example + +```bash +curl --request DELETE \ + --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Bearer ' \ + --data '{}' +``` + +##### Request parameters + +- `agent_id`: (*Path parameter*), `string` + The id of the agent to be deleted. + +#### Response + +Success: + +```json +{ + "code": 0, + "data": true, + "message": "success" +} +``` + +Failure: + +```json +{ + "code": 103, + "message": "Only owner of canvas authorized for this operation." +} +``` + +--- + +### System +--- +### Check system health + +**GET** `/v1/system/healthz` + +Check the health status of RAGFlow’s dependencies (database, Redis, document engine, object storage). + +#### Request + +- Method: GET +- URL: `/v1/system/healthz` +- Headers: + - 'Content-Type: application/json' + (no Authorization required) + +##### Request example + +```bash +curl --request GET + --url http://{address}/v1/system/healthz + --header 'Content-Type: application/json' +``` + +##### Request parameters + +- `address`: (*Path parameter*), string + The host and port of the backend service (e.g., `localhost:7897`). + +--- + +#### Responses + +- **200 OK** – All services healthy + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "db": "ok", + "redis": "ok", + "doc_engine": "ok", + "storage": "ok", + "status": "ok" +} +``` + +- **500 Internal Server Error** – At least one service unhealthy + +```http +HTTP/1.1 500 INTERNAL SERVER ERROR +Content-Type: application/json + +{ + "db": "ok", + "redis": "nok", + "doc_engine": "ok", + "storage": "ok", + "status": "nok", + "_meta": { + "redis": { + "elapsed": "5.2", + "error": "Lost connection!" + } + } +} +``` + +Explanation: +- Each service is reported as "ok" or "nok". +- The top-level `status` reflects overall health. +- If any service is "nok", detailed error info appears in `_meta`. diff --git a/website/versioned_docs/version-v0.21.1/references/python_api_reference.md b/website/versioned_docs/version-v0.21.1/references/python_api_reference.md new file mode 100644 index 0000000..6b8e154 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/references/python_api_reference.md @@ -0,0 +1,1962 @@ +--- +sidebar_position: 5 +slug: /python_api_reference +--- + +# Python API + +A complete reference for RAGFlow's Python APIs. Before proceeding, please ensure you [have your RAGFlow API key ready for authentication](https://ragflow.io/docs/dev/acquire_ragflow_api_key). + +:::tip NOTE +Run the following command to download the Python SDK: + +```bash +pip install ragflow-sdk +``` + +::: + +--- + +## ERROR CODES + +--- + +| Code | Message | Description | +|------|----------------------|-----------------------------| +| 400 | Bad Request | Invalid request parameters | +| 401 | Unauthorized | Unauthorized access | +| 403 | Forbidden | Access denied | +| 404 | Not Found | Resource not found | +| 500 | Internal Server Error| Server internal error | +| 1001 | Invalid Chunk ID | Invalid Chunk ID | +| 1002 | Chunk Update Failed | Chunk update failed | + +--- + +## OpenAI-Compatible API + +--- + +### Create chat completion + +Creates a model response for the given historical chat conversation via OpenAI's API. + +#### Parameters + +##### model: `str`, *Required* + +The model used to generate the response. The server will parse this automatically, so you can set it to any value for now. + +##### messages: `list[object]`, *Required* + +A list of historical chat messages used to generate the response. This must contain at least one message with the `user` role. + +##### stream: `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. + +#### Returns + +- Success: Response [message](https://platform.openai.com/docs/api-reference/chat/create) like OpenAI +- Failure: `Exception` + +#### Examples + +```python +from openai import OpenAI + +model = "model" +client = OpenAI(api_key="ragflow-api-key", base_url=f"http://ragflow_address/api/v1/chats_openai/") + +stream = True +reference = True + +completion = client.chat.completions.create( + model=model, + messages=[ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Who are you?"}, + {"role": "assistant", "content": "I am an AI assistant named..."}, + {"role": "user", "content": "Can you tell me how to install neovim"}, + ], + stream=stream, + extra_body={"reference": reference} +) + +if stream: + for chunk in completion: + print(chunk) + if reference and chunk.choices[0].finish_reason == "stop": + print(f"Reference:\n{chunk.choices[0].delta.reference}") + print(f"Final content:\n{chunk.choices[0].delta.final_content}") +else: + print(completion.choices[0].message.content) + if reference: + print(completion.choices[0].message.reference) +``` + +## DATASET MANAGEMENT + +--- + +### Create dataset + +```python +RAGFlow.create_dataset( + name: str, + avatar: Optional[str] = None, + description: Optional[str] = None, + embedding_model: Optional[str] = "BAAI/bge-large-zh-v1.5@BAAI", + permission: str = "me", + chunk_method: str = "naive", + parser_config: DataSet.ParserConfig = None +) -> DataSet +``` + +Creates a dataset. + +#### Parameters + +##### name: `str`, *Required* + +The unique name of the dataset to create. It must adhere to the following requirements: + +- Maximum 128 characters. +- Case-insensitive. + +##### avatar: `str` + +Base64 encoding of the avatar. Defaults to `None` + +##### description: `str` + +A brief description of the dataset to create. Defaults to `None`. + + +##### permission + +Specifies who can access the dataset to create. Available options: + +- `"me"`: (Default) Only you can manage the dataset. +- `"team"`: All team members can manage the dataset. + +##### chunk_method, `str` + +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 +- `"email"`: Email + +##### parser_config + +The parser configuration of the dataset. A `ParserConfig` object's attributes vary based on the selected `chunk_method`: + +- `chunk_method`=`"naive"`: + `{"chunk_token_num":512,"delimiter":"\\n","html4excel":False,"layout_recognize":True,"raptor":{"use_raptor":False}}`. +- `chunk_method`=`"qa"`: + `{"raptor": {"use_raptor": False}}` +- `chunk_method`=`"manuel"`: + `{"raptor": {"use_raptor": False}}` +- `chunk_method`=`"table"`: + `None` +- `chunk_method`=`"paper"`: + `{"raptor": {"use_raptor": False}}` +- `chunk_method`=`"book"`: + `{"raptor": {"use_raptor": False}}` +- `chunk_method`=`"laws"`: + `{"raptor": {"use_raptor": False}}` +- `chunk_method`=`"picture"`: + `None` +- `chunk_method`=`"presentation"`: + `{"raptor": {"use_raptor": False}}` +- `chunk_method`=`"one"`: + `None` +- `chunk_method`=`"knowledge-graph"`: + `{"chunk_token_num":128,"delimiter":"\\n","entity_types":["organization","person","location","event","time"]}` +- `chunk_method`=`"email"`: + `None` + +#### Returns + +- Success: A `dataset` object. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.create_dataset(name="kb_1") +``` + +--- + +### Delete datasets + +```python +RAGFlow.delete_datasets(ids: list[str] | None = None) +``` + +Deletes datasets by ID. + +#### Parameters + +##### ids: `list[str]` or `None`, *Required* + +The IDs of the datasets to delete. Defaults to `None`. + - If `None`, all datasets will be deleted. + - If an array of IDs, only the specified datasets will be deleted. + - If an empty array, no datasets will be deleted. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +rag_object.delete_datasets(ids=["d94a8dc02c9711f0930f7fbc369eab6d","e94a8dc02c9711f0930f7fbc369eab6e"]) +``` + +--- + +### List datasets + +```python +RAGFlow.list_datasets( + page: int = 1, + page_size: int = 30, + orderby: str = "create_time", + desc: bool = True, + id: str = None, + name: str = None +) -> list[DataSet] +``` + +Lists datasets. + +#### Parameters + +##### page: `int` + +Specifies the page on which the datasets will be displayed. Defaults to `1`. + +##### page_size: `int` + +The number of datasets on each page. Defaults to `30`. + +##### orderby: `str` + +The field by which datasets should be sorted. Available options: + +- `"create_time"` (default) +- `"update_time"` + +##### desc: `bool` + +Indicates whether the retrieved datasets should be sorted in descending order. Defaults to `True`. + +##### id: `str` + +The ID of the dataset to retrieve. Defaults to `None`. + +##### name: `str` + +The name of the dataset to retrieve. Defaults to `None`. + +#### Returns + +- Success: A list of `DataSet` objects. +- Failure: `Exception`. + +#### Examples + +##### List all datasets + +```python +for dataset in rag_object.list_datasets(): + print(dataset) +``` + +##### Retrieve a dataset by ID + +```python +dataset = rag_object.list_datasets(id = "id_1") +print(dataset[0]) +``` + +--- + +### Update dataset + +```python +DataSet.update(update_message: dict) +``` + +Updates configurations for the current dataset. + +#### Parameters + +##### update_message: `dict[str, str|int]`, *Required* + +A dictionary representing the attributes to update, with the following keys: + +- `"name"`: `str` The revised name of the dataset. + - Basic Multilingual Plane (BMP) only + - Maximum 128 characters + - Case-insensitive +- `"avatar"`: (*Body parameter*), `string` + The updated base64 encoding of the avatar. + - Maximum 65535 characters +- `"embedding_model"`: (*Body parameter*), `string` + The updated embedding model name. + - Ensure that `"chunk_count"` is `0` before updating `"embedding_model"`. + - Maximum 255 characters + - Must follow `model_name@model_factory` format +- `"permission"`: (*Body parameter*), `string` + The updated dataset permission. Available options: + - `"me"`: (Default) Only you can manage the dataset. + - `"team"`: All team members can manage the dataset. +- `"pagerank"`: (*Body parameter*), `int` + refer to [Set page rank](https://ragflow.io/docs/dev/set_page_rank) + - Default: `0` + - Minimum: `0` + - Maximum: `100` +- `"chunk_method"`: (*Body parameter*), `enum` + The chunking method for the dataset. Available options: + - `"naive"`: General (default) + - `"book"`: Book + - `"email"`: Email + - `"laws"`: Laws + - `"manual"`: Manual + - `"one"`: One + - `"paper"`: Paper + - `"picture"`: Picture + - `"presentation"`: Presentation + - `"qa"`: Q&A + - `"table"`: Table + - `"tag"`: Tag + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets(name="kb_name") +dataset = dataset[0] +dataset.update({"embedding_model":"BAAI/bge-zh-v1.5", "chunk_method":"manual"}) +``` + +--- + +## FILE MANAGEMENT WITHIN DATASET + +--- + +### Upload documents + +```python +DataSet.upload_documents(document_list: list[dict]) +``` + +Uploads documents to the current dataset. + +#### Parameters + +##### document_list: `list[dict]`, *Required* + +A list of dictionaries representing the documents to upload, each containing the following keys: + +- `"display_name"`: (Optional) The file name to display in the dataset. +- `"blob"`: (Optional) The binary content of the file to upload. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +dataset = rag_object.create_dataset(name="kb_name") +dataset.upload_documents([{"display_name": "1.txt", "blob": ""}, {"display_name": "2.pdf", "blob": ""}]) +``` + +--- + +### Update document + +```python +Document.update(update_message:dict) +``` + +Updates configurations for the current document. + +#### Parameters + +##### update_message: `dict[str, str|dict[]]`, *Required* + +A dictionary representing the attributes to update, with the following keys: + +- `"display_name"`: `str` The name of the document to update. +- `"meta_fields"`: `dict[str, Any]` The meta fields of the document. +- `"chunk_method"`: `str` The parsing method to apply to the document. + - `"naive"`: General + - `"manual`: Manual + - `"qa"`: Q&A + - `"table"`: Table + - `"paper"`: Paper + - `"book"`: Book + - `"laws"`: Laws + - `"presentation"`: Presentation + - `"picture"`: Picture + - `"one"`: One + - `"email"`: Email +- `"parser_config"`: `dict[str, Any]` The parsing configuration for the document. Its attributes vary based on the selected `"chunk_method"`: + - `"chunk_method"`=`"naive"`: + `{"chunk_token_num":128,"delimiter":"\\n","html4excel":False,"layout_recognize":True,"raptor":{"use_raptor":False}}`. + - `chunk_method`=`"qa"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"manuel"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"table"`: + `None` + - `chunk_method`=`"paper"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"book"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"laws"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"presentation"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"picture"`: + `None` + - `chunk_method`=`"one"`: + `None` + - `chunk_method`=`"knowledge-graph"`: + `{"chunk_token_num":128,"delimiter":"\\n","entity_types":["organization","person","location","event","time"]}` + - `chunk_method`=`"email"`: + `None` + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets(id='id') +dataset = dataset[0] +doc = dataset.list_documents(id="wdfxb5t547d") +doc = doc[0] +doc.update([{"parser_config": {"chunk_token_num": 256}}, {"chunk_method": "manual"}]) +``` + +--- + +### Download document + +```python +Document.download() -> bytes +``` + +Downloads the current document. + +#### Returns + +The downloaded document in bytes. + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets(id="id") +dataset = dataset[0] +doc = dataset.list_documents(id="wdfxb5t547d") +doc = doc[0] +open("~/ragflow.txt", "wb+").write(doc.download()) +print(doc) +``` + +--- + +### List documents + +```python +Dataset.list_documents( + id: str = None, + keywords: str = None, + page: int = 1, + page_size: int = 30, + order_by: str = "create_time", + desc: bool = True, + create_time_from: int = 0, + create_time_to: int = 0 +) -> list[Document] +``` + +Lists documents in the current dataset. + +#### Parameters + +##### id: `str` + +The ID of the document to retrieve. Defaults to `None`. + +##### keywords: `str` + +The keywords used to match document titles. Defaults to `None`. + +##### page: `int` + +Specifies the page on which the documents will be displayed. Defaults to `1`. + +##### page_size: `int` + +The maximum number of documents on each page. Defaults to `30`. + +##### orderby: `str` + +The field by which documents should be sorted. Available options: + +- `"create_time"` (default) +- `"update_time"` + +##### desc: `bool` + +Indicates whether the retrieved documents should be sorted in descending order. Defaults to `True`. + +##### create_time_from: `int` +Unix timestamp for filtering documents created after this time. 0 means no filter. Defaults to 0. + +##### create_time_to: `int` +Unix timestamp for filtering documents created before this time. 0 means no filter. Defaults to 0. + +#### Returns + +- Success: A list of `Document` objects. +- Failure: `Exception`. + +A `Document` object contains the following attributes: + +- `id`: The document ID. Defaults to `""`. +- `name`: The document name. Defaults to `""`. +- `thumbnail`: The thumbnail image of the document. Defaults to `None`. +- `dataset_id`: The dataset ID associated with the document. Defaults to `None`. +- `chunk_method` The chunking method name. Defaults to `"naive"`. +- `source_type`: The source type of the document. Defaults to `"local"`. +- `type`: Type or category of the document. Defaults to `""`. Reserved for future use. +- `created_by`: `str` The creator of the document. Defaults to `""`. +- `size`: `int` The document size in bytes. Defaults to `0`. +- `token_count`: `int` The number of tokens in the document. Defaults to `0`. +- `chunk_count`: `int` The number of chunks in the document. Defaults to `0`. +- `progress`: `float` The current processing progress as a percentage. Defaults to `0.0`. +- `progress_msg`: `str` A message indicating the current progress status. Defaults to `""`. +- `process_begin_at`: `datetime` The start time of document processing. Defaults to `None`. +- `process_duration`: `float` Duration of the processing in seconds. Defaults to `0.0`. +- `run`: `str` The document's processing status: + - `"UNSTART"` (default) + - `"RUNNING"` + - `"CANCEL"` + - `"DONE"` + - `"FAIL"` +- `status`: `str` Reserved for future use. +- `parser_config`: `ParserConfig` Configuration object for the parser. Its attributes vary based on the selected `chunk_method`: + - `chunk_method`=`"naive"`: + `{"chunk_token_num":128,"delimiter":"\\n","html4excel":False,"layout_recognize":True,"raptor":{"use_raptor":False}}`. + - `chunk_method`=`"qa"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"manuel"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"table"`: + `None` + - `chunk_method`=`"paper"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"book"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"laws"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"presentation"`: + `{"raptor": {"use_raptor": False}}` + - `chunk_method`=`"picure"`: + `None` + - `chunk_method`=`"one"`: + `None` + - `chunk_method`=`"email"`: + `None` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.create_dataset(name="kb_1") + +filename1 = "~/ragflow.txt" +blob = open(filename1 , "rb").read() +dataset.upload_documents([{"name":filename1,"blob":blob}]) +for doc in dataset.list_documents(keywords="rag", page=0, page_size=12): + print(doc) +``` + +--- + +### Delete documents + +```python +DataSet.delete_documents(ids: list[str] = None) +``` + +Deletes documents by ID. + +#### Parameters + +##### ids: `list[list]` + +The IDs of the documents to delete. Defaults to `None`. If it is not specified, all documents in the dataset will be deleted. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets(name="kb_1") +dataset = dataset[0] +dataset.delete_documents(ids=["id_1","id_2"]) +``` + +--- + +### Parse documents + +```python +DataSet.async_parse_documents(document_ids:list[str]) -> None +``` + +Parses documents in the current dataset. + +#### Parameters + +##### document_ids: `list[str]`, *Required* + +The IDs of the documents to parse. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.create_dataset(name="dataset_name") +documents = [ + {'display_name': 'test1.txt', 'blob': open('./test_data/test1.txt',"rb").read()}, + {'display_name': 'test2.txt', 'blob': open('./test_data/test2.txt',"rb").read()}, + {'display_name': 'test3.txt', 'blob': open('./test_data/test3.txt',"rb").read()} +] +dataset.upload_documents(documents) +documents = dataset.list_documents(keywords="test") +ids = [] +for document in documents: + ids.append(document.id) +dataset.async_parse_documents(ids) +print("Async bulk parsing initiated.") +``` + +--- + +### Parse documents (with document status) + +```python +DataSet.parse_documents(document_ids: list[str]) -> list[tuple[str, str, int, int]] +``` + +*Asynchronously* parses documents in the current dataset. + +This method encapsulates `async_parse_documents()`. It awaits the completion of all parsing tasks before returning detailed results, including the parsing status and statistics for each document. If a keyboard interruption occurs (e.g., `Ctrl+C`), all pending parsing tasks will be cancelled gracefully. + +#### Parameters + +##### document_ids: `list[str]`, *Required* + +The IDs of the documents to parse. + +#### Returns + +A list of tuples with detailed parsing results: + +```python +[ + (document_id: str, status: str, chunk_count: int, token_count: int), + ... +] +``` +- `status`: The final parsing state (e.g., `success`, `failed`, `cancelled`). +- `chunk_count`: The number of content chunks created from the document. +- `token_count`: The total number of tokens processed. + +--- + +#### Example + +```python +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.create_dataset(name="dataset_name") +documents = dataset.list_documents(keywords="test") +ids = [doc.id for doc in documents] + +try: + finished = dataset.parse_documents(ids) + for doc_id, status, chunk_count, token_count in finished: + print(f"Document {doc_id} parsing finished with status: {status}, chunks: {chunk_count}, tokens: {token_count}") +except KeyboardInterrupt: + print("\nParsing interrupted by user. All pending tasks have been cancelled.") +except Exception as e: + print(f"Parsing failed: {e}") +``` + +--- + +### Stop parsing documents + +```python +DataSet.async_cancel_parse_documents(document_ids:list[str])-> None +``` + +Stops parsing specified documents. + +#### Parameters + +##### document_ids: `list[str]`, *Required* + +The IDs of the documents for which parsing should be stopped. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.create_dataset(name="dataset_name") +documents = [ + {'display_name': 'test1.txt', 'blob': open('./test_data/test1.txt',"rb").read()}, + {'display_name': 'test2.txt', 'blob': open('./test_data/test2.txt',"rb").read()}, + {'display_name': 'test3.txt', 'blob': open('./test_data/test3.txt',"rb").read()} +] +dataset.upload_documents(documents) +documents = dataset.list_documents(keywords="test") +ids = [] +for document in documents: + ids.append(document.id) +dataset.async_parse_documents(ids) +print("Async bulk parsing initiated.") +dataset.async_cancel_parse_documents(ids) +print("Async bulk parsing cancelled.") +``` + +--- + +## CHUNK MANAGEMENT WITHIN DATASET + +--- + +### Add chunk + +```python +Document.add_chunk(content:str, important_keywords:list[str] = []) -> Chunk +``` + +Adds a chunk to the current document. + +#### Parameters + +##### content: `str`, *Required* + +The text content of the chunk. + +##### important_keywords: `list[str]` + +The key terms or phrases to tag with the chunk. + +#### Returns + +- Success: A `Chunk` object. +- Failure: `Exception`. + +A `Chunk` object contains the following attributes: + +- `id`: `str`: The chunk ID. +- `content`: `str` The text content of 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_timestamp`: `float` The timestamp representing the creation time of the chunk, expressed in seconds since January 1, 1970. +- `dataset_id`: `str` The ID of the associated dataset. +- `document_name`: `str` The name 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: + - `False`: Unavailable + - `True`: Available (default) + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +datasets = rag_object.list_datasets(id="123") +dataset = datasets[0] +doc = dataset.list_documents(id="wdfxb5t547d") +doc = doc[0] +chunk = doc.add_chunk(content="xxxxxxx") +``` + +--- + +### List chunks + +```python +Document.list_chunks(keywords: str = None, page: int = 1, page_size: int = 30, id : str = None) -> list[Chunk] +``` + +Lists chunks in the current document. + +#### Parameters + +##### keywords: `str` + +The keywords used to match chunk content. Defaults to `None` + +##### page: `int` + +Specifies the page on which the chunks will be displayed. Defaults to `1`. + +##### page_size: `int` + +The maximum number of chunks on each page. Defaults to `30`. + +##### id: `str` + +The ID of the chunk to retrieve. Default: `None` + +#### Returns + +- Success: A list of `Chunk` objects. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets("123") +dataset = dataset[0] +docs = dataset.list_documents(keywords="test", page=1, page_size=12) +for chunk in docs[0].list_chunks(keywords="rag", page=0, page_size=12): + print(chunk) +``` + +--- + +### Delete chunks + +```python +Document.delete_chunks(chunk_ids: list[str]) +``` + +Deletes chunks by ID. + +#### Parameters + +##### chunk_ids: `list[str]` + +The IDs of the chunks to delete. Defaults to `None`. If it is not specified, all chunks of the current document will be deleted. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets(id="123") +dataset = dataset[0] +doc = dataset.list_documents(id="wdfxb5t547d") +doc = doc[0] +chunk = doc.add_chunk(content="xxxxxxx") +doc.delete_chunks(["id_1","id_2"]) +``` + +--- + +### Update chunk + +```python +Chunk.update(update_message: dict) +``` + +Updates content or configurations for the current chunk. + +#### Parameters + +##### update_message: `dict[str, str|list[str]|int]` *Required* + +A dictionary representing the attributes to update, with the following keys: + +- `"content"`: `str` The text content of the chunk. +- `"important_keywords"`: `list[str]` A list of key terms or phrases to tag with the chunk. +- `"available"`: `bool` The chunk's availability status in the dataset. Value options: + - `False`: Unavailable + - `True`: Available (default) + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets(id="123") +dataset = dataset[0] +doc = dataset.list_documents(id="wdfxb5t547d") +doc = doc[0] +chunk = doc.add_chunk(content="xxxxxxx") +chunk.update({"content":"sdfx..."}) +``` + +--- + +### Retrieve chunks + +```python +RAGFlow.retrieve(question:str="", dataset_ids:list[str]=None, document_ids=list[str]=None, page:int=1, page_size:int=30, similarity_threshold:float=0.2, vector_similarity_weight:float=0.3, top_k:int=1024,rerank_id:str=None,keyword:bool=False,cross_languages:list[str]=None,metadata_condition: dict=None) -> list[Chunk] +``` + +Retrieves chunks from specified datasets. + +#### Parameters + +##### question: `str`, *Required* + +The user query or query keywords. Defaults to `""`. + +##### dataset_ids: `list[str]`, *Required* + +The IDs of the datasets to search. Defaults to `None`. + +##### document_ids: `list[str]` + +The IDs of the documents to search. Defaults to `None`. You must ensure all selected documents use the same embedding model. Otherwise, an error will occur. + +##### page: `int` + +The starting index for the documents to retrieve. Defaults to `1`. + +##### page_size: `int` + +The maximum number of chunks to retrieve. Defaults to `30`. + +##### Similarity_threshold: `float` + +The minimum similarity score. Defaults to `0.2`. + +##### vector_similarity_weight: `float` + +The weight of vector cosine similarity. Defaults to `0.3`. If x represents the vector cosine similarity, then (1 - x) is the term similarity weight. + +##### top_k: `int` + +The number of chunks engaged in vector cosine computation. Defaults to `1024`. + +##### rerank_id: `str` + +The ID of the rerank model. Defaults to `None`. + +##### keyword: `bool` + +Indicates whether to enable keyword-based matching: + +- `True`: Enable keyword-based matching. +- `False`: Disable keyword-based matching (default). + +##### cross_languages: `list[string]` + +The languages that should be translated into, in order to achieve keywords retrievals in different languages. + +##### metadata_condition: `dict` + +filter condition for `meta_fields`. + +#### Returns + +- Success: A list of `Chunk` objects representing the document chunks. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +dataset = rag_object.list_datasets(name="ragflow") +dataset = dataset[0] +name = 'ragflow_test.txt' +path = './test_data/ragflow_test.txt' +documents =[{"display_name":"test_retrieve_chunks.txt","blob":open(path, "rb").read()}] +docs = dataset.upload_documents(documents) +doc = docs[0] +doc.add_chunk(content="This is a chunk addition test") +for c in rag_object.retrieve(dataset_ids=[dataset.id],document_ids=[doc.id]): + print(c) +``` + +--- + +## CHAT ASSISTANT MANAGEMENT + +--- + +### Create chat assistant + +```python +RAGFlow.create_chat( + name: str, + avatar: str = "", + dataset_ids: list[str] = [], + llm: Chat.LLM = None, + prompt: Chat.Prompt = None +) -> Chat +``` + +Creates a chat assistant. + +#### Parameters + +##### name: `str`, *Required* + +The name of the chat assistant. + +##### avatar: `str` + +Base64 encoding of the avatar. Defaults to `""`. + +##### dataset_ids: `list[str]` + +The IDs of the associated datasets. Defaults to `[""]`. + +##### llm: `Chat.LLM` + +The LLM settings for the chat assistant to create. Defaults to `None`. When the value is `None`, a dictionary with the following values will be generated as the default. An `LLM` object contains the following attributes: + +- `model_name`: `str` + The chat model name. If it is `None`, 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`. + +##### prompt: `Chat.Prompt` + +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 reranking score during retrieval. 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`: `list[dict[]]` 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`: `str` If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used. Defaults to `""`. +- `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`: `str` 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. Defaults to `None`. +- `opener`: `str` The opening greeting for the user. Defaults to `"Hi! I am your assistant, can I help you?"`. +- `show_quote`: `bool` Indicates whether the source of text should be displayed. Defaults to `True`. +- `prompt`: `str` The prompt content. + +#### Returns + +- Success: A `Chat` object representing the chat assistant. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +datasets = rag_object.list_datasets(name="kb_1") +dataset_ids = [] +for dataset in datasets: + dataset_ids.append(dataset.id) +assistant = rag_object.create_chat("Miss R", dataset_ids=dataset_ids) +``` + +--- + +### Update chat assistant + +```python +Chat.update(update_message: dict) +``` + +Updates configurations for the current chat assistant. + +#### Parameters + +##### update_message: `dict[str, str|list[str]|dict[]]`, *Required* + +A dictionary representing the attributes to update, with the following keys: + +- `"name"`: `str` The revised name of the chat assistant. +- `"avatar"`: `str` Base64 encoding of the avatar. Defaults to `""` +- `"dataset_ids"`: `list[str]` The datasets to update. +- `"llm"`: `dict` The LLM settings: + - `"model_name"`, `str` The chat model name. + - `"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. + - `"top_p"`, `float` Also known as “nucleus sampling”, this parameter sets a threshold to select a smaller set of words to sample from. + - `"presence_penalty"`, `float` This discourages the model from repeating the same information by penalizing words that have appeared in the conversation. + - `"frequency penalty"`, `float` Similar to presence penalty, this reduces the model’s tendency to repeat the same words. +- `"prompt"` : Instructions for the LLM to follow. + - `"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"`: `list[dict[]]` 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"`: `str` If it is not specified, vector cosine similarity will be used; otherwise, reranking score will be used. Defaults to `""`. + - `"empty_response"`: `str` 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 retrieved, leave this blank. Defaults to `None`. + - `"opener"`: `str` The opening greeting for the user. Defaults to `"Hi! I am your assistant, can I help you?"`. + - `"show_quote`: `bool` Indicates whether the source of text should be displayed Defaults to `True`. + - `"prompt"`: `str` The prompt content. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +datasets = rag_object.list_datasets(name="kb_1") +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}}) +``` + +--- + +### Delete chat assistants + +```python +RAGFlow.delete_chats(ids: list[str] = None) +``` + +Deletes chat assistants by ID. + +#### Parameters + +##### ids: `list[str]` + +The IDs of the chat assistants to delete. Defaults to `None`. If it is empty or not specified, all chat assistants in the system will be deleted. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +rag_object.delete_chats(ids=["id_1","id_2"]) +``` + +--- + +### List chat assistants + +```python +RAGFlow.list_chats( + page: int = 1, + page_size: int = 30, + orderby: str = "create_time", + desc: bool = True, + id: str = None, + name: str = None +) -> list[Chat] +``` + +Lists chat assistants. + +#### Parameters + +##### page: `int` + +Specifies the page on which the chat assistants will be displayed. Defaults to `1`. + +##### page_size: `int` + +The number of chat assistants on each page. Defaults to `30`. + +##### orderby: `str` + +The attribute by which the results are sorted. Available options: + +- `"create_time"` (default) +- `"update_time"` + +##### desc: `bool` + +Indicates whether the retrieved chat assistants should be sorted in descending order. Defaults to `True`. + +##### id: `str` + +The ID of the chat assistant to retrieve. Defaults to `None`. + +##### name: `str` + +The name of the chat assistant to retrieve. Defaults to `None`. + +#### Returns + +- Success: A list of `Chat` objects. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +for assistant in rag_object.list_chats(): + print(assistant) +``` + +--- + +## SESSION MANAGEMENT + +--- + +### Create session with chat assistant + +```python +Chat.create_session(name: str = "New session") -> Session +``` + +Creates a session with the current chat assistant. + +#### Parameters + +##### name: `str` + +The name of the chat session to create. + +#### Returns + +- Success: A `Session` object containing the following attributes: + - `id`: `str` The auto-generated unique identifier of the created session. + - `name`: `str` The name of the created session. + - `message`: `list[Message]` The opening message of the created session. Default: `[{"role": "assistant", "content": "Hi! I am your assistant, can I help you?"}]` + - `chat_id`: `str` The ID of the associated chat assistant. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +assistant = rag_object.list_chats(name="Miss R") +assistant = assistant[0] +session = assistant.create_session() +``` + +--- + +### Update chat assistant's session + +```python +Session.update(update_message: dict) +``` + +Updates the current session of the current chat assistant. + +#### Parameters + +##### update_message: `dict[str, Any]`, *Required* + +A dictionary representing the attributes to update, with only one key: + +- `"name"`: `str` The revised name of the session. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +assistant = rag_object.list_chats(name="Miss R") +assistant = assistant[0] +session = assistant.create_session("session_name") +session.update({"name": "updated_name"}) +``` + +--- + +### List chat assistant's sessions + +```python +Chat.list_sessions( + page: int = 1, + page_size: int = 30, + orderby: str = "create_time", + desc: bool = True, + id: str = None, + name: str = None +) -> list[Session] +``` + +Lists sessions associated with the current chat assistant. + +#### Parameters + +##### page: `int` + +Specifies the page on which the sessions will be displayed. Defaults to `1`. + +##### page_size: `int` + +The number of sessions on each page. Defaults to `30`. + +##### orderby: `str` + +The field by which sessions should be sorted. Available options: + +- `"create_time"` (default) +- `"update_time"` + +##### desc: `bool` + +Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `True`. + +##### id: `str` + +The ID of the chat session to retrieve. Defaults to `None`. + +##### name: `str` + +The name of the chat session to retrieve. Defaults to `None`. + +#### Returns + +- Success: A list of `Session` objects associated with the current chat assistant. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +assistant = rag_object.list_chats(name="Miss R") +assistant = assistant[0] +for session in assistant.list_sessions(): + print(session) +``` + +--- + +### Delete chat assistant's sessions + +```python +Chat.delete_sessions(ids:list[str] = None) +``` + +Deletes sessions of the current chat assistant by ID. + +#### Parameters + +##### ids: `list[str]` + +The IDs of the sessions to delete. Defaults to `None`. If it is not specified, all sessions associated with the current chat assistant will be deleted. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +assistant = rag_object.list_chats(name="Miss R") +assistant = assistant[0] +assistant.delete_sessions(ids=["id_1","id_2"]) +``` + +--- + +### Converse with chat assistant + +```python +Session.ask(question: str = "", stream: bool = False, **kwargs) -> Optional[Message, iter[Message]] +``` + +Asks a specified chat assistant a question to start an AI-powered conversation. + +:::tip NOTE +In streaming mode, not all responses include a reference, as this depends on the system's judgement. +::: + +#### Parameters + +##### question: `str`, *Required* + +The question to start an AI-powered conversation. Default to `""` + +##### stream: `bool` + +Indicates whether to output responses in a streaming way: + +- `True`: Enable streaming (default). +- `False`: Disable streaming. + +##### **kwargs + +The parameters in prompt(system). + +#### Returns + +- A `Message` object containing the response to the question if `stream` is set to `False`. +- An iterator containing multiple `message` objects (`iter[Message]`) if `stream` is set to `True` + +The following shows the attributes of a `Message` object: + +##### id: `str` + +The auto-generated message ID. + +##### content: `str` + +The content of the message. Defaults to `"Hi! I am your assistant, can I help you?"`. + +##### reference: `list[Chunk]` + +A list of `Chunk` objects representing references to the message, each containing the following attributes: + +- `id` `str` + The chunk ID. +- `content` `str` + The content of the chunk. +- `img_id` `str` + The ID of the snapshot of the chunk. Applicable only when the source of the chunk is an image, PPT, PPTX, or PDF file. +- `document_id` `str` + The ID of the referenced document. +- `document_name` `str` + The name of the referenced document. +- `position` `list[str]` + The location information of the chunk within the referenced document. +- `dataset_id` `str` + The ID of the dataset to which the referenced document belongs. +- `similarity` `float` + A composite similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity. It is the weighted sum of `vector_similarity` and `term_similarity`. +- `vector_similarity` `float` + A vector similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity between vector embeddings. +- `term_similarity` `float` + A keyword similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity between keywords. + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +assistant = rag_object.list_chats(name="Miss R") +assistant = assistant[0] +session = assistant.create_session() + +print("\n==================== Miss R =====================\n") +print("Hello. What can I do for you?") + +while True: + question = input("\n==================== User =====================\n> ") + print("\n==================== Miss R =====================\n") + + cont = "" + for ans in session.ask(question, stream=True): + print(ans.content[len(cont):], end='', flush=True) + cont = ans.content +``` + +--- + +### Create session with agent + +```python +Agent.create_session(**kwargs) -> Session +``` + +Creates a session with the current agent. + +#### Parameters + +##### **kwargs + +The parameters in `begin` component. + +#### Returns + +- Success: A `Session` object containing the following attributes: + - `id`: `str` The auto-generated unique identifier of the created session. + - `message`: `list[Message]` The messages of the created session assistant. Default: `[{"role": "assistant", "content": "Hi! I am your assistant, can I help you?"}]` + - `agent_id`: `str` The ID of the associated agent. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow, Agent + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +agent_id = "AGENT_ID" +agent = rag_object.list_agents(id = agent_id)[0] +session = agent.create_session() +``` + +--- + +### Converse with agent + +```python +Session.ask(question: str="", stream: bool = False) -> Optional[Message, iter[Message]] +``` + +Asks a specified agent a question to start an AI-powered conversation. + +:::tip NOTE +In streaming mode, not all responses include a reference, as this depends on the system's judgement. +::: + +#### Parameters + +##### question: `str` + +The question to start an AI-powered conversation. Ifthe **Begin** component takes parameters, a question is not required. + +##### stream: `bool` + +Indicates whether to output responses in a streaming way: + +- `True`: Enable streaming (default). +- `False`: Disable streaming. + +#### Returns + +- A `Message` object containing the response to the question if `stream` is set to `False` +- An iterator containing multiple `message` objects (`iter[Message]`) if `stream` is set to `True` + +The following shows the attributes of a `Message` object: + +##### id: `str` + +The auto-generated message ID. + +##### content: `str` + +The content of the message. Defaults to `"Hi! I am your assistant, can I help you?"`. + +##### reference: `list[Chunk]` + +A list of `Chunk` objects representing references to the message, each containing the following attributes: + +- `id` `str` + The chunk ID. +- `content` `str` + The content of the chunk. +- `image_id` `str` + The ID of the snapshot of the chunk. Applicable only when the source of the chunk is an image, PPT, PPTX, or PDF file. +- `document_id` `str` + The ID of the referenced document. +- `document_name` `str` + The name of the referenced document. +- `position` `list[str]` + The location information of the chunk within the referenced document. +- `dataset_id` `str` + The ID of the dataset to which the referenced document belongs. +- `similarity` `float` + A composite similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity. It is the weighted sum of `vector_similarity` and `term_similarity`. +- `vector_similarity` `float` + A vector similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity between vector embeddings. +- `term_similarity` `float` + A keyword similarity score of the chunk ranging from `0` to `1`, with a higher value indicating greater similarity between keywords. + +#### Examples + +```python +from ragflow_sdk import RAGFlow, Agent + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +AGENT_id = "AGENT_ID" +agent = rag_object.list_agents(id = AGENT_id)[0] +session = agent.create_session() + +print("\n===== Miss R ====\n") +print("Hello. What can I do for you?") + +while True: + question = input("\n===== User ====\n> ") + print("\n==== Miss R ====\n") + + cont = "" + for ans in session.ask(question, stream=True): + print(ans.content[len(cont):], end='', flush=True) + cont = ans.content +``` + +--- + +### List agent sessions + +```python +Agent.list_sessions( + page: int = 1, + page_size: int = 30, + orderby: str = "update_time", + desc: bool = True, + id: str = None +) -> List[Session] +``` + +Lists sessions associated with the current agent. + +#### Parameters + +##### page: `int` + +Specifies the page on which the sessions will be displayed. Defaults to `1`. + +##### page_size: `int` + +The number of sessions on each page. Defaults to `30`. + +##### orderby: `str` + +The field by which sessions should be sorted. Available options: + +- `"create_time"` +- `"update_time"`(default) + +##### desc: `bool` + +Indicates whether the retrieved sessions should be sorted in descending order. Defaults to `True`. + +##### id: `str` + +The ID of the agent session to retrieve. Defaults to `None`. + +#### Returns + +- Success: A list of `Session` objects associated with the current agent. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +AGENT_id = "AGENT_ID" +agent = rag_object.list_agents(id = AGENT_id)[0] +sessons = agent.list_sessions() +for session in sessions: + print(session) +``` +--- +### Delete agent's sessions + +```python +Agent.delete_sessions(ids: list[str] = None) +``` + +Deletes sessions of a agent by ID. + +#### Parameters + +##### ids: `list[str]` + +The IDs of the sessions to delete. Defaults to `None`. If it is not specified, all sessions associated with the agent will be deleted. + +#### Returns + +- Success: No value is returned. +- Failure: `Exception` + +#### Examples + +```python +from ragflow_sdk import RAGFlow + +rag_object = RAGFlow(api_key="", base_url="http://:9380") +AGENT_id = "AGENT_ID" +agent = rag_object.list_agents(id = AGENT_id)[0] +agent.delete_sessions(ids=["id_1","id_2"]) +``` + +--- + +## AGENT MANAGEMENT + +--- + +### List agents + +```python +RAGFlow.list_agents( + page: int = 1, + page_size: int = 30, + orderby: str = "create_time", + desc: bool = True, + id: str = None, + title: str = None +) -> List[Agent] +``` + +Lists agents. + +#### Parameters + +##### page: `int` + +Specifies the page on which the agents will be displayed. Defaults to `1`. + +##### page_size: `int` + +The number of agents on each page. Defaults to `30`. + +##### orderby: `str` + +The attribute by which the results are sorted. Available options: + +- `"create_time"` (default) +- `"update_time"` + +##### desc: `bool` + +Indicates whether the retrieved agents should be sorted in descending order. Defaults to `True`. + +##### id: `str` + +The ID of the agent to retrieve. Defaults to `None`. + +##### name: `str` + +The name of the agent to retrieve. Defaults to `None`. + +#### Returns + +- Success: A list of `Agent` objects. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow +rag_object = RAGFlow(api_key="", base_url="http://:9380") +for agent in rag_object.list_agents(): + print(agent) +``` + +--- + +### Create agent + +```python +RAGFlow.create_agent( + title: str, + dsl: dict, + description: str | None = None +) -> None +``` + +Create an agent. + +#### Parameters + +##### title: `str` + +Specifies the title of the agent. + +##### dsl: `dict` + +Specifies the canvas DSL of the agent. + +##### description: `str` + +The description of the agent. Defaults to `None`. + +#### Returns + +- Success: Nothing. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow +rag_object = RAGFlow(api_key="", base_url="http://:9380") +rag_object.create_agent( + title="Test Agent", + description="A test agent", + dsl={ + # ... canvas DSL here ... + } +) +``` + +--- + +### Update agent + +```python +RAGFlow.update_agent( + agent_id: str, + title: str | None = None, + description: str | None = None, + dsl: dict | None = None +) -> None +``` + +Update an agent. + +#### Parameters + +##### agent_id: `str` + +Specifies the id of the agent to be updated. + +##### title: `str` + +Specifies the new title of the agent. `None` if you do not want to update this. + +##### dsl: `dict` + +Specifies the new canvas DSL of the agent. `None` if you do not want to update this. + +##### description: `str` + +The new description of the agent. `None` if you do not want to update this. + +#### Returns + +- Success: Nothing. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow +rag_object = RAGFlow(api_key="", base_url="http://:9380") +rag_object.update_agent( + agent_id="58af890a2a8911f0a71a11b922ed82d6", + title="Test Agent", + description="A test agent", + dsl={ + # ... canvas DSL here ... + } +) +``` + +--- + +### Delete agent + +```python +RAGFlow.delete_agent( + agent_id: str +) -> None +``` + +Delete an agent. + +#### Parameters + +##### agent_id: `str` + +Specifies the id of the agent to be deleted. + +#### Returns + +- Success: Nothing. +- Failure: `Exception`. + +#### Examples + +```python +from ragflow_sdk import RAGFlow +rag_object = RAGFlow(api_key="", base_url="http://:9380") +rag_object.delete_agent("58af890a2a8911f0a71a11b922ed82d6") +``` + +--- diff --git a/website/versioned_docs/version-v0.21.1/references/supported_models.mdx b/website/versioned_docs/version-v0.21.1/references/supported_models.mdx new file mode 100644 index 0000000..9c00840 --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/references/supported_models.mdx @@ -0,0 +1,81 @@ +--- +sidebar_position: 1 +slug: /supported_models +--- + +# Supported models + +import APITable from '@site/src/components/APITable'; + +A complete list of models supported by RAGFlow, which will continue to expand. + +```mdx-code-block + +``` + +| Provider | Chat | Embedding | Rerank | Img2txt | Speech2txt | TTS | +| --------------------- | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | +| Anthropic | :heavy_check_mark: | | | | | | +| Azure-OpenAI | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | :heavy_check_mark: | | +| BAAI | | :heavy_check_mark: | :heavy_check_mark: | | | | +| BaiChuan | :heavy_check_mark: | :heavy_check_mark: | | | | | +| BaiduYiyan | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| Bedrock | :heavy_check_mark: | :heavy_check_mark: | | | | | +| Cohere | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| DeepSeek | :heavy_check_mark: | | | | | | +| FastEmbed | | :heavy_check_mark: | | | | | +| Fish Audio | | | | | | :heavy_check_mark: | +| Gemini | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | | | +| Google Cloud | :heavy_check_mark: | | | | | | +| GPUStack | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | :heavy_check_mark: | +| Groq | :heavy_check_mark: | | | | | | +| HuggingFace | :heavy_check_mark: | :heavy_check_mark: | | | | | +| Jina | | :heavy_check_mark: | :heavy_check_mark: | | | | +| LeptonAI | :heavy_check_mark: | | | | | | +| LocalAI | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | | | +| LM-Studio | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | | | +| MiniMax | :heavy_check_mark: | | | | | | +| Mistral | :heavy_check_mark: | :heavy_check_mark: | | | | | +| ModelScope | :heavy_check_mark: | | | | | | +| Moonshot | :heavy_check_mark: | | | :heavy_check_mark: | | | +| Novita AI | :heavy_check_mark: | :heavy_check_mark: | | | | | +| NVIDIA | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| Ollama | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | | | +| OpenAI | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| OpenAI-API-Compatible | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| OpenRouter | :heavy_check_mark: | | | :heavy_check_mark: | | | +| PerfXCloud | :heavy_check_mark: | :heavy_check_mark: | | | | | +| Replicate | :heavy_check_mark: | :heavy_check_mark: | | | | | +| PPIO | :heavy_check_mark: | | | | | | +| SILICONFLOW | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| StepFun | :heavy_check_mark: | | | | | | +| Tencent Hunyuan | :heavy_check_mark: | | | | | | +| Tencent Cloud | | | | | :heavy_check_mark: | | +| TogetherAI | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| Tongyi-Qianwen | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| Upstage | :heavy_check_mark: | :heavy_check_mark: | | | | | +| VLLM | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| VolcEngine | :heavy_check_mark: | | | | | | +| Voyage AI | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| Xinference | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| XunFei Spark | :heavy_check_mark: | | | | | :heavy_check_mark: | +| xAI | :heavy_check_mark: | | | :heavy_check_mark: | | | +| Youdao | | :heavy_check_mark: | :heavy_check_mark: | | | | +| ZHIPU-AI | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | | | +| 01.AI | :heavy_check_mark: | | | | | | +| DeepInfra | :heavy_check_mark: | :heavy_check_mark: | | | :heavy_check_mark: | :heavy_check_mark: | +| 302.AI | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | | +| CometAPI | :heavy_check_mark: | :heavy_check_mark: | | | | | +| DeerAPI | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: | | :heavy_check_mark: | + +```mdx-code-block + +``` + +:::danger IMPORTANT +If your model is not listed here but has APIs compatible with those of OpenAI, click **OpenAI-API-Compatible** on the **Model providers** page to configure your model. +::: + +:::note +The list of supported models is extracted from [this source](https://github.com/infiniflow/ragflow/blob/main/rag/llm/__init__.py) and may not be the most current. For the latest supported model list, please refer to the Python file. +::: diff --git a/website/versioned_docs/version-v0.21.1/release_notes.md b/website/versioned_docs/version-v0.21.1/release_notes.md new file mode 100644 index 0000000..38cd81a --- /dev/null +++ b/website/versioned_docs/version-v0.21.1/release_notes.md @@ -0,0 +1,758 @@ +--- +sidebar_position: 2 +slug: /release_notes +--- + +# Releases + +Key features, improvements and bug fixes in the latest releases. + +:::info +Each RAGFlow release is available in two editions: +- **Slim edition**: excludes built-in embedding models and is identified by a **-slim** suffix added to the version name. Example: `infiniflow/ragflow:v0.21.1-slim` +- **Full edition**: includes built-in embedding models and has no suffix added to the version name. Example: `infiniflow/ragflow:v0.21.1` +::: + +:::danger IMPORTANT +The embedding models included in a full edition are: + +- BAAI/bge-large-zh-v1.5 +- maidalun1020/bce-embedding-base_v1 + +These two embedding models are optimized specifically for English and Chinese, so performance may be compromised if you use them to embed documents in other languages. +::: + +## v0.21.1 + +Released on October 23, 2025. + +### New features + +- Experimental: Adds support for PDF document parsing using MinerU. See [here](./faq.mdx#how-to-use-mineru-to-parse-pdf-documents). + +### Improvements + +- Enhances UI/UX for the dataset and personal center pages. +- Upgrades RAGFlow's document engine, [Infinity](https://github.com/infiniflow/infinity), to v0.6.1. + +### Fixed issues + +- An issue with video parsing. + +## v0.21.0 + +Released on October 15, 2025. + +### New features + +- Orchestratable ingestion pipeline: Supports customized data ingestion and cleansing workflows, enabling users to flexibly design their data flows or directly apply the official data flow templates on the canvas. +- GraphRAG & RAPTOR write process optimized: Replaces the automatic incremental build process with manual batch building, significantly reducing construction overhead. +- Long-context RAG: Automatically generates document-level table of contents (TOC) structures to mitigate context loss caused by inaccurate or excessive chunking, substantially improving retrieval quality. This feature is now available via a TOC extraction template. See [here](./guides/dataset/extract_table_of_contents.md). +- Video file parsing: Expands the system's multimodal data processing capabilities by supporting video file parsing. +- Admin CLI: Introduces a new command-line tool for system administration, allowing users to manage and monitor RAGFlow's service status via command line. + +### Improvements + +- Redesigns RAGFlow's Login and Registration pages. +- Upgrades RAGFlow's document engine Infinity to v0.6.0. + +### Added models + +- Tongyi Qwen 3 series +- Claude Sonnet 4.5 +- Meituan LongCat-Flash-Thinking + +### New agent templates + +- Company Research Report Deep Dive Agent: Designed for financial institutions to help analysts quickly organize information, generate research reports, and make investment decisions. +- Orchestratable Ingestion Pipeline Template: Allows users to apply this template on the canvas to rapidly establish standardized data ingestion and cleansing processes. + +## v0.20.5 + +Released on September 10, 2025. + +### Improvements + +- Agent: + - Agent Performance Optimized: Improves planning and reflection speed for simple tasks; optimizes concurrent tool calls for parallelizable scenarios, significantly reducing overall response time. + - Four framework-level prompt blocks are available in the **System prompt** section, enabling customization and overriding of prompts at the framework level, thereby enhancing flexibility and control. See [here](./guides/agent/agent_component_reference/agent.mdx#system-prompt). + - **Execute SQL** component enhanced: Replaces the original variable reference component with a text input field, allowing users to write free-form SQL queries and reference variables. See [here](./guides/agent/agent_component_reference/execute_sql.md). +- Chat: Re-enables **Reasoning** and **Cross-language search**. + +### Added models + +- Meituan LongCat +- Kimi: kimi-k2-turbo-preview and kimi-k2-0905-preview +- Qwen: qwen3-max-preview +- SiliconFlow: DeepSeek V3.1 + +### Fixed issues + +- Dataset: Deleted files remained searchable. +- Chat: Unable to chat with an Ollama model. +- Agent: + - A **Cite** toggle failure. + - An Agent in task mode still required a dialogue to trigger. + - Repeated answers in multi-turn dialogues. + - Duplicate summarization of parallel execution results. + +### API changes + +#### HTTP APIs + +- Adds a body parameter `"metadata_condition"` to the [Retrieve chunks](./references/http_api_reference.md#retrieve-chunks) method, enabling metadata-based chunk filtering during retrieval. [#9877](https://github.com/infiniflow/ragflow/pull/9877) + +#### Python APIs + +- Adds a parameter `metadata_condition` to the [Retrieve chunks](./references/python_api_reference.md#retrieve-chunks) method, enabling metadata-based chunk filtering during retrieval. [#9877](https://github.com/infiniflow/ragflow/pull/9877) + +## v0.20.4 + +Released on August 27, 2025. + +### Improvements + +- Agent component: Completes Chinese localization for the Agent component. +- Introduces the `ENABLE_TIMEOUT_ASSERTION` environment variable to enable or disable timeout assertions for file parsing tasks. +- Dataset: + - Improves Markdown file parsing, with AST support to avoid unintended chunking. + - Enhances HTML parsing, supporting bs4-based HTML tag traversal. + +### Added models + +ZHIPU GLM-4.5 + +### New Agent templates + +Ecommerce Customer Service Workflow: A template designed to handle enquiries about product features and multi-product comparisons using the internal dataset, as well as to manage installation appointment bookings. + +### Fixed issues + +- Dataset: + - Unable to share resources with the team. + - Inappropriate restrictions on the number and size of uploaded files. +- Chat: + - Unable to preview referenced files in responses. + - Unable to send out messages after file uploads. +- An OAuth2 authentication failure. +- A logical error in multi-conditioned metadata searches within a dataset. +- Citations infinitely increased in multi-turn conversations. + +## v0.20.3 + +Released on August 20, 2025. + +### Improvements + +- Revamps the user interface for the **Datasets**, **Chat**, and **Search** pages. +- Search and Chat: Introduces document-level metadata filtering, allowing automatic or manual filtering during chats or searches. +- Search: Supports creating search apps tailored to various business scenarios +- Chat: Supports comparing answer performance of up to three chat model settings on a single **Chat** page. +- Agent: + - Implements a toggle in the **Agent** component to enable or disable citation. + - Introduces a drag-and-drop method for creating components. +- Documentation: Corrects inaccuracies in the API reference. + +### New Agent templates + +- Report Agent: A template for generating summary reports in internal question-answering scenarios, supporting the display of tables and formulae. [#9427](https://github.com/infiniflow/ragflow/pull/9427) + +### Fixed issues + +- The timeout mechanism introduced in v0.20.0 caused tasks like GraphRAG to halt. +- Predefined opening greeting in the **Agent** component was missing during conversations. +- An automatic line break issue in the prompt editor. +- A memory leak issue caused by PyPDF. [#9469](https://github.com/infiniflow/ragflow/pull/9469) + +### API changes + +#### Deprecated + +[Create session with agent](./references/http_api_reference.md#create-session-with-agent) + +## v0.20.1 + +Released on August 8, 2025. + +### New Features + +- The **Retrieval** component now supports the dynamic specification of dataset names using variables. +- The user interface now includes a French language option. + +### Added Models + +- GPT-5 +- Claude 4.1 + +### New agent templates (both workflow and agentic) + +- SQL Assistant Workflow: Empowers non-technical teams (e.g., operations, product) to independently query business data. +- Choose Your Knowledge Base Workflow: Lets users select a dataset to query during conversations. [#9325](https://github.com/infiniflow/ragflow/pull/9325) +- Choose Your Knowledge Base Agent: Delivers higher-quality responses with extended reasoning time, suited for complex queries. [#9325](https://github.com/infiniflow/ragflow/pull/9325) + +### Fixed Issues + +- The **Agent** component was unable to invoke models installed via vLLM. +- Agents could not be shared with the team. +- Embedding an Agent into a webpage was not functioning properly. + +## v0.20.0 + +Released on August 4, 2025. + +### Compatibility changes + +From v0.20.0 onwards, Agents are no longer compatible with earlier versions, and all existing Agents from previous versions must be rebuilt following the upgrade. + +### New features + +- Unified orchestration of both Agents and Workflows. +- A comprehensive refactor of the Agent, greatly enhancing its capabilities and usability, with support for Multi-Agent configurations, planning and reflection, and visual functionalities. +- Fully implemented MCP functionality, allowing for MCP Server import, Agents functioning as MCP Clients, and RAGFlow itself operating as an MCP Server. +- Access to runtime logs for Agents. +- Chat histories with Agents available through the management panel. +- Integration of a new, more robust version of Infinity, enabling the auto-tagging functionality with Infinity as the underlying document engine. +- An OpenAI-compatible API that supports file reference information. +- Support for new models, including Kimi K2, Grok 4, and Voyage embedding. +- RAGFlow’s codebase is now mirrored on Gitee. +- Introduction of a new model provider, Gitee AI. + +### New agent templates introduced + +- Multi-Agent based Deep Research: Collaborative Agent teamwork led by a Lead Agent with multiple Subagents, distinct from traditional workflow orchestration. +- An intelligent Q&A chatbot leveraging internal datasets, designed for customer service and training scenarios. +- A resume analysis template used by the RAGFlow team to screen, analyze, and record candidate information. +- A blog generation workflow that transforms raw ideas into SEO-friendly blog content. +- An intelligent customer service workflow. +- A user feedback analysis template that directs user feedback to appropriate teams through semantic analysis. +- Trip Planner: Uses web search and map MCP servers to assist with travel planning. +- Image Lingo: Translates content from uploaded photos. +- An information search assistant that retrieves answers from both internal datasets and the web. + +## v0.19.1 + +Released on June 23, 2025. + +### Fixed issues + +- A memory leak issue during high-concurrency requests. +- Large file parsing freezes when GraphRAG entity resolution is enabled. [#8223](https://github.com/infiniflow/ragflow/pull/8223) +- A context error occurring when using Sandbox in standalone mode. [#8340](https://github.com/infiniflow/ragflow/pull/8340) +- An excessive CPU usage issue caused by Ollama. [#8216](https://github.com/infiniflow/ragflow/pull/8216) +- A bug in the Code Component. [#7949](https://github.com/infiniflow/ragflow/pull/7949) +- Added support for models installed via Ollama or VLLM when creating a dataset through the API. [#8069](https://github.com/infiniflow/ragflow/pull/8069) +- Enabled role-based authentication for S3 bucket access. [#8149](https://github.com/infiniflow/ragflow/pull/8149) + +### Added models + +- Qwen 3 Embedding. [#8184](https://github.com/infiniflow/ragflow/pull/8184) +- Voyage Multimodal 3. [#7987](https://github.com/infiniflow/ragflow/pull/7987) + +## v0.19.0 + +Released on May 26, 2025. + +### New features + +- [Cross-language search](./references/glossary.mdx#cross-language-search) is supported in the Knowledge and Chat modules, enhancing search accuracy and user experience in multilingual environments, such as in Chinese-English datasets. +- Agent component: A new Code component supports Python and JavaScript scripts, enabling developers to handle more complex tasks like dynamic data processing. +- Enhanced image display: Images in Chat and Search now render directly within responses, rather than as external references. Knowledge retrieval testing can retrieve images directly, instead of texts extracted from images. +- Claude 4 and ChatGPT o3: Developers can now use the newly released, most advanced Claude model and OpenAI’s latest ChatGPT o3 inference model. + +> The following features have been contributed by our community: + +- Agent component: Enables tool calling within the Generate Component. Thanks to [notsyncing](https://github.com/notsyncing). +- Markdown rendering: Image references in a markdown file can be displayed after chunking. Thanks to [Woody-Hu](https://github.com/Woody-Hu). +- Document engine support: OpenSearch can now be used as RAGFlow's document engine. Thanks to [pyyuhao](https://github.com/pyyuhao). + +### Documentation + +#### Added documents + +- [Select PDF parser](./guides/dataset/select_pdf_parser.md) +- [Enable Excel2HTML](./guides/dataset/enable_excel2html.md) +- [Code component](./guides/agent/agent_component_reference/code.mdx) + +## v0.18.0 + +Released on April 23, 2025. + +### Compatibility changes + +From this release onwards, built-in rerank models have been removed because they have minimal impact on retrieval rates but significantly increase retrieval time. + +### New features + +- MCP server: enables access to RAGFlow's datasets via MCP. +- DeepDoc supports adopting VLM model as a processing pipeline during document layout recognition, enabling in-depth analysis of images in PDF and DOCX files. +- OpenAI-compatible APIs: Agents can be called via OpenAI-compatible APIs. +- User registration control: administrators can enable or disable user registration through an environment variable. +- Team collaboration: Agents can be shared with team members. +- Agent version control: all updates are continuously logged and can be rolled back to a previous version via export. + +![export_agent](https://raw.githubusercontent.com/infiniflow/ragflow-docs/main/images/export_agent_as_json.jpg) + +### Improvements + +- Enhanced answer referencing: Citation accuracy in generated responses is improved. +- Enhanced question-answering experience: users can now manually stop streaming output during a conversation. + +### Documentation + +#### Added documents + +- [Set page rank](./guides/dataset/set_page_rank.md) +- [Enable RAPTOR](./guides/dataset/enable_raptor.md) +- [Set variables for your chat assistant](./guides/chat/set_chat_variables.md) +- [Launch RAGFlow MCP server](./develop/mcp/launch_mcp_server.md) + +## v0.17.2 + +Released on March 13, 2025. + +### Compatibility changes + +- Removes the **Max_tokens** setting from **Chat configuration**. +- Removes the **Max_tokens** setting from **Generate**, **Rewrite**, **Categorize**, **Keyword** agent components. + +From this release onwards, if you still see RAGFlow's responses being cut short or truncated, check the **Max_tokens** setting of your model provider. + +### Improvements + +- Adds OpenAI-compatible APIs. +- Introduces a German user interface. +- Accelerates knowledge graph extraction. +- Enables Tavily-based web search in the **Retrieval** agent component. +- Adds Tongyi-Qianwen QwQ models (OpenAI-compatible). +- Supports CSV files in the **General** chunking method. + +### Fixed issues + +- Unable to add models via Ollama/Xinference, an issue introduced in v0.17.1. + +### API changes + +#### HTTP APIs + +- [Create chat completion](./references/http_api_reference.md#openai-compatible-api) + +#### Python APIs + +- [Create chat completion](./references/python_api_reference.md#openai-compatible-api) + +## v0.17.1 + +Released on March 11, 2025. + +### Improvements + +- Improves English tokenization quality. +- Improves the table extraction logic in Markdown document parsing. +- Updates SiliconFlow's model list. +- Supports parsing XLS files (Excel 97-2003) with improved corresponding error handling. +- Supports Huggingface rerank models. +- Enables relative time expressions ("now", "yesterday", "last week", "next year", and more) in chat assistant and the **Rewrite** agent component. + +### Fixed issues + +- A repetitive knowledge graph extraction issue. +- Issues with API calling. +- Options in the **PDF parser**, aka **Document parser**, dropdown are missing. +- A Tavily web search issue. +- Unable to preview diagrams or images in an AI chat. + +### Documentation + +#### Added documents + +- [Use tag set](./guides/dataset/use_tag_sets.md) + +## v0.17.0 + +Released on March 3, 2025. + +### New features + +- AI chat: Implements Deep Research for agentic reasoning. To activate this, enable the **Reasoning** toggle under the **Prompt engine** tab of your chat assistant dialogue. +- AI chat: Leverages Tavily-based web search to enhance contexts in agentic reasoning. To activate this, enter the correct Tavily API key under the **Assistant settings** tab of your chat assistant dialogue. +- AI chat: Supports starting a chat without specifying datasets. +- AI chat: HTML files can also be previewed and referenced, in addition to PDF files. +- Dataset: Adds a **PDF parser**, aka **Document parser**, dropdown menu to dataset configurations. This includes a DeepDoc model option, which is time-consuming, a much faster **naive** option (plain text), which skips DLA (Document Layout Analysis), OCR (Optical Character Recognition), and TSR (Table Structure Recognition) tasks, and several currently *experimental* large model options. See [here](./guides/dataset/select_pdf_parser.md). +- Agent component: **(x)** or a forward slash `/` can be used to insert available keys (variables) in the system prompt field of the **Generate** or **Template** component. +- Object storage: Supports using Aliyun OSS (Object Storage Service) as a file storage option. +- Models: Updates the supported model list for Tongyi-Qianwen (Qwen), adding DeepSeek-specific models; adds ModelScope as a model provider. +- APIs: Document metadata can be updated through an API. + +The following diagram illustrates the workflow of RAGFlow's Deep Research: + +![Image](https://github.com/user-attachments/assets/f65d4759-4f09-4d9d-9549-c0e1fe907525) + +The following is a screenshot of a conversation that integrates Deep Research: + +![Image](https://github.com/user-attachments/assets/165b88ff-1f5d-4fb8-90e2-c836b25e32e9) + +### API changes + +#### HTTP APIs + +Adds a body parameter `"meta_fields"` to the [Update document](./references/http_api_reference.md#update-document) method. + +#### Python APIs + +Adds a key option `"meta_fields"` to the [Update document](./references/python_api_reference.md#update-document) method. + +### Documentation + +#### Added documents + +- [Run retrieval test](./guides/dataset/run_retrieval_test.md) + +## v0.16.0 + +Released on February 6, 2025. + +### New features + +- Supports DeepSeek R1 and DeepSeek V3. +- GraphRAG refactor: Knowledge graph is dynamically built on an entire dataset rather than on an individual file, and automatically updated when a newly uploaded file starts parsing. See [here](https://ragflow.io/docs/dev/construct_knowledge_graph). +- Adds an **Iteration** agent component and a **Research report generator** agent template. See [here](./guides/agent/agent_component_reference/iteration.mdx). +- New UI language: Portuguese. +- Allows setting metadata for a specific file in a dataset to enhance AI-powered chats. See [here](./guides/dataset/set_metadata.md). +- Upgrades RAGFlow's document engine [Infinity](https://github.com/infiniflow/infinity) to v0.6.0.dev3. +- Supports GPU acceleration for DeepDoc (see [docker-compose-gpu.yml](https://github.com/infiniflow/ragflow/blob/main/docker/docker-compose-gpu.yml)). +- Supports creating and referencing a **Tag** dataset as a key milestone towards bridging the semantic gap between query and response. + +:::danger IMPORTANT +The **Tag dataset** feature is *unavailable* on the [Infinity](https://github.com/infiniflow/infinity) document engine. +::: + +### Documentation + +#### Added documents + +- [Construct knowledge graph](./guides/dataset/construct_knowledge_graph.md) +- [Set metadata](./guides/dataset/set_metadata.md) +- [Begin component](./guides/agent/agent_component_reference/begin.mdx) +- [Generate component](./guides/agent/agent_component_reference/generate.mdx) +- [Interact component](./guides/agent/agent_component_reference/interact.mdx) +- [Retrieval component](./guides/agent/agent_component_reference/retrieval.mdx) +- [Categorize component](./guides/agent/agent_component_reference/categorize.mdx) +- [Keyword component](./guides/agent/agent_component_reference/keyword.mdx) +- [Message component](./guides/agent/agent_component_reference/message.mdx) +- [Rewrite component](./guides/agent/agent_component_reference/rewrite.mdx) +- [Switch component](./guides/agent/agent_component_reference/switch.mdx) +- [Concentrator component](./guides/agent/agent_component_reference/concentrator.mdx) +- [Template component](./guides/agent/agent_component_reference/template.mdx) +- [Iteration component](./guides/agent/agent_component_reference/iteration.mdx) +- [Note component](./guides/agent/agent_component_reference/note.mdx) + +## v0.15.1 + +Released on December 25, 2024. + +### Upgrades + +- Upgrades RAGFlow's document engine [Infinity](https://github.com/infiniflow/infinity) to v0.5.2. +- Enhances the log display of document parsing status. + +### Fixed issues + +This release fixes the following issues: + +- The `SCORE not found` and `position_int` errors returned by [Infinity](https://github.com/infiniflow/infinity). +- Once an embedding model in a specific dataset is changed, embedding models in other datasets can no longer be changed. +- Slow response in question-answering and AI search due to repetitive loading of the embedding model. +- Fails to parse documents with RAPTOR. +- Using the **Table** parsing method results in information loss. +- Miscellaneous API issues. + +### API changes + +#### HTTP APIs + +Adds an optional parameter `"user_id"` to the following APIs: + +- [Create session with chat assistant](https://ragflow.io/docs/dev/http_api_reference#create-session-with-chat-assistant) +- [Update chat assistant's session](https://ragflow.io/docs/dev/http_api_reference#update-chat-assistants-session) +- [List chat assistant's sessions](https://ragflow.io/docs/dev/http_api_reference#list-chat-assistants-sessions) +- [Create session with agent](https://ragflow.io/docs/dev/http_api_reference#create-session-with-agent) +- [Converse with chat assistant](https://ragflow.io/docs/dev/http_api_reference#converse-with-chat-assistant) +- [Converse with agent](https://ragflow.io/docs/dev/http_api_reference#converse-with-agent) +- [List agent sessions](https://ragflow.io/docs/dev/http_api_reference#list-agent-sessions) + +## v0.15.0 + +Released on December 18, 2024. + +### New features + +- Introduces additional Agent-specific APIs. +- Supports using page rank score to improve retrieval performance when searching across multiple datasets. +- Offers an iframe in Chat and Agent to facilitate the integration of RAGFlow into your webpage. +- Adds a Helm chart for deploying RAGFlow on Kubernetes. +- Supports importing or exporting an agent in JSON format. +- Supports step run for Agent components/tools. +- Adds a new UI language: Japanese. +- Supports resuming GraphRAG and RAPTOR from a failure, enhancing task management resilience. +- Adds more Mistral models. +- Adds a dark mode to the UI, allowing users to toggle between light and dark themes. + +### Improvements + +- Upgrades the Document Layout Analysis model in DeepDoc. +- Significantly enhances the retrieval performance when using [Infinity](https://github.com/infiniflow/infinity) as document engine. + +### API changes + +#### HTTP APIs + +- [List agent sessions](https://ragflow.io/docs/dev/http_api_reference#list-agent-sessions) +- [List agents](https://ragflow.io/docs/dev/http_api_reference#list-agents) + +#### Python APIs + +- [List agent sessions](https://ragflow.io/docs/dev/python_api_reference#list-agent-sessions) +- [List agents](https://ragflow.io/docs/dev/python_api_reference#list-agents) + +## v0.14.1 + +Released on November 29, 2024. + +### Improvements + +Adds [Infinity's configuration file](https://github.com/infiniflow/ragflow/blob/main/docker/infinity_conf.toml) to facilitate integration and customization of [Infinity](https://github.com/infiniflow/infinity) as a document engine. From this release onwards, updates to Infinity's configuration can be made directly within RAGFlow and will take effect immediately after restarting RAGFlow using `docker compose`. [#3715](https://github.com/infiniflow/ragflow/pull/3715) + +### Fixed issues + +This release fixes the following issues: + +- Unable to display or edit content of a chunk after clicking it. +- A `'Not found'` error in Elasticsearch. +- Chinese text becoming garbled during parsing. +- A compatibility issue with Polars. +- A compatibility issue between Infinity and GraphRAG. + +## v0.14.0 + +Released on November 26, 2024. + +### New features + +- Supports [Infinity](https://github.com/infiniflow/infinity) or Elasticsearch (default) as document engine for vector storage and full-text indexing. [#2894](https://github.com/infiniflow/ragflow/pull/2894) +- Enhances user experience by adding more variables to the Agent and implementing auto-saving. +- Adds a three-step translation agent template, inspired by [Andrew Ng's translation agent](https://github.com/andrewyng/translation-agent). +- Adds an SEO-optimized blog writing agent template. +- Provides HTTP and Python APIs for conversing with an agent. +- Supports the use of English synonyms during retrieval processes. +- Optimizes term weight calculations, reducing the retrieval time by 50%. +- Improves task executor monitoring with additional performance indicators. +- Replaces Redis with Valkey. +- Adds three new UI languages (*contributed by the community*): Indonesian, Spanish, and Vietnamese. + +### Compatibility changes + +From this release onwards, **service_config.yaml.template** replaces **service_config.yaml** for configuring backend services. Upon Docker container startup, the environment variables defined in this template file are automatically populated and a **service_config.yaml** is auto-generated from it. [#3341](https://github.com/infiniflow/ragflow/pull/3341) + +This approach eliminates the need to manually update **service_config.yaml** after making changes to **.env**, facilitating dynamic environment configurations. + +:::danger IMPORTANT +Ensure that you [upgrade **both** your code **and** Docker image to this release](https://ragflow.io/docs/dev/upgrade_ragflow#upgrade-ragflow-to-the-most-recent-officially-published-release) before trying this new approach. +::: + +### API changes + +#### HTTP APIs + +- [Create session with agent](https://ragflow.io/docs/dev/http_api_reference#create-session-with-agent) +- [Converse with agent](https://ragflow.io/docs/dev/http_api_reference#converse-with-agent) + +#### Python APIs + +- [Create session with agent](https://ragflow.io/docs/dev/python_api_reference#create-session-with-agent) +- [Converse with agent](https://ragflow.io/docs/dev/python_api_reference#create-session-with-agent) + +### Documentation + +#### Added documents + +- [Configurations](https://ragflow.io/docs/dev/configurations) +- [Manage team members](./guides/team/manage_team_members.md) +- [Run health check on RAGFlow's dependencies](https://ragflow.io/docs/dev/run_health_check) + +## v0.13.0 + +Released on October 31, 2024. + +### New features + +- Adds the team management functionality for all users. +- Updates the Agent UI to improve usability. +- Adds support for Markdown chunking in the **General** chunking method. +- Introduces an **invoke** tool within the Agent UI. +- Integrates support for Dify's knowledge base API. +- Adds support for GLM4-9B and Yi-Lightning models. +- Introduces HTTP and Python APIs for dataset management, file management within dataset, and chat assistant management. + +:::tip NOTE +To download RAGFlow's Python SDK: + +```bash +pip install ragflow-sdk==0.13.0 +``` +::: + +### Documentation + +#### Added documents + +- [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md) +- [HTTP API Reference](./references/http_api_reference.md) +- [Python API Reference](./references/python_api_reference.md) + +## v0.12.0 + +Released on September 30, 2024. + +### New features + +- Offers slim editions of RAGFlow's Docker images, which do not include built-in BGE/BCE embedding or reranking models. +- Improves the results of multi-round dialogues. +- Enables users to remove added LLM vendors. +- Adds support for **OpenTTS** and **SparkTTS** models. +- Implements an **Excel to HTML** toggle in the **General** chunking method, allowing users to parse a spreadsheet into either HTML tables or key-value pairs by row. +- Adds agent tools **YahooFinance** and **Jin10**. +- Adds an investment advisor agent template. + +### Compatibility changes + +From this release onwards, RAGFlow offers slim editions of its Docker images to improve the experience for users with limited Internet access. A slim edition of RAGFlow's Docker image does not include built-in BGE/BCE embedding models and has a size of about 1GB; a full edition of RAGFlow is approximately 9GB and includes two built-in embedding models. + +The default Docker image edition is `nightly-slim`. The following list clarifies the differences between various editions: + +- `nightly-slim`: The slim edition of the most recent tested Docker image. +- `v0.12.0-slim`: The slim edition of the most recent **officially released** Docker image. +- `nightly`: The full edition of the most recent tested Docker image. +- `v0.12.0`: The full edition of the most recent **officially released** Docker image. + +See [Upgrade RAGFlow](https://ragflow.io/docs/dev/upgrade_ragflow) for instructions on upgrading. + +### Documentation + +#### Added documents + +- [Upgrade RAGFlow](https://ragflow.io/docs/dev/upgrade_ragflow) + +## v0.11.0 + +Released on September 14, 2024. + +### New features + +- Introduces an AI search interface within the RAGFlow UI. +- Supports audio output via **FishAudio** or **Tongyi Qwen TTS**. +- Allows the use of Postgres for metadata storage, in addition to MySQL. +- Supports object storage options with S3 or Azure Blob. +- Supports model vendors: **Anthropic**, **Voyage AI**, and **Google Cloud**. +- Supports the use of **Tencent Cloud ASR** for audio content recognition. +- Adds finance-specific agent components: **WenCai**, **AkShare**, **YahooFinance**, and **TuShare**. +- Adds a medical consultant agent template. +- Supports running retrieval benchmarking on the following datasets: + - [ms_marco_v1.1](https://huggingface.co/datasets/microsoft/ms_marco) + - [trivia_qa](https://huggingface.co/datasets/mandarjoshi/trivia_qa) + - [miracl](https://huggingface.co/datasets/miracl/miracl) + +## v0.10.0 + +Released on August 26, 2024. + +### New features + +- Introduces a text-to-SQL template in the Agent UI. +- Implements Agent APIs. +- Incorporates monitoring for the task executor. +- Introduces Agent tools **GitHub**, **DeepL**, **BaiduFanyi**, **QWeather**, and **GoogleScholar**. +- Supports chunking of EML files. +- Supports more LLMs or model services: **GPT-4o-mini**, **PerfXCloud**, **TogetherAI**, **Upstage**, **Novita AI**, **01.AI**, **SiliconFlow**, **PPIO**, **XunFei Spark**, **Baidu Yiyan**, and **Tencent Hunyuan**. + +## v0.9.0 + +Released on August 6, 2024. + +### New features + +- Supports GraphRAG as a chunking method. +- Introduces Agent component **Keyword** and search tools, including **Baidu**, **DuckDuckGo**, **PubMed**, **Wikipedia**, **Bing**, and **Google**. +- Supports speech-to-text recognition for audio files. +- Supports model vendors **Gemini** and **Groq**. +- Supports inference frameworks, engines, and services including **LM studio**, **OpenRouter**, **LocalAI**, and **Nvidia API**. +- Supports using reranker models in Xinference. + +## v0.8.0 + +Released on July 8, 2024. + +### New features + +- Supports Agentic RAG, enabling graph-based workflow construction for RAG and agents. +- Supports model vendors **Mistral**, **MiniMax**, **Bedrock**, and **Azure OpenAI**. +- Supports DOCX files in the MANUAL chunking method. +- Supports DOCX, MD, and PDF files in the Q&A chunking method. + +## v0.7.0 + +Released on May 31, 2024. + +### New features + +- Supports the use of reranker models. +- Integrates reranker and embedding models: [BCE](https://github.com/netease-youdao/BCEmbedding), [BGE](https://github.com/FlagOpen/FlagEmbedding), and [Jina](https://jina.ai/embeddings/). +- Supports LLMs Baichuan and VolcanoArk. +- Implements [RAPTOR](https://arxiv.org/html/2401.18059v1) for improved text retrieval. +- Supports HTML files in the GENERAL chunking method. +- Provides HTTP and Python APIs for deleting documents by ID. +- Supports ARM64 platforms. + +:::danger IMPORTANT +While we also test RAGFlow on ARM64 platforms, we do not maintain RAGFlow Docker images for ARM. + +If you are on an ARM platform, follow [this guide](./develop/build_docker_image.mdx) to build a RAGFlow Docker image. +::: + +### API changes + +#### HTTP API + +- [Delete documents](https://ragflow.io/docs/dev/http_api_reference#delete-documents) + +#### Python API + +- [Delete documents](https://ragflow.io/docs/dev/python_api_reference#delete-documents) + +## v0.6.0 + +Released on May 21, 2024. + +### New features + +- Supports streaming output. +- Provides HTTP and Python APIs for retrieving document chunks. +- Supports monitoring of system components, including Elasticsearch, MySQL, Redis, and MinIO. +- Supports disabling **Layout Recognition** in the GENERAL chunking method to reduce file chunking time. + +### API changes + +#### HTTP API + +- [Retrieve chunks](https://ragflow.io/docs/dev/http_api_reference#retrieve-chunks) + +#### Python API + +- [Retrieve chunks](https://ragflow.io/docs/dev/python_api_reference#retrieve-chunks) + +## v0.5.0 + +Released on May 8, 2024. + +### New features + +- Supports LLM DeepSeek. diff --git a/website/versioned_sidebars/version-v0.21.1-sidebars.json b/website/versioned_sidebars/version-v0.21.1-sidebars.json new file mode 100644 index 0000000..a926af6 --- /dev/null +++ b/website/versioned_sidebars/version-v0.21.1-sidebars.json @@ -0,0 +1,3 @@ +{ + "tutorialSidebar": [{"type": "autogenerated", "dirName": "."}] + } \ No newline at end of file diff --git a/website/versions.json b/website/versions.json index df3f3cb..19a41c0 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,3 +1,3 @@ [ - "v0.21.0" + "v0.21.1" ] \ No newline at end of file