docs/faq.mdx
Answers to questions about general features, troubleshooting, usage, and more.
import TOCInline from '@theme/TOCInline';
<TOCInline toc={toc} />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.
Starting from v0.22.0, we ship only the slim edition and no longer append the -slim suffix to the image tag.
You can find the RAGFlow version number on the System page of the UI:
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
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.Currently, only Elasticsearch and 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, the AI-native database, from the ground up.
cloud.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, cloud.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 cloud.ragflow.io.
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 has a number of built-in models for document structure parsing, which account for the additional computational resources.
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 to build a RAGFlow Docker image.
The corresponding APIs are now available. See the RAGFlow HTTP API Reference or the RAGFlow Python API Reference for more information.
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:
RESTful:
No, this feature is not supported.
Yes, we support enhancing user queries based on existing context of an ongoing conversation:
When debugging your chat assistant, you can use AI search as a reference to verify your model settings and retrieval strategy.
Request error 404: undefined when upgrading to v0.25.1To resolve this issue, do either of the following:
RAGFLOW_IMAGE from infiniflow/ragflow:latest to infiniflow/ragflow:v0.25.1 in the .env file, then restart the service.See Build a RAGFlow Docker image.
A locally deployed RAGFlow downloads OCR models from Huggingface website 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:
Stop all containers and remove all related resources:
cd ragflow/docker/
docker compose down
Uncomment the following line in ragflow/docker/.env:
# HF_ENDPOINT=https://hf-mirror.com
Start up the server:
docker compose up -d
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.
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:
Manually download the resource files from huggingface.co/InfiniFlow/deepdoc to your local folder ~/deepdoc.
Add a volumes to docker-compose.yml, for example:
- ~/deepdoc:/ragflow/rag/res/deepdoc
RuntimeError: Unable to start Tika server.This error is almost always caused by Java not being installed or not accessible in the environment. See here for detailed instructions.
Cannot stat '/etc/nginx/conf.d/ragflow.conf.python': No such file or directoryTo resolve this, either download the missing file from the corresponding tag on GitHub or update ~/ragflow/docker/docker-compose.yml as follows:
WARNING: can't find /ragflow/rag/res/borker.tmIgnore 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.You will not log in to RAGFlow unless the server is fully initialized. Run docker logs -f docker-ragflow-cpu-1.
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 connectionIgnore this warning and continue. All system warnings can be ignored.
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:
Check the log of your RAGFlow server to see if it is running properly:
docker logs -f docker-ragflow-cpu-1
Check if the task_executor.py process exists.
Check if your RAGFlow server can access hf-mirror.com or huggingface.com.
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!
docker compose stop
docker compose up -d
:::
Index failureAn index failure usually indicates an unavailable Elasticsearch service.
tail -f ragflow/docker/ragflow-logs/*.log
Check the status of the Elasticsearch Docker container:
$ docker ps
The following is an example result:
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 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
Follow this document 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 clusterCheck the status of the Elasticsearch Docker container:
$ 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
Follow this document 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 your container keeps restarting, ensure vm.max_map_count >= 262144 as per this README. 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.
Elasticsearch did not exit normallyThis 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":"<NotFound '404: Not Found'>"}Your IP address or port number may be incorrect. If you are using the default configurations, enter http://<IP_OF_YOUR_MACHINE> (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 RagFlowA correct Ollama IP address and port is crucial to adding models to Ollama:
See Deploy a local LLM for more information.
Yes, we do. See the Python files under the rag/app folder.
FileNotFoundError: [Errno 2] No such file or directoryCheck the status of the MinIO Docker container:
$ docker ps
The status of a healthy Elasticsearch component should look as follows:
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
Follow this document 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. :::
You can use Ollama or Xinference to deploy local LLM. See here for more information.
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:
See here for more information.
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:
# MAX_CONTENT_LENGTH=1073741824, adjust the value as needed, and note that 1073741824 represents 1GB in bytes.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:
See Acquire a RAGFlow API key.
See Upgrade RAGFlow for more information.
To switch your document engine from Elasticsearch to Infinity:
Stop all running containers:
$ 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.
:::
In docker/.env, set DOC_ENGINE=${DOC_ENGINE:-infinity}
Restart your Docker image:
$ docker compose -f docker-compose.yml up -d
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.
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.
See here.
See here.
From v0.22.0 onwards, RAGFlow includes MinerU (≥ 2.6.3) as an optional PDF parser of multiple backends. Please note that RAGFlow acts only as a remote client for MinerU, calling the MinerU API to parse PDFs and reading the returned files. To use this feature:
MINERU_APISERVER: The MinerU API endpoint (e.g., http://mineru-host:8886).MINERU_BACKEND: The MinerU backend:
"pipeline" (default)"vlm-http-client""vlm-transformers""vlm-vllm-engine""vlm-mlx-engine""vlm-vllm-async-engine""vlm-lmdeploy-engine".MINERU_SERVER_URL: (optional) The downstream vLLM HTTP server (e.g., http://vllm-host:30000). Applicable when MINERU_BACKEND is set to "vlm-http-client".MINERU_OUTPUT_DIR: (optional) The local directory for holding the outputs of the MinerU API service (zip/JSON) before ingestion.MINERU_DELETE_OUTPUT: Whether to delete temporary output when a temporary directory is used:
1: Delete.0: Retain.:::note All MinerU environment variables are optional. When set, these values are used to auto-provision a MinerU OCR model for the tenant on first use. To avoid auto-provisioning, skip the environment variable settings and only configure MinerU from the Model providers page in the UI. :::
The table below summarizes the most frequently used MinerU environment variables for remote MinerU:
| Environment variable | Description | Default | Example |
|---|---|---|---|
MINERU_APISERVER | URL of the MinerU API service | unset | MINERU_APISERVER=http://your-mineru-server:8886 |
MINERU_BACKEND | MinerU parsing backend | pipeline | MINERU_BACKEND=pipeline|vlm-transformers|vlm-vllm-engine|vlm-mlx-engine|vlm-vllm-async-engine|vlm-http-client |
MINERU_SERVER_URL | URL of remote vLLM server (for vlm-http-client) | unset | MINERU_SERVER_URL=http://your-vllm-server-ip:30000 |
MINERU_OUTPUT_DIR | Directory for MinerU output files | System-defined temporary directory | MINERU_OUTPUT_DIR=/home/ragflow/mineru/output |
MINERU_DELETE_OUTPUT | Whether to delete MinerU output directory when a temp dir is used | 1 (delete temp output) | MINERU_DELETE_OUTPUT=0 |
MINERU_APISERVER to point RAGFlow to your MinerU API server.MINERU_BACKEND to specify a parsing backend."vlm-http-client" backend, set MINERU_SERVER_URL to your vLLM server's URL. MinerU API expects backend=vlm-http-client and server_url=http://<server>:30000 in the request body.MINERU_OUTPUT_DIR to specify where RAGFlow stores MinerU API output; otherwise, a system temp directory is used.MINERU_DELETE_OUTPUT to 0 to keep MinerU's temp output (useful for debugging).:::tip NOTE For information about other environment variables natively supported by MinerU, see here. :::
RAGFlow supports MinerU's vlm-http-client backend, enabling you to delegate document parsing tasks to a remote vLLM server while calling MinerU via HTTP. To configure:
http://mineru-host:8886).http://vllm-host:30000).MINERU_APISERVER=http://mineru-host:8886MINERU_BACKEND="vlm-http-client"MINERU_SERVER_URL="http://vllm-host:30000"
MinerU API calls expect backend=vlm-http-client and server_url=http://<server>:30000 in the request body.MINERU_OUTPUT_DIR / MINERU_DELETE_OUTPUT as desired to manage the returned zip/JSON before ingestion.:::tip NOTE
When using the vlm-http-client backend, the RAGFlow server requires no GPU, only network connectivity. This enables cost-effective distributed deployment with multiple RAGFlow instances sharing one remote vLLM server.
:::
RAGFlow supports Docling in two modes:
USE_DOCLING=true) and parse in-process.To enable remote mode, set:
DOCLING_SERVER_URL=http://your-docling-serve-host:5001
Behavior:
DOCLING_SERVER_URL is set, RAGFlow sends PDFs to Docling Serve using /v1/convert/source (and falls back to /v1alpha/convert/source for older servers).DOCLING_SERVER_URL is not set, RAGFlow uses local in-process Docling.From v0.24.0 onwards, RAGFlow includes PaddleOCR as an optional PDF parser. Please note that RAGFlow acts only as a remote client for PaddleOCR, calling the PaddleOCR API to parse PDFs and reading the returned files.
There are two main ways to configure and use PaddleOCR in RAGFlow:
This method uses PaddleOCR's official API service with an access token.
Step 1: Configure RAGFlow
Via Environment Variables:
# In your docker/.env file:
PADDLEOCR_API_URL=https://your-paddleocr-api-endpoint
PADDLEOCR_ALGORITHM=PaddleOCR-VL
PADDLEOCR_ACCESS_TOKEN=your-access-token-here
Via UI:
Step 2: Usage in Dataset Configuration
Notes:
API_URL.This method allows you to deploy your own PaddleOCR service and use it without an access token.
Step 1: Deploy PaddleOCR Service Follow the PaddleOCR serving documentation to deploy your own service. For layout parsing, you can use an endpoint like:
http://localhost:8080/layout-parsing
Step 2: Configure RAGFlow
Via Environment Variables:
PADDLEOCR_API_URL=http://localhost:8080/layout-parsing
PADDLEOCR_ALGORITHM=PaddleOCR-VL
# No access token required for self-hosted service
Via UI:
Step 3: Usage in Dataset Configuration
| Environment Variable | Description | Default | Required |
|---|---|---|---|
PADDLEOCR_API_URL | PaddleOCR API endpoint URL | "" | Yes, when using environment variables |
PADDLEOCR_ALGORITHM | Algorithm to use for parsing | "PaddleOCR-VL" | No |
PADDLEOCR_ACCESS_TOKEN | Access token for official API | None | Only when using official API |
Environment variables can be used for auto-provisioning, but are not required if configuring via UI. When environment variables are set, these values are used to auto-provision a PaddleOCR model for the tenant on first use.