From 03d1265cfd515a066154b25a0f56b27c327a69bf Mon Sep 17 00:00:00 2001 From: writinwaters <93570324+writinwaters@users.noreply.github.com> Date: Mon, 3 Mar 2025 15:42:39 +0800 Subject: [PATCH] Restructured guides (#5549) ### What problem does this PR solve? ### Type of change - [x] Documentation Update --- docs/configurations.md | 2 +- docs/guides/agent/agent_introduction.md | 4 ++-- docs/guides/agent/embed_agent_into_webpage.md | 2 +- docs/guides/agent/general_purpose_chatbot.md | 4 ++-- docs/guides/agent/text2sql_agent.md | 8 ++++---- .../_category_.json | 2 +- .../configure_knowledge_base.md | 4 ++-- .../construct_knowledge_graph.md | 0 .../run_retrieval_test.md | 0 .../set_metadata.md | 0 docs/guides/develop/build_docker_image.mdx | 11 ++++++----- docs/guides/manage_files.md | 2 +- docs/guides/models/_category_.json | 8 ++++++++ docs/guides/{ => models}/deploy_local_llm.mdx | 2 +- docs/guides/{ => models}/llm_api_key_setup.md | 7 +++---- docs/guides/run_health_check.md | 2 +- docs/guides/start_chat.md | 12 ++++++------ docs/quickstart.mdx | 2 +- docs/references/http_api_reference.md | 2 +- docs/references/python_api_reference.md | 2 +- docs/release_notes.md | 8 ++++---- 21 files changed, 46 insertions(+), 38 deletions(-) rename docs/guides/{configure_knowledge_base => dataset}/_category_.json (75%) rename docs/guides/{configure_knowledge_base => dataset}/configure_knowledge_base.md (99%) rename docs/guides/{configure_knowledge_base => dataset}/construct_knowledge_graph.md (100%) rename docs/guides/{configure_knowledge_base => dataset}/run_retrieval_test.md (100%) rename docs/guides/{configure_knowledge_base => dataset}/set_metadata.md (100%) create mode 100644 docs/guides/models/_category_.json rename docs/guides/{ => models}/deploy_local_llm.mdx (99%) rename docs/guides/{ => models}/llm_api_key_setup.md (83%) diff --git a/docs/configurations.md b/docs/configurations.md index d494d2b39..3c573a263 100644 --- a/docs/configurations.md +++ b/docs/configurations.md @@ -3,7 +3,7 @@ sidebar_position: 1 slug: /configurations --- -# Configurations +# Configuration Configurations for deploying RAGFlow via Docker. diff --git a/docs/guides/agent/agent_introduction.md b/docs/guides/agent/agent_introduction.md index c4f97526e..d1779f543 100644 --- a/docs/guides/agent/agent_introduction.md +++ b/docs/guides/agent/agent_introduction.md @@ -22,8 +22,8 @@ Agents and RAG are complementary techniques, each enhancing the other’s capabi Before proceeding, ensure that: -1. You have properly set the LLM to use. See the guides on [Configure your API key](../llm_api_key_setup.md) or [Deploy a local LLM](../deploy_local_llm.mdx) for more information. -2. You have a knowledge base configured and the corresponding files properly parsed. See the guide on [Configure a knowledge base](../configure_knowledge_base.md) for more information. +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 knowledge base configured and the corresponding files properly parsed. See the guide on [Configure a knowledge base](../dataset/configure_knowledge_base.md) for more information. ::: diff --git a/docs/guides/agent/embed_agent_into_webpage.md b/docs/guides/agent/embed_agent_into_webpage.md index 7acbfe0b4..e452a862f 100644 --- a/docs/guides/agent/embed_agent_into_webpage.md +++ b/docs/guides/agent/embed_agent_into_webpage.md @@ -7,7 +7,7 @@ slug: /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](https://ragflow.io/docs/dev/acquire_ragflow_api_key); otherwise, an error message would appear. +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 **>** **Edit** to access its editing page. 3. Click **Embed into webpage** on the top right corner of the canvas to show the **iframe** window: diff --git a/docs/guides/agent/general_purpose_chatbot.md b/docs/guides/agent/general_purpose_chatbot.md index 9cb2f098b..fa2d555b8 100644 --- a/docs/guides/agent/general_purpose_chatbot.md +++ b/docs/guides/agent/general_purpose_chatbot.md @@ -13,8 +13,8 @@ This document provides guides on creating such a chatbot using our chatbot templ ## Prerequisites -1. Ensure you have properly set the LLM to use. See the guides on [Configure your API key](../llm_api_key_setup.md) or [Deploy a local LLM](../deploy_local_llm.mdx) for more information. -2. Ensure you have a knowledge base configured and the corresponding files properly parsed. See the guide on [Configure a knowledge base](../configure_knowledge_base.md) for more information. +1. Ensure 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. Ensure you have a knowledge base configured and the corresponding files properly parsed. See the guide on [Configure a knowledge base](../dataset/configure_knowledge_base.md) for more information. 3. Make sure you have read the [Introduction to Agentic RAG](./agent_introduction.md). ## Create a chatbot agent from template diff --git a/docs/guides/agent/text2sql_agent.md b/docs/guides/agent/text2sql_agent.md index f57c2965d..b024339b8 100644 --- a/docs/guides/agent/text2sql_agent.md +++ b/docs/guides/agent/text2sql_agent.md @@ -31,10 +31,10 @@ However, traditional Text2SQL solutions often require model fine-tuning, which c A list of components required: -- [Begin](https://ragflow.io/docs/dev/begin_component) -- [Interact](https://ragflow.io/docs/dev/interact_component) -- [Retrieval](https://ragflow.io/docs/dev/retrieval_component) -- [Generate](https://ragflow.io/docs/dev/generate_component) +- [Begin](./agent_component_reference/begin.mdx) +- [Interact](./agent_component_reference/interact.mdx) +- [Retrieval](./agent_component_reference/retrieval.mdx) +- [Generate](./agent_component_reference/generate.mdx) - ExeSQL ## Procedure diff --git a/docs/guides/configure_knowledge_base/_category_.json b/docs/guides/dataset/_category_.json similarity index 75% rename from docs/guides/configure_knowledge_base/_category_.json rename to docs/guides/dataset/_category_.json index 210a248a7..f0d79edfd 100644 --- a/docs/guides/configure_knowledge_base/_category_.json +++ b/docs/guides/dataset/_category_.json @@ -1,5 +1,5 @@ { - "label": "Configure a knowledge base", + "label": "Datasets", "position": 0, "link": { "type": "generated-index", diff --git a/docs/guides/configure_knowledge_base/configure_knowledge_base.md b/docs/guides/dataset/configure_knowledge_base.md similarity index 99% rename from docs/guides/configure_knowledge_base/configure_knowledge_base.md rename to docs/guides/dataset/configure_knowledge_base.md index 4560f9082..f84bb9a56 100644 --- a/docs/guides/configure_knowledge_base/configure_knowledge_base.md +++ b/docs/guides/dataset/configure_knowledge_base.md @@ -3,7 +3,7 @@ sidebar_position: 0 slug: /configure_knowledge_base --- -# Configure a knowledge base +# Configure knowledge base Knowledge base, hallucination-free chat, and file management are the three pillars of RAGFlow. RAGFlow's AI chats are based on knowledge bases. Each of RAGFlow's knowledge bases 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 knowledge base feature, covering the following topics: @@ -26,7 +26,7 @@ The following screenshot shows the configuration page of a knowledge base. A pro ![knowledge base configuration](https://github.com/infiniflow/ragflow/assets/93570324/384c671a-8b9c-468c-b1c9-1401128a9b65) -This section covers the following topics: +This section covers the following topics: - Select chunk method - Select embedding model diff --git a/docs/guides/configure_knowledge_base/construct_knowledge_graph.md b/docs/guides/dataset/construct_knowledge_graph.md similarity index 100% rename from docs/guides/configure_knowledge_base/construct_knowledge_graph.md rename to docs/guides/dataset/construct_knowledge_graph.md diff --git a/docs/guides/configure_knowledge_base/run_retrieval_test.md b/docs/guides/dataset/run_retrieval_test.md similarity index 100% rename from docs/guides/configure_knowledge_base/run_retrieval_test.md rename to docs/guides/dataset/run_retrieval_test.md diff --git a/docs/guides/configure_knowledge_base/set_metadata.md b/docs/guides/dataset/set_metadata.md similarity index 100% rename from docs/guides/configure_knowledge_base/set_metadata.md rename to docs/guides/dataset/set_metadata.md diff --git a/docs/guides/develop/build_docker_image.mdx b/docs/guides/develop/build_docker_image.mdx index d85780205..6ebf3623f 100644 --- a/docs/guides/develop/build_docker_image.mdx +++ b/docs/guides/develop/build_docker_image.mdx @@ -21,7 +21,6 @@ A guide explaining how to build a RAGFlow Docker image from its source code. By - RAM ≥ 16 GB - Disk ≥ 50 GB - Docker ≥ 24.0.0 & Docker Compose ≥ v2.26.1 -- For ARM64 platforms, please upgrade the `xgboost` version in **pyproject.toml** to `1.6.0` and ensure **unixODBC** is properly installed. ## Build a Docker image @@ -35,8 +34,9 @@ A guide explaining how to build a RAGFlow Docker image from its source code. By This image is approximately 2 GB in size and relies on external LLM and embedding services. -:::tip NOTE -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. +:::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 @@ -53,8 +53,9 @@ docker build --build-arg LIGHTEN=1 -f Dockerfile -t infiniflow/ragflow:nightly-s This image is approximately 9 GB in size. As it includes embedding models, it relies on external LLM services only. -:::tip NOTE -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. +:::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 diff --git a/docs/guides/manage_files.md b/docs/guides/manage_files.md index cac66d7a8..4a75c708f 100644 --- a/docs/guides/manage_files.md +++ b/docs/guides/manage_files.md @@ -3,7 +3,7 @@ sidebar_position: 5 slug: /manage_files --- -# Manage files +# Files Knowledge base, hallucination-free chat, and file management are the three pillars of RAGFlow. RAGFlow's file management allows you to upload files individually or in bulk. You can then link an uploaded file to multiple target knowledge bases. This guide showcases some basic usages of the file management feature. diff --git a/docs/guides/models/_category_.json b/docs/guides/models/_category_.json new file mode 100644 index 000000000..8536f8e47 --- /dev/null +++ b/docs/guides/models/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Models", + "position": -1, + "link": { + "type": "generated-index", + "description": "Guides on model settings." + } +} diff --git a/docs/guides/deploy_local_llm.mdx b/docs/guides/models/deploy_local_llm.mdx similarity index 99% rename from docs/guides/deploy_local_llm.mdx rename to docs/guides/models/deploy_local_llm.mdx index 5e66f32b1..75b3e320a 100644 --- a/docs/guides/deploy_local_llm.mdx +++ b/docs/guides/models/deploy_local_llm.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 2 slug: /deploy_local_llm --- diff --git a/docs/guides/llm_api_key_setup.md b/docs/guides/models/llm_api_key_setup.md similarity index 83% rename from docs/guides/llm_api_key_setup.md rename to docs/guides/models/llm_api_key_setup.md index 72b3fe375..da8f57fe3 100644 --- a/docs/guides/llm_api_key_setup.md +++ b/docs/guides/models/llm_api_key_setup.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 1 slug: /llm_api_key_setup --- @@ -9,7 +9,7 @@ An API key is required for RAGFlow to interact with an online AI model. This gui ## 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. +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). @@ -31,8 +31,7 @@ You have two options for configuring your model API key: - 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.* + _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 diff --git a/docs/guides/run_health_check.md b/docs/guides/run_health_check.md index f3c983ed7..66b127c43 100644 --- a/docs/guides/run_health_check.md +++ b/docs/guides/run_health_check.md @@ -3,7 +3,7 @@ sidebar_position: 7 slug: /run_health_check --- -# Run dependency health check +# Monitoring Double-check the health status of RAGFlow's dependencies. diff --git a/docs/guides/start_chat.md b/docs/guides/start_chat.md index 89b7b35bc..9074176f2 100644 --- a/docs/guides/start_chat.md +++ b/docs/guides/start_chat.md @@ -3,9 +3,9 @@ sidebar_position: 1 slug: /start_chat --- -# Start an AI-powered chat +# Chat -Initiate a chat with a configured chat assistant. +Initiate an AI-powered chat with a configured chat assistant. --- @@ -80,13 +80,13 @@ Hover over an intended chat assistant **>** **Edit** to show the chat configurat 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](https://ragflow.io/docs/dev/acquire_ragflow_api_key) -- [HTTP API reference](https://ragflow.io/docs/dev/http_api_reference) -- [Python API reference](https://ragflow.io/docs/dev/python_api_reference) +- [Acquire a RAGFlow API key](./models/llm_api_key_setup.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](https://ragflow.io/docs/dev/acquire_ragflow_api_key); otherwise, an error message would appear. +1. Before proceeding, you must [acquire an API key](./models/llm_api_key_setup.md); otherwise, an error message would appear. 2. Hover over an intended chat assistant **>** **Edit** to show the **iframe** window: ![chat-embed](https://github.com/user-attachments/assets/13ea3021-31c4-4a14-9b32-328cd3318fb5) diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 5dca6c83f..5693c10dd 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -3,7 +3,7 @@ sidebar_position: 0 slug: / --- -# Quick start +# Get started import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import APITable from '@site/src/components/APITable'; diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.md index 920ff08cb..f66794a5e 100644 --- a/docs/references/http_api_reference.md +++ b/docs/references/http_api_reference.md @@ -5,7 +5,7 @@ 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). +A complete reference for RAGFlow's RESTful API. Before proceeding, please ensure you [have your RAGFlow API key ready for authentication](../guides/models/llm_api_key_setup.md). --- diff --git a/docs/references/python_api_reference.md b/docs/references/python_api_reference.md index 2d69b5424..b96ab9068 100644 --- a/docs/references/python_api_reference.md +++ b/docs/references/python_api_reference.md @@ -5,7 +5,7 @@ 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). +A complete reference for RAGFlow's Python APIs. Before proceeding, please ensure you [have your RAGFlow API key ready for authentication](../guides/models/llm_api_key_setup.md). :::tip NOTE Run the following command to download the Python SDK: diff --git a/docs/release_notes.md b/docs/release_notes.md index b99800e75..94dc2b93d 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -3,7 +3,7 @@ sidebar_position: 2 slug: /release_notes --- -# Release notes +# Releases Key features, improvements and bug fixes in the latest releases. @@ -17,7 +17,7 @@ Released on February 6, 2025. - GraphRAG refactor: Knowledge graph is dynamically built on an entire knowledge base (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 knowledge base to enhance AI-powered chats. See [here](./guides/configure_knowledge_base/set_metadata.md). +- Allows setting metadata for a specific file in a knowledge base 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** knowledge base as a key milestone towards bridging the semantic gap between query and response. @@ -30,8 +30,8 @@ The **Tag knowledge base** feature is *unavailable* on the [Infinity](https://gi #### Added documents -- [Construct knowledge graph](./guides/configure_knowledge_base/construct_knowledge_graph.md) -- [Set metadata](./guides/configure_knowledge_base/set_metadata.md) +- [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)