Agent Knowledge Base

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

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

后续产品方向与建设顺序见 PRODUCT 总纲 与 ROADMAP 路线图：先优化现有文档入库，再建设单用户、多 Agent 共享的 Memory / Knowledge 服务。条目服务（写入、协作修订、无模型全文检索、生命周期与有效期）与文档派生条目（来源引用、版本化回查、长条目分块）已交付并接入 HTTP/MCP；两个真实 Agent 客户端（Pi 与 Claude Code）的接入验证与价值对照实验已完成（报告见 agents-2026-09-21），阶段 2 全部交付。

该方向与 Codex、Claude Code 等调用方的原生记忆配合使用，重点补足不同 Agent 之间的内容共享、外部资料与积累条目的关联，以及共享内容的持续修订与证据回查。调用方通过公开工具接入，无需服务接管其内部记忆文件；这些目标流程的实际收益仍待验证。

Why

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

三种用法：

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

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

• 多 Agent 共享 Memory / Knowledge：不同 Agent 共同保存、取用和修订事实与知识，并回查资料依据；单用户共享读写，保留作者与修订历史，第一版不做私有分区，见 PRODUCT 总纲

Related MCP server: MCP Elasticsearch Demo

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 的工具即知识库

• 共享条目服务（Memory/Knowledge）：Agent 跨会话/跨客户端写入、修订、搜索与回查持久条目；全文搜索（SQLite FTS5 + jieba 预分词 + bm25，无模型）按全局/单项目/多项目/全部项目范围过滤；原子版本检查（409 附当前条目）、幂等写入、软生命周期（archive/delete/restore）、查询时到期判定、全量修订历史；长条目按分块检索（超阈值自动分块、命中返回匹配片段与 span、条目身份不变）。接入指南见 docs/ENTRY_TOOL_GUIDE.md

• 文档派生条目与来源回查：条目 source.document 引用文档注册表的版本化规范化文本（doc_id/version/精确 span），写入时机械校验引用存在；文档更新注册新版本、旧版本与旧引用永久可解析；resolve_document / list_document_versions / read_document 经 HTTP/MCP 回查原文窗口（content_hash 可复算）

• 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          # 仅跑服务；含评测/UI 的完整环境装 requirements-eval.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 "$PWD/entries.db:/app/entries.db" \
  -v "$PWD/docs.db:/app/docs.db" \
  -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

• 入口脚本发现无索引快照时先入库再启动（需联网下载嵌入模型，建议挂载既有索引/缓存卷）；镜像约 1.7 GB（CPU-only torch，不含 CUDA）；entries.db/docs.db 挂载卷保证条目与文档注册表跨容器重建保留

• 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.86.0 + pi-mcp-adapter 2.34.0 ↔ 服务端 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>]（含条目工具 save→revise→冲突通道→lifecycle→历史全链路）。

两客户端真实 Agent 验证（Pi 0.86.0 + Claude Code 2.1.268）：Pi 记录（自主 + 用户显式，global/单项目/多项目 × 双类型）→ Claude Code 跨客户端检索复用、故意制造 409 后按冲突体重试修订、历史回查 → 两客户端同修订竞争单胜一败 → 服务重启数据保留，五场景全过；价值对照（原生记忆 vs 原生记忆+服务）如实报告，未预设收益。见 agents-2026-09-21。

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 与峰值资源见规模实测报告。

条目服务：检索挑战集三门槛全过（recall@5=mrr@10=1.0，契约 sha256 冻结）见挑战集报告；容量/并发/重启实测（1 万 active 条目 / 10 万修订、3 并发写 0 busy、搜索 P95 7.7ms 对 500ms 门槛、SIGTERM 重启数据保留、禁生成模型核心流程全链）见容量实测报告。分块检索改动后挑战集三门槛回归通过（eval/reports/entries-challenge-2026-09-21.md）。

真实 Agent 验证（T6/T7）：Pi 与 Claude Code 两客户端五场景全过、文档派生条目端到端（提取 → 来源引用 → 回查 → 文档更新后旧引用仍指原修订）、价值对照两臂如实报告，见 agents-2026-09-21。

运行评测：

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 · /entries · /mcp
        |
L2  AppService  search/read_evidence/entries + AnswerService  rag/agentic 单次问答
        |
L1  LangGraph  rag 单图 · agentic 主图 + 检索子图
        |
L0  Qdrant hybrid retrieval + parent store + corpus · SQLite 条目库（FTS5 + jieba）

依赖方向保持单向：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）两个适配器坐实

• 条目服务（db/entry_store.py + core/entry_service.py）：SQLite WAL 单事务并发纪律（expected_revision 409 附当前条目）、FTS5 + jieba 预分词无模型全文搜索、软生命周期与查询时到期判定；长条目分块检索（阈值 4000 字符，chunks + FTS，matched 加性字段）

• 文档注册表（db/doc_store.py + core/doc_service.py）：离线 ingest 注册版本化规范化文本（内容 hash 变化才 +1，旧版本永久保留）；source.document 写入时机械校验引用存在与 span 合法；来源回查窗口 content_hash 可复算

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

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

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

测试：python -m pytest tests/（本地实测 249 passed / 0 skipped，含 4 项真实索引集成测试；stub 隔离真实 LLM 与 Qdrant，覆盖 schemas、decision 协议、引用校验、跨请求状态隔离、检索路径与 chunker span、fixture 静态契约、ingest 样例集 Level A 管道验证与入库终态分类、条目存储/契约/搜索/生命周期/到期与并发、文档注册表/source.document 校验/来源回查/长条目分块；无本地索引时 4 项集成测试自动跳过）。CI 在 push/PR 时执行 compile 检查 + 全量 pytest。

API

条目写操作复用并发槽纪律（busy 不排队 → 429）；错误统一 {code, message}： invalid_request 400 · invalid_project 400 · invalid_source 400 · not_found 404 · revision_conflict 409（附 current）· idempotency_conflict 409 · entry_deleted 409 · invalid_transition 409 · busy 429。条目库为独立 SQLite 文件（ENTRIES_DB_PATH，默认 entries.db，WAL）；文档注册表为独立 SQLite（DOCS_DB_PATH，默认 docs.db），离线 ingest 注册版本化规范化文本。

问答结果统一为单次 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。

Ingest 样例集与失败终态

data/ingest_samples/：10 项样例（S1–S10，独立 manifest 登记 SHA-256 与用途，不进主语料 manifest）覆盖三种支持格式与空文本、无文本层 PDF、重复提交、同名冲突、不支持格式、非 UTF-8 编码等边界情形。两级验证：Level A（无模型，进 CI）断言结构锚点保留、child==parent span 切片、内容散列可复算与分块边界质量；Level B（eval/ingest_samples/run_level_b.py，本地手动跑，scratch 索引与质量索引隔离）逐样例对账目标终态表。

入库结果结构化：DocumentManager.add_documents 逐文档返回显式终态（ok / duplicate / conflict / unsupported_format / unsupported_encoding / empty_text / no_text_layer / parse_error），ingest_corpus.py 汇总输出分类计数与失败明细——失败不冒充成功、不支持格式不静默剔除。要点：同名目标按内容比对区分重复与冲突（静默去重会掩盖登记错误）；无文本层 PDF 剥除页界标记后判空（不再假成功入库），转换全程无 OCR 调用（注意是依赖门控：装入 OCR 依赖后图像页会自动启用，升级依赖须重验）；PDF 条目 metadata 显式标注 origin_page: "missing"（原文件页码映射需在 chunker 合并/拆分中维护绝对偏移，属后续重写范围）；分块边界在 S1/S3/S4 上检查无缺陷（代码块/表格/标题在 parent 层完整、产物零丢失；句中切口仅见于超尺寸无结构文本，为 splitter 降级加重平衡的设计内行为）；快照 index_id 摘要剔除随机 point UUID，同输入同产物可复现。

Background & Attribution

本项目脱胎于开源 LangGraph 教学项目 agentic-rag-for-dummies，不把"重写框架"当目标，而是模拟更常见的工程任务：接手一个可运行的开源底座，把它改造成能够测量、能够通过 API 集成的知识库服务。如今两者已是两套系统：底座是 40 文件的教学 demo，本仓库共 241 个受版本控制文件（代码/评测/文档 188 个，受治理语料 53 个；逐项对照见下表）。

• 原作者：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；使用或分发时须分别遵守对应条款。