Agent Knowledge Base

自托管、给 Agent 用的知识库服务：hybrid 检索、可精确回查的证据（span/版本/内容哈希）、HTTP 与 MCP 只读接入，以及 rag/agentic 双模式单次问答。入库与证据链路由 manifest 驱动，语料可整体替换；仓库内置一份受治理的中文 RAG 示例语料与配套评测集，本页评测结果均在该示例语料上测得。

状态：活跃原型，面向本地部署。 鉴权可选（Bearer）；未内置限流与 TLS，不建议直接暴露公网。

Why

LLM Agent 的答案质量取决于它引用的事实是否可信。与其让模型在参数里猜，不如给它一个可回查的事实来源：检索命中带精确 span 与版本元数据，引用经机械校验必须命中真实证据，过期版本有明确标识。过程上下文归调用方的 agent，事实依据归本库——服务无会话状态。

三种用法：

• Agent 接地（重心）：外部 MCP 客户端（Pi 等）把 search/get_context 当工具，取带 span/版本的证据，用自己的模型回答

• 问答委托：应用调 ask_knowledge 得 decision（answered/澄清/拒答）与机械校验过的引用；rag/agentic 双模式同时是接地质量与编排成本的测量仪

• 多 Agent 共享知识（规划中）：身份、公共/私有分区、协作写入、文档历史

Related MCP server: OKF MCP Server

Features

• Hybrid 检索：Qdrant dense + FastEmbed BM25 sparse 融合；父子分块，child 命中、parent 全文取回

• 证据可精确回查：evidence_id → 有界原文窗口，content_hash 客户端可复算，span 是父文本的精确字符切片

• 引用机械校验：evidence_id 必属本次实际证据、quote 必须是证据原文精确子串；预算内自动修复一次，仍失败显式报错——不伪造引用

• 单次 decision 协议：answered / clarification_required / refused 皆为终态；无会话、无跨请求状态

• 双模式问答：rag 单图（快、便宜）与 agentic 双图（改写/拆解/并行补查，共享请求级预算：3 子问题 / 8 工具调用 / 10 迭代），同 index/模型同场对照见 Evaluation

• MCP 只读接入：Streamable HTTP 端点 + Bearer 鉴权，Agent 的工具即知识库

• manifest 语料治理：逐文件登记来源、许可、SHA-256；同步采用镜像语义清理清单外残留，语料可整体替换

• 版本元数据全链路：version / effective_date / expired_date / priority 从 manifest 流经 chunk → 检索 → API → eval

• 可复现评测：30 题 golden set（6 类题型）、40 题检索挑战集、规模与并发实测；报告绑定 commit / index / 模型 / 参数

• 生成模型可选：未配置 key 时检索照常 ready，问答返回明确的 llm_not_configured

Quick Start

需要 Python 3.11+。

git clone https://github.com/mothieras/agent-knowledge-base.git
cd agent-knowledge-base
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -r requirements.txt

（可选）配置生成模型——不配置也能完整使用检索与证据回查：

cp .env.example .env
# DEEPSEEK_API_KEY=sk-...  LLM_MODEL=deepseek-chat  LLM_BASE_URL=...  JUDGE_MODEL=...

构建本地索引（首次运行会下载 embedding 模型）并启动 API：

python src/ingest_corpus.py
cd src && uvicorn api.main:app --host 127.0.0.1 --port 8000

curl http://127.0.0.1:8000/health                                   # 检索 readiness（不依赖 LLM）
curl http://127.0.0.1:8000/invoke -H 'Content-Type: application/json' \
  -d '{"message":"什么是 HyDE？","mode":"rag"}'                     # 单次问答
curl -N http://127.0.0.1:8000/stream -H 'Content-Type: application/json' \
  -d '{"message":"解释 HyDE 如何改写检索问题","mode":"agentic"}'    # SSE 流式

Gradio 客户端：cd src && API_URL=http://127.0.0.1:8000 python app.py（UI 只是 API 的薄客户端）。

Docker

