mirror of
https://github.com/infiniflow/ragflow.git
synced 2026-11-10 21:32:43 +08:00
docs： update FAQs (#19538)
Update FAQs Recover the deleted sandbox_quickstart.md
This commit is contained in:
YanZhang authored and 
GitHub committed
1 parent
a36615c6fa
commit
9386b42eae
4 files changed
+390
-112
No files matched your search
@@ -0,0 +1,241 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Sandbox Quickstart
|
||||
sidebar_label: Sandbox Quickstart
|
||||
slug: /sandbox_quickstart
|
||||
sidebar_custom_props: {
|
||||
categoryIcon: LucideCog
|
||||
}
|
||||
---
|
||||
# Sandbox quickstart
|
||||
|
||||
RAGFlow's `CodeExec` agent component needs a sandbox provider to run Python and JavaScript code.
|
||||
|
||||
The simplest setup flow is:
|
||||
|
||||
1. Start the required sandbox services.
|
||||
2. Open the RAGFlow admin page.
|
||||
3. Go to **Admin > Sandbox Settings**.
|
||||
4. Choose a provider and save the configuration.
|
||||
5. Test the connection in the same page.
|
||||
|
||||
## Admin page
|
||||
|
||||
Configure sandbox providers from the admin page:
|
||||
|
||||
- `self_managed`: Uses the executor manager service.
|
||||
- `local`: Runs code on the current machine.
|
||||
- `ssh`: Runs code on a remote machine over SSH.
|
||||
- `aliyun_codeinterpreter`, `e2b`, and `tenki`: Cloud providers.
|
||||
|
||||
<img width="2547" height="1475" alt="admin-sandbox-settings" src="https://github.com/user-attachments/assets/59ab948e-b98a-45a8-9db4-f1afbf6c3685" />
|
||||
|
||||
## Provider options
|
||||
|
||||
|
||||
RAGFlow supports multiple sandbox providers. Configure the active provider in
|
||||
Admin > Sandbox Settings after the services are up.
|
||||
|
||||
- `self_managed`: Runs code inside Docker-managed sandbox containers. This is the default provider.
|
||||
- `local`: Runs code as local Python or Node.js subprocesses. Use this only in trusted development environments.
|
||||
- `ssh`: Runs code on a remote machine over SSH.
|
||||
- `aliyun_codeinterpreter` and `e2b`: Cloud-hosted providers that remain available in the admin provider list.
|
||||
- `tenki`: Cloud-hosted provider that runs each execution in a disposable [Tenki](https://tenki.cloud) microVM. See [Tenki](#tenki) below.
|
||||
|
||||
### Tenki
|
||||
|
||||
`tenki` runs each code execution in a fresh Tenki microVM and destroys it afterwards. It is cloud-hosted, so it needs no local sandbox services, gVisor, or Docker base images — only outbound network access and an API key.
|
||||
|
||||
The `tenki-sandbox` SDK is an optional dependency (it requires `protobuf>=6.31`, which differs from RAGFlow's default gRPC stack), so it is not installed by default. Install it into the RAGFlow runtime before selecting this provider:
|
||||
|
||||
```bash
|
||||
pip install tenki-sandbox
|
||||
```
|
||||
|
||||
Configure it in **Admin > Sandbox Settings**:
|
||||
|
||||
- `api_key` (required): Tenki API key. Create one at [app.tenki.cloud](https://app.tenki.cloud) under **API Keys**.
|
||||
- `project_id` (required): the Tenki project that sandboxes are created under.
|
||||
- `base_url` (optional): override the Tenki API endpoint.
|
||||
- `image` (optional): sandbox base image. Leave empty to use the Tenki default image, which includes `python3` and `node`.
|
||||
- `allow_outbound` (optional, security-relevant): whether the sandbox may make outbound network connections. Defaults to `false` so sandboxed code has no network access; set it to `true` when code needs the network (for example, to install packages).
|
||||
- `timeout`, `max_lifetime`, `cpu_cores`, `memory_mb`, `disk_size_gb`, and the output/artifact limits have sensible defaults and can be tuned in the same page.
|
||||
|
||||
Notes:
|
||||
|
||||
- Supported languages are Python and JavaScript.
|
||||
- Files written to the `artifacts/` directory of the working directory are returned as run artifacts.
|
||||
- The provider uses only Tenki's create/exec/destroy operations; it does not use volumes or snapshots.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Linux distribution compatible with gVisor.
|
||||
- gVisor installed and configured.
|
||||
- Docker version 25.0 or higher (API 1.44+). Ensure your executor manager image ships with Docker CLI `29.1.0` or higher to stay compatible with the latest Docker daemons.
|
||||
- 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.
|
||||
|
||||
:::tip NOTE
|
||||
The error message `client version 1.43 is too old. Minimum supported API version is 1.44` indicates that your executor manager image's built-in Docker CLI version is lower than `29.1.0` required by the Docker daemon in use.
|
||||
:::
|
||||
|
||||
## Build Docker base images
|
||||
|
||||
The sandbox uses isolated base images for secure containerized execution environments.
|
||||
|
||||
### Option 1: Build from source
|
||||
|
||||
Build the runtime base images:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Build the executor manager image:
|
||||
|
||||
```bash
|
||||
docker build -t sandbox-executor-manager:latest ./executor_manager
|
||||
```
|
||||
|
||||
### Option 2: Pull base images from Docker Hub
|
||||
|
||||
If you do not need to customize runtime dependencies, pull the published base images and tag them with the names used by standalone Docker Compose:
|
||||
|
||||
```bash
|
||||
docker pull infiniflow/sandbox-base-python:latest
|
||||
docker pull infiniflow/sandbox-base-nodejs:latest
|
||||
|
||||
docker tag infiniflow/sandbox-base-python:latest sandbox-base-python:latest
|
||||
docker tag infiniflow/sandbox-base-nodejs:latest sandbox-base-nodejs:latest
|
||||
```
|
||||
|
||||
Then restart the standalone sandbox services:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.yml down
|
||||
docker compose -f docker-compose.yml up -d
|
||||
```
|
||||
|
||||
## Running with RAGFlow
|
||||
|
||||
1. Verify that gVisor is properly installed and operational.
|
||||
|
||||
2. Configure the .env file located at docker/.env:
|
||||
|
||||
- Set `SANDBOX_ENABLED=1`.
|
||||
- Include `sandbox` in `COMPOSE_PROFILES` if you want the default
|
||||
`self_managed` executor-manager service.
|
||||
- Keep the self-managed deployment defaults in `.env` if you need to change the
|
||||
sandbox-executor-manager image, pool size, base images, seccomp, memory, or
|
||||
timeout.
|
||||
|
||||
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.
|
||||
5. Open **Admin > Sandbox Settings**.
|
||||
6. Select a provider.
|
||||
7. Fill in the required fields.
|
||||
8. Click **Save**.
|
||||
9. Click **Test Connection** if needed.
|
||||
|
||||
## Environment variables
|
||||
|
||||
The variables in `docker/.env` are grouped by scope.
|
||||
|
||||
### System-level variables
|
||||
|
||||
These variables apply to sandbox support in general:
|
||||
|
||||
- `SANDBOX_ENABLED`: Enables sandbox support in RAGFlow.
|
||||
- `COMPOSE_PROFILES`: Include `sandbox` to start the default self-managed executor-manager service.
|
||||
- `SANDBOX_ARTIFACT_BUCKET`: MinIO bucket used for files generated by sandbox code.
|
||||
- `SANDBOX_ARTIFACT_EXPIRE_DAYS`: Number of days before sandbox artifacts expire.
|
||||
|
||||
### Self-managed deployment defaults
|
||||
|
||||
These variables are shown in Admin as deployment defaults for `self_managed`.
|
||||
Changing them requires restarting `sandbox-executor-manager`.
|
||||
|
||||
- `SANDBOX_EXECUTOR_MANAGER_IMAGE`: Docker image for the executor manager service.
|
||||
- `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE`: Number of Python and Node.js sandbox containers kept in the pool.
|
||||
- `SANDBOX_BASE_PYTHON_IMAGE`: Python runtime image used by executor-managed containers.
|
||||
- `SANDBOX_BASE_NODEJS_IMAGE`: Node.js runtime image used by executor-managed containers.
|
||||
- `SANDBOX_EXECUTOR_MANAGER_PORT`: Host port exposed by the executor manager.
|
||||
- `SANDBOX_ENABLE_SECCOMP`: Enables the optional seccomp profile for sandbox containers.
|
||||
- `SANDBOX_MAX_MEMORY`: Memory limit for each sandbox runtime container.
|
||||
- `SANDBOX_TIMEOUT`: Default execution timeout.
|
||||
|
||||
### Admin-managed runtime settings
|
||||
|
||||
Provider selection and runtime settings are configured in **Admin > Sandbox Settings**.
|
||||
|
||||
Examples:
|
||||
|
||||
- Choose the active provider
|
||||
- Configure `self_managed` runtime settings
|
||||
- Configure all `local` settings
|
||||
- Configure all `ssh` settings
|
||||
|
||||
For `self_managed`:
|
||||
|
||||
- Runtime settings are editable in Admin
|
||||
- Deployment defaults come from `.env` and are shown as read-only values
|
||||
|
||||
## 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
|
||||
```
|
||||
+133
-109
@@ -21,17 +21,16 @@ import TOCInline from '@theme/TOCInline';
|
||||
|
||||
### 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.
|
||||
RAGFlow provides an end-to-end RAG platform that goes beyond basic document chunking and retrieval. Its key strengths include:
|
||||
|
||||
- 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.
|
||||
- **Deep document understanding** for complex content such as text, tables, and images.
|
||||
- **Flexible retrieval and traceable answers** with multiple retrieval strategies, reranking, and citations.
|
||||
- **Agentic capabilities** for multi-step retrieval, reasoning, tool use, and workflows.
|
||||
- **Knowledge compilation** for organizing documents into structured knowledge artifacts.
|
||||
- **Broad model and integration support** for building different RAG applications.
|
||||
|
||||
---
|
||||
|
||||
### Which embedding models can be deployed locally?
|
||||
|
||||
Starting from `v0.22.0`, we ship only the slim edition and no longer append the **-slim** suffix to the image tag.
|
||||
|
||||
---
|
||||
|
||||
### Where to find the version of RAGFlow? How to interpret it?
|
||||
@@ -60,11 +59,11 @@ Where:
|
||||
|
||||
---
|
||||
|
||||
### Why not use other open-source vector databases as the document engine?
|
||||
### Why does RAGFlow use Elasticsearch or Infinity as its default 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.
|
||||
Elasticsearch and [Infinity](https://github.com/infiniflow/infinity) meet RAGFlow's core hybrid search requirements, including full-text search, vector search, phrase search, and advanced ranking capabilities.
|
||||
RAGFlow also supports other document engines, including OpenSearch, OceanBase, SeekDB, and GaussDB. Support levels and available features may vary between document engines.
|
||||
[Infinity](https://github.com/infiniflow/infinity) is an AI-native database developed by InfiniFlow and optimized for RAG workloads.
|
||||
|
||||
---
|
||||
|
||||
@@ -76,21 +75,17 @@ You can deploy an open-source RAGFlow service and call it from a Python client o
|
||||
|
||||
---
|
||||
|
||||
### Why does it take longer for RAGFlow to parse a document than LangChain?
|
||||
### Why does RAGFlow require substantial system resources?
|
||||
|
||||
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.
|
||||
RAGFlow runs multiple components for document parsing, embedding, full-text and vector indexing, retrieval, task processing, metadata storage, caching, and object storage. Some document parsers also load or download machine-learning models and may require significant memory or GPU resources.
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
Actual resource usage depends on the selected document engine, parser, model provider, document volume, and workload. See the deployment prerequisites and configuration documentation for the current minimum requirements.
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
We officially support x86 CPUs and NVIDIA GPUs. 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.
|
||||
|
||||
---
|
||||
|
||||
@@ -118,28 +113,12 @@ RESTful:
|
||||
|
||||
---
|
||||
|
||||
### Do you support sharing dialogue through URL?
|
||||
### Key differences between search and chat?
|
||||
|
||||
No, this feature is not supported.
|
||||
- **Search** is designed for direct knowledge retrieval. It retrieves and ranks relevant content from one or more datasets and presents the results for users to review.
|
||||
- **Chat** is designed for conversational question answering. It retrieves relevant knowledge and uses an LLM to generate answers, supporting multi-turn conversations and more advanced retrieval capabilities such as Agentic Retrieval.
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
Use **Search** when you want to find and inspect relevant knowledge directly, and **Chat** when you want generated answers based on that knowledge.
|
||||
|
||||
---
|
||||
|
||||
@@ -160,9 +139,11 @@ See [Build a RAGFlow Docker image](./develop/build_docker_image.mdx).
|
||||
|
||||
---
|
||||
|
||||
### Cannot access https://huggingface.co
|
||||
### PDF parsing fails because required Hugging Face models cannot be downloaded
|
||||
|
||||
A locally deployed RAGFlow downloads OCR models 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:
|
||||
Some RAGFlow document parsers download required model files from [Hugging Face](https://huggingface.co). If the RAGFlow container cannot access Hugging Face and the files are not already cached, model initialization or document parsing may fail.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
FileNotFoundError: [Errno 2] No such file or directory: '/root/.cache/huggingface/hub/models--InfiniFlow--deepdoc/snapshots/be0c1e50eef6047b412d1800aa89aba4d275f997/ocr.res'
|
||||
@@ -193,7 +174,11 @@ To fix this issue, use https://hf-mirror.com instead:
|
||||
|
||||
### `Fail to access model(Ollama/xxxxx)`
|
||||
|
||||
Ollama may time out or fail during its first model load due to memory constraints or out-of-memory (OOM). It is best to test your local model in isolation first. If sharing hardware with other services, memory exhaustion is likely. To resolve this, switch to a smaller model or increase RAM.
|
||||
This error means that RAGFlow cannot access the configured Ollama model. Check that Ollama is running, the model has been downloaded, the model name is correct, and the Ollama Base URL is reachable from the RAGFlow container.
|
||||
|
||||
If the request times out while loading the model, check the Ollama logs and available memory. Try a smaller model or allocate more memory if necessary.
|
||||
|
||||
See [Deploy a local LLM](./guides/models/deploy_local_llm.mdx) for more information.
|
||||
|
||||
---
|
||||
|
||||
@@ -202,7 +187,7 @@ Ollama may time out or fail during its first model load due to memory constraint
|
||||
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:
|
||||
2. Add a volume mapping to **docker/docker-compose.yml**, for example:
|
||||
|
||||
```
|
||||
- ~/deepdoc:/ragflow/rag/res/deepdoc
|
||||
@@ -224,12 +209,6 @@ To resolve this, either download the missing file from the corresponding tag on
|
||||
|
||||
---
|
||||
|
||||
### `WARNING: can't find /ragflow/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.`
|
||||
|
||||
|
||||
@@ -248,8 +227,8 @@ You will not log in to RAGFlow unless the server is fully initialized. Run `dock
|
||||
* 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
|
||||
```
|
||||
Then use the [system health API](./references/http_api_reference.md#check-system-health) to check the database, Redis, document engine, and object storage.
|
||||
|
||||
---
|
||||
|
||||
@@ -263,7 +242,7 @@ Ignore this warning and continue. All system warnings can be ignored.
|
||||
|
||||
### `xxx tasks are ahead in the queue`
|
||||
|
||||
### For RAGFlow versions earlier than v0.26.0
|
||||
#### For RAGFlow versions earlier than v0.26.0
|
||||
|
||||
1. Clear the Redis task queue:
|
||||
|
||||
@@ -283,7 +262,7 @@ FLUSHDB
|
||||
|
||||
```bash
|
||||
# Option 1: Restart specific container
|
||||
docekr restart docker-redis-1 docker-ragflow-cpu-1
|
||||
docker restart docker-redis-1 docker-ragflow-cpu-1
|
||||
|
||||
# Option 2: Recreate containers via Docker Compose
|
||||
docker compose -f docker/docker-compose.yml down
|
||||
@@ -295,7 +274,7 @@ docker stop $(docker ps -aq)
|
||||
docker rm $(docker ps -aq)
|
||||
```
|
||||
|
||||
### For RAGFlow v0.26.0 and later
|
||||
#### For RAGFlow v0.26.0 and later
|
||||
|
||||
1. Clear the Redis task queue:
|
||||
|
||||
@@ -305,17 +284,18 @@ $ docker exec -it ragflow-redis /bin/bash
|
||||
$ redis-cli -a infini_rag_flow
|
||||
# In redis-cli
|
||||
select 1
|
||||
XGROUP DESTROY te.0.common_queue te.0.common_task_broker
|
||||
XGROUP CREATE te.0.common_queue te.0.common_task_broker $ MKSTREAM
|
||||
# When CREATE raises and error:
|
||||
FLUSHDB
|
||||
XGROUP DESTROY te.0.common rag_flow_svr_task_broker
|
||||
XGROUP CREATE te.0.common rag_flow_svr_task_broker $ MKSTREAM
|
||||
|
||||
XGROUP DESTROY te.1.common rag_flow_svr_task_broker
|
||||
XGROUP CREATE te.1.common rag_flow_svr_task_broker $ MKSTREAM
|
||||
```
|
||||
|
||||
2. If the parser remains stuck at 0%, restart the RAGFlow containers using one of the following methods:
|
||||
|
||||
```bash
|
||||
# Option 1: Restart specific container
|
||||
docekr restart docker-redis-1 docker-ragflow-cpu-1
|
||||
docker restart docker-redis-1 docker-ragflow-cpu-1
|
||||
|
||||
# Option 2: Recreate containers via Docker Compose
|
||||
docker compose -f docker/docker-compose.yml down
|
||||
@@ -369,7 +349,9 @@ docker compose up -d
|
||||
|
||||
### `Index failure`
|
||||
|
||||
An index failure usually indicates an unavailable Elasticsearch service.
|
||||
An index failure means that RAGFlow could not write the processed document chunks to the configured document engine.
|
||||
|
||||
Check the task logs, embedding model, document engine connection, and system health. If you use Elasticsearch, OpenSearch, Infinity, or another supported document engine, verify that the corresponding service is running and accessible.
|
||||
|
||||
---
|
||||
|
||||
@@ -383,26 +365,20 @@ 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:
|
||||
1. Check the status of the RAGFlow Docker container:
|
||||
|
||||
```bash
|
||||
$ docker ps
|
||||
$ docker compose ps
|
||||
```
|
||||
|
||||
*The following is an example result:*
|
||||
|
||||
Review the service logs:
|
||||
```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 docker-ragflow-cpu-1
|
||||
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 pgsty/silo:RELEASE.2026-08-06T00-00-00Z "/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
|
||||
docker compose logs -f ragflow
|
||||
|
||||
```
|
||||
|
||||
2. Follow [the system health API](./references/http_api_reference.md#check-system-health) to check the health status of the Elasticsearch service.
|
||||
2. Use the [system health API](./references/http_api_reference.md#check-system-health) to check the database, Redis, document engine, and object storage.
|
||||
|
||||
:::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.
|
||||
:::
|
||||
A running container does not necessarily mean that the service inside it is healthy. Check the health API and logs for connection, port, DNS, and configuration errors.
|
||||
|
||||
---
|
||||
|
||||
@@ -500,30 +476,21 @@ See [Deploy a local LLM](./guides/models/deploy_local_llm.mdx) for more informat
|
||||
|
||||
### 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.
|
||||
Yes. See the parser entry points and examples in the [`rag/app`](https://github.com/infiniflow/ragflow/tree/main/rag/app) directory.
|
||||
|
||||
For example, `rag/app/naive.py` shows how RAGFlow selects and invokes document parsers for different file types.
|
||||
|
||||
---
|
||||
|
||||
### `FileNotFoundError: [Errno 2] No such file or directory`
|
||||
|
||||
1. Check the status of the MinIO Docker container:
|
||||
This error means that RAGFlow cannot find a required file. Check the complete error message and stack trace to identify the missing path.
|
||||
|
||||
```bash
|
||||
$ docker ps
|
||||
```
|
||||
|
||||
*The status of a healthy Elasticsearch component should look as follows:*
|
||||
|
||||
```bash
|
||||
cd29bcb254bc pgsty/silo:RELEASE.2026-08-06T00-00-00Z "/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 [the system health API](./references/http_api_reference.md#check-system-health) 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.
|
||||
:::
|
||||
- If a model file is missing, check whether the required model was downloaded successfully.
|
||||
- If an uploaded document is missing, check the configured object storage service.
|
||||
- If a temporary or local file is missing, check the container volume mappings and file permissions.
|
||||
|
||||
Use the [system health API](./references/http_api_reference.md#check-system-health) to verify the configured object storage and other dependencies.
|
||||
---
|
||||
|
||||
## Usage
|
||||
@@ -566,19 +533,6 @@ It is not recommended to manually change the 32-file batch upload limit. However
|
||||
|
||||
---
|
||||
|
||||
### `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.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### How to get an API key for integration with third-party applications?
|
||||
|
||||
See [Acquire a RAGFlow API key](./develop/acquire_ragflow_api_key.md).
|
||||
@@ -595,7 +549,11 @@ See [Upgrade RAGFlow](./administrator/upgrade_ragflow.mdx) for more information.
|
||||
|
||||
To switch your document engine from Elasticsearch to [Infinity](https://github.com/infiniflow/infinity):
|
||||
|
||||
1. Stop all running containers:
|
||||
:::danger WARNING
|
||||
Switching the document engine requires rebuilding the document indexes. The following command deletes Docker volumes and existing data. Back up any data you need before continuing.
|
||||
:::
|
||||
|
||||
1. Stop all running containers and remove the existing volumes:
|
||||
|
||||
```bash
|
||||
$ docker compose -f docker/docker-compose.yml down -v
|
||||
@@ -604,18 +562,25 @@ To switch your document engine from Elasticsearch to [Infinity](https://github.c
|
||||
`-v` will delete all Docker container volumes, and the existing data will be cleared.
|
||||
:::
|
||||
|
||||
2. In **docker/.env**, set `DOC_ENGINE=${DOC_ENGINE:-infinity}`
|
||||
2. Set the following value in **docker/.env** :
|
||||
|
||||
```env
|
||||
DOC_ENGINE=infinity
|
||||
```
|
||||
|
||||
3. Restart your Docker image:
|
||||
|
||||
```bash
|
||||
$ docker compose -f docker-compose.yml up -d
|
||||
$ docker compose -f docker/docker-compose.yml up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Where are my uploaded files stored in RAGFlow's image?
|
||||
### Where are uploaded files stored in RAGFlow?
|
||||
|
||||
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 `<knowledgebase_id>/filename`.
|
||||
Uploaded files are stored in the configured object storage backend. MinIO is used by default, while other supported options include Amazon S3, Azure Blob Storage, Alibaba Cloud OSS, Google Cloud Storage, and OpenDAL-compatible storage.
|
||||
|
||||
The internal bucket and object path depend on how and where the file was uploaded. Manage uploaded files through RAGFlow instead of relying on a fixed storage path.
|
||||
|
||||
---
|
||||
|
||||
@@ -625,6 +590,67 @@ You can control the batch size for document parsing and embedding by setting the
|
||||
|
||||
---
|
||||
|
||||
### Why can't I retrieve relevant content in Search or Chat even though the document was parsed successfully?
|
||||
|
||||
Successful parsing only means that the document has been parsed and chunked. It does not guarantee that relevant content can be retrieved.
|
||||
|
||||
First, use **Retrieval testing** to check whether the expected chunks can be retrieved. If not, check the chunking results, embedding model, similarity threshold, and reranker settings. If the expected chunks are retrieved but Chat still gives an incorrect answer, check the Chat retrieval settings, system prompt, and LLM.
|
||||
|
||||
---
|
||||
|
||||
### Why does the same query produce different results in Retrieval testing, Search, and Chat?
|
||||
|
||||
**Retrieval testing** is mainly used to evaluate whether relevant chunks can be retrieved from a dataset. **Search** further filters and ranks retrieved content according to its configuration, while **Chat** uses the retrieved content as context for an LLM to generate an answer.
|
||||
|
||||
Therefore, even when using the same dataset, differences in retrieval settings, reranking, and answer generation can lead to different results.
|
||||
|
||||
---
|
||||
|
||||
### How can I tell whether a problem comes from document parsing, chunking, retrieval, or answer generation?
|
||||
|
||||
Check the RAG pipeline step by step:
|
||||
|
||||
1. Verify that the document has been parsed correctly.
|
||||
2. Check whether the resulting chunks contain the expected content.
|
||||
3. Use **Retrieval testing** to verify that the relevant chunks can be retrieved.
|
||||
4. If retrieval works correctly but Chat or Agent produces an unexpected answer, check the application settings, system prompt, and LLM.
|
||||
|
||||
This helps identify which stage of the pipeline is causing the problem.
|
||||
|
||||
---
|
||||
|
||||
### Can the same dataset be used by Search, Chat, and Agent?
|
||||
|
||||
Yes. The same dataset can be used by different knowledge applications and Agents.
|
||||
|
||||
The dataset manages and indexes the underlying knowledge, while Search, Chat, and Agent use that knowledge in different ways. Changing application-level settings generally does not modify the original documents or chunks in the dataset.
|
||||
|
||||
---
|
||||
|
||||
### Should I adjust chunking, retrieval settings, or models first?
|
||||
|
||||
Start by verifying that the document is parsed and chunked correctly. Then use **Retrieval testing** to evaluate retrieval quality.
|
||||
|
||||
If retrieval needs improvement, adjust settings such as the similarity threshold, vector similarity weight, or reranker. If retrieval results are already relevant but the generated answer is still unsatisfactory, consider adjusting the prompt or changing the LLM.
|
||||
|
||||
---
|
||||
|
||||
### What needs to be reprocessed after changing the embedding model, reranker, or LLM?
|
||||
|
||||
- Changing the **embedding model** requires rebuilding the document indexes. RAGFlow does not normally allow you to change the embedding model after documents in the dataset have been parsed. Create a new dataset or remove the existing parsed data before using another embedding model.
|
||||
- Changing the **reranker** affects only the ranking of retrieved results and does not require reparsing the documents.
|
||||
- Changing the **LLM** affects query understanding and answer generation and does not normally require reparsing the dataset.
|
||||
|
||||
---
|
||||
|
||||
### Why can the model still hallucinate when the answer exists in the dataset?
|
||||
|
||||
Having the correct information in the dataset does not guarantee that it will be retrieved or that the LLM will strictly follow the retrieved context.
|
||||
|
||||
Check whether the content has been indexed correctly, whether the relevant chunks are retrieved, and whether the model uses the retrieved context appropriately when generating its answer.
|
||||
|
||||
---
|
||||
|
||||
### How to accelerate the question-answering speed of my chat assistant?
|
||||
|
||||
To reduce response latency, consider the following:
|
||||
@@ -635,8 +661,6 @@ To reduce response latency, consider the following:
|
||||
- Use a reranker only when it provides a meaningful improvement in retrieval quality.
|
||||
- Make sure the deployed model service has sufficient computing resources and low network latency.
|
||||
|
||||
See [here](./guides/chat/best_practices/accelerate_question_answering.mdx).
|
||||
|
||||
---
|
||||
|
||||
### How to accelerate the question-answering speed of my Agent?
|
||||
|
||||
+11
-3
@@ -1,8 +1,8 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
title: Multimodel Comparison
|
||||
sidebar_label: Multimodel_Comparison
|
||||
slug: /chat_Multimodel_Comparison
|
||||
title: Multimodel Comparison & FAQ
|
||||
sidebar_label: Multimodel_Comparison_and_FAQ
|
||||
slug: /chat_Multimodel_Comparison_and_FAQ
|
||||
sidebar_custom_props:
|
||||
categoryIcon: LucideTestTube
|
||||
---
|
||||
@@ -21,3 +21,11 @@ Select the models to compare, enter a test question, and run the comparison. Foc
|
||||
|
||||
Use representative questions from actual business scenarios instead of selecting a model based on a single question. Multi-model comparison is primarily intended for model selection and debugging. For example, after changing a model provider or model version, use the same questions to quickly compare the practical performance of the old and new models.
|
||||
|
||||
# FAQ
|
||||
## 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.
|
||||
@@ -107,6 +107,11 @@ The following screenshot shows retrieval testing using the knowledge graph. It s
|
||||
|
||||
Yes. Your LLM participates in analyzing your query and extracting relevant entities and relationships from the knowledge graph. This also explains why extra tokens and time are consumed.
|
||||
|
||||
#### 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.
|
||||
|
||||
|
||||
## Best Practices: Index Acceleration
|
||||
|
||||
A checklist for accelerating document parsing and indexing.
|
||||
|
||||
Reference in new issue
Block a user