Skip to main content

FAQs

Answers to questions about general features, troubleshooting, usage, and more.

General features

What sets RAGFlow apart from other RAG products?

RAGFlow provides an end-to-end RAG platform that goes beyond basic document chunking and retrieval. Its key strengths include:

  • 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.

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

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.

Why does RAGFlow use Elasticsearch or Infinity as its default document engine?

Elasticsearch and 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 is an AI-native database developed by InfiniFlow and optimized for RAG workloads.

Differences between cloud.ragflow.io and a locally deployed open-source RAGFlow service?

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.

Why does RAGFlow require substantial system resources?

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.

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 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 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 or the RAGFlow Python API Reference 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:

RESTful:

Key differences between search and chat?

  • 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.

Use Search when you want to find and inspect relevant knowledge directly, and Chat when you want generated answers based on that knowledge.

Troubleshooting

Get a Request error 404: undefined when upgrading to v0.27.2

To resolve this issue, do either of the following:

  • Pull the latest source code from the main branch, then pull and start the v0.27.2 image.
  • Update RAGFLOW_IMAGE from infiniflow/ragflow:latest to infiniflow/ragflow:v0.27.2 in the .env file, then restart the service.

How to build the RAGFlow image from scratch?

See Build a RAGFlow Docker image.

PDF parsing fails because required Hugging Face models cannot be downloaded

Some RAGFlow document parsers download required model files from Hugging Face. 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'

To fix this issue, use https://hf-mirror.com instead:

  1. Stop all containers and remove all related resources:

    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:

    docker compose up -d

Fail to access model(Ollama/xxxxx)

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 for more information.

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 to your local folder ~/deepdoc.

  2. Add a volume mapping to docker/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 directory

To resolve this, either download the missing file from the corresponding tag on GitHub or update ~/ragflow/docker/docker-compose.yml as follows:

network anomaly There is an abnormality in your network and you cannot connect to the server.

anomaly

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

Then use the system health API to check the database, Redis, document engine, and object storage.

Realtime synonym is disabled, since no redis connection

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

  1. Clear the Redis task queue:
$ docker exec -it ragflow-redis /bin/bash
# In container
$ redis-cli -a infini_rag_flow
# In redis-cli
select 1
XGROUP DESTROY rag_flow_svr_queue rag_flow_svr_task_broker
XGROUP CREATE rag_flow_svr_queue rag_flow_svr_task_broker $ MKSTREAM
# When CREATE raises and error:
FLUSHDB
  1. If the parser remains stuck at 0%, restart the RAGFlow containers using one of the following methods:
# Option 1: Restart specific container
docker restart docker-redis-1 docker-ragflow-cpu-1

# Option 2: Recreate containers via Docker Compose
docker compose -f docker/docker-compose.yml down
docker compose -f docker/docker-compose.yml up -d

# Option 3: Reset all Docker containers
# WARNING: Run this ONLY if your environment contains no other non-RAGFlow containers.
docker stop $(docker ps -aq)
docker rm $(docker ps -aq)

For RAGFlow v0.26.0 and later

  1. Clear the Redis task queue:
$ docker exec -it ragflow-redis /bin/bash
# In container
$ redis-cli -a infini_rag_flow
# In redis-cli
select 1
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
  1. If the parser remains stuck at 0%, restart the RAGFlow containers using one of the following methods:
# Option 1: Restart specific container
docker restart docker-redis-1 docker-ragflow-cpu-1

# Option 2: Recreate containers via Docker Compose
docker compose -f docker/docker-compose.yml down
docker compose -f docker/docker-compose.yml up -d

# Option 3: Reset all Docker containers
# WARNING: Run this ONLY if your environment contains no other non-RAGFlow containers.
docker stop $(docker ps -aq)
docker rm $(docker ps -aq)

Why does my document parsing stall at under one percent?

stall

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:

    docker logs -f docker-ragflow-cpu-1

  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!

docker compose stop
docker compose up -d

nearcompletion

Index failure

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.

How to check the log of RAGFlow?

tail -f ragflow/docker/ragflow-logs/*.log

How to check the status of each component in RAGFlow?

  1. Check the status of the RAGFlow Docker container:

    $ docker compose ps

    Review the service logs:

    docker compose logs -f ragflow

  2. Use the system health API to check the database, Redis, document engine, and object storage.

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.

Exception: Can't connect to ES cluster

  1. Check 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

  2. Follow the system health API to check the health status of the Elasticsearch service.

    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. On Linux, update /etc/sysctl.conf to keep the change permanent. For macOS, see the following FAQ.

Can't start ES container and get Elasticsearch did not exit normally

On Linux, 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.

How do I configure vm.max_map_count on macOS?

vm.max_map_count is a Linux kernel parameter required only by Elasticsearch. It does not affect RAGFlow deployments that use Infinity as the document engine.

On Docker Desktop, set the value in its Linux virtual machine:

docker run --rm --privileged alpine sysctl -w vm.max_map_count=262144

This setting is temporary and is reset when Docker Desktop restarts.

On Colima, check the current value inside its virtual machine:

colima ssh -- sysctl vm.max_map_count

To set the value temporarily:

colima ssh -- sudo sysctl -w vm.max_map_count=262144

For a persistent setting, run colima start --edit and add a provision script to colima.yaml:

provision:
  - mode: system
    script: |
      #!/bin/bash
      sysctl -w vm.max_map_count=262144

Then restart Colima:

colima stop
colima start

Contributed by @helloxjade.

{"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 RagFlow

A correct Ollama IP address and port is crucial to adding models to Ollama:

  • If you are on cloud.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 for more information.

Do you offer examples of using DeepDoc to parse PDF or other files?

Yes. See the parser entry points and examples in the 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

This error means that RAGFlow cannot find a required file. Check the complete error message and stack trace to identify the missing path.

  • 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 to verify the configured object storage and other dependencies.

Usage

How to run RAGFlow with a locally deployed LLM?

You can use Ollama or Xinference to deploy local LLM. See here 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

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 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, uncomment # 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.
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.

How to get an API key for integration with third-party applications?

See Acquire a RAGFlow API key.

How to upgrade RAGFlow?

See Upgrade RAGFlow for more information.

How to switch the document engine to Infinity?

To switch your document engine from Elasticsearch to Infinity:

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:

    $ docker compose -f docker/docker-compose.yml down -v
    WARNING

    -v will delete all Docker container volumes, and the existing data will be cleared.

  2. Set the following value in docker/.env :

   DOC_ENGINE=infinity

  1. Restart your Docker image:

    $ docker compose -f docker/docker-compose.yml up -d

Where are uploaded files stored in RAGFlow?

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.

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.

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:

  • Use a faster LLM with lower inference latency.
  • Reduce the number of retrieved chunks by adjusting retrieval parameters such as Top N.
  • Keep prompts concise and avoid unnecessary context.
  • Disable optional features that require additional model calls when they are not needed.
  • 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.

How to accelerate the question-answering speed of my Agent?

Agent response time depends on the number of components, model calls, and external services involved in the workflow. To improve response speed:

  • Use faster models for components that do not require strong reasoning capabilities.
  • Reduce unnecessary LLM, retrieval, tool, and HTTP calls.
  • Simplify the Agent workflow and avoid excessively long execution paths.
  • Limit the number of iterations in loops or reasoning-intensive components.
  • Reduce the amount of context passed between components where possible.
  • Run independent operations in parallel when the workflow supports it.
  • Make sure external APIs and model services used by the Agent have low latency.

How to use MinerU to parse PDF documents?

From v0.22.0 onwards, RAGFlow includes MinerU (≥ 3.3.0) 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:

  1. Prepare a reachable MinerU API service (FastAPI server, MinerU ≥ 3.3.0).
  2. In the .env file or from the Model providers page in the UI, configure RAGFlow as a remote client to MinerU:
    • MINERU_APISERVER: The MinerU API endpoint (e.g., http://mineru-host:8886).
    • MINERU_BACKEND: The MinerU backend (matches current MinerU API / CLI -b values):
      • "pipeline" (default)
      • "vlm-engine"
      • "hybrid-engine"
      • "vlm-http-client"
      • "hybrid-http-client".
    • MINERU_SERVER_URL: Required when MINERU_BACKEND is "vlm-http-client" or "hybrid-http-client"; unused for other backends. The downstream OpenAI-compatible HTTP server (e.g., http://vllm-host:30000).
    • 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.
  3. In the web UI, navigate to your dataset's Configuration page and find the Ingestion pipeline section:
    • If you decide to use a chunking method from the Built-in dropdown, ensure it supports PDF parsing, then select MinerU from the PDF parser dropdown.
    • If you use a custom ingestion pipeline instead, select MinerU in the PDF parser section of the Parser component.
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.

WARNING

Upgrade note: Older backend names (vlm-transformers, vlm-vllm-engine, vlm-mlx-engine, vlm-vllm-async-engine, vlm-lmdeploy-engine) are no longer accepted. After upgrading, re-select a current backend in Model providers (or update MINERU_BACKEND) and ensure your MinerU API service is ≥ 3.3.0.

WARNING

Third-party visual models are marked Experimental, because we have not fully tested these models for the aforementioned data extraction tasks.

How to configure MinerU-specific settings?

The table below summarizes the most frequently used MinerU environment variables for remote MinerU:

Environment variableDescriptionDefaultExample
MINERU_APISERVERURL of the MinerU API serviceunsetMINERU_APISERVER=http://your-mineru-server:8886
MINERU_BACKENDMinerU parsing backendpipelineMINERU_BACKEND=pipeline|vlm-engine|hybrid-engine|vlm-http-client|hybrid-http-client
MINERU_SERVER_URLRequired for vlm-http-client / hybrid-http-client; unused otherwiseunsetMINERU_SERVER_URL=http://your-vllm-server-ip:30000
MINERU_OUTPUT_DIRDirectory for MinerU output filesSystem-defined temporary directoryMINERU_OUTPUT_DIR=/home/ragflow/mineru/output
MINERU_DELETE_OUTPUTWhether to delete MinerU output directory when a temp dir is used1 (delete temp output)MINERU_DELETE_OUTPUT=0
  1. Set MINERU_APISERVER to point RAGFlow to your MinerU API server.
  2. Set MINERU_BACKEND to specify a parsing backend.
  3. If using "vlm-http-client" or "hybrid-http-client", set MINERU_SERVER_URL to your OpenAI-compatible server's URL. MinerU API expects backend=<http-client-backend> and server_url=http://<server>:30000 in the request body.
  4. Set MINERU_OUTPUT_DIR to specify where RAGFlow stores MinerU API output; otherwise, a system temp directory is used.
  5. Set MINERU_DELETE_OUTPUT to 0 to keep MinerU's temp output (useful for debugging).
NOTE

For information about other environment variables natively supported by MinerU, see here.

How to use MinerU with a vLLM server for document parsing?

RAGFlow supports MinerU's vlm-http-client and hybrid-http-client backends, enabling you to delegate document parsing tasks to a remote OpenAI-compatible server (for example vLLM) while calling MinerU via HTTP. To configure:

  1. Ensure a MinerU API service is reachable (for example http://mineru-host:8886).
  2. Set up or point to an OpenAI-compatible HTTP server (for example http://vllm-host:30000).
  3. Configure the following in your docker/.env file (or your shell if running from source):
    • MINERU_APISERVER=http://mineru-host:8886
    • MINERU_BACKEND="vlm-http-client" (or "hybrid-http-client")
    • MINERU_SERVER_URL="http://vllm-host:30000" MinerU API calls expect backend=vlm-http-client (or hybrid-http-client) and server_url=http://<server>:30000 in the request body.
  4. Configure MINERU_OUTPUT_DIR / MINERU_DELETE_OUTPUT as desired to manage the returned zip/JSON before ingestion.
NOTE

When using an *-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 inference server.

How to use an external Docling Serve server for document parsing?

RAGFlow supports Docling in two modes:

  1. Local Docling (existing mode): install Docling in the RAGFlow runtime (USE_DOCLING=true) and parse in-process.
  2. External Docling Serve (remote mode): point RAGFlow to a Docling Serve endpoint.

To enable remote mode, set:

DOCLING_SERVER_URL=http://your-docling-serve-host:5001

Behavior:

  • When 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).
  • When DOCLING_SERVER_URL is not set, RAGFlow uses local in-process Docling.

How to use PaddleOCR for document parsing?

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:

1. Using PaddleOCR Official API

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:

    • Navigate to Model providers page
    • Add a new OCR model with factory type "PaddleOCR"
    • Configure the following fields:
      • PaddleOCR API URL: Your PaddleOCR API endpoint
      • PaddleOCR Algorithm: Select the algorithm corresponding to the API endpoint
      • AI Studio Access Token: Your access token for the PaddleOCR API

Step 2: Usage in Dataset Configuration

  • In your dataset's Configuration page, find the Ingestion pipeline section
  • If using built-in chunking methods that support PDF parsing, select PaddleOCR from the PDF parser dropdown
  • If using custom ingestion pipeline, select PaddleOCR in the Parser component

Notes:

  • To obtain the API URL, visit the PaddleOCR official website, click the API button, choose the example code for the specific algorithm you want to use (e.g., PaddleOCR-VL), and copy the API_URL.
  • Access tokens can be obtained from the AI Studio platform.
  • This method requires internet connectivity to reach the official PaddleOCR API.

2. Using Self-Hosted PaddleOCR Service

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:

    • Navigate to Model providers page
    • Add a new OCR model with factory type "PaddleOCR"
    • Configure the following fields:
      • PaddleOCR API URL: The endpoint of your deployed service
      • PaddleOCR Algorithm: Select the algorithm corresponding to the deployed service
      • AI Studio Access Token: Leave empty

Step 3: Usage in Dataset Configuration

  • In your dataset's Configuration page, find the Ingestion pipeline section
  • If using built-in chunking methods that support PDF parsing, select PaddleOCR from the PDF parser dropdown
  • If using custom ingestion pipeline, select PaddleOCR in the Parser component

Environment Variables Summary

Environment VariableDescriptionDefaultRequired
PADDLEOCR_API_URLPaddleOCR API endpoint URL""Yes, when using environment variables
PADDLEOCR_ALGORITHMAlgorithm to use for parsing"PaddleOCR-VL"No
PADDLEOCR_ACCESS_TOKENAccess token for official APINoneOnly 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.

How do I use Ollama with RAGFlow for local LLM inference?

RAGFlow supports Ollama as a local model provider for private, offline inference.

Step 1: Start Ollama and pull a model

export OLLAMA_HOST=0.0.0.0
ollama serve
ollama pull llama3

Step 2: Add Ollama in RAGFlow

  1. Go to Settings > Model providers > Ollama.
  2. Set the Base URL to http://host.docker.internal:11434 (Docker) or http://localhost:11434 (bare-metal).
  3. Enter the model name (e.g., llama3) and click Save.

Step 3: Use Ollama in your assistant

  • Open an assistant's Configuration page and select the Ollama model under Chat model.
On this page