外部知识库集成指南：知识库 provider 路径（Dify dataset 兼容 + WeKnora）

项目概述

本指南说明 Servify 如何把外部知识库接入到 AI 编排链路中。当前代码选择链以 RagFlow 为首选 provider，Dify 为次选兼容路径，WeKnora 用于协议回归与 fallback 验证；未启用外部源时回落无知识源运行（knowledge.provider 默认为空，选择链返回「无源」即按无知识源形态启动）。pgvector / local 不是自动回落路径：二者需在配置文件显式声明 provider: "pgvector" / provider: "local" 才会启用（apps/server/internal/config/config.go:1316）。选择链实现见 apps/server/internal/app/server/knowledge_source.go，选型全景见知识库选型全景。

定位澄清（2026-09）：Dify 严格说是 LLM 应用编排平台，dataset 知识库只是其附属能力，不宜作为知识库长期主推方向。主流知识库选型与适配规划（RAGFlow 链首、pgvector 直配默认路径、Dify 定位降级）见知识库选型全景。文档名保留 WEKNORA_INTEGRATION 主要是为了兼容历史链接；内容语义以通用 knowledge provider 为主。

集成计划完成情况

已完成任务

项目路线图更新
- 更新了 README.md 中的第二阶段计划
- 将外部知识库 provider 集成纳入 AI 演进主路径
- 更新了技术架构图和技术栈说明
技术实施方案设计
- KnowledgeProvider 抽象与 QueryOrchestrator
- Dify provider 适配 (apps/server/internal/platform/knowledgeprovider/dify/)
- WeKnora provider 适配 (apps/server/internal/platform/knowledgeprovider/weknora/)
- 降级策略和熔断器机制
开发环境配置
- Dify / WeKnora provider 配置模板
- WeKnora mock 验收配置 (infra/compose/docker-compose.weknora.yml)
- 数据库初始化脚本 (scripts/init-db.sql)
- 环境变量配置模板 (.env.weknora.example)
- 配置文件模板 (config.weknora.yml)
兼容路径部署和管理脚本
- 一键启动脚本 (scripts/start-weknora.sh)
- 知识库初始化脚本 (scripts/init-knowledge-base.sh；初始化完成时会生成 scripts/manage-knowledge-base.sh 辅助脚本，供 search/list/stats 使用)

技术架构

集成架构

Servify 智能客服
       ↓
 Query Orchestrator
       ↓
 KnowledgeProvider（外部选择链：健康逐级降级，终点为无知识源运行）
   ├─ RagFlow (primary)
   ├─ Dify (secondary / compatibility)
   └─ WeKnora (compatibility)
（provider=pgvector / local 时配置直通，优先于外部选择链）

服务部署图

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Servify   │───▶│   RagFlow   │
│  (Port 8080)│    │  (primary)  │
└─────────────┘    └─────────────┘
         │
         ├────────────▶ Dify (secondary / compatibility)
         │
         └────────────▶ WeKnora (compatibility)

快速开始

当前项目的默认推荐是接入 RagFlow（外部专职知识库）或 pgvector（零外部依赖、进程内直配）；Dify 作为兼容路径保留。仓库里的 infra/compose/docker-compose.weknora.yml 仍然保留，用于 WeKnora 协议回归和 fallback 验证，不代表 WeKnora 是主路径。

1. 环境准备

bash

# 检查环境
docker --version
docker-compose --version

# 克隆项目（如果还没有）
git clone <your-servify-repo>
cd servify

2. 配置环境变量

bash

# 复制环境变量模板
cp .env.weknora.example .env

# 编辑环境变量，至少需要配置：
# - OPENAI_API_KEY: OpenAI API 密钥
# - RagFlow（链首）与 Dify（次选）的密钥不来自 .env.weknora.example，而是经 config.yml 的
#   ragflow 段与 dify 段配置（enabled/base_url/api_key/dataset_id）；.env.weknora.example
#   不含 DIFY_* / RAGFLOW_* 占位符
#   或 knowledge.provider=pgvector 直配（零外部依赖）
# - WEKNORA_API_KEY: 仅在需要兼容或 fallback 验收时配置
nano .env

3. 启动服务

bash

# 一键启动开发环境
./scripts/start-weknora.sh dev

# 等待服务启动完成...

4. 初始化兼容知识库

bash

# 创建 WeKnora compatibility 知识库并上传示例文档
./scripts/init-knowledge-base.sh

5. 验证 compatibility 集成

bash

# 检查服务健康状态
curl http://localhost:8080/health
curl http://localhost:9000/api/v1/health

# 测试知识库搜索（manage-knowledge-base.sh 由 init-knowledge-base.sh 初始化时生成）
./scripts/manage-knowledge-base.sh search "远程协助"

6. 运行 provider 验收脚本

bash

# Dify 兼容路径 mock 回归
DIFY_ACCEPTANCE_MODE=mock \
EVIDENCE_DIR=./scripts/test-results/dify-acceptance/mock \
./scripts/test-dify-integration.sh

# Dify 兼容路径真实环境验收
DIFY_ACCEPTANCE_MODE=real \
SERVIFY_URL=http://localhost:8080 \
DIFY_URL=https://<real-dify-host>/v1 \
DIFY_DATASET_ID=<real-dataset-id> \
EVIDENCE_DIR=./scripts/test-results/dify-acceptance/real \
./scripts/test-dify-integration.sh

# mock / 本地协议回归
WEKNORA_ACCEPTANCE_MODE=mock \
EVIDENCE_DIR=./scripts/test-results/weknora-acceptance/mock \
./scripts/test-weknora-integration.sh

# real / 真实 WeKnora 环境验收（仅用于兼容路径）
WEKNORA_ACCEPTANCE_MODE=real \
SERVIFY_URL=http://localhost:8080 \
WEKNORA_URL=https://<real-weknora-host> \
EVIDENCE_DIR=./scripts/test-results/weknora-acceptance/real \
./scripts/test-weknora-integration.sh

脚本会输出最小验收证据：

Dify 兼容路径：
- summary.txt
- manifest.json
- servify-health.json
- dify-dataset.json（可用时）
- ai-status.json
- ai-query.json
- knowledge-upload.json
- knowledge-sync.json
- ai-metrics.json
WeKnora compatibility 路径：
summary.txt
manifest.json
servify-health.json
weknora-health.json（可用时）
ai-status.json
ai-query.json
knowledge-upload.json
knowledge-sync.json
knowledge-provider-disable.json
ai-status-after-disable.json
ai-query-after-disable.json
ai-metrics-after-fallback.json
knowledge-provider-enable.json
ai-status-after-enable.json
circuit-breaker-reset.json

其中 Dify real 模式会严格拒绝 localhost、127.0.0.1、0.0.0.0、私网地址和 .local/.internal 主机名，避免把本地 mock 或内网临时地址误记为真实环境证据；同时要求：

dify-dataset 探针成功
knowledge provider 当前激活为 dify
knowledge_provider_enabled=true 且 knowledge_provider_healthy=true
ai-query 必须成功，且不能只返回 strategy=fallback
knowledge upload 和 knowledge sync 必须都成功

其中 WeKnora real 模式针对兼容路径，按严格口径验收：

WEKNORA_URL 不能是 localhost、127.0.0.1、0.0.0.0、私网地址或 .local/.internal 主机名
健康检查返回若标识 service=weknora-mock，脚本会直接拒绝作为真实证据
WeKnora 健康检查必须通过
Servify 必须运行在 enhanced 模式
knowledge provider 当前必须为 weknora
knowledge_provider_enabled=true 且 knowledge_provider_healthy=true
disable 后的 fallback 查询必须成功，证明外部 provider 不可用时降级路径可控
knowledge upload 和 knowledge sync 必须都成功

可以通过 make dify-acceptance、make weknora-acceptance 作为统一入口运行脚本；其中 knowledge-provider-acceptance 目前等价于 make weknora-acceptance，用于兼容路径回归。

只有满足以上条件，才能把结果回填到 docs/acceptance-checklist.md 里，分别作为 Dify 兼容路径和 WeKnora compatibility 路径的真实运行证据。

manifest.json 是机器可读验收索引，包含 provider、mode、关键状态、核心检查结果和实际生成的证据文件列表。真实环境回填时优先以 manifest.json 判断是否满足验收门槛，再引用具体响应文件作为人工审阅证据。

真实环境建议追加执行：

bash

# 先运行对应 acceptance 脚本，确保 real 目录下已生成 manifest.json
make validate-acceptance-manifest MANIFEST=./scripts/test-results/dify-acceptance/real/manifest.json
make validate-acceptance-manifest MANIFEST=./scripts/test-results/weknora-acceptance/real/manifest.json

# 如果需要校验仓库里已纳入 git 的全部证据目录
make check-acceptance-evidence

只有 validator 返回成功，才建议把该目录作为“可回填验收清单”的证据集；批量扫描也只会检查已纳入 git 的 manifest，避免把本地临时产物误算成正式证据。

开发指南

项目结构

servify/
├── docs/
│   └── WEKNORA_INTEGRATION.md     # 本文档
├── scripts/
│   ├── start-weknora.sh           # 启动脚本
│   ├── init-knowledge-base.sh     # 知识库初始化
│   ├── test-weknora-integration.sh # 集成验收（mock/real 两模式）
│   └── init-db.sql                # 数据库初始化
├── apps/server/
│   ├── pkg/weknora/               # WeKnora HTTP 客户端（client.go / types.go）
│   └── internal/platform/knowledgeprovider/
│       ├── weknora/               # WeKnora provider（知识库 provider 接口实现）
│       ├── dify/ ragflow/ local/ memory/ mock/ pgvector/   # 其他 provider
│       └── provider.go types.go   # provider 契约
├── infra/compose/
│   ├── docker-compose.weknora.yml # WeKnora 叠加编排（含 weknora-mock 服务）
│   └── weknora-mock/              # mock 实现（Dockerfile / main.go / main_test.go）
├── config.weknora.yml             # 配置文件模板
└── .env.weknora.example           # 环境变量模板

核心代码示例

Dify provider 使用

provider := difyprovider.NewProvider(
    dify.NewClient(&dify.Config{
        BaseURL: "https://dify.example.com/v1",
        APIKey:  "dify-key",
    }),
    "dataset-id",
    difyprovider.SearchConfig{
        TopK:           5,
        ScoreThreshold: 0.7,
        SearchMethod:   "semantic_search",
    },
)

WeKnora compatibility 客户端使用

// 创建客户端
client := weknora.NewClient(config, logger)

// 搜索知识库
response, err := client.SearchKnowledge(ctx, &weknora.SearchRequest{
    Query:           "用户问题",
    KnowledgeBaseID: "kb-id",
    Limit:           5,
    Strategy:        "hybrid",
})

// 上传文档
docInfo, err := client.UploadDocument(ctx, kbID, &weknora.Document{
    Type:    "text",
    Title:   "文档标题",
    Content: "文档内容",
    Tags:    []string{"tag1", "tag2"},
})

AI 服务集成

// 处理用户查询（知识源按 provider 直通 + ragflow→dify→weknora 选择链逐级降级，终点为无知识源运行）
response, err := aiService.ProcessQuery(ctx, userQuery, sessionID)

监控和维护

健康检查端点

Servify API: GET http://localhost:8080/health
Dify API: 以 GET /datasets/:id 作为 dataset 级健康探针
WeKnora API: GET http://localhost:9000/api/v1/health（兼容路径）
PostgreSQL: docker-compose -f infra/compose/docker-compose.yml exec postgres pg_isready
Redis: docker-compose -f infra/compose/docker-compose.yml exec redis redis-cli ping

日志查看

bash

# 查看所有服务日志
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs -f

# 查看特定服务日志
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs -f servify
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs -f weknora

# 查看应用日志文件
tail -f logs/servify.log

性能监控

bash

# 查看服务状态
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml ps

# 查看资源使用情况
docker stats

# 查看知识库统计（脚本由 init-knowledge-base.sh 初始化时生成）
./scripts/manage-knowledge-base.sh stats

安全配置

生产环境配置

修改默认密钥：
- 更改 JWT_SECRET
- 更改 WEKNORA_API_KEY
- 更改数据库密码
网络安全：
- 限制 CORS 允许的域名
- 配置防火墙规则
- 使用 HTTPS
数据安全：
- 定期备份数据库
- 加密敏感数据
- 实施访问控制

配置示例

yaml

# 生产环境配置
security:
  cors:
    allowed_origins: ["https://yourdomain.com"]
  rate_limiting:
    enabled: true
    requests_per_minute: 60

性能优化

故障排除

常见问题

1. WeKnora compatibility 服务无法启动

bash

# 检查端口占用
lsof -i :9000

# 检查配置文件
docker-compose config

# 查看详细错误日志
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml logs weknora

2. 数据库连接失败

bash

# 检查数据库状态
docker-compose -f infra/compose/docker-compose.yml exec postgres pg_isready -U postgres

# 检查网络连接
docker network ls
docker network inspect servify-network

3. 知识库搜索无结果

bash

# 检查文档是否上传成功（脚本由 init-knowledge-base.sh 初始化时生成）
./scripts/manage-knowledge-base.sh list

# 检查索引状态
curl -H "X-API-Key: default-api-key" \
     http://localhost:9000/api/v1/knowledge/default-kb

更新和维护

版本更新

bash

# 停止服务
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml down

# 更新镜像
docker-compose -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.weknora.yml pull

# 重新启动
./scripts/start-weknora.sh

数据备份

bash

# 备份 PostgreSQL
docker-compose -f infra/compose/docker-compose.yml exec postgres pg_dump -U postgres servify > backup.sql

# 备份 WeKnora compatibility 数据
docker cp servify_weknora:/app/data ./backup/weknora_data

当前状态与后续方向

当前仓库里的外部知识库集成已经完成了角色调整：

外部知识库选择链以 RagFlow 为首选，Dify 为次选兼容路径（provider=pgvector/local 时配置直通、优先于外部链）
WeKnora 不再作为系统内核能力存在，而是 KnowledgeProvider 的一个兼容实现
AI 主流程已经迁移到 QueryOrchestrator，只依赖统一检索抽象
标准模式和增强模式都可以在不改 handler 协议的前提下切换到编排式实现
后续如果切换到其他知识库，只需要新增 provider adapter，不需要重写 AI 主流程

更细的实施任务已经迁移到 docs/implementation/02-ai-and-knowledge.md 与 docs/implementation/04-sdk-and-channel-adapters.md，当前两份 backlog 都已清零。

后续增量工作不再单独挂在 WeKnora 文档里，而是归到下面几个长期方向：

新增更多 KnowledgeProvider 实现，例如 Milvus、Elasticsearch 或自行开发检索服务（pgvector 已实现：internal/platform/knowledgeprovider/pgvector/，经 knowledge.provider=pgvector 直配）
补齐文档上传、批量索引、重建索引等管理能力的统一接口
把监控、缓存、故障恢复、安全策略沉到平台层，而不是绑定到某一个知识库实现
让 Web/API/App SDK 统一消费稳定的 AI/knowledge contract，而不是感知具体 provider

支持和反馈

如有问题或建议，请：

查看本文档的故障排除部分
检查 Dify 或 WeKnora compatibility 对应 provider 文档
在项目 Issues 中提交问题
联系开发团队

当前结论：外部知识库默认推荐接入 RagFlow（专职知识库，选择链首选）或 pgvector（零外部依赖直配）；Dify 作为次选兼容路径保留，WeKnora 可以继续作为兼容或回退适配器保留，但系统架构已经不再依赖单一 provider。

外部知识库集成指南：知识库 provider 路径（Dify dataset 兼容 + WeKnora） ​

项目概述 ​

集成计划完成情况 ​

已完成任务 ​

技术架构 ​

集成架构 ​

服务部署图 ​

快速开始 ​

1. 环境准备 ​

2. 配置环境变量 ​

3. 启动服务 ​

4. 初始化兼容知识库 ​

5. 验证 compatibility 集成 ​

6. 运行 provider 验收脚本 ​

开发指南 ​

项目结构 ​

核心代码示例 ​

Dify provider 使用 ​

WeKnora compatibility 客户端使用 ​

AI 服务集成 ​

监控和维护 ​

健康检查端点 ​

日志查看 ​

性能监控 ​

安全配置 ​

生产环境配置 ​

配置示例 ​

性能优化 ​

推荐配置 ​

故障排除 ​

常见问题 ​

1. WeKnora compatibility 服务无法启动 ​

2. 数据库连接失败 ​

3. 知识库搜索无结果 ​

更新和维护 ​

版本更新 ​

数据备份 ​

相关资源 ​

官方文档 ​

社区资源 ​

当前状态与后续方向 ​

支持和反馈 ​

外部知识库集成指南：知识库 provider 路径（Dify dataset 兼容 + WeKnora）

项目概述

集成计划完成情况

已完成任务

技术架构

集成架构

服务部署图

快速开始

1. 环境准备

2. 配置环境变量

3. 启动服务

4. 初始化兼容知识库

5. 验证 compatibility 集成

6. 运行 provider 验收脚本

开发指南

项目结构

核心代码示例

Dify provider 使用

WeKnora compatibility 客户端使用

AI 服务集成

监控和维护

健康检查端点

日志查看

性能监控

安全配置

生产环境配置

配置示例

性能优化

推荐配置

故障排除

常见问题

1. WeKnora compatibility 服务无法启动

2. 数据库连接失败

3. 知识库搜索无结果

更新和维护

版本更新

数据备份

相关资源

官方文档

社区资源

当前状态与后续方向

支持和反馈