llmwiki-suite

🌐 English · 中文

把一堆 Markdown 笔记，编译成「会生长、能问答」的个人知识库。

源自 Karpathy 的 LLM-wiki 思路：不做每次查询临时切片的 RAG，而是用工具链 持续编译笔记——补 frontmatter、建 BM25 + wikilink 图索引、巡检断链， 最后通过 CLI 或微信 / 企微 / 飞书 / Telegram 通道问答。

目标是让个人知识库只进不退：每一条笔记都被规范化、可检索、可追问， 而不是躺在文件夹里堆灰。

快速体验（30 秒）

# 一条命令装好全部能力（核心 + 服务/通道运行时）
pip install "llmwiki-suite[serve]"

# 五步接入你已有的笔记库
cd ~/my-notes           # 你的 Markdown 笔记目录
llmwiki init            # 生成 llmwiki.toml + 脚手架
llmwiki ingest          # 补 frontmatter + 规范化 wikilink
llmwiki index           # 建 BM25 + wikilink 图索引
llmwiki query "..."     # 检索 / 问答 / 输出完整回答

包名 vs 命令名：PyPI 发布名为 llmwiki-suite（llmwiki 包名已被占用）， 安装后命令仍是 llmwiki —— 装 llmwiki-suite，用 llmwiki。

安装

已在 PyPI 发布。推荐直接装 serve 版（核心 + 跑 llmwiki serve 所需的 fastapi/uvicorn，也是所有通道——微信/企微/飞书/Telegram 共用的运行时）； 只看检索/巡检则装核心版（零第三方依赖）。

# 推荐：一条命令装好【全部能力】（核心 + 通道时代 fastapi/uvicorn）
pip install "llmwiki-suite[serve]"

# 轻量：只装核心（ingest / index / query / lint / eval，零第三方依赖）
# pip install llmwiki-suite

要求 Python >= 3.11。

本地开发安装（源码）

推荐在项目级虚拟环境中安装（与 CI 同构、依赖隔离）：

git clone https://github.com/voidvec/llmwiki-suite.git
cd llmwiki-suite
python -m venv .venv
# Windows: .venv\Scripts\activate     macOS/Linux: source .venv/bin/activate
pip install -e ".[wechat,dev]"       # 全部通道 + 测试/pre-commit 依赖
pre-commit install                   # 注册仓库级钩子（可选但推荐）

五步接入你已有的笔记库

cd ~/my-notes          # 1. 进入你的笔记目录
llmwiki init           # 2. 生成 llmwiki.toml 配置模板
llmwiki ingest         # 3. 补 frontmatter + 规范化 wikilink
llmwiki index          # 4. 建检索索引
llmwiki query "..."    # 5. 检索 / 问答

可选：llmwiki lint（巡检断链/词表）、llmwiki eval（召回质量评估：recall@k / MRR）、 llmwiki serve（启动 HTTP 问答服务，需 serve extras）。

命令一览

所有命令支持 --repo <path> 显式指定库路径（默认取当前目录）。

渠道接入（微信 / 企业微信 / 飞书 / Telegram）

用 llmwiki serve 把知识库接到 IM，直接发消息问答：

# ① 已装渠道版则直接可用；否则先补装渠道依赖
pip install "llmwiki-suite[serve]"

# ② 配置 LLM（OpenAI 兼容端点；只设 KEY 时默认走 OpenAI）
export LLM_WIKI_API_KEY="sk-xxx"
export LLM_WIKI_BASE_URL="https://api.openai.com/v1"        # 不设则默认 OpenAI
export LLM_WIKI_MODEL="gpt-4o-mini"                          # 不设则默认 gpt-4o-mini

export LLM_WIKI_BRIDGE_TOKEN="my-secret"       # 可选：保护问答接口（本地验证通道可忽略）
llmwiki serve --host 127.0.0.1 --port 8000

• 个人微信（推荐，免费官方 iLink 通道）：浏览器打开 http://127.0.0.1:8000/ilink/webui → 手机微信扫码 → 绑定后在微信里直接给 bot 发消息即查即答。
• 企业微信：配置 LLM_WIKI_WECOM_* 环境变量后自动启用回调 / 主动推送通道。
• 飞书：配置 LLM_WIKI_FEISHU_APP_ID / LLM_WIKI_FEISHU_APP_SECRET（可选 LLM_WIKI_FEISHU_VERIFY_TOKEN 签名校验），回调地址设为 https://<你的域名>/feishu/callback 即可。
• Telegram：用 @BotFather 建 bot 得 token，配置 LLM_WIKI_TELEGRAM_BOT_TOKEN， webhook 指向 https://<你的域名>/telegram/callback。 （webhook 需公网可达地址：可用 frp / ngrok / 腾讯云轻量等反代到 8000。）

路由总是注册：serve 启动时四个通道的路由无条件挂载，缺凭据时返回可读的 hint （不会 404）。可通过 http://127.0.0.1:8000/healthz 查看各通道 configured / enabled 状态。

换 LLM 厂商 / 模型（OpenAI 兼容协议即可）

套件只调 OpenAI 兼容的 /chat/completions，不看厂商名——任何提供该协议的服务都能用：

任意 OpenAI /chat/completions 兼容服务（DeepSeek / 通义 / Kimi / 本地 Ollama / vLLM 等）都行。 完整对接、会话持久化与排错见 [[llmwiki-tutorial-02-channel]]。

配置与密钥

• 库配置：库根 llmwiki.toml（categories 词表、排除目录、模型名等非密钥项）
• 密钥：只走环境变量（LLM_WIKI_API_KEY、LLM_WIKI_BRIDGE_TOKEN（可选）、 LLM_WIKI_WECOM_*、LLM_WIKI_ILINK_*、LLM_WIKI_FEISHU_*、LLM_WIKI_TELEGRAM_*）， 本套件不读任何 .env 文件

文档

全部文档在 docs/，按「入口 → 进阶 → 参考」组织：

建议顺序：getting-started → tutorial-01 → 02/03（按需）→ architecture。

参与贡献

• 想提 bug / 功能？开 Issue
• 想参与开发？见 CONTRIBUTING.md（本地开发环境、测试、提交规范）
• 安全相关？见 SECURITY.md（漏洞报告、密钥与 env 规范）
• 有想法想聊？来 Discussions
• 一键支持：点亮 ⭐ Star，让更多人被搜索到

License

MIT

作者与公众号

作者：voidvec

公众号持续输出：

• LLM / RAG / 知识库的第一手踩坑记录
• 这套工具链的演进连载（从 L0 被动问答到 L3 自进化）
• 开源项目从 0 到 1 的全过程复盘

搜索「[公众号名待填]」关注（二维码待替换，可 Q 我）