RAGFlow 使用指南：从深度解析到生产化部署运维全攻略

1. 引言：为什么选择 RAGFlow？

在 RAG（检索增强生成）领域，业界公认的挑战在于：“Garbage in, garbage out”。如果输入的上下文质量低下、版式混乱，LLM 再强也无法给出准确答案。

RAGFlow 的核心优势在于它对高质量数据接入的执着。它不只是简单的“向量化工具”，而是强调两点：

细粒度文档解析（DeepDoc）：针对图片、表格等复杂版式，通过 OCR 和版面分析，确保文档被“吃透”。
可追溯引用：每一个答案都能精准追溯到原始文档片段，有效降低大模型幻觉。

如果你需要处理大量复杂的 PDF、扫描件、金融财报或技术手册，RAGFlow 提供的“数据质量优先”路径将是你的不二之选。

2. 核心功能深度解析

2.1 知识库（Datasets）与 DeepDoc 解析

知识库是 RAGFlow 的底座。它将非结构化文件转化为可检索的证据库。

深度解析（DeepDoc）：这是 RAGFlow 的杀手锏。它在解析阶段执行 OCR、表格结构识别等重度预处理。
切分策略（Chunking）：
- 通用文档：建议使用中等 chunk + 适度重叠，兼顾语义完整性。
- 手册/规范：推荐按标题层级切分，减少跨章节误导。
最佳实践：
- 先小样验证：先导入 5-10 份典型文档调试效果，再大规模导入。
- 元数据过滤：利用分类、版本等标签，在检索时减少噪声。

2.2 搜索与对话：AI Search vs AI Chat

RAGFlow 提供了两种不同的检索交互方式：

特性	AI Search (单轮搜索)	AI Chat (多轮对话)
定位	智能百科，追求快、稳、证据直观	业务助理，追求深度理解、多轮推进
交互	单轮（不维护上下文）	多轮（保留历史对话）
策略	预设的混合检索（Hybrid Search）	可自定义 RAG 策略与 Agent 流程
展示	直接在答案下方列出所有 chunks	通过引用标签展示来源，更像成品体验
建议场景	故障排查、条款快速定位	方案咨询、复杂文档对比

2.3 Chat Assistant：面向业务的入口

Assistant 是 RAGFlow 的封装层，将模型、知识库、Prompt 整合为可运营的服务。

System Prompt：定义角色人设和规则（如“无依据则拒答”）。
参数精修：针对不同助理配置不同的温度、Top-K 和 Rerank 模型。
工具调用：支持挂载外部工具（搜索、计算等），赋予助理行动力。

2.4 Agent 与 Workflow：从问答升级到自动化

Workflow 将 RAG 从简单的“一问一答”升级为“多步任务”。

核心组件：
- 基础节点：Begin, Answer, Message。
- 检索节点：Retrieval, Rerank, Rewrite（重写查询词）。
- 逻辑节点：Generate, Categorize, Switch, Python Executor。
注意：若要在 Workflow 中运行 Python Executor 节点进行自定义逻辑计算，必须部署 Sandbox Executor Manager 服务，否则代码将无法执行。
设计原则：Workflow 优先，Agent 其次。能用固定流程解决的，就不要让模型自由发挥，以确保结果的一致性。

2.5 Memory：实现长期协作记忆

Memory 将对话转为可检索的结构化记忆，存入 DOC_ENGINE（ES 或 Infinity）。

记忆类型：Raw（原始）、Semantic（语义）、Episodic（情景）、Procedural（流程）。
读写逻辑：通过 LLM 自动抽取关键信息，并基于向量相似度召回。
调参旋钮：keywords_similarity_weight（文本 vs 向量权重）和 similarity_threshold（阈值控制召回灵活性）。

3. 团队协作与组织管理

RAGFlow 支持多人协作，提供了细粒度的资源管理能力：

资源共享：支持团队成员间共享 Dataset 和 Agent。
Admin 工具链：
- Admin UI：可视化管理用户、修改密码、查看服务状态。
- Admin CLI：应急时通过命令行管理资源、恢复服务。
权限边界：企业版支持更高级的模型和助理共享功能。

4. 架构设计与生产部署

4.1 核心组件概览

基于 docker-compose 的标准部署包含：

存储层：MySQL（元数据）、Elasticsearch/Infinity（文档引擎）、MinIO（对象存储）。
中间件：Redis/Valkey（任务队列）。
计算层：RAGFlow API、Admin Server、Worker（处理解析任务）、Sandbox Executor Manager（可选，代码执行沙箱）。

4.2 部署实战

快速启动：

1
2
3

# 进入 docker 目录并启动 (默认 CPU 模式)
cd ragflow/docker
docker compose up -d

生产化思路：Web 与 Worker 分离
解析任务（Worker）极为消耗资源，建议将其部署在带有 GPU 的节点上，而 Web/API 则部署在常规节点，实现负载隔离。
GPU 加速解析：
如果需要 GPU 加速，在 .env 中设置 DEVICE=gpu。对于自定义环境，建议使用 uv 管理依赖，并安装匹配 CUDA 版本的 torch。

4.3 部署 Sandbox Executor (实现 Workflow 代码运行)

如果你需要使用 Workflow 中的 Python Executor 运行自定义代码，必须额外部署沙箱环境：
当前ragflow 沙箱依赖 gVisor 提供内核级隔离，请确保宿主机已安装。如果使用pod sidecar的方式部署的话，需要构建支持gVisor的Dind容器。

FROM docker:27-dind
RUN apk add --no-cache curl bash
RUN curl -Lo /usr/local/bin/runsc https://storage.googleapis.com/gvisor/releases/release/latest/x86_64/runsc && \
    chmod +x /usr/local/bin/runsc

RUN mkdir -p /etc/docker && \
    echo '{ \
        "runtimes": { \
            "runsc": { \
                "path": "/usr/local/bin/runsc" \
            } \
        } \
    }' > /etc/docker/daemon.json

EXPOSE 2375 2376

ENTRYPOINT ["dockerd-entrypoint.sh"]

4.4 可观测性与运维

健康检查：访问 /v1/system/healthz 接口进行监控接入。
全链路追踪（Tracing）：集成 Langfuse。无需修改代码，只需在后台配置 Key，即可实时监控检索、重排、生成的完整链路。
安全性：严禁使用默认密码。务必修改 .env 中的 MYSQL_PASSWORD、MINIO_PASSWORD 等敏感配置。

5. 选型建议与对比

维度	RAGFlow	Dify	LangChain / LlamaIndex
核心优势	复杂文档解析、可追溯性	应用搭建、工作流编排	研发灵活性、高度可组合
适用团队	追求检索效果、有运维能力	追求快速上线、业务优先	深度研发、自研平台
主要挑战	部署较重、解析耗时较长	RAG 深度调节受限	维护成本高、需补齐运维面