用 Dify 从零搭一条能上线的 RAG + Agentic 工作流：15 万星平台实操指南

demo 阶段, 上传十份文档, 问十个问题, 命中率九成, 团队一片叫好。

上线两周后, 用户开始问一些 demo 里没测过的问题: 长文档里第 200 页的一个条款, 两份文档互相矛盾的数据, 一个带口语化措辞的模糊提问。命中率掉到六成, 群里开始有人问"这玩意是不是不太行"。

问题很少出在模型上。真正的坑, 藏在切分策略、检索参数和权限隔离这几个不起眼的配置项里, 而这些恰恰是 demo 阶段没人认真调过的地方。

Dify 想解决的就是这层落差。它把 Agentic 工作流和 RAG 管线放进一个协作工作区, 支持云端、VPC 和自托管三种部署方式。据 GitHub 数据, 这个项目 2023 年 4 月 12 日创建仓库, 到目前 star 数已经超过 15 万, 是目前最活跃的开源 LLM 应用开发平台之一。本文按一个真实项目会走的节奏过一遍: 从想清楚边界问题, 到知识库调参, 到工作流编排, 到评估上线, 每一步都标出容易翻车的地方。

一、动手前先想清楚三件事(数据边界/更新频率/谁能看)

很多团队一上来就建知识库, 三件事没想清楚就开始传文档, 结果建到一半发现权限模型不对, 只能推倒重来。

第一件事: 数据边界。这个知识库到底覆盖哪些文档? 产品手册、内部 SOP、客户合同, 这三类东西的更新频率、敏感级别、检索需求完全不一样, 混进同一个知识库, 检索精度会被互相拖累。Dify 允许一个应用挂载多个知识库, 也支持给不同知识库设不同的检索策略, 建库前先按"更新频率 + 敏感级别"分好类, 比事后拆分省事得多。

第二件事: 更新频率。天天变的内容(比如价格表)和几乎不变的内容(比如产品架构文档)不该用同一套索引策略。频繁更新的文档, 建议开小粒度切分加高频重建索引；稳定文档可以用大一点的 chunk, 减少检索开销。

第三件事: 谁能看。这是最容易被 demo 阶段忽略、上线后捅娄子的一条。Dify 的知识库权限分到应用级和成员级, 但真正的隔离逻辑得靠架构设计, 比如给不同客户或部门建独立工作区, 而不是指望一个知识库里靠"标签过滤"做数据隔离。如果你的场景涉及多租户或者客户数据互相看不见, 这条必须在建库之前敲定, 不是上线前临时补。

提示: 边界定义写成一份 20 分钟能读完的文档, 团队所有人对齐一次, 比事后返工省下来的时间要多得多。这份文档也会成为后面验收标准的输入。

二、知识库: 切分与检索参数怎么调

demo 好用不代表参数选对了, 大概率是文档少、问题简单, 参数怎么设都能糊弄过去。真正的考验在文档量上来、问题变刁钻之后。

切分策略

Dify 官方文档里, 通用模式(General)下默认 chunk 长度是 500 tokens, 上限 4000 tokens, 同时可以配置 chunk 之间的重叠量(overlap)来避免关键信息被切断在两个 chunk 边界上。

这张表最容易被忽略的一行是 Rerank。Dify 支持接入第三方 rerank 模型, 对向量检索返回的候选 chunk 做二次打分排序, 官方说明里明确写了默认是关闭的。如果你的知识库里存在大量语义相近但答案不同的内容(比如多个产品型号的说明书), 不开 rerank, 检索质量会明显偏低, 这也是很多团队"模型换了好几个,效果还是上不去"的真实原因,问题根本不在模型。

一个常见的参数误区

有团队看到"chunk 越小召回越精准", 直接把所有文档都切成 100 token 一个 chunk, 结果检索出来的片段碎片化, 模型拿到的上下文缺乏完整语境, 回答反而变差。切分粒度要跟着内容结构走, 不是越小越好。

