4.5 · 外部知识库集成（External Knowledge Base Integration）

外部知识库集成

外部知识库集成

相关源文件

本章引用的主要源码文件：

• api/controllers/console/app/annotation.py
• api/controllers/console/datasets/data_source.py
• api/controllers/console/datasets/datasets_document.py
• api/controllers/console/datasets/datasets_segments.py
• api/controllers/console/datasets/external.py
• api/controllers/console/datasets/hit_testing.py
• api/controllers/console/datasets/metadata.py
• api/controllers/console/datasets/rag_pipeline/datasource_auth.py
• api/controllers/console/workspace/trigger_providers.py
• api/controllers/service_api/app/annotation.py
• api/controllers/service_api/dataset/dataset.py
• api/controllers/service_api/dataset/document.py
• api/controllers/service_api/dataset/metadata.py
• api/controllers/service_api/dataset/segment.py
• api/services/annotation_service.py
• api/services/attachment_service.py
• api/services/dataset_service.py
• api/services/entities/knowledge_entities/knowledge_entities.py
• api/services/external_knowledge_service.py
• api/services/knowledge_service.py
• api/services/plugin/plugin_parameter_service.py
• api/services/retention/workflow_run/restore_archived_workflow_run.py
• api/services/trigger/trigger_provider_service.py
• api/services/trigger/trigger_subscription_builder_service.py
• api/tests/test_containers_integration_tests/models/test_conversation_status_count.py
• api/tests/test_containers_integration_tests/services/test_trigger_provider_service.py
• api/tests/unit_tests/controllers/service_api/app/test_annotation.py
• api/tests/unit_tests/controllers/service_api/dataset/test_dataset_segment.py
• api/tests/unit_tests/controllers/service_api/dataset/test_document.py
• api/tests/unit_tests/controllers/web/test_web_login.py
• api/tests/unit_tests/models/test_app_models.py
• api/tests/unit_tests/services/auth/test_jina_auth_standalone_module.py
• api/tests/unit_tests/services/hit_service.py
• api/tests/unit_tests/services/retention/workflow_run/test_restore_archived_workflow_run.py
• api/tests/unit_tests/services/test_annotation_service.py
• api/tests/unit_tests/services/test_batch_indexing_base.py
• api/tests/unit_tests/services/test_external_dataset_service.py
• api/tests/unit_tests/services/test_knowledge_service.py
• api/tests/unit_tests/services/test_message_service.py
• api/tests/unit_tests/services/test_metadata_bug_complete.py
• api/tests/unit_tests/services/test_metadata_nullable_bug.py
• api/tests/unit_tests/services/test_operation_service.py
• api/tests/unit_tests/services/test_trigger_provider_service.py
• api/tests/unit_tests/services/test_website_service.py

目的与范围

本文档记录了 Dify 的外部知识库集成系统。该系统使数据集能够从基于外部 HTTP API 的知识源检索信息，而非依赖内部存储的文档。内部数据集使用 Dify 的索引管线（参见文档索引管线），而外部数据集则将存储和检索委托给第三方系统。

外部知识集成使组织能够：

• 将 Dify 连接到现有的知识管理系统（例如 AWS Bedrock 知识库）。
• 通过 API 直接查询外部源，避免数据重复。
• 在利用 Dify 的编排和检索增强生成（RAG）能力的同时，保持数据主权。

架构总览

外部知识集成采用基于模板的架构。通过可复用的 API 配置（ExternalKnowledgeApis），多个数据集可以借助 ExternalKnowledgeBindings 连接到不同的外部知识源。

组件图

来源：api/services/dataset_service.py:39-54, api/services/external_knowledge_service.py:27-28, api/models/dataset.py:15-19

数据模型与领域实体

外部知识 API 模板

ExternalKnowledgeApis 模型存储可复用的 API 配置。这些模板定义了与外部提供方通信所需的端点和认证信息。

关键设置结构： settings 字段是一个 JSON 字符串（通过 settings_dict 属性以字典形式处理），通常包含：

• endpoint：目标 API URL。
• api_key：认证凭证。

在创建模板之前，ExternalDatasetService 会通过 ssrf_proxy 向提供的 URL 的 /retrieval 端点发送 POST 请求，执行连通性检查。

来源：api/services/external_knowledge_service.py:59-75, api/services/external_knowledge_service.py:78-103, api/models/dataset.py:17-17

外部数据集绑定

ExternalKnowledgeBindings 模型充当标准 Dataset 实体与外部提供方之间的桥梁。

来源：api/models/dataset.py:39-54, api/services/external_knowledge_service.py:170-185

外部数据集生命周期

创建流程

外部数据集通过服务 API 或控制台创建，需要指定 external_knowledge_api_id 和具体的 external_knowledge_id（外部系统中的标识符）。

实现逻辑：

1. 调用 DatasetService.create_empty_dataset，并将 provider 设置为 external。
2. 如果提供了 external_knowledge_api_id，系统会验证该 API 模板是否存在。
3. 创建一个 Dataset 记录，其 DatasetRuntimeMode 为 EXTERNAL。
4. 初始化一个 ExternalKnowledgeBindings 记录，将 Dify 数据集与外部提供方的 API 及特定知识库 ID 关联起来。

来源：api/services/dataset_service.py:203-280, api/controllers/service_api/dataset/dataset.py:43-54, api/models/enums.py:56-56

检索与命中测试

与通过 VectorService 查询本地向量数据库的内部数据集不同，外部数据集通过 ExternalDatasetService 使用 HTTP 客户端获取结果。

执行流程：

1. 系统获取与 Dataset 关联的 ExternalKnowledgeBindings。
2. 检索 ExternalKnowledgeApis 模板以获取 endpoint 和 api_key。
3. 构建检索请求，目标路径为 {endpoint}/retrieval。
4. 使用 ssrf_proxy.post 执行请求，传递查询和检索参数。
5. 结果以外部源返回的片段列表形式呈现。

来源：api/services/external_knowledge_service.py:170-205, api/services/external_knowledge_service.py:78-103, api/core/helper/ssrf_proxy.py:1-20

服务层实现

ExternalDatasetService 函数

api/services/external_knowledge_service.py 中的 ExternalDatasetService 类处理外部集成的核心逻辑。

DatasetService 集成

DatasetService 在数据集管理过程中集成了外部逻辑：

对比：外部 vs 内部

来源：api/services/external_knowledge_service.py:78-103, api/models/enums.py:55-57

安全与隔离

1. 租户隔离：对 ExternalKnowledgeApis 或 ExternalKnowledgeBindings 的每次查询都包含 tenant_id 过滤器，以防止跨租户数据泄露。api/services/external_knowledge_service.py:32-36, api/services/external_knowledge_service.py:105-110
2. SSRF 保护：所有对外部知识端点的出站调用都通过 core.helper.ssrf_proxy 路由，以降低服务端请求伪造（SSRF）风险。api/services/external_knowledge_service.py:94-94
3. 基于角色的访问：对外部数据集配置的访问权限受与内部数据集相同的 TenantAccountRole 逻辑控制，需要相应的权限。api/services/dataset_service.py:134-150

来源：api/services/external_knowledge_service.py:32-36, api/services/external_knowledge_service.py:105-110, api/services/dataset_service.py:134-150