如何使用 RAGFlow：构建可靠 RAG 应用的实用指南
更新于 2025年9月19日
8 分钟
如何使用 RAGFlow：构建可靠 RAG 应用的实用指南
如果您尝试构建过检索增强生成 (RAG) 系统，您可能已经遇到了经典的痛点：幻觉、检索不稳定、管道速度慢以及文档预处理混乱。RAGFlow 作为一个端到端的工作流工具，可以帮助您编排文档摄取、分块、向量化、检索和生成，并提供更多的控制和可观察性。
本指南采用实用且以解决方案为导向的方法。我们将介绍一个清晰的设置，展示如何使用 RAGFlow 处理真实文档，并分享实际减少幻觉并提高答案质量的模式。
什么是 RAGFlow，为什么要使用它？
RAGFlow 是一个用于构建检索增强生成管道的系统。在典型的 RAG 设置中，您需要：
- 文档（PDF、网页、幻灯片、代码等）
- 内容为可检索的单元
- 块到向量中以进行语义搜索
- 在提问时前 k 个相关的块
- 使用 LLM 一个有根据的答案
RAGFlow 添加了带有倾向性的默认设置、工作流块和防护措施，以便您可以更快地迭代并发布更可靠的应用程序。如果您想要以下功能，它尤其有用：
- ：更好的检索始于更好的分块。
- ：交换 OpenAI、本地模型或企业端点。
- ：衡量检索质量并减少幻觉。
- ：以更少的重写次数从 notebook 转移到生产环境。
快速开始：从零开始构建一个可用的 RAGFlow 管道
以下是一个最小的端到端工作流程，您可以对其进行调整。即使您的环境不同，该序列和防护措施也是可移植的。
1) 准备您的环境
- 创建一个
.env文件，其中包含您的密钥：
- （或其他 LLM 提供商）
- （如果使用单独的提供商）
- （例如，Pinecone、Weaviate、Qdrant 或本地）
- 设置一个项目目录，例如
ragflow-project/，其中包含以下文件夹：
- （源文件）
- （清理后的块）
- （YAML/JSON 格式的管道设置）
- （数据集和报告）
2) 摄取具有干净元数据的文档
良好的元数据 = 更好的检索。标准化标题、作者、日期和来源。
- 使用强大的解析器将 PDF 和幻灯片转换为文本
- 保留结构：标题、列表、代码块和表格
- 将元数据附加到每个块：
source、section、page、timestamp、version
提示：保留
doc_id 和 chunk_id 以支持引用和重新摄取。3) 选择适合您内容的分块策略
分块会严重影响检索质量和延迟。
- 对于叙述性文档：语义分块（按标题/段落分割）
- 对于技术文档：使用 混合分块（语义 + 固定窗口）
- 对于代码：按 函数/类 分块，并使用小的滑动窗口
建议的起始设置：
- ：600–1,000 个 token
- ：50–100 个 token
- ：将嵌套部分限制为 2-3 层，以避免碎片化
4) 选择嵌入和向量存储
- 从强大的通用嵌入模型开始（例如，text-embedding-3-large 或现代本地模型）。如果隐私至关重要，请考虑自托管嵌入。
- 使用支持以下功能的向量数据库：
- （密集 + 关键字）
- （元数据约束）
- 和 索引指标
要测试的索引设置：
- 用于初始检索
- （或某些模型的点积）
- 启用 最大边际相关性 (MMR) 以减少冗余
5) 检索编排
实现一个两阶段检索器：
- 混合搜索 (BM25 + 密集)
- 大的
top_k（例如，30–50）
- 交叉编码器重排序器或基于 LLM 的评分
- 减少到最终的
top_k（例如，5–8）
添加元数据过滤器：
source:"handbook" AND section:"benefits" AND version:"v2" 以将答案限制为可信文档。6) 具有结构的有根据的生成
您的提示应强制执行引用，并在证据不足时拒绝回答。
示例系统提示：
- 以 [doc_id:chunk_id] 的形式内联引用来源。- 如果上下信息不足，请说“提供的文档中信息不足。”- 不要捏造事实。用户提示模板：
上下文：{top_chunks}说明：- 首先提供简洁的答案，然后提供详细信息。- 在每个事实性声明后包括引用。7) 添加防护措施以减少幻觉
- ：在生成之前，询问一个小模型：“检索到的块中是否有直接证据？” 如果没有，则返回一个澄清问题。
- 策略：阻止缺少引用的输出。
- 用于企业内容的 。
8) 评估和持续改进
创建一个
eval/ 集，其中包含：- 50–200 个真实用户问题
- 基本事实答案（或可信参考）
- 适用的预期来源（文档 ID）
测量：
- （黄金来源是否出现在 top-k 中？）
- （引用支持的陈述）
- （p95 端到端）
- （每 100 个查询）
迭代：
- 块大小和重叠
- 嵌入模型选择
- 重排序器与更高的 top-k
- 提示结构和约束
完整的 RAGFlow 管道：示例配置
以下是一个概念配置，您可以将其调整为您的工具链。根据需要替换提供商名称。
project: product-handbook-ragio:input_path: data/raw/output_index: product-handbook-indexparsing:pdf:strategy: autokeep_layout: trueextract_tables: truemarkdown:preserve_headings: truechunking:method: semantic_hybridtarget_tokens: 800overlap_tokens: 80windowing: 2metadata:fields: [doc_id, title, section, page, version, source]embeddings:provider: openaimodel: text-embedding-3-largevectorstore:type: qdranturl: ${VECTOR_DB_URL}similarity: cosineretrieval:hybrid: truelexical_weight: 0.35semantic_weight: 0.65candidate_top_k: 40rerank:enabled: truemodel: bge-reranker-largefinal_top_k: 7generation:llm: gpt-4otemperature: 0.2cite_or_silence: trueguardrails:answerability_check: truepii_filter: truetoxicity_filter: moderatemonitoring:log_traces: truelatency_budget_ms: 3500cost_budget_per_100: 1.25如何为不同的内容类型使用 RAGFlow
产品手册和指南
- 首选具有清晰章节边界的语义分块
- 附加版本和生效日期以防止过时的答案
- 使用严格的过滤器：始终要求
version = latest
知识库和常见问题解答
- 使用较小的块（400–600 个 token）以获得精确的答案
- 增加候选池并依靠重排序来找到确切的片段
- 自动生成规范的问答对，以通过词汇搜索提高召回率
工程文档和代码
- 按函数/模块分块，并在元数据中包含导入图
- 启用父子检索：返回函数及其文档字符串上下文
- 使用代码感知重排序器来优先考虑相关的符号
法律和合规
- 需要段落级别的引用
- 为不完整的上下文添加拒绝逻辑
- 在单独的索引中保留一套监管机构批准的黄金来源
实际有效的提示模式
- ：简短的答案在顶部；每次声明后内联引用
- ：首先要求模型总结每个块，然后进行综合
- ：在检索之前，使用同义词和领域术语扩展用户查询
- ：“根据上下文解释为什么选项 A 比 B 更好。” 这迫使使用证据
示例查询重写步骤：
重写：“带薪休假结转政策；假期展期；最大小时数；策略版本最新”可观察性和反馈循环
- 记录使用了哪些块、它们的分数以及哪些被忽略
- 捕获赞/踩，并提供简短的理由；将其反馈到检索器调整中
- 在部署任何模型更改之前，每周在您的 eval 集上运行回归测试
性能调优备忘单
- 如果答案感觉过于通用：增加
candidate_top_k并添加更强大的重排序器
- 如果答案遗漏了细节：减小块大小；稍微提高词汇权重
- 如果引用重复相同的块：启用 MMR 并提高多样性
- 如果延迟很高：缓存嵌入，预先计算查询重写，使用较小的重排序器
- 如果成本飙升：降低生成温度，缩短提示，尝试使用较小的 LLM 进行第一遍
安全性和治理要点
- 加密存储的向量并编辑元数据中的敏感字段
- 使用每个索引的访问控制；按团队或数据敏感性进行分段
- 维护数据沿袭记录：文档源 URL、校验和和摄取时间戳
案例研究快照：从混乱的 PDF 到可信的答案
一个支持团队摄取了 1,200 页的 PDF。初始检索不一致；代理不信任该机器人。在切换到语义-混合分块（800 个 token，80 个重叠），启用交叉编码器重排序并强制执行引用或沉默后，top-k 命中率从 62% 提高到 89%，代理采用率翻了一番。关键不是更大的 LLM，而是更干净的块和更严格的检索。
工具提示：使用 AI 侧边栏进行快速迭代
值得注意的是：如果您正在跨许多文档试验提示和检索片段，那么一个允许您直接从浏览器通过 PDF、网页和代码进行聊天的 AI 助手可以加速迭代。顺便说一下，Sider.AI（https://sider.ai/）提供了一个 AI 侧边栏，可让您从您所在的页面中提取上下文，快速总结和优化提示。在您正式确定管道之前，它可以方便地用于原型设计 RAG 提示和测试块质量。
RAGFlow 故障排除：快速修复
- “模型很自信，但错了。”
- 启用可回答性检查；降低温度；需要引用
- “搜索返回了近似重复项。”
- 打开 MMR；添加重排序器；减少块重叠
- “高峰时段延迟飙升。”
- 批量嵌入；缓存查询重写；使用流式生成
- “旧政策不断出现。”
- 过滤
version = latest；弃用或删除过时的文档
后续步骤：使您的 RAGFlow 在生产中可靠
- 从一个小型、可信的语料库开始；首先完善分块和过滤器
- 在升级 LLM 之前添加重排序器
- 构建一个包含 100 个问题的评估集，并每周跟踪命中率
- 连接用户反馈以持续调整检索
主要要点：
- 对于 RAG 而言，检索质量胜过模型大小
- 分块、元数据和重排序是您的核心杠杆
- 像引用或沉默这样的防护措施可以极大地提高信任度
- 尽早投资于可观察性和评估
通过这些实践，RAGFlow 成为有根据的答案的可靠支柱——无论您是为帮助机器人、开发人员副驾驶还是内部知识助手提供支持。
