Enterprise Internal Knowledge Base: Production-Ready RAG + MCP

企业内部知识库——生产就绪的 RAG + MCP

作为 MCP 服务公开的检索增强生成（RAG）流水线。内容示例取自美国退伍军人事务部教育手册。

该仓库实现了评估、可观测性和结构感知式数据摄取。成本/延迟优化、租户级访问控制及其他生产环境考量，请参阅下方链接的文章。

📖 Towards AI 上的完整文章： 企业内部知识库 RAG MCP：从 POC 到生产

---

项目缘由

RAG 演示往往只关注检索流水线的质量，却没有意识到生产环境中的 RAG 会在接下来的十个环节出问题：提示词或模型的变更通过代码审查，却令答案质量大幅下降；成本和延迟不断波动，却无法追溯到具体查询；跨租户数据泄露，直到审计时才浮出水面。这个仓库展示了如何在实践中发现这些问题。

语料库是公开的（美国退伍军人事务部教育手册——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"]
    }
  }
}

然后向 Claude 提出诸如 “德克萨斯州 GI Bill 申请由哪个 RPO 负责？” 这样的问题——MCP 服务会返回经过排序且附有引用的分块。

---

架构

数据摄取（每个语料库一次）：

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，支持每条 trace 公开分享
• 评估： DeepEval + 110 个查询的黄金集 + GitHub Actions 合并门禁

---

评估分数

完整的 110 个问题黄金集，使用上下文化分块 + 重排器：

指标	分数
忠实度	0.95
答案相关性	0.91
上下文精确率	0.61
上下文召回率	0.52
上下文相关性	0.56

🔗 Langfuse 实时 trace（公开，无需登录）。

值得注意的结果： 在此规模下，Anthropic 的上下文检索模式在重排基础上仅带来了有限提升（答案相关性 +4.8 个百分点，上下文精确率 +4.1 个百分点），远低于其公布数据所暗示的 +35% 召回率。结果如实呈现；夸大数字就违背了初衷。

---

将 CI 评估用作合并门禁

每个 PR 都会在快速模式下（FlashRank 重排器，实际运行约 3–4 分钟，Sonnet 调用费用 $0.30）使用 fixture DB 运行黄金集。若 PR 导致 top1/topk/keyword_recall 下降超过 ±5 个百分点，或 idk_rate 上升 +10 个百分点，则会被阻止合并。

永久留存的示例： PR #5——一个先故意失败、再修复通过的 PR。CI 红灯发现 top1 下降 20 个百分点；CI 绿灯则确认修复有效。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，验证评测基线是否能复现。

---

延伸阅读

• 完整演示说明：企业内部知识库 RAG MCP：从 POC 到生产（Towards AI，Medium）
• docs/2026-04-11-engineering-rag-evidence-and-howtos.md — 工程分析、证据基础、从零到 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。