# Dify 知识库配置示例(General 模式)
indexing_technique: high_quality
process_rule:
  mode: custom
  rules:
    segmentation:
      max_tokens: 500
      chunk_overlap: 50
    pre_processing_rules:
      - id: remove_extra_spaces
        enabled: true
      - id: remove_urls_emails
        enabled: false
retrieval_model:
  search_method: hybrid_search
  reranking_enable: true
  top_k: 5
  score_threshold_enabled: true
  score_threshold: 0.6

建库时先用 Dify 自带的 Preview 功能看一眼实际切出来的 chunk 长什么样, 别只看参数数字, 眼睛过一遍比脑子算一遍靠谱。

三、工作流编排: 一个可用的 Agentic 流程长什么样

单纯的"检索然后生成"(one-shot RAG)在简单问答场景够用, 但遇到需要多轮判断、需要调用外部工具、需要在检索结果不够时重新组织问题的场景, 就得靠 Agentic 工作流。

Dify 最新版本(v1.14.2, 2026-05-19 发布)的更新重点之一就是 Agent Node 支持的 Agentic RAG: 和一次性检索生成不同, agent 会迭代地分析用户意图、选择合适的工具和数据源、重写查询、评估检索到的证据是否够用, 不够就重试或走兜底路径。这个版本同时补了两个安全项, 把 Jinja2 模板渲染切换成 SandboxedEnvironment, 防止工作流代码节点被模板注入攻击, 也修了一个 React Server Components 的 DoS 漏洞。

一个可用的 Agentic RAG 工作流, 大致长这样:

1. 意图识别节点: 判断用户问题属于哪类(事实查询/多步推理/需要外部工具)
2. 查询重写节点: 把用户的口语化提问重写成更适合检索的形式
3. 知识检索节点: 命中知识库, 拿到候选 chunk
4. 证据评估节点: 判断检索结果是否足够回答问题, 不够则触发重试或降级
5. 工具调用节点(可选): 需要查实时数据或调用内部 API 时触发
6. 生成节点: 综合检索结果和工具返回, 生成最终答案
7. 兜底节点: 检索和工具都没有命中时, 明确告诉用户"没有找到相关信息", 而不是让模型编

[用户输入]
    ↓
[意图识别] → 分类: 事实类 / 推理类 / 需要工具
    ↓
[查询重写] → 优化检索用语
    ↓
[知识检索] → Top-K 命中 + Rerank 排序
    ↓
[证据评估] → 分数不够? → 重试/降级
    ↓                    ↓
[工具调用(可选)]      [兜底: 明确告知未命中]
    ↓
[生成节点] → 最终回答

第 6 步和第 7 步是最容易在 demo 阶段被省略、上线后最先出事的两步。demo 时团队只测"能答对的问题", 没人认真测"答不出来的时候系统该怎么办"。一个不设兜底路径的 RAG 系统, 遇到检索不到内容的问题时, 大模型大概率会自信满满地编一个答案出来, 这比"答不上来"更危险。

另外, v1.14+ 版本里 Agent skill 支持在沙箱环境里跑 Python 代码, 意味着复杂的数据处理或计算类任务不用再绕道外部服务, 直接在工作流内完成, 但这也意味着代码节点的沙箱隔离配置得认真核对一遍, 尤其是自托管场景。

一个经验判断: 如果你的场景里 80% 的问题靠简单检索就能答对, Agentic 编排的收益主要体现在剩下那 20% 的复杂问题上, 值不值得投入取决于这 20% 对业务的重要程度, 不是所有场景都需要上全套 Agentic 流程。

四、评估与上线: 别用感觉验收

demo 阶段的验收标准往往是"团队几个人试了几十个问题, 感觉还不错"。这套标准撑不到上线。

真正能撑住上线的验收, 至少要做三件事:

建立测试问题集, 覆盖边界情况。 不只是测"能答对的问题", 更要测"文档里没有的问题"(系统应该说不知道)、“多份文档矛盾的问题”(系统应该指出矛盾而不是随便选一个)、“模糊提问”(系统应该反问或给出多种可能)。这个测试集至少要覆盖真实用户可能问出来的极端情况, 而不是团队自己脑补的"标准问题"。

