Enterprise Internal Knowledge Base: Production-Ready RAG + MCP

エンタープライズ向け内部ナレッジベース — 本番運用に対応した RAG + MCP

MCP サーバーとして公開されるパブリックな検索拡張生成パイプラインです。退役軍人省の教育マニュアルからサンプルコンテンツを使用しています。

このリポジトリでは、評価、可観測性、構造を考慮した取り込みを実装しています。コストやレイテンシーの調整、テナント単位のアクセス制御、その他の本番運用上の考慮事項については、以下の記事で解説しています。

📖 Towards AI の記事全文： Enterprise Internal Knowledge Base RAG MCP: POC-to-Production

---

これが存在する理由

RAG のデモは検索パイプラインの品質に注目しがちですが、本番環境の RAG がその後に続く 10 のステップで失敗することは見落とされています。コードレビューを通過しても回答品質を大きく損なうプロンプトやモデルの変更、特定のクエリまで追跡できないコストやレイテンシーの変動、監査で初めて明らかになるテナント間の情報漏えいなどです。このリポジトリでは、実際にそれらをどう検知するかを示しています。

コーパスは公開されています（退役軍人省の教育マニュアル — 238 件のドキュメント、9,000 件以上のチャンク）。誰でもパイプラインをクローンして実行し、応用できます。

---

クイックスタート

git clone https://github.com/kimsb2429/internal-knowledge-base
cd internal-knowledge-base

# 1. Start Postgres + pgvector
docker compose up -d

# 2. Python env + dependencies
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 3. Restore corpus fixture (~2 min — 238 docs + 9k chunks pre-embedded)
docker exec -i ikb_pgvector pg_restore -U ikb -d ikb < evals/fixture_v1.dump

# 4. Smoke-test the MCP server
python scripts/test_mcp_server.py     # 7/7 tests pass

# 5. Start the MCP server (stdio transport)
python scripts/mcp_server.py

Claude Desktop から利用する

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "ikb": {
      "command": "python",
      "args": ["/absolute/path/to/internal-knowledge-base/scripts/mcp_server.py"]
    }
  }
}

その後、「テキサス州で GI Bill の請求を扱う RPO はどこですか？」 のように Claude に質問してください。MCP サーバーは、引用付きのランキング済みチャンクを返します。

---

アーキテクチャ

取り込み（コーパスごとに 1 回）：

graph LR
    A[KnowVA crawler<br/>HTML + PDF] --> B[Source-specific<br/>preprocessor]
    B --> C[Structure-aware<br/>chunker]
    C --> D[mxbai-embed-large<br/>local, 1024-dim]
    D --> E[(pgvector)]
    F[Anthropic Contextual<br/>Retrieval] -.-> E
    E -.-> F
    style E fill:#e1f5fe

クエリ（MCP ツールの呼び出しごと）：

graph LR
    A[Claude Desktop<br/>MCP client] --> B[FastMCP server]
    B --> C[pgvector top-K]
    C --> D[Reranker<br/>mxbai or FlashRank]
    D --> E[Claude Sonnet<br/>generation]
    E --> A
    E --> F[Langfuse trace]
    style F fill:#fff9c4

技術スタック：

• ベクトルストア： Postgres + pgvector（Docker、ポート 5433）。content_tsv GIN インデックスはハイブリッド検索に対応
• 埋め込み： mxbai-embed-large（1024 次元、sentence-transformers を使ってローカルで実行）— API コスト $0
• リランカー： mxbai-rerank-base-v2（完全評価）／FlashRank MiniLM（CI の高速モード、22M ONNX、クエリあたり約 2 秒）
• 生成： Claude Sonnet
• MCP サーバー： FastMCP 3.2.4 — ツール（query）、リソース（document://{source_id}）、プロンプト（cite_from_chunks）
• 可観測性： Langfuse Cloud、トレースごとの公開共有
• 評価： DeepEval + 110 クエリのゴールデンセット + GitHub Actions のマージゲート

---

評価スコア

コンテキスト化したチャンクとリランカーを使用した、110 問のゴールデンセット全体の結果です：

