Knowledge Base 構築の3つの方式 – 手動アップロード・API同期・Webスクレイピングの使い分けガイド

Dify の Knowledge Base（ナレッジベース）は、RAG（Retrieval-Augmented Generation）アプリケーションの品質を左右する最も重要な基盤です。本記事では、Knowledge Base を構築する3つの主要な方式について、それぞれの適用シーン・設定のポイント・Embedding モデルの選択基準を実践的に解説します。

1. Knowledge Base 構築方式の全体像

Dify では、Knowledge Base にデータを投入する方法として大きく3つのアプローチがあります。

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. 方式1: 手動アップロード（Web UI）

2.1 適用シーン

• PoC（概念実証）フェーズで素早く検証したい
• ドキュメント数が数十件以下で、更新頻度が低い
• 非エンジニアのビジネスチームがナレッジを管理する
• 初期の精度検証や Chunk 設定のチューニングを行う

2.2 操作手順

1. Dify コンソール左メニューの 「Knowledge」 をクリック
2. 「Create Knowledge」 ボタンを押下
3. 「Import from file」 を選択
4. 対象ファイルをドラッグ＆ドロップ（対応形式: TXT, Markdown, PDF, DOCX, CSV, HTML）
5. Chunk 設定・Embedding モデルを選択して 「Save & Process」

2.3 対応ファイル形式と制限

2.4 Chunk（チャンク）設定のベストプラクティス

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

設定の考え方:

• 短いチャンク（300-500トークン）: 精度重視。FAQ、定義集、手順書向き
• 長いチャンク（800-1500トークン）: 文脈維持重視。技術解説、レポート向き
• overlap: 文脈の途切れを防ぐ。全体の10-15%程度を目安に設定

2.5 手動アップロードの限界

• 前処理（OCR、クリーニング、メタデータ付与）は手動で事前に行う必要がある
• 大量ファイルの一括更新には向かない
• バージョン管理や差分更新の仕組みがない

3. 方式2: API 同期（Dataset API / Knowledge Pipeline）

3.1 適用シーン

• 100件以上のドキュメントを定期的に更新する
• 社内 CMS・ドキュメント管理システムとの自動連携が必要
• OCR、テキストクリーニング、メタデータ抽出などの前処理パイプラインを組みたい
• CI/CD パイプラインの一部としてナレッジ更新を自動化したい

3.2 Dataset API の基本構造

Dify は Dataset 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 Knowledge Pipeline の設計パターン

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. 方式3: Web スクレイピング（Firecrawl 連携）

4.1 適用シーン

• 公開ヘルプサイトや FAQ ページをナレッジ化したい
• 自社 Web ドキュメントを定期的にクロールして最新状態を維持したい
• 手動コピー＆ペーストの手間を省きたい

4.2 Firecrawl の設定

Dify は Firecrawl との連携により、Web ページの自動クロール・テキスト抽出・Knowledge Base への投入をサポートしています。

環境変数設定（Self-hosted の場合）:

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

4.3 Web スクレイピングによる Knowledge 作成手順

1. Knowledge 作成画面で 「Sync from website」 を選択
2. 対象 URL を入力（例: https://docs.example.com/）
3. クロール設定を指定:
   • Max pages: クロール対象の最大ページ数
   • Crawl sub-pages: サブページも含めるかどうか
   • Exclude paths: 除外するパスパターン
4. プレビューで取得結果を確認
5. Chunk 設定を調整して 「Save & Process」

4.4 Web スクレイピング時の注意点

5. Embedding モデルの選択基準

Knowledge Base 構築時に選択する Embedding モデルは、検索精度に直結する重要な設定です。

5.1 Dify で利用可能な主要 Embedding モデル

5.2 日本語コンテンツでの選択指針

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

5.3 Indexing 方式の選択

推奨: 本番環境では必ず High Quality を選択してください。Economical モードはキーワード一致のみで、意味的な検索ができません。

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. 構築後の品質検証チェックリスト

Knowledge Base を構築した後は、以下の観点で品質を検証します。

• 検索テスト: 想定される質問を10件以上投げて、関連セグメントが上位に返るか確認
• チャンクの粒度確認: セグメントが細かすぎて文脈が失われていないか
• ノイズ確認: 不要なヘッダー、フッター、メニュー文字列が混入していないか
• メタデータ確認: ドキュメント名、ソース情報が正しく付与されているか
• Embedding モデルの一貫性: 同一 Knowledge Base 内で異なるモデルが混在していないか
• 重複排除: 同一内容のセグメントが複数存在していないか

8. トラブルシューティング

よくある問題と対処法

9. まとめ

Knowledge Base の構築方式は「どれが正解」ではなく、プロジェクトの規模・データソース・更新頻度・チーム体制に応じて最適な方式を選ぶことが重要です。

実際のプロジェクトでは、PoC は手動アップロードで素早く検証し、本番移行時に API 同期パイプラインを構築するという段階的アプローチが最も一般的です。Web スクレイピングは公開コンテンツの取り込みに特化して併用するのが効果的です。