Dify 插件开发实验（08）：外部知识库插件——如何把外部检索能力做成插件？

1. 业务场景

先讲一个我们实际遇到的场景。

客服工单 SaaS 的问答要引用企业自建知识库：用户问「工单怎么创建」「退款规则是什么」，客服助手要给出有依据的回答。但这家企业早就有一套自建检索系统（LightRAG/自研 RAG），文档管线、权限体系、更新流程都跑了好几年——数据不搬进 Dify，客服问答时实时检索外部服务。

我们第一次接这类需求时，第一反应也是「把文档导进 Dify 知识库不就行了」。真正动手才发现——「搬进来」和「接进来」，是两种完全不同的交付：数据搬进 Dify 等于放弃数据主权，合规过不去；已有管线为接 Dify 再建一套纯属重复投入；文档每天在更新，插件不感知更新反而永远查的是最新状态——企业要的是把外部检索接进来，不是把数据搬进来。

这不是个例。任何已有自建检索系统的企业都是这个模式：数据主权要保留、已有管线不想重搭、文档每天在更新——「把外部检索能力接进 Dify」而不是「把数据搬进 Dify」，是这类场景的共同诉求。

2. 场景痛点

这个流程的痛点，在接入外部知识库时体现得最直接：

• 数据搬不动：企业知识库有严格的权限与审计要求，数据搬进 Dify 知识库等于放弃数据主权，合规过不去。
• 已有管线不想重搭：文档采集、清洗、索引、更新都是现成管线，为接 Dify 再建一套纯属重复投入。
• 实时性要求：客服问答要检索最新文档，外部管线负责更新——插件不感知更新，永远查的是最新状态。
• 原生/外部两难：Dify 原生知识库和外部检索到底用哪个？没有对照实验，决策全靠拍脑袋。

本质上，这类场景的诉求是「接进来」而不是「搬进来」——外部检索要做成 Dify 可消费的能力，还要能跟原生知识库对照评估、按需切换。

3. 方案：为什么是工具型检索插件

选工具型检索插件，我们实际对比过：

• 社区版唯一现实路径：实测 Dify 1.16 社区版平台级「外部知识库 API」是 enterprise 功能——工具型（tool 插件封装检索）是社区版唯一可行方案；
• 返回结构与原生对齐：{results: [{content, source, score}]} 与 Dify 检索语义一致，工作流里原生/外部双路径可互换处理；
• 空结果与故障分层：无命中返回 {results: []}（正常业务态），服务不可达返回 error（故障态）——下游降级逻辑清晰。

这篇文章我们就用它把外部检索能力做成工具插件：external_retrieve（query 必填、top_k 可选默认 3），并用 mock 外部检索服务验证「命中/空结果/故障」三态，与原生知识库做 6 题对照实验。

4. 整体架构

链路很清晰：收问题 → 调外部检索 → 按空结果/命中/故障三态分流。关键设计是语义分层——空结果和故障是两回事，空结果走正常降级提示，故障才走错误分支，下游才不会误降级。

5. 模块设计

5.1 工具参数声明（tools/external_retrieve.yaml）

parameters:

  - name: query

    type: string

    required: true

    form: llm

    llm_description: 'The user question to search against the external knowledge base'

  - name: top_k

    type: number

    required: false

    form: llm

    llm_description: 'Number of results to return, 1-10, default 3'

5.2 检索调用与语义分层（tools/external_retrieve.py）

空结果与故障分开，下游降级逻辑才清晰：

try:

    resp = requests.post(f"{service_url}/search",

                         json={"query": query, "top_k": top_k},

                         headers={"X-API-Key": api_key}, timeout=10)

except requests.exceptions.RequestException as e:

    yield self.create_text_message(err("upstream_error", f"retrieval service unreachable: {type(e).__name__}"))

    return

if resp.status_code == 401:

    yield self.create_text_message(err("auth_failed", "authentication failed, check api_key"))

    return

if resp.status_code != 200:

    yield self.create_text_message(err("upstream_error", f"retrieval service returned HTTP {resp.status_code}"))

    return

results = data.get("results") or []

# 空结果 = 正常业务态（无命中），返回 {results: []} 非错误

yield self.create_text_message(json.dumps({"results": results}, ensure_ascii=False))

5.3 关键决策点

Dify 1.16 外部知识库有两条路——平台级「外部知识库 API」对接 vs 工具型检索。实测结论：1.16 社区版平台级 API 是 enterprise 功能（社区版无），工具型（tool 插件封装检索）是社区版唯一现实路径。

6. 运行验证

对照结论：检索命中由内容覆盖决定——对照核心是「双路径可并存 + 工作流可切换」，质量对照需同内容库才有意义。接入成本：外部=插件安装+凭证（分钟级，数据不搬）；原生=建库+分段+索引（数据需搬入）。更新时效：外部由企业管线负责（插件不感知），原生由 Dify 管理。

7. 实战坑

8. 实验文档及源码获取

• 实验文档：DIFY-106-08：外部知识库插件.md
• 验证应用 DSL：dify106_08_验证应用.yml
• 插件安装包：dify106_08_retrieve_tool.signed.difypkg
• 源码目录：dify-106/dsl | dify-106/plugins

文章聚焦核心配置与采坑点，完整分步操作与对照实验记录见实验文档原文。