Fix: Correct pagination and early termination bugs in chunk_list() (#11692)

Summary

This PR fixes two critical bugs in chunk_list() method that prevent processing large documents (>128 chunks) in GraphRAG and other workflows.

Bugs Fixed

Bug 1: Incorrect pagination offset calculation

Location: rag/nlp/search.py lines 530-531

Problem: The loop variable p was used directly as offset, causing incorrect pagination:

```python

BEFORE (BUGGY):

for p in range(offset, max_count, bs): # p = 0, 128, 256, 384… es_res = self.dataStore.search(…, p, bs, …) # p used as offset

Fix: Use page number multiplied by batch size:

AFTER (FIXED):

for page_num, p in enumerate(range(offset, max_count, bs)): es_res = self.dataStore.search(…, page_num * bs, bs, …)

Bug 2: Premature loop termination

Location: rag/nlp/search.py lines 538-539

Problem: Loop terminates when any page returns fewer than 128 chunks, even when thousands more remain:

BEFORE (BUGGY):

if len(dict_chunks.values()) < bs: # Breaks at 126 chunks even if 3,000+ remain break

Fix: Only terminate when zero chunks returned:

AFTER (FIXED):

if len(dict_chunks.values()) == 0: break

Enhancement: Add max_count parameter to GraphRAG

Location: graphrag/general/index.py line 60

Added max_count=10000 parameter to chunk loading for both LightRAG and General GraphRAG paths to ensure all chunks are processed.

Testing

Validated with a 314-page legal document containing 3,207 chunks:

Before fixes:

Only 2-126 chunks processed
GraphRAG generated 25 nodes, 8 edges

After fixes:

All 3,209 chunks processed ✅
GraphRAG processing complete dataset

Impact

These bugs affect any workflow using chunk_list() with large documents, particularly:

GraphRAG knowledge graph generation
RAPTOR hierarchical summarization
Document processing pipelines with >128 chunks

Related Issue

Fixes #11687

Checklist

Code follows project style guidelines
Tested with large documents (3,207+ chunks)
Both bugs validated by Dosu bot in issue #11687
No breaking changes to API

Co-authored-by: Kevin Hu kevinhu.sh@gmail.com

Document | Roadmap | Twitter | Discord | Demo

📕 目录

💡 RAGFlow 是什么？
🎮 Demo
📌 近期更新
🌟 主要功能
🔎 系统架构
🎬 快速开始
🔧 系统配置
🔨 以源代码启动服务
📚 技术文档
📜 路线图
🏄 贡献指南
🙌 加入社区
🤝 商务合作

💡 RAGFlow 是什么？

RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，通过融合前沿的 RAG 技术与 Agent 能力，为大型语言模型提供卓越的上下文层。它提供可适配任意规模企业的端到端 RAG 工作流，凭借融合式上下文引擎与预置的 Agent 模板，助力开发者以极致效率与精度将复杂数据转化为高可信、生产级的人工智能系统。

🎮 Demo 试用

请登录网址 https://demo.ragflow.io 试用 demo。

🔥 近期更新

2025-11-19 支持 Gemini 3 Pro.
2025-11-12 支持从 Confluence、S3、Notion、Discord、Google Drive 进行数据同步。
2025-10-23 支持 MinerU 和 Docling 作为文档解析方法。
2025-10-15 支持可编排的数据管道。
2025-08-08 支持 OpenAI 最新的 GPT-5 系列模型。
2025-08-01 支持 agentic workflow 和 MCP。
2025-05-23 Agent 新增 Python/JS 代码执行器组件。
2025-05-05 支持跨语言查询。
2025-03-19 PDF 和 DOCX 中的图支持用多模态大模型去解析得到描述.
2024-12-18 升级了 DeepDoc 的文档布局分析模型。
2024-08-22 支持用 RAG 技术实现从自然语言到 SQL 语句的转换。

🎉 关注项目

⭐️ 点击右上角的 Star 关注 RAGFlow，可以获取最新发布的实时通知 !🌟

🌟 主要功能

🍭 “Quality in, quality out”

基于深度文档理解，能够从各类复杂格式的非结构化数据中提取真知灼见。
真正在无限上下文（token）的场景下快速完成大海捞针测试。

🍱 基于模板的文本切片

不仅仅是智能，更重要的是可控可解释。
多种文本模板可供选择

🌱 有理有据、最大程度降低幻觉（hallucination）

文本切片过程可视化，支持手动调整。
有理有据：答案提供关键引用的快照并支持追根溯源。

🍔 兼容各类异构数据源

支持丰富的文件类型，包括 Word 文档、PPT、excel 表格、txt 文件、图片、PDF、影印件、复印件、结构化数据、网页等。

🛀 全程无忧、自动化的 RAG 工作流

全面优化的 RAG 工作流可以支持从个人应用乃至超大型企业的各类生态系统。
大语言模型 LLM 以及向量模型均支持配置。
基于多路召回、融合重排序。
提供易用的 API，可以轻松集成到各类企业系统。

🔎 系统架构

🎬 快速开始

📝 前提条件

CPU >= 4 核
RAM >= 16 GB
Disk >= 50 GB
Docker >= 24.0.0 & Docker Compose >= v2.26.1
gVisor: 仅在你打算使用 RAGFlow 的代码执行器（沙箱）功能时才需要安装。

[!TIP] 如果你并没有在本机安装 Docker（Windows、Mac，或者 Linux）, 可以参考文档 Install Docker Engine 自行安装。

🚀 启动服务器

确保 vm.max_map_count 不小于 262144：
如需确认 vm.max_map_count 的大小：
```
$ sysctl vm.max_map_count
```
如果 vm.max_map_count 的值小于 262144，可以进行重置：
```
# 这里我们设为 262144:
$ sudo sysctl -w vm.max_map_count=262144
```
你的改动会在下次系统重启时被重置。如果希望做永久改动，还需要在 /etc/sysctl.conf 文件里把 vm.max_map_count 的值再相应更新一遍：
```
vm.max_map_count=262144
```

克隆仓库：

$ git clone https://github.com/infiniflow/ragflow.git

进入 docker 文件夹，利用提前编译好的 Docker 镜像启动服务器：

[!CAUTION] 请注意，目前官方提供的所有 Docker 镜像均基于 x86 架构构建，并不提供基于 ARM64 的 Docker 镜像。如果你的操作系统是 ARM64 架构，请参考这篇文档自行构建 Docker 镜像。

运行以下命令会自动下载 RAGFlow Docker 镜像 v0.22.1。请参考下表查看不同 Docker 发行版的描述。如需下载不同于 v0.22.1 的 Docker 镜像，请在运行 docker compose 启动服务之前先更新 docker/.env 文件内的 RAGFLOW_IMAGE 变量。

$ cd ragflow/docker

# git checkout v0.22.1
# 可选：使用稳定版本标签（查看发布：https://github.com/infiniflow/ragflow/releases）
# 这一步确保代码中的 entrypoint.sh 文件与 Docker 镜像的版本保持一致。

# Use CPU for DeepDoc tasks:
$ docker compose -f docker-compose.yml up -d

# To use GPU to accelerate DeepDoc tasks:
# sed -i '1i DEVICE=gpu' .env
# docker compose -f docker-compose.yml up -d

注意：在 v0.22.0 之前的版本，我们会同时提供包含 embedding 模型的镜像和不含 embedding 模型的 slim 镜像。具体如下：

RAGFlow image tag	Image size (GB)	Has embedding models?	Stable?
v0.21.1	≈9	✔️	Stable release
v0.21.1-slim	≈2	❌	Stable release

从 v0.22.0 开始，我们只发布 slim 版本，并且不再在镜像标签后附加 -slim 后缀。

[!TIP] 如果你遇到 Docker 镜像拉不下来的问题，可以在 docker/.env 文件内根据变量 RAGFLOW_IMAGE 的注释提示选择华为云或者阿里云的相应镜像。

华为云镜像名：swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow

阿里云镜像名：registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow

服务器启动成功后再次确认服务器状态：

$ docker logs -f docker-ragflow-cpu-1

出现以下界面提示说明服务器启动成功：

     ____   ___    ______ ______ __
    / __ \ /   |  / ____// ____// /____  _      __
   / /_/ // /| | / / __ / /_   / // __ \| | /| / /
  / _, _// ___ |/ /_/ // __/  / // /_/ /| |/ |/ /
 /_/ |_|/_/  |_|\____//_/    /_/ \____/ |__/|__/

 * Running on all addresses (0.0.0.0)

如果您在没有看到上面的提示信息出来之前，就尝试登录 RAGFlow，你的浏览器有可能会提示 network anormal 或 网络异常。

在你的浏览器中输入你的服务器对应的 IP 地址并登录 RAGFlow。

上面这个例子中，您只需输入 http://IP_OF_YOUR_MACHINE 即可：未改动过配置则无需输入端口（默认的 HTTP 服务端口 80）。
在 service_conf.yaml.template 文件的 user_default_llm 栏配置 LLM factory，并在 API_KEY 栏填写和你选择的大模型相对应的 API key。

详见 llm_api_key_setup。

好戏开始，接着奏乐接着舞！

🔧 系统配置

系统配置涉及以下三份文件：

.env：存放一些基本的系统环境变量，比如 SVR_HTTP_PORT、MYSQL_PASSWORD、MINIO_PASSWORD 等。
service_conf.yaml.template：配置各类后台服务。
docker-compose.yml: 系统依赖该文件完成启动。

请务必确保 .env 文件中的变量设置与 service_conf.yaml.template 文件中的配置保持一致！

如果不能访问镜像站点 hub.docker.com 或者模型站点 huggingface.co，请按照 .env 注释修改 RAGFLOW_IMAGE 和 HF_ENDPOINT。

./docker/README 解释了 service_conf.yaml.template 用到的环境变量设置和服务配置。

如需更新默认的 HTTP 服务端口(80), 可以在 docker-compose.yml 文件中将配置 80:80 改为 <YOUR_SERVING_PORT>:80。

所有系统配置都需要通过系统重启生效：
$ docker compose -f docker-compose.yml up -d

把文档引擎从 Elasticsearch 切换成为 Infinity

RAGFlow 默认使用 Elasticsearch 存储文本和向量数据. 如果要切换为 Infinity, 可以按照下面步骤进行:

停止所有容器运行:
```
$ docker compose -f docker/docker-compose.yml down -v
```
Note: -v 将会删除 docker 容器的 volumes，已有的数据会被清空。
设置 docker/.env 目录中的 DOC_ENGINE 为 infinity.

启动容器:

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

[!WARNING] Infinity 目前官方并未正式支持在 Linux/arm64 架构下的机器上运行.

🔧 源码编译 Docker 镜像

本 Docker 镜像大小约 2 GB 左右并且依赖外部的大模型和 embedding 服务。

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/
docker build --platform linux/amd64 -f Dockerfile -t infiniflow/ragflow:nightly .

🔨 以源代码启动服务

安装 uv 和 pre-commit。如已经安装，可跳过本步骤：

pipx install uv pre-commit
export UV_INDEX=https://mirrors.aliyun.com/pypi/simple

下载源代码并安装 Python 依赖：

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/
uv sync --python 3.10 # install RAGFlow dependent python modules
uv run download_deps.py
pre-commit install

通过 Docker Compose 启动依赖的服务（MinIO, Elasticsearch, Redis, and MySQL）：
```
docker compose -f docker/docker-compose-base.yml up -d
```
在 /etc/hosts 中添加以下代码，目的是将 conf/service_conf.yaml 文件中的所有 host 地址都解析为 127.0.0.1：
```
127.0.0.1       es01 infinity mysql minio redis sandbox-executor-manager
```
如果无法访问 HuggingFace，可以把环境变量 HF_ENDPOINT 设成相应的镜像站点：
```
export HF_ENDPOINT=https://hf-mirror.com
```

如果你的操作系统没有 jemalloc，请按照如下方式安装：

# ubuntu
sudo apt-get install libjemalloc-dev
# centos
sudo yum install jemalloc
# mac
sudo brew install jemalloc

启动后端服务：

source .venv/bin/activate
export PYTHONPATH=$(pwd)
bash docker/launch_backend_service.sh

安装前端依赖：
```
cd web
npm install
```
启动前端服务：
```
npm run dev
```
以下界面说明系统已经成功启动：
开发完成后停止 RAGFlow 前端和后端服务：
```
pkill -f "ragflow_server.py|task_executor.py"
```

📚 技术文档

📜 路线图

详见 RAGFlow Roadmap 2025 。

🏄 开源社区

🙌 贡献指南

RAGFlow 只有通过开源协作才能蓬勃发展。秉持这一精神,我们欢迎来自社区的各种贡献。如果您有意参与其中,请查阅我们的贡献者指南。

🤝 商务合作

预约咨询

👥 加入社区

扫二维码添加 RAGFlow 小助手，进 RAGFlow 交流群。