llmwiki-suite

🌐 English · 中文

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

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

包名 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（评估低质量子集并输出诊断）、 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 即可（challenge 自动应答）。
• Telegram：用 @BotFather 建 bot 得 token，配置 LLM_WIKI_TELEGRAM_BOT_TOKEN， 把 webhook 设到 https://<你的域名>/telegram/callback （setWebhook；可用 LLM_WIKI_TELEGRAM_SECRET_TOKEN 做回调鉴权）。

路由总是注册：serve 启动时四条通道的路由（/ilink/*、/wecom/*、 /feishu/callback、/telegram/callback）无条件挂载，缺凭据时返回可读的 hint（不会 404）。可通过 http://127.0.0.1:8000/healthz 查看各通道 configured / enabled 状态。通道回调用不到 LLM_WIKI_BRIDGE_TOKEN。 Telegram webhook 需要公网可达地址（可用 frp / ngrok / 腾讯云轻量等反代到 8000）。

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

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

换厂商只需把上面三个变量一起设；只有 OpenAI 时只用 LLM_WIKI_API_KEY 即可。 支持任意 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。

License

MIT