infiniflow/ragflow · 上手攻略

• 仓库：infiniflow/ragflow
• 链接：https://github.com/infiniflow/ragflow
• 分类：ai · rag · llm-infra
• 作者：Tom
• 更新：2026-07-07

这是什么

RAGFlow 是 InfiniFlow 出品的开源 RAG（检索增强生成）引擎，主打"深度文档理解 + 融合上下文引擎"，将 RAG 与 Agent 能力结合，让大模型拥有可解释、可控的私有知识库。

核心理念：高质量输入才有高质量输出——RAGFlow 花大量精力在文档解析和切片质量上，而不是简单地把文档切成固定块塞进向量数据库。它支持可视化切片、智能重排序、多路召回、MCP 集成和 Agentic Workflow。

GitHub Stars 84,416，周增 +364；最新版本 v0.26.3（2025 年中），2026 年持续更新（支持 DeepSeek v4、Gemini 3 Pro、GPT-5 等）。

解决什么问题

• 传统 RAG 精度差：把文档切成固定长度块导致语义割裂，检索回来的是片段而不是完整答案。
• 文档解析质量差：PDF、Word、扫描件等复杂格式，传统方案只能提取原始文字，忽略表格、标题层级、图表等结构信息。
• 引用不可信：返回的答案无法溯源到原文，开发者无法确认 RAG 输出是否 hallucinate。
• 企业级需求：SSO、多租户、权限控制、API 集成——个人 RAG 工具无法满足。

快速安装

硬件要求

⚠️ 目前 Docker 镜像仅提供 x86_64 版本，ARM64 需自行编译。

步骤 1：配置系统参数

# 检查
sysctl vm.max_map_count

# 临时设置（重启后失效）
sudo sysctl -w vm.max_map_count=262144

# 永久写入 /etc/sysctl.conf
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

步骤 2：克隆并启动

git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

# CPU 版本（推荐先用这个）
docker compose -f docker-compose.yml up -d

# GPU 加速 DeepDoc 任务
# sed -i '1i DEVICE=gpu' .env
# docker compose -f docker-compose.yml up -d

版本锁定（可选但建议）：git checkout v0.26.3，确保 entrypoint.sh 与 Docker 镜像版本一致。

步骤 3：确认启动成功

docker logs -f docker-ragflow-cpu-1

看到以下 ASCII art 即启动完成：

 ____ ___ ______ ______ __
 / __ \ / | / ____// ____// /____ _ __
 / /_/ // /| | / __ / /_ / // __ \| | /| / /
 / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ /
 /_/ |_|/_/  |_|\____//_/ /_/ \____/ |__/|__/
 * Running on all addresses (0.0.0.0)

步骤 4：配置 LLM 并访问

# 浏览器打开
# http://<YOUR_SERVER_IP>  （默认 HTTP 端口 80）

首次使用需要在 docker/service_conf.yaml.template 中填写 LLM 厂商和 API Key。可选：华为云镜像 swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow 或阿里云镜像 registry.cn-hangzhou.aliyuncs.com/infiniflow/ragflow（国内加速）。

核心用法

上传知识库文档

RAGFlow 支持的文件类型：Word、PPT、Excel、PDF（扫描件/图片）、TXT、图片、Markdown、HTML、XML、CSV 等。

1. 登录 Web UI（默认 http://localhost:80）
2. 进入「知识库」→ 创建知识库 → 上传文档
3. 选择解析模板（适合不同文档类型）
4. 可视化调整切片：RAGFlow 提供切片可视化界面，可手动合并/分割块
5. 等待解析完成（进度可在 UI 查看）

API 调用示例

RAGFlow 提供 RESTful API，可集成到自有系统：

# 创建数据集
curl -X POST "http://localhost:80/v1/datasets" \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_kb", "description": "My knowledge base"}'

# 上传文档（略，见官方 API 文档）
# ...

Python SDK 调用示例（需 pip install ragflow-python-sdk，注意：SDK 非默认安装，需单独安装）：

# 需确认 SDK 名称和用法，官方 README 未附完整 SDK 示例
# 参考：https://github.com/infiniflow/ragflow-python-sdk
import ragflow

client = ragflow.RAGFlow(api_key="YOUR_API_KEY", base_url="http://localhost")

不确定处：Python SDK 安装包名和 API 用法请以 官方 GitHub SDK 最新文档为准，当前 README 未附完整 SDK 示例代码。

Agent 模式（2025-08 新增）

支持 Agentic Workflow 和 MCP，可配置： - 多跳推理（Multi-hop reasoning） - 工具调用（Code Executor / Python REPL） - 带记忆的对话 Agent（2025-12 新增 Memory 功能）

多渠道集成（2026-06 新增）

支持飞书、Discord、Telegram、Line 等 IM 渠道接入 AI 助手。

典型适用场景

坑与注意

1. Python >= 3.13：大多数 Linux 发行版默认 Python 低于此版本，需单独安装或使用 pyenv/virtualenv。
2. ARM64 镜像缺失：在 Mac（M 系列芯片）或 ARM 服务器上需自行构建镜像，参考 官方构建指南，构建过程较长。
3. vm.max_map_count 必须设：不设这个参数，Qdrant 向量数据库会无法启动，切片解析也会报错。
4. 首次启动慢：Docker 镜像约 9GB+，下载和启动需要等待；使用 slim 镜像（v0.22.0+）可减少到 ~2GB 但不含 embedding 模型。
5. LLM API Key 必填：RAGFlow 本身不含 LLM，必须在 service_conf.yaml.template 配置 OpenAI / Azure / DeepSeek 等 API key，否则无法进行对话。
6. 中文文档解析：部分中文 PDF 解析质量依赖 DeepDoc 模型效果，复杂版式可能需要手动调切片策略。
7. v0.22.0 之后镜像策略变更：v0.22.0 起只发 slim 镜像（含 embedding 模型版本取消），如需 embedding 功能需自行配置外部模型。

与同类对比

RAGFlow 的核心差异化：文档解析质量（DeepDoc）和可视化切片干预，让非技术人员也能掌控知识库质量。

一句话推荐结论

如果你需要把成百上千份 PDF/Word 文档变成可问答的知识库，RAGFlow 是目前开源界文档解析质量最好、可控性最强的 RAG 平台——尤其适合对答案精度有要求的企业场景。

来源

• GitHub README（英文）：https://github.com/infiniflow/ragflow
• GitHub README（中文）：https://github.com/infiniflow/ragflow/blob/main/README_zh.md
• 官方文档：https://ragflow.io/docs
• 官方云服务：https://cloud.ragflow.io
• Docker Hub：https://hub.docker.com/r/infiniflow/ragflow
• 最新 Release：https://github.com/infiniflow/ragflow/releases/latest
• RAGFlow Skill（OpenClaw）：https://clawhub.ai/yingfeng/ragflow-skill