指標	スコア
忠実度	0.95
回答の関連性	0.91
コンテキストの適合率	0.61
コンテキストの再現率	0.52
コンテキストの関連性	0.56

🔗 Langfuse のライブトレース（公開、ログイン不要）。

注目すべき結果： Anthropic の Contextual Retrieval パターンは、この規模ではリランキングに加えてわずかな改善をもたらしました（AnsRel は +4.8pp、CtxPrec は +4.1pp）。公表された数値が示唆していた再現率 +35% には遠く及びません。数値を誇張すれば、この取り組みの意義が損なわれるため、実測結果をそのまま報告しています。

---

マージゲートとしての CI での評価

すべての PR で、フィクスチャ DB に対してゴールデンセットを高速モード（FlashRank リランカー、所要時間約 3〜4 分、Sonnet の呼び出し料金 $0.30）で実行します。top1／topk／keyword_recall が ±5pp を超えて悪化する PR、または idk_rate が +10pp を超える PR はブロックされます。

恒久的な成果物： PR #5 — 意図的に失敗してから成功させた PR です。CI の赤表示で top1 の 20pp の回帰を検知し、緑表示で修正を確認できます。Actions タブがその証拠です。

ワークフロー： .github/workflows/eval-gate.yml。

---

このリポジトリで扱わない内容

本番運用で必要になる項目の一部は、実装ではなく拡張ポイントとして設けています：

• マルチテナントのスコープ設定 — すべての MCP ツールに auth_context パラメーターがあり、型も定義されていますが、現在は未使用です（SSO／ACL の拡張ポイントを示しています）
• 取り込みの並行処理 — チャンカーと埋め込み生成器はシングルスレッドです。本番環境では、剰余分散方式のワーカープールを使用します
• ハイブリッド検索の接続 — content_tsv GIN インデックスは稼働中です。クエリ時の BM25 + RRF 融合は、リリース後の追加項目として残しています

これらのトピックについては、上記の記事で解説しています。

---

リポジトリの構成

docs/                    Research, evidence base, deep-dives
data/                    Crawled corpus + golden query set
scripts/
  crawl_knowva.py            eGain v11 API crawler
  enrich_metadata.py         Headings, ACL, authority tier, content_category
  knowva_preprocess.py       Source-specific HTML normalization
  chunk_documents.py         Structure-aware splitter (preserves table colspan/rowspan)
  embed_and_store.py         mxbai-embed-large → pgvector
  contextualize_chunks.py    Anthropic Batches API for Contextual Retrieval
  rerank.py                  mxbai-rerank + FlashRank
  retrieve.py / generate.py  RAG path
  mcp_server.py              FastMCP exposure
  run_eval.py / score_eval.py / check_regression.py   Eval harness + CI gate
evals/                   Fixture DB dump + baseline JSON
.github/workflows/       eval-gate.yml — merge-gate workflow

---

生コーパスからの再現（約30分）

各スクリプトは冪等で、中断後も安全に再開できます。

python scripts/crawl_knowva.py            # Crawl raw HTML (skip if data/knowva_manuals/articles/ exists)
python scripts/enrich_metadata.py         # Add headings, ACL, authority tier
python scripts/knowva_preprocess.py       # Normalize HTML quirks
python scripts/chunk_documents.py         # Structure-aware split
python scripts/embed_and_store.py         # mxbai → pgvector
python scripts/contextualize_chunks.py    # Anthropic Batches API (~$12, optional but recommended)

続いて、python scripts/run_eval.py --fast を実行し、評価のベースラインが再現されることを確認します。

---

さらに詳しく

• デモの詳細な解説：Enterprise Internal Knowledge Base RAG MCP: POC-to-Production（Towards AI、Medium）
• docs/2026-04-11-engineering-rag-evidence-and-howtos.md — エンジニアリング分析、エビデンスの基盤、Zero-to-MCP の計画
• docs/2026-04-12-rag-pipeline-buy-vs-build.md — パイプラインの各段階における購入と自社構築の比較
• docs/deep-dive/2026-04-16-docs-vs-code-rag-adjudication.md — 統合 RAG が機能しなくなる場合

---

ライセンス

MIT — LICENSE を参照してください。