量化召回和生成两个环节的指标, 分开看。 很多团队只看"最终回答对不对", 出了问题不知道是检索没找对内容, 还是找对了但模型没用好。至少要分别记录: 检索命中率(相关 chunk 有没有被召回)、生成准确率(基于召回内容, 回答是否准确)。这两个数字分开跟踪, 排查问题时才知道该调检索参数还是该调 prompt。

上线前跑一轮"故意刁难"测试。 找几个对系统了解最少的同事(比如客服/运营), 让他们用真实用户的口吻随便问, 不设剧本。这一步能暴露 demo 阶段最容易被忽略的问题: 真实用户的提问方式往往比工程师预想的更随意、更模糊、更容易踩坑。

上线之后也不是就此结束。检索命中率这类指标建议做成周期性巡检, 知识库内容会随时间过期, 一份三个月前的价格表如果没被替换, 系统照样会拿它自信地回答用户, 这种"过期知识"问题在长期运行的系统里比冷启动阶段的问题更隐蔽。

五、自托管成本与部署清单

Dify 支持云端(Dify Cloud)、VPC 和自托管三种部署形态, 选哪种取决于数据合规要求和团队的运维能力。

云端定价 (据 Dify 官网 pricing 页面):

云端方案适合快速验证或者不想自建运维团队的场景, 但消息额度这个计费模型意味着调用量一旦上去, 成本会跟着线性涨, 这是选型时容易被低估的一点。

自托管: Dify 的社区版(Community Edition)开源免费, 可以部署在自己的基础设施上, 企业版功能则通过 license key 在自托管环境里激活。自托管适合对数据合规有硬性要求, 或者调用量大到云端按消息计费不划算的团队。

自托管前建议过一遍这份清单:

• 确认部署环境(Docker Compose 适合中小规模, 生产级建议 Kubernetes)
• 向量数据库选型确定(自带 Weaviate, 也支持接入 Qdrant/pgvector 等外部方案)
• 模型供应商接入方式确定, Dify 支持 50 多家 LLM 服务商, 私有化场景常见做法是本地部署开源模型 + Dify 的 OpenAI 兼容接口对接
• Rerank 模型和 embedding 模型是否需要单独部署(默认走云端 API 的话, 自托管场景要评估延迟和成本)
• 备份策略: 知识库文档 + 向量索引 + 工作流配置, 三者都要纳入备份, 光备份数据库不够
• 升级路径: 关注官方 Release 节奏, v1.14.2 这类版本里常带安全补丁(比如这次修的模板注入和 DoS 漏洞), 自托管团队升级不能拖太久

自托管最容易被低估的成本不是硬件, 是持续的版本跟进和安全补丁应用。开源项目更新快是好事, 但团队得有人专门盯着这件事, 不然"能跑"和"跑得安全"之间会越拉越远。

写在最后

RAG 系统上线后翻车, 十次里有八次不是模型能力的问题, 是切分策略、检索参数、兜底路径这些配置层面的细节没扛住真实场景的压力。Dify 把这些环节变成了可视化、可复查的配置项, 这比把逻辑散落在几百行胶水代码里更容易排查, 也更容易在团队内部对齐和交接。

但配置项摆在那不代表自动调对了。默认值(500 tokens 的 chunk, Top-K 为 3, rerank 默认关闭)是给通用场景兜底的起点, 不是终点。真正决定一条 RAG 管线好不好用的, 还是那句老话: 边界想清楚, 参数试出来, 验收标准别用感觉。

相关阅读可参考 如何为团队搭建可持续维护的知识库检索系统。

参考来源:

• langgenius/dify GitHub 仓库
• Dify 官方定价页面
• Dify Docs: 知识库分块与清洗设置
• Dify Docs: 知识检索节点
• langgenius/dify Releases