docker build -t agent-kb-demo .
docker run -d --name agent-kb -p 8000:8000 \
  -v "$PWD/qdrant_db:/app/qdrant_db" \
  -v "$PWD/parent_store:/app/parent_store" \
  -v "$HOME/.cache/huggingface:/app/.cache/huggingface" \
  -v "$PWD/.fastembed_cache:/app/.cache/fastembed" \
  -e HF_HUB_OFFLINE=1 \
  [-e DEMO_API_TOKEN=<token>] [-e DEEPSEEK_API_KEY=sk-...] \
  agent-kb-demo

• 入口脚本发现无索引快照时先入库再启动（需联网下载嵌入模型，建议挂载既有索引/缓存卷）；镜像约 7 GB（含 torch/CUDA 运行库）

• DEMO_API_TOKEN 设置后 HTTP 与 MCP 统一要求 Authorization: Bearer <token>（无/错凭据 401）；不设置则本地免鉴权

MCP Integration

MCP 端点（Streamable HTTP）：http://127.0.0.1:8000/mcp，与 HTTP 共用 Bearer 鉴权。

{
  "mcpServers": {
    "agent-kb": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer ${DEMO_API_TOKEN}" }
    }
  }
}

实测（Pi 0.85.1 + pi-mcp-adapter 2.32.1 ↔ 服务端 MCP SDK 2.1.1）：工具发现 → Bearer 鉴权 → search 命中 → get_context 回查 → Pi 用自己的模型基于证据作答并引用 source，五步全绿；ask_knowledge decision=answered。工具的文本通道与 structuredContent 同载荷，只渲染文本的 MCP 客户端也能拿到完整结构化结果。冒烟脚本：python src/smoke_mcp.py --url http://127.0.0.1:8000/mcp [--token <token>]。

Evaluation

以下评测在内置示例语料（中文 RAG 教程集 + 受治理版本 fixture）上测得；更换语料需重建索引并重跑全部评测。

当前基准：2026-09-10 单次 decision 协议基线（rag/agentic 同 index/模型/参数同场运行；本表由脚本从同场 summary 生成）。完整报告：agentic、rag、对照报告（含 badcase 审计）。检索指标统计进入检索流程的 20 题，5 条歧义题由 clarification 指标单独评估。

两种模式的已知差异（同场对照，不预设结论）：rag 单图无改写/拆解，单次检索的 top-k 证据直接约束回答——明确可答题误拒 0.1（2/20，证据片段不足以支撑完整回答），歧义题不会澄清且 2/5 被硬拒（计入 refusal FP，故拒答 precision 0.556）；agentic 拆解/多轮工具后拒答精度 1.000，歧义题澄清 1/5。代价：agentic 延迟与成本显著更高（P50 13.99s vs 1.84s，约 7.6×；成本约 9×），检索指标两者持平（Recall@5 均 1.000），context precision 双图更低（0.624 vs 0.815）——多路证据摊薄了上下文精度，但 context recall 更高（0.917 vs 0.722）。

检索挑战集（40 题直接检索）：回归锚点 Recall@5=1.000 与冻结基线持平；全量 Recall@5=0.950、MRR=0.933、2 题 hard-negative 泄漏（其一为"当前有效"问题命中过期版本）。Recall 1.000 只代表这套固定语料与 golden set，不是对开放问题的泛化承诺。

规模与并发：100 文档 / 12,098 块合成快照，3 并发 126/126 有效查询，0 错误 0 busy；P50/P95 与峰值资源见规模实测报告。

运行评测：

cd eval
env -u ALL_PROXY -u all_proxy ../.venv/bin/python run_eval.py --mode agentic   # 或 --mode rag
env -u ALL_PROXY -u all_proxy ../.venv/bin/python run_challenge.py            # 检索挑战集（不调生成模型）

Architecture

L4  Gradio UI
        |
        v
    AgentClient (HTTP / SSE)
        |
L3  FastAPI  /health /info /search /evidence /invoke /stream · /mcp
        |
L2  AppService  search/read_evidence + AnswerService  rag/agentic 单次问答
        |
L1  LangGraph  rag 单图 · agentic 主图 + 检索子图
        |
L0  Qdrant hybrid retrieval + parent store + corpus

依赖方向保持单向：UI 只依赖 client；API 层只通过 L2 公共接口使用检索与问答，不 import db/ / rag_agent/ 内部；检索与 Agent 内部可以继续演进而不改变 HTTP 协议。

关键设计决策：

• 单次 decision 协议：三种 decision 皆为终态，单次请求语义贯穿 HTTP / SSE / MCP，服务无会话状态

• 引用机械校验（rag_agent/validation.py）：evidence_id 必属本次实际取得的证据集合，quote 必须是证据原文精确子串，span 由 quote 位置推导并绑定快照；失败在预算内修复一次，仍失败返回 result_validation_failed，不伪造引用、不冒充正常拒答

• 类型化 RetrievalHit 契约（db/retrieval.py）：命中作为对象流经 AgentState → events → eval，全程无字符串解析；Retriever Protocol 由 QdrantRetriever（prod）与 InMemoryRetriever（test）两个适配器坐实

• manifest 语料治理：每篇文档登记 source_url / sha256 / license / topic / 版本，同步采用镜像语义清理清单外残留

src/
  api/             FastAPI 路由、SSE 序列化、MCP 工具与鉴权
  client/          HTTP/SSE 客户端
  core/            AppService composition、检索/问答服务、预算与 usage
  db/              Qdrant、parent store、快照与证据存储
  rag_agent/       rag 单图、agentic 双图、节点、引用校验
  schema/          HTTP/MCP 共用 DTO 与 SSE event schemas
  ui/              Gradio 薄客户端
data/              受治理示例语料、manifest 与版本 fixture
eval/              golden set、挑战集、metrics、runner 和 reports
tests/             API/schema/graph/validation 测试
docs/              架构：分层依赖规则与领域词汇（ARCHITECTURE.md）

分层规则与领域词汇详见 ARCHITECTURE。

测试：python -m pytest tests/（CI 实测 93 passed / 4 skipped；stub 隔离真实 LLM 与 Qdrant，覆盖 schemas、decision 协议、引用校验、跨请求状态隔离、检索路径与 chunker span、fixture 静态契约；4 项真实索引集成测试仅在本地已入库时运行，fresh clone 自动跳过）。CI 在 push/PR 时执行 compile 检查 + 全量 pytest。

API

问答结果统一为单次 decision 协议：

request_id · index_id · mode
decision = answered | clarification_required | refused
answer · clarification_question? · limitations[]
citations[] = citation_id + evidence_id + source + chunk_id + span + quote
usage = input/output tokens + estimated cost + model calls

/stream 使用结构化 SSE 事件（status · tool_call · tool_result · done · error）；done 携带校验后的完整结果——答案不实时流式输出未校验文本，异常恰好一个 error。

Sample Corpus

仓库内置一份受治理的示例语料，用于演示与评测：从 mothieras/all-in-rag 固定修订版选取的 14 篇中文 RAG 教程（七类 topic），加上项目自有的两对虚构政策文档 fixture（各含一个已过期与一个当前有效版本，入库进同一 collection，用于验证版本元数据全链路传播并为版本冲突评测提供素材）。服务本身语料无关——入库与证据链路由 data/manifest.json 驱动，可整体替换为其他语料并重跑评测。治理规则与目录说明见 data/README.md。

Background & Attribution

本项目脱胎于开源 LangGraph 教学项目 agentic-rag-for-dummies，不把"重写框架"当目标，而是模拟更常见的工程任务：接手一个可运行的开源底座，把它改造成能够测量、能够通过 API 集成的知识库服务。如今两者已是两套系统：底座是 40 文件的教学 demo，本仓库是 157 文件的服务——132 个文件为本项目新增，约 20 个沿上游模块演进的文件集中在 LangGraph 双图骨架与检索基础设施（逐项对照见下表）。

• 原作者：Giovanni Pasqualino

• 上游许可：MIT；原始版权声明保留在 LICENSE

• 示例语料：来自 mothieras/all-in-rag 固定修订版，遵循 CC BY-NC-SA 4.0，不适用本仓库代码的 MIT License；详见 data/THIRD_PARTY_NOTICES.md

Non-goals

内置 Web/Chrome 工具、自动记忆学习、跨请求聊天历史或 HITL 恢复、管理后台、OCR 均不在本服务范围；它不是聊天机器人产品，而是 Agent 的知识层。

License

代码沿用上游的 MIT License，原作者版权声明保持不变。data/raw/docs/ 与 data/interview_docs/docs/ 中的第三方语料遵循 CC BY-NC-SA 4.0，不适用 MIT License；使用或分发时须分别遵守对应条款。