Nano KB

A minimalist personal knowledge base, built on Karpathy's LLM-as-Wiki philosophy.

Nano KB 是一个基于 Andrej Karpathy 提出的 LLM Wiki 理论构建的个人知识库工具。核心理念是:用 LLM 作为知识的索引、连接与推理引擎,而知识本身以纯文本形式沉淀,人类可读、可编辑、可版本管理。

它不采用传统 RAG 的"即时检索"范式,而是走 "知识预编译" 路线——把原始文档当作源码,通过一条流水线将其编译成结构化的知识图谱(节点为概念/实体,边为关系),再基于图谱实现可推理、可溯源的智能问答。

flowchart LR
    A["原始文档 raw/"] --> B["增量检测与加载"]
    B --> C["双轨知识抽取"]
    C --> D["图谱编译与融合"]
    D --> E["社区发现与索引"]
    E --> F["知识图谱 + 向量库"]
    F --> G["问答推理引擎"]
    G --> H["用户交互 & 主动学习"]

• Nano KB
  • 目录
  • 特性
  • 安装
  • 快速开始
  • Usage
    • 命令总览
    • nanokb build — 编译知识库
    • nanokb query — 图谱推理问答
    • nanokb ask — 向量语义问答
    • nanokb search — 社区宏观检索
    • nanokb shell — 交互式 REPL
    • nanokb serve — 守护进程
    • nanokb status — 查看编译状态
    • nanokb review — 主动学习待审队列
  • 典型工作流
  • 配置参考
    • LLM
    • Embedding
    • 目录与分块
    • 检索与问答
    • 图谱
  • 目录与产物
  • 置信度与溯源
  • 开发
  • License

• 知识预编译:把文档一次性编译为知识图谱,问答时不再扫描全文,速度快且答案可溯源。
• 双轨抽取:代码文件走 tree-sitter 确定性解析(零 Token、零幻觉);文本/PDF/DOCX 走 LLM 语义抽取概念、实体与关系。
• 增量编译:基于 SHA256 哈希的变更检测,仅处理新增/修改/删除的文件;支持 --watch 实时增量。
• 三路召回问答:图谱检索(精确多跳)+ 向量检索(模糊语义)+ 社区检索(宏观主题域)三路融合。
• 社区发现:Leiden 算法自动归纳知识主题域,提供宏观背景综述。
• 主动学习:无法回答或存在冲突的问题自动进入待审队列,引导人工补充数据。
• 多后端 LLM:支持 OpenAI 兼容端点(含智谱 GLM)、Anthropic、本地 Ollama。
• 会话热加载:nanokb shell 交互式 REPL 与 nanokb serve 守护进程复用同一 RetrievalSession,连续查询只加载一次图谱/向量库;普通 nanokb query 也可透明转发到守护进程享热加载,未存活则自动回退直连。
• Agentic 两阶段阅读(可选):开启后 LLM 用 Glob/Grep/ReadFile 工具对召回重排后的文档粗读 5-10 篇、精读 3-5 篇,组装信息密集的上下文,产出更丰满、可溯源的答案;默认关闭、失败降级到基础召回路径。

Nano KB 需要 Python ≥ 3.10。推荐使用 uv 管理依赖(仓库已包含 uv.lock)。

# 克隆仓库
git clone <repo-url> nanokb && cd nanokb

# 方式一:uv(推荐,自动读取 uv.lock 锁定版本)
uv sync

# 方式二:pip(可编辑安装)
python -m venv .venv && source .venv/bin/activate
pip install -e .

# 验证安装
nanokb --help        # 或 python -m nanokb --help

# 1. 从模板生成配置,填入 LLM API Key
cp .env.example .env
#   编辑 .env,至少设置 NANOKB_LLM_PROVIDER / NANOKB_LLM_MODEL
#   以及对应 provider 的 API Key(缺失会以 exit code 2 退出)

# 2. 把文档放进 raw/(支持 .md .txt .pdf .docx .py .js .java)
cp ~/notes/*.md raw/

# 3. 编译知识库(首次会全量抽取,调用 LLM)
nanokb build

# 4. 提问
nanokb query "Transformer 依赖哪些核心技术?"

nanokb build    编译知识库(增量检测 → 双轨抽取 → 图谱融合 → 索引)
nanokb query    图谱推理问答(graph + vector + community 三路召回融合;可选 Agentic 两阶段阅读)
nanokb ask      向量语义问答(仅向量召回,适合模糊语义匹配)
nanokb search   社区宏观检索(按关键词返回所属社区摘要)
nanokb shell    交互式 REPL(会话内连续 query/ask/search,复用 RetrievalSession 热加载)
nanokb serve    守护进程(长驻监听,供 query/ask/search 透明转发;--daemon 后台 / --stop 停止)
nanokb status   显示知识库编译状态(raw/ 文档数 + out/ 是否已编译)
nanokb review   列出 / 清空主动学习待审队列(out/review_queue.md)

所有命令均支持 --help 查看详细参数。运行 nanokb(不带子命令)会打印帮助。

冷启动:在执行 query / ask / search 前,必须先 nanokb build 产出图谱与社区索引。若 out/graph.json 不存在,这些命令会报 ColdStartError 并以 exit code 1 退出,提示先 build。

执行完整的五阶段流水线:增量检测 → 双轨抽取 → 图谱编译融合 → 社区发现 → 索引写入。基于 out/manifest.json 中的 SHA256 哈希做增量,默认仅处理变更文件。

nanokb build [OPTIONS]

选项:

示例:

nanokb build                  # 增量编译
nanokb build --force          # 全量重编译(清空增量缓存语义)
nanokb build --watch          # 实时监听 raw/ 并增量编译
nanokb build --replay         # 离线重放重建图谱(不耗 Token)

编译完成后会打印一行摘要,例如:

编译完成:added=12, modified=0, deleted=0, extracted=87, fallback=2

其中 fallback 表示因抽取置信度过低、由 LLM 兜底综合出描述的概念数量。

最强问答模式,三路召回融合:以 LLM 识别的实体为中心做图谱多跳子图扩展(精确结构化三元组)+ 向量语义检索(模糊)+ 社区检索(宏观主题背景),融合重排后编译上下文交给 LLM 生成答案。

nanokb query <QUESTION>

示例:

nanokb query "Transformer 依赖哪些核心技术?"
nanokb query "Leiden 算法和 Louvain 有什么区别?"

答案末尾会附带引用来源(对应 raw/ 中的源文件)。若回答用到了 INFERRED/AMBIGUOUS 关系,会额外提示"此结论为 AI 推理,建议核实源文件"。

Agentic 两阶段阅读(可选):设置 NANOKB_ENABLE_AGENTIC_READING=true 后,query/ask 在召回融合后会多走一层 agent 阅读——LLM 用 Glob/Grep/ReadFile 工具粗读 5-10 篇、精读 3-5 篇原始文档,组装更密集的上下文,答案更丰满。默认关闭、任何失败自动降级回基础路径(见配置参考)。

仅向量召回的单路问答:把问题向量化,检索语义最相似的节点描述/文本块。适合不需要多跳关系推理、只需模糊语义匹配的场景(如"找讲注意力机制的那段内容")。

nanokb ask <QUESTION>

示例:

nanokb ask "哪里讲了 self-attention 的计算流程?"

社区路宏观检索:按关键词定位实体所属的 Leiden 社区,返回该主题域的背景摘要。适合"我要这整块主题的概览"这类宏观需求。

nanokb search <KEYWORD> [--community]

选项:

示例:

nanokb search "深度学习"

找到 2 个相关社区:
- 深度学习基础模型与训练方法 (来源:notes/dl.md)
- 自然语言处理与注意力机制 (来源:notes/nlp.md)

单进程内构造一个 RetrievalSession 后循环复用,连续查询只加载一次图谱/向量库/社区索引(热加载)。适合密集提问、反复试探的场景。

nanokb shell

进入后支持子指令::query <问题> / :ask <问题> / :search <关键词> / 裸问题(默认走 :query) / :stats(查看加载计数) / :exit;Ctrl-D / Ctrl-C 干净退出。

nanokb> Transformer 依赖哪些核心技术?      # 裸问题默认走 query
nanokb> :ask 哪里讲了 self-attention?       # 切到 ask
nanokb> :stats                              # 查看会话加载计数
nanokb> :exit

build 协调:shell/serve 期间若另一进程在 nanokb build,会自动等待或失效重载(依赖 enable_build_progress 心跳)。关闭该项会打印 WARNING——并发 build 可能触发 chroma 锁错误。

长驻监听的后台服务,持有线程安全的 RetrievalSession,供 query/ask/search 透明转发复用(单次命令也享热加载)。客户端经 KB 身份指纹比对后才转发,不匹配/未存活自动回退直连(向后兼容)。

nanokb serve [--daemon] [--stop]

选项:

示例:

nanokb serve               # 前台运行,Ctrl-C / SIGTERM 优雅退出
nanokb serve --daemon      # 后台拉起
nanokb serve --stop        # 停止守护进程
nanokb query "..."         # 自动检测守护进程:存活且身份匹配则转发,否则回退直连

守护进程监听 kb_server_host:kb_server_port(默认 127.0.0.1:18731,仅本机不暴露网络),PID 文件写入 out/.nanokb-server.pid。多项目防串答:客户端比对 KB 身份指纹(out_dir + manifest mtime + 检索 settings),不一致则不转发。

显示 raw/ 下受支持文档的数量,以及 out/ 是否已编译(graph.json 是否存在)。

nanokb status
# raw/ 下 42 个文档 | out/ 已编译

查看或清空主动学习待审队列 out/review_queue.md。当一次问答命中以下任一条件时,会被自动追加到队列,引导人工补充数据或修正:

• 命中数过少(< NANOKB_MIN_HIT_COUNT,默认 3)
• 最高置信度过低(< NANOKB_MIN_CONFIDENCE_SCORE,默认 0.3)
• 命中 AMBIGUOUS(信息冲突)关系

nanokb review [--clear]

示例:

nanokb review              # 列出所有待审条目
nanokb review --clear      # 清空待审队列

输出示例:

待审条目(2 条):
1. 量子计算的主要挑战是什么?
   原因:low_hit_count | 实体:量子计算 | 时间:2026-06-23T...

# 首次初始化
cp .env.example .env        # 配置 LLM
nanokb status               # 确认 raw/ 有文档

# 日常:增量编译 + 提问
nanokb build
nanokb query "..."
nanokb ask   "..."

# 密集提问:进 shell 复用会话(只加载一次图谱)
nanokb shell

# 长期复用:起守护进程,普通 query 自动透明转发
nanokb serve --daemon
nanokb query "..."        # 自动转发到守护进程;未存活则回退直连
nanokb serve --stop

# 更丰满的答案:开启 Agentic 两阶段阅读
NANOKB_ENABLE_AGENTIC_READING=true nanokb query "..."

# 长期监听:编辑 raw/ 自动重建
nanokb build --watch

# 离线/调参:不耗 Token 重建图谱
nanokb build --replay

# 复核低质量问答,反哺知识库
nanokb review               # 检查待审队列 → 补充 raw/ 文档 → rebuild

所有配置通过环境变量(前缀 NANOKB_)或项目根的 .env 文件覆盖,由 pydantic-settings 自动加载。完整模板见 .env.example。

智谱 GLM 示例:用 GLM 做生成时,embedding 需同步换成智谱模型(如 embedding-3),不能继续用 OpenAI 的 text-embedding-3-small。

extract 阶段支持可配置的文档级 + chunk 级并发（ThreadPoolExecutor），加速大文档库的冷启动与增量重编译。LLM 调用是网络 IO 等待，不受 GIL 限制，线程并发对语义轨抽取显著有效。

并发度与限流的关系：实际对 LLM API 的并发请求数 ≈ extract_doc_concurrency × extract_chunk_concurrency。三者由进程级共享的 RateLimiter（基于 llm_request_interval）统一节流——即使并发度乘积远大于 provider 的 RPM 限额，RateLimiter 也会自动串行化请求，保证不突破限流。无需手动计算"并发度 ≤ 60/RPM"，但建议保持合理乘积避免线程空等。

确定性保证：并发抽取采用"先并发收集、再按 chunk_index 升序回放合并"，输出与串行模式逐字节一致（last-write-wins / concat_dedup 顺序确定）。两并发度均为 1 时行为与改造前完全一致（零回归）。

提示：纯代码库（全 .py / .js / .java）走 CodeTrack（tree-sitter CPU 密集、零 Token），线程并发受 GIL 限制无加速——不建议开启 extract_doc_concurrency，否则只会创建多个线程抢 GIL 反增开销。

生文与向量解耦：NANOKB_EMBEDDING_* 三件套允许生文和 embedding 用不同厂商。 不配置时 embedding 复用生文的 OpenAI 兼容端点（向后兼容）。

例 1：生文 DeepSeek + embedding 智谱 GLM embedding-3

NANOKB_LLM_PROVIDER=openai
NANOKB_LLM_MODEL=deepseek-chat
NANOKB_OPENAI_API_KEY=sk-deepseek...
NANOKB_OPENAI_BASE_URL=https://api.deepseek.com
NANOKB_EMBEDDING_PROVIDER=openai
NANOKB_EMBEDDING_MODEL=embedding-3
NANOKB_EMBEDDING_API_KEY=<智谱 key>
NANOKB_EMBEDDING_BASE_URL=https://open.bigmodel.cn/api/paas/v4

例 2：生文 DeepSeek + embedding 本地 Ollama

NANOKB_LLM_PROVIDER=openai
NANOKB_OPENAI_API_KEY=sk-deepseek...
NANOKB_OPENAI_BASE_URL=https://api.deepseek.com
NANOKB_EMBEDDING_PROVIDER=ollama
NANOKB_EMBEDDING_MODEL=nomic-embed-text
NANOKB_OLLAMA_BASE_URL=http://localhost:11434

shell / serve 共用同一 RetrievalSession,连续查询只加载一次图谱;客户端透明转发默认 opt-in 关闭(kb_server_autostart=false),未存活/身份不匹配自动回退直连(零回归)。

依赖 NANOKB_ENABLE_BUILD_PROGRESS=true(默认开):守护进程据此做 build 协调与 chroma 跨进程并发防护;关闭则协调静默失效。

可选的两阶段阅读 agent(粗读 + 精读),让 query/ask 的答案更丰满。默认关闭(enable_agentic_reading=false),开启后仍保证失败降级到基础召回路径。

三预算关系:工具读取预算(粗读 4000 + 精读 8000)> 最终 context 上限(4000),即 agent 可读取更广范围再压缩提炼。agent 任意阶段失败都不阻断问答——预期降级(预算耗尽/解析失败)记 WARNING,意外异常记 ERROR,均回退 compile_context 并在 AnswerQueryResult 标记 degraded。

raw/                         原始文档(知识源,建议提交到版本控制)
  *.md *.txt *.pdf *.docx      → unstructured 文本抽取
  *.py *.js *.java             → tree-sitter 确定性抽取
out/                         编译产物(默认 gitignore,可由 --replay 重建)
  graph.json                 知识图谱(NetworkX MultiDiGraph 序列化)
  graph.graphml              GraphML 格式(当 GRAPH_SERIALIZATION=graphml)
  triples.jsonl              三元组追加日志(--replay 的数据源)
  communities.json           Leiden 社区发现结果 + 主题摘要
  keywords.json              关键词索引
  manifest.json              增量检测清单(文件 → SHA256,近似事务提交点)
  review_queue.md            主动学习待审队列
  chroma/                    ChromaDB 向量库

每条抽取出的关系都携带 confidence 标签,直接影响问答的可信度提示:

答案末尾的引用来源对应 raw/ 中的源文件,可一键溯源核对。

uv sync                     # 安装依赖(含 dev 组)

# 质量检查
ruff check .                # lint
mypy src                    # 类型检查(strict 模式)

# 测试(默认跳过真实 LLM 调用)
pytest                      # 等价于 pytest -m "not llm"
pytest -m llm               # 仅跑真实 LLM 集成测试

技术方案详见 docs/design/knowledge-graph-extraction-qa-system.md。

MIT