构建知识库的三种方法–手动上传、API同步、网页抓取的使用指南

Dify 的知识库是检索增强生成 (RAG) 应用程序质量的最重要基础。在本文中，我们将实际讲解构建知识库的三种主要方法，以及每种方法的适用场景、设置要点以及嵌入模型选择标准。

1.知识库构建方法概述

Dify 具有三种主要方法来用数据填充知识库。

flowchart LR
    A[データソース] --> B{構築方式の選択}
    B -->|少量・検証| C[手動アップロード]
    B -->|大規模・自動化| D[API 同期]
    B -->|Webコンテンツ| E[Web スクレイピング]
    C --> F[Knowledge Base]
    D --> F
    E --> F
    F --> G[RAG アプリケーション]

2.方法一：手动上传（Web UI）

2.1 适用场景

• 想要在 PoC（概念验证）阶段快速验证
• 文档数量不到几十个且更新不频繁
• 非工程业务团队管理知识
• 执行初始精度验证并调整块设置

2.2 操作流程

1.点击Dify控制台左侧菜单知识 2. 按**“创建知识”按钮 3. 选择从文件导入** 4. 拖放目标文件（支持格式：TXT、Markdown、PDF、DOCX、CSV、HTML） 5. 块设置/嵌入选择模型并**“保存并处理”**

2.3 支持的文件格式和限制

2.4 Chunk配置最佳实践

# 推奨設定例
chunk_mode: automatic       # 自動分割を推奨（初回）
max_segment_length: 500     # トークン数ベース
overlap: 50                 # セグメント間の重複トークン
separator: "\n\n"           # 段落区切りを優先

设置理念：

• 短块（300-500 个标记）：注重精度。适用于常见问题解答、定义集合和程序手册
• 长块（800-1500 个标记）：专注于维护上下文。技术说明和报告
• 重叠：防止上下文中断。设置为总数的10-15%左右。

2.5 手动上传的限制

• 预处理（OCR、清理、元数据添加）必须提前手动完成
• 不适合大量文件的批量更新
• 无版本控制或差异更新机制

3.方法二：API同步（Dataset API / Knowledge Pipeline）

3.1 适用场景

• 定期更新100+文档
• 需要与内部CMS/文档管理系统自动联动
• 我想为 OCR、文本清理、元数据提取等构建一个预处理管道。
• 希望将知识更新自动化作为 CI/CD 管道的一部分

3.2 Dataset API的基本结构

Dify 提供以下端点作为数据集 API。

# ベースURL
BASE_URL="https://your-dify-instance.com/v1"

# データセット作成
curl -X POST "${BASE_URL}/datasets" \
  -H "Authorization: Bearer ${DATASET_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "製品マニュアル_v2",
    "permission": "only_me"
  }'

3.3 文档输入的API流程

# ドキュメントをテキストで投入
curl -X POST "${BASE_URL}/datasets/${DATASET_ID}/document/create-by-text" \
  -H "Authorization: Bearer ${DATASET_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ_営業部門.md",
    "text": "## よくある質問\n\nQ: 納期の目安は？\nA: 通常2-3営業日です。",
    "indexing_technique": "high_quality",
    "process_rule": {
      "mode": "automatic"
    }
  }'

# ファイルアップロードによる投入
curl -X POST "${BASE_URL}/datasets/${DATASET_ID}/document/create-by-file" \
  -H "Authorization: Bearer ${DATASET_API_KEY}" \
  -F "file=@/path/to/document.pdf" \
  -F 'data={"indexing_technique":"high_quality","process_rule":{"mode":"automatic"}}'

3.4 知识管道设计模式

flowchart TD
    A[外部データソース] --> B[抽出 Extract]
    B --> C[前処理 Transform]
    C --> C1[OCR変換]
    C --> C2[HTMLクリーニング]
    C --> C3[メタデータ付与]
    C --> C4[重複排除]
    C1 --> D[Dataset API 投入]
    C2 --> D
    C3 --> D
    C4 --> D
    D --> E[Embedding & Index]
    E --> F[Knowledge Base]

3.5 自动同步脚本示例（Python）

import os
import requests
import hashlib
from pathlib import Path

DIFY_BASE_URL = os.environ["DIFY_BASE_URL"]
DATASET_API_KEY = os.environ["DATASET_API_KEY"]
DATASET_ID = os.environ["DATASET_ID"]

HEADERS = {
    "Authorization": f"Bearer {DATASET_API_KEY}"
}

def compute_hash(filepath: str) -> str:
    """ファイルのハッシュ値を計算（差分検知用）"""
    return hashlib.md5(Path(filepath).read_bytes()).hexdigest()

def upload_document(filepath: str, dataset_id: str):
    """ドキュメントを Dataset API 経由でアップロード"""
    url = f"{DIFY_BASE_URL}/v1/datasets/{dataset_id}/document/create-by-file"
    with open(filepath, "rb") as f:
        response = requests.post(
            url,
            headers=HEADERS,
            files={"file": f},
            data={
                "data": '{"indexing_technique":"high_quality","process_rule":{"mode":"automatic"}}'
            }
        )
    response.raise_for_status()
    return response.json()

def sync_directory(directory: str, dataset_id: str):
    """ディレクトリ内の全ドキュメントを同期"""
    supported_ext = {".txt", ".md", ".pdf", ".docx", ".csv"}
    for path in Path(directory).rglob("*"):
        if path.suffix.lower() in supported_ext:
            print(f"Uploading: {path.name}")
            result = upload_document(str(path), dataset_id)
            print(f"  -> Document ID: {result['document']['id']}")

if __name__ == "__main__":
    sync_directory("./docs", DATASET_ID)

3.6 API 同步最佳实践

• 实施差异更新：记录文件哈希并仅重新填充更改的文档
• 使用元数据：添加文档类别、更新日期和版本作为元数据
• 控制批量大小：一次输入大量可能会导致超时。一次处理 50-100 个项目
• 错误处理：确保包含重试逻辑和失败日志记录

4.方法三：网页抓取（Firecrawl配合）

4.1 适用场景

• 我想将公共帮助网站和常见问题解答页面变成知识
• 我想定期抓取公司的网络文档以使其保持最新状态。
• 想要避免手动复制和粘贴的麻烦吗？

4.2 Firecrawl配置

Dify 与 Firecrawl 配合，支持网页自动抓取、文本提取、输入知识库。

环境变量设置（自托管）：

# docker-compose.yml または .env
FIRECRAWL_API_KEY=fc-xxxxxxxxxxxxx

4.3 通过网络抓取创建知识的过程

1. 在知识创建屏幕上选择**“从网站同步”**
2. 输入目标URL（例如https://docs.example.com/）
3. 指定爬网设置：
   • 最大页面：要抓取的最大页面数
   • 抓取子页面：是否也包含子页面。
   • 排除路径：要排除的路径模式
4. 在预览中查看获得的结果
5. 调整块设置并保存并处理

4.4 网页抓取时的注意事项

5.嵌入模型选择标准

构建知识库时选择的嵌入模型是一个重要的设置，直接影响搜索的准确性。

5.1 Dify 中可用的主要嵌入模型

5.2 日语内容的选择指南

判断フロー:
├── データを外部に送信できない
│   └── ローカルモデル（Ollama + multilingual-e5-large 等）
├── 多言語混在コンテンツ
│   └── Cohere embed-multilingual-v3.0
├── 日本語中心 + 高精度を求める
│   └── text-embedding-3-large
└── コストを抑えたい
    └── text-embedding-3-small

5.3 索引方法选择

推荐：对于生产环境始终选择高质量。经济模式仅允许关键字匹配，不允许语义搜索。

6. 方法选择的决策树

根据项目情况选择流程如下所示。

flowchart TD
    START[Knowledge Base 構築開始] --> Q1{ドキュメント数は?}
    Q1 -->|50件以下| Q2{更新頻度は?}
    Q1 -->|50件超| Q3{データソースは?}
    Q2 -->|月1回以下| MANUAL[手動アップロード]
    Q2 -->|週1回以上| API[API 同期]
    Q3 -->|社内CMS/DB| API
    Q3 -->|公開Webサイト| WEB[Web スクレイピング]
    Q3 -->|ファイルサーバ| API
    MANUAL --> TUNE[Chunk 設定チューニング]
    API --> TUNE
    WEB --> TUNE
    TUNE --> VERIFY[検索精度検証]
    VERIFY --> PROD[本番運用]

7. 施工后质量验证检查表

建立知识库后，请使用以下方面验证其质量：

• 搜索测试：询问至少 10 个预期问题，看看相关细分是否返回较高水平。
• 检查块粒度：段是否太小而无法丢失上下文？
• 噪音检查：是否混入了任何不必要的页眉、页脚或菜单字符串？
• 元数据确认：文档名称和来源信息是否正确指定？
• 嵌入模型一致性：不同模型是否混合在同一个知识库中？
• 重复数据删除：是否存在多个具有相同内容的片段？

8. 故障排除

常见问题及解决方案

9. 总结

选择正确的构建知识库的方法并不重要，重要的是根据项目的规模、数据来源、更新频率、团队结构来选择最合适的方法。

在实际项目中，最常见的方法是通过手动上传快速验证 PoC，然后在投入生产时构建 API 同步管道。专门用于捕获公共内容时，网络抓取非常有效。