Dify 通用外部知识库 API 服务

本项目是一个遵循 Dify.ai 外部知识库 API 规范的通用后端服务。它能够索引本地文件目录，并作为一个或多个独立的知识库，通过 API 响应 Dify 平台的检索请求。

✨ 核心功能

• 兼容 Dify: 完全遵循 Dify 的外部知识库 API 规范。
• 多知识库支持: 可同时管理多个独立的知识库，通过 knowledge_id 进行隔离和调用。
• 增量更新: 通过文件内容哈希值比对，高效地对知识库进行增量更新，仅处理新增或有修改的文档。
• 可配置元数据: 每个知识库可通过独立的 kb_config.json 文件定义灵活的元数据提取规则。
• 先进的检索架构 (Recall & Re-rank):
  1. 查询扩展: 利用大语言模型 (LLM) 自动扩展用户查询，提高召回率。
  2. 向量召回: 使用 FAISS 进行高效的向量相似度搜索，初步筛选候选文档。
  3. 精准排序: 将召回的文档交由专业的 Re-rank 模型进行二次排序，确保最相关的结果排在最前。

📂 项目结构

.
├── .env                # (需手动创建) 存放 API 密钥
├── .env.example        # 环境变量模板文件
├── .gitignore          # Git 忽略规则
├── .gitattributes      # Git 文件属性配置
├── GEMINI.md           # Gemini 代理的项目记忆文件
├── requirements.txt    # Python 依赖
|
├── knowledge_base/     # (用户提供) 存放一个或多个知识库的源文档目录
│   ├── fluffos/        # "fluffos" 知识库
│   └── demo/           # "demo" 知识库
|
├── data/               # (自动生成) 存放所有知识库的索引文件
│   ├── fluffos_index.faiss
│   ├── fluffos_meta.db
│   └── ...
|
├── generate_index.py   # 用于生成/更新知识库索引的脚本
└── main.py             # API 服务启动文件

🚀 安装与设置

1. 克隆仓库

   git clone <your-repo-url>
   cd <repo-name>

2. 创建并激活虚拟环境 (推荐)

   python -m venv venv
   # Windows
   .\venv\Scripts\activate
   # macOS/Linux
   source venv/bin/activate

3. 安装依赖

   pip install -r requirements.txt

4. 配置环境变量 将 .env.example 文件复制一份并重命名为 .env，然后填入您的 API 密钥。

   # Windows
   copy .env.example .env
   # macOS/Linux
   cp .env.example .env

   编辑 .env 文件:

   DASHSCOPE_API_KEY="sk-your-dashscope-key"
   DIFY_API_KEY="your-custom-secret-key"
   

🛠️ 使用方法

1. 填充知识库 在 knowledge_base 目录下，创建您自己的知识库目录（目录名将作为 knowledge_id），并放入您的文档（目前支持 .md 和 .txt）。

2. 生成索引 运行索引脚本来处理您的文档。您可以选择处理单个知识库或所有知识库。

   # 处理名为 "fluffos" 的知识库
   python generate_index.py fluffos
   
   # 处理所有知识库
   python generate_index.py --all

3. 启动 API 服务

   python main.py

   服务将默认启动在 http://127.0.0.1:8080。

🔗 在 Dify 中配置

请遵循 Dify 官方的 连接外部知识库 指南，分为两步进行配置。

第一步：关联外部知识库 API

前往 “知识库” 页，点击右上角的 “外部知识库 API”，轻点 “添加外部知识库 API”。

• 知识库的名称: 自定义，例如 My Local API Service。
• API 接口地址: http://<您的公网或可访问地址>:8080
• API Key: 填写您在 .env 文件中为 DIFY_API_KEY 设置的密钥。

第二步：连接知识库实例

在 Dify 的 知识库 页面，点击“创建知识库”，然后选择“连接外部知识库”。

• 外部知识库 API: 选择您在上一步中创建的 API (My Local API Service)。
• 外部知识库 ID: 指定您要连接的具体知识库，即您在 knowledge_base 目录下创建的子目录名。例如，填写 fluffos 或 demo。
• 召回设置: 根据您的需求调整 Top K 和 Score 阈值。我们的 API 服务会完全遵循您在此处设置的参数。

完成以上步骤后，您的 Dify 应用便可以正式使用这个外部知识库了。