RAGFlow 1.0 Tutorial: Setup, PDF Parsing and Real Test Results

On this page
RAGFlow is an open-source RAG engine (Apache 2.0) that turns documents into a searchable knowledge base and answers questions about them with citations. Its focus is the hard part of RAG: getting clean text, tables and layout out of PDFs and Office files before anything is embedded. Version 1.0.0 was released on 6 November 2026 and is a rewrite of the backend in Go.
We installed RAGFlow 1.0 with the official Docker Compose setup, connected OpenAI models and loaded a real document with lots of tables: the 147-page statistics report "Austria. Data. Figures. Facts 2025/26" by Statistics Austria. The short version: setup is quick, and the chat answers with page-level citations and says so when it finds nothing. But the built-in DeepDoc parser turned most of this particular PDF into letter salad. Switching the parser to a vision model (gpt-4.1-mini) fixed that, and the same five test questions went from two correct answers to five. This guide shows the setup, the configuration, our measurements and what to watch out for.
What RAGFlow is and when it beats a simple vector store
A minimal RAG pipeline extracts text from documents, splits it into chunks, embeds the chunks in a vector store and gives the best matches to an LLM. That works well for clean text. It breaks down when the knowledge sits in tables, multi-column layouts, scanned pages or charts: the text extractor mixes up columns, loses the relation between a number and its row label, or returns nothing at all.
RAGFlow puts most of its effort into that first step and wraps the rest into a ready-made application:
- Parsing with DeepDoc, RAGFlow's own model stack for OCR, layout analysis and table structure recognition. Alternatively you can plug in other parsers or a vision LLM.
- Chunking templates for different document types (general text, tables, papers, books, laws, Q&A pairs, manuals, presentations).
- Hybrid retrieval with vector and keyword search, plus an optional reranker.
- A chat UI with citations, a search UI, a visual agent builder, an HTTP API and an MCP server.
- A chunk view in which you see exactly what the parser extracted from each page, next to the original, and can switch single chunks off.
Compared with a few dozen lines of LangChain or LlamaIndex code on top of a vector database, you get a complete system with a UI that non-developers can use, and you can inspect every parsing step. You pay for that with a larger stack (six containers by default) and less control over the details. RAGFlow is a good fit when you want to give a team a document Q&A system on your own infrastructure quickly, and when your documents are PDFs or Office files with structure. For a few clean Markdown files it is more than you need.
How RAGFlow works
How RAGFlow 1.0 works: ingestion pipeline, answering path and the containers of the default stack
When you upload a document, the Ingestor service runs it through a pipeline: the parser extracts text, tables and images, the chunker splits the result according to the chosen template, an optional extractor lets an LLM add keywords, questions or summaries, and the indexer writes embeddings and full text into the document engine (Elasticsearch by default). When someone asks a question, the API service runs a hybrid search over these chunks, passes the best ones to the LLM and returns the answer with references to the source chunks and pages.
Since 1.0 all of this runs in a single Go binary inside the ragflow-cpu
container (API, Admin, Ingestor and Syncer). NATS is the task queue, Kvrocks
the cache, MySQL stores users and settings, and MinIO stores the uploaded
files.
What changed since RAGFlow 0.19
The first version of this guide used RAGFlow 0.19 from May 2025. The main changes since then, according to the official release notes:
| Version | Change |
|---|---|
| 0.20 | Agents rebuilt; MCP support: RAGFlow as MCP server, agents as MCP clients |
| 0.21 | Ingestion pipelines you can design on a canvas |
| 0.22 to 0.27 | Data source connectors (S3, Confluence, Notion, Google Drive, SharePoint, OneDrive, Teams, Slack, Jira and more) |
| 0.23 to 0.25 | Memory module with its own HTTP and Python API |
| 0.27 | Knowledge Compilation (wiki, graph, tree, page index, timeline). GraphRAG and RAPTOR are no longer in the UI and live on as Graph and Tree |
| 0.27, 1.0 | Agentic RAG in chat; 1.0 calls it Agentic mode and adds a decision model for evidence checks |
| 1.0 | Backend rewritten in Go, NATS replaces Redis as queue, arm64 images; DeepDoc runs on CPU only |
If you run an older version: according to the release notes, data from v0.27.2 is migrated automatically when the 1.0 container starts, and the migration cannot be rolled back. Older versions have to go to 0.27.2 first. Back up before you upgrade.
Installing RAGFlow with Docker Compose
The README recommends 4 CPU cores, 16 GB RAM and 50 GB disk space as a starting configuration, plus Docker 24.0.0 and Docker Compose v2.26.1 or newer. The Go backend runs on Linux (x86-64 and arm64); macOS is not supported at the moment.
If you keep the default Elasticsearch engine, check vm.max_map_count on
the Docker host first. If the value is below 262144, raise it. The
README's commands:
The sysctl -w change is lost on reboot. To keep it, add
vm.max_map_count=262144 to /etc/sysctl.conf.
Then clone the repository, check out the release tag and start the stack, again as in the README:
The images are moderate in size: infiniflow/ragflow:v1.0.0 is 1.16 GB,
Elasticsearch 8.11.3 another 2.1 GB. With the images in place, our stack
reported healthy 17 seconds after up. The README's health check:
Then open http://localhost (or the IP of your server), click "Sign up",
create the first account and sign in.
Change these defaults before anyone else can reach the server
The default configuration is meant for a quick local start. Three things
are worth changing in docker/.env before the first start:
-
Passwords.
.envitself starts with "SECURITY WARNING: DO NOT DEPLOY WITH DEFAULT PASSWORDS". That coversELASTIC_PASSWORD,MYSQL_PASSWORD,MINIO_PASSWORD,REDIS_PASSWORDandADMIN_DEFAULT_PASSWORD(default:admin). The admin password only applies when the first superuser is created; changing it later has no effect. -
Ports. Compose publishes the web UI (80, 443), the API (9380), the Admin service (9381) and every dependency (Elasticsearch, MySQL, MinIO, Kvrocks, NATS) on all network interfaces. Put a firewall or reverse proxy in front, or bind the ports to
127.0.0.1with a Compose override file. This is the override we used (pick your own host ports): -
Time zone.
TZdefaults toAsia/Shanghai, so the start times in the logs and the file list are seven hours ahead of Vienna. SetTZ=Europe/Vienna(or your zone).
Elasticsearch or Infinity as document engine
The document engine stores chunks, vectors and the full-text index.
Elasticsearch is the default; the alternatives in .env are Infinity
(InfiniFlow's own database), OpenSearch, OceanBase, seekDB, GaussDB and
Vastbase. Elasticsearch is mature and well known. Infinity is much lighter:
idle, our default stack used 5.8 GiB RAM, of which Elasticsearch alone took
4.4 GiB. With Infinity the whole stack idled at about 1.5 GiB, the Infinity
container at 210 MiB.
| Stack (6 containers) | Idle RAM | Peak while parsing 147 pages with DeepDoc |
|---|---|---|
| Elasticsearch (default) | 5.8 GiB | 9.1 GiB |
| Infinity | 1.5 GiB | 5.4 GiB |
Measured with docker stats --no-stream every three seconds. The peak is
the sum over all containers; during DeepDoc parsing the RAGFlow container
alone grew to 4.0 GiB.
To switch engines, the FAQ says to stop the stack, set the engine in
docker/.env and start again (run from the repository root):
Existing indexes are not moved; you have to parse your documents again.
Decide before you load a lot of data. According to the README, raising
vm.max_map_count is usually not necessary with Infinity.
Connecting OpenAI models
RAGFlow ships without models. Click your avatar (top right), then "Model providers", choose OpenAI, give the instance a name and paste your API key. After saving, RAGFlow fetches the model list from the API.
OpenAI as model provider in RAGFlow 1.0; the API key is masked
Then click "Set default models". You need at least an LLM for chat and an
embedding model. We used gpt-4.1-mini and text-embedding-3-small. The
other slots are optional: VLM (vision model for images and, as it turns
out, PDF parsing), ASR, rerank, TTS and the "Decision model" that 1.0 uses
in Agentic mode to judge whether the retrieved evidence is sufficient.
Default models: gpt-4.1-mini as LLM and text-embedding-3-small for embeddings
The default embedding model is used for new datasets. Changing it later means embedding every chunk again, so choose before you upload.
Creating a dataset and choosing a chunking template
Under "Dataset" click the plus sign and give the dataset a name. The dialog also asks for the embedding model and the parsing mode: one of the built-in templates or an ingestion pipeline you built yourself.
Creating a dataset with the list of built-in chunking templates
The templates differ in how they split a document:
| Template | Use it for |
|---|---|
| General | Most documents; splits along layout blocks up to a token limit |
| Table | Spreadsheets and CSV files where each row should become a chunk |
| Paper, Book, Laws | Long documents with chapters, sections or articles |
| Manual | Technical manuals with a heading hierarchy |
| Q&A | Question/answer pairs, for example from an FAQ export |
| Presentation | Slides, one chunk per slide |
| One | The whole document as a single chunk |
| Picture, Audio, Email | Images (OCR or vision model), audio (speech recognition), emails |
The configuration page has four tabs that mirror the pipeline. "Parser" sets the parser per file type, "General Chunker" the chunk size (default 512 tokens, no overlap) and delimiters, "Extractor" the optional LLM steps for keywords, questions, tags and summaries, and "Indexer" which fields are searched.
Dataset configuration with the tabs Parser, General Chunker, Extractor and Indexer
The PDF parser deserves a closer look. Besides DeepDoc, the dropdown offers Naive (plain text layer, no OCR), Docling, OpenDataLoader, TCADP Parser, MonkeyOCRv2 and every vision model you have configured, marked "Experimental". Several of the external parsers need an additional service or a cloud account.
PDF parser options: DeepDOC, Naive, Docling, OpenDataLoader, TCADP Parser, MonkeyOCRv2 and the OpenAI vision models
Keep the extractor options off at first. Each one adds an LLM call per chunk, which multiplies indexing time and cost. Turn them on when retrieval tests show that a specific problem would benefit from them.
How DeepDoc parsed a 147-page statistics report
Our test document has everything that trips up PDF extraction: two-column text, more than a hundred tables, charts, maps, photos and vertical labels in the margins. Statistics Austria allows reuse with attribution, and every number can be checked against the original.
We uploaded it with the defaults (General template, DeepDoc parser) and "Parse on creation" switched on. The log shows each step:
Parse log of the document: 9 minutes 10 seconds in total, almost all of it in the parser
| Step | Duration |
|---|---|
| Parser (DeepDoc, CPU) | 8 min 49 s |
| Chunker | 8 s |
| Tokenizer and embedding (OpenAI) | 12 s |
| Total | 9 min 10 s |
That is about 3.6 seconds per page. The result was 510 chunks: 302 text chunks, 162 image chunks and 46 table chunks. During parsing the RAGFlow container used at most about 1.8 CPU cores, although the host had 32 threads. More cores did not speed up a single document.
DeepDoc did several things well. It found the layout blocks and table regions, and it read text inside images, such as the map of the federal provinces with all names, areas and population figures:
DeepDoc chunk view: the map of the federal provinces as an image chunk with the recognized labels and numbers
The problem was the body text and most tables. On the large majority of pages DeepDoc produced letter salad: single characters from different lines and columns mixed together, words glued together without spaces. In the next screenshot the table region "Tyrol at a glance" is detected correctly (highlighted on the left), but the cell contents on the right are unusable:
DeepDoc chunk view: the table "Tyrol at a glance" is detected, but its text is garbled
This depends on the document, not on DeepDoc in general. Five pages of a
Eurostat publication came out as readable text in the same installation,
chart labels included. The Statistics Austria PDF has a valid text layer
(pdftotext extracts it cleanly), small square pages, condensed fonts and
rotated labels in the margins. We did not find out which of these throws
DeepDoc off. Turning on "Detect multi-column layout" did not change the
result.
Naive and a vision LLM as alternatives
We parsed three representative pages again with the other two parsers that need no extra service:
| Parser | 3 sample pages | Result |
|---|---|---|
| DeepDoc | 14 s | Letter salad in text and most tables |
| Naive (text layer) | 1.1 s | Readable text and table rows; numbers with thin-space separators broken ("239â€0† 00" instead of "239 000") |
| gpt-4.1-mini (vision) | 18 s | Clean text, tables as Markdown, all numbers correct |
Then we parsed the full document with gpt-4.1-mini as PDF parser. It took 11 minutes 9 seconds and produced 110 chunks with 57,203 tokens of text, compared with 510 chunks and 145,734 tokens from DeepDoc. The difference in size is mostly the noise DeepDoc produced. The vision model returns each page as Markdown, so tables stay tables:
Chunk from the gpt-4.1-mini parser: "Vorarlberg at a glance" as a Markdown table next to the original page
A vision model costs one API call per page plus the image tokens, and the option is marked experimental. For a few hundred pages that is cheap; for hundreds of thousands of pages, calculate first. The same approach without RAGFlow is described in our post on document extraction with LLMs.
A chat assistant that answers with citations
Under "Chat", create a chat app, open its settings (gear icon top right) and select the dataset. The defaults are fine to start with: the default LLM, "Show citations" on, and the mode switch in the input field set to "Naive" (classic retrieve-then-answer). "Agentic" lets the model search in several steps.
We created one chat per dataset and asked the same five questions, each in a new conversation. The answers are checked against the PDF:
| Question | Correct answer (page) | DeepDoc dataset | gpt-4.1-mini dataset |
|---|---|---|---|
| Austria's population on 1 January 2025 | 9,197,213 (p. 13) | 9,197,213 | "about 9.2 million" |
| Inhabitants of Graz in 2025; smallest municipality | 305,314; Gramais with 43 (p. 13) | correct | correct |
| Unemployment rate (ILO) in Vorarlberg 2024 vs. Austria | 4.1 % vs. 5.2 % (p. 137) | not found | correct |
| Electricity generation in Vorarlberg 2024, green share | 4,218 GWh, 100 % (p. 136) | not found | correct |
| Life expectancy of women, Vorarlberg vs. Tyrol 2024 | 85.05 vs. 85.54 years (pp. 135, 137) | not found | correct (85.5 rounded) |
With the DeepDoc dataset the chat answered 2 of 5 questions. Both answers came from the population table on page 13, one of the few tables DeepDoc read correctly. For the other three it replied "The answer you are looking for is not found in the dataset!" instead of making something up. With the gpt-4.1-mini dataset all five answers were correct; two were rounded by the LLM, while the parsed tables contain the exact values.
Every answer carries numbered citations. Hover over one and RAGFlow shows the chunk and a thumbnail of the source page:
Chat answer with citation: hovering over [1] shows the source chunk "Vorarlberg at a glance"
Each answer took 1.4 to 2.8 seconds and used about 4,500 to 9,400 input tokens; RAGFlow 1.0 shows both under every answer. Five questions are a spot check, not an evaluation. For a systematic check of retrieval and answer quality, see our post on evaluating RAG with Ragas.
Agents, MCP and the API
The chat is only one way to use a dataset. The agent builder offers templates such as a dataset chatbot, a deep research agent and a stock research assistant, and agents can call external MCP servers as tools.
RAGFlow itself is also an MCP server: the API exposes POST /api/v1/mcp
with the tools ragflow_retrieval, ragflow_list_datasets and
ragflow_list_chats, authenticated with a RAGFlow API key (avatar, "API",
"API Key"). The docs' example for listing the tools:
In our installation this returned exactly those three tools, and a
ragflow_retrieval call with a question and a dataset ID returned the
matching chunks as JSON. This lets you use a RAGFlow dataset from Claude,
an IDE agent or your own agent framework without touching the RAGFlow UI.
The HTTP API covers the rest (datasets, upload, parsing, chunks, chats);
note that 1.0 removed deprecated API aliases, so check older scripts against
the API reference.
Limits and pitfalls
- Parsing quality depends on the document. DeepDoc failed on our report and worked on another. Upload five typical pages of each document type, open the chunk view and read the chunks before you load everything.
- DeepDoc is CPU-only in the open-source 1.0 release and used less than two cores per document in our run. Expect a few seconds per page; large archives take hours. A vision model parser is not faster per document (11 minutes for 147 pages) but moves the load to the API.
- Resources: plan for 6 to 10 GiB RAM with Elasticsearch, or use Infinity.
MEM_LIMITin.envcaps each container (default about 7.5 GiB), not the whole stack. - Six containers and many settings. RAGFlow hides much of that behind the UI, but updates, backups (MySQL, MinIO and the document engine) and migrations are your job when you self-host.
- Upgrades from 0.x are one-way. Back up first.
Our assessment
RAGFlow 1.0 is a complete RAG application you can run on your own server in under an hour: upload, parsing, hybrid search, a chat with reliable citations, agents, an HTTP API and MCP. The Go rewrite made the stack noticeably lighter, especially with Infinity. The chunk view is its most useful feature in practice, because it shows immediately whether a document was understood.
What our test also shows: "deep document understanding" is not a guarantee. The default parser can fail on a perfectly normal PDF, and RAGFlow will index the garbage without complaint. The chat then answers "not found", which is honest but not helpful. If your documents are heterogeneous, budget time for testing parsers per document type, and consider a vision model for the difficult ones.
If you want a managed alternative on Azure instead of a self-hosted stack, our guide to RAG with Azure AI Search covers that route.
We help companies choose and build RAG systems on their own documents, from the parser test to production. If you are evaluating RAGFlow or a custom setup, our AI consulting team in Vorarlberg is happy to talk it through.
Test document: Statistics Austria, "Austria. Data. Figures. Facts 2025/26" (Vienna, 2026). Screenshots show excerpts of the document as displayed in RAGFlow.
Interested in building high-quality AI agent systems?
We prepared a comprehensive guide based on cutting-edge research for how to build robust, reliable AI agent systems that actually work in production. This guide covers:
- Understanding the 14 systematic failure modes in multi-agent systems
- Evidence-based best practices for agent design
- Structured communication protocols and verification mechanisms



