# NLKB **Repository Path**: dongfq/nlkb ## Basic Information - **Project Name**: NLKB - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-09 - **Last Updated**: 2026-06-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # NLKB - 本地知识库助手 基于本地文档的 RAG 问答系统，支持向量 + BM25 混合检索、Cross-Encoder 重排序、多 Agent 策略、Web UI 和 RAGFlow 前置处理流水线。所有运行数据本地存储，隐私优先。 ## 特性 - **混合检索**：ChromaDB 向量检索 + Whoosh BM25 关键词检索 + Cross-Encoder 重排序 - **多格式文档解析**：PDF、Word（doc/docx）、Excel（xls/xlsx）、PPT、Markdown、代码文件、HTML、CSV、JSON - **本地 LLM 后端**：Ollama 优先，可选 vLLM，自动路由，支持流式对话 - **本地 Embedding**：默认启用 sentence-transformers，离线运行，可配置 cuda/cpu - **云端 Fallback**：本地模型不可用或指定云端时切换 DeepSeek / Kimi - **多 Agent 策略**：RAG / ReACT / GraphRAG 三种推理模式 - **多轮会话记忆**：自动加载最近历史上下文 - **引用溯源**：答案附带来源文档引用 - **Web UI**：React + FastAPI，文档按二级目录分组展示 - **MCP Server**：支持 stdio / SSE，暴露 Tools / Resources / Prompts - **文件监视**：自动检测文档变更并重新索引 - **文档前置处理**：为 RAGFlow 提供四阶段流水线（扫描→标准化→优化→批量上传） - **安全与稳定**：CORS 限制、API Key 认证、速率限制、内存自检、临时文件过滤、断点续传 ## 环境要求 - Python >= 3.10 - Node.js >= 18（开发 Web UI 需要） - Ollama（Windows 上运行 LLM + Embedding） - Docker Desktop + WSL 集成（运行 RAGFlow） ## 安装 ```bash # 克隆项目 git clone cd NLKB # 安装 Python 依赖（含 Web、重排序和预处理依赖） pip install -e ".[web,dev,preprocessing]" # 安装前端依赖（可选） cd frontend && npm install && cd .. ``` ## 快速开始 ### 1. 配置 Ollama 按 [RAGFlow_ops.md](/home/d0ngfq/ragflow/docs/RAGFlow_ops.md) 在 Windows 上部署 Ollama，并设置： ```text OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=24h OLLAMA_MAX_LOADED_MODELS=2 OLLAMA_NUM_PARALLEL=4 ``` 拉取模型： ```powershell ollama pull qwen3.5:9b ollama pull bge-m3:latest ``` ### 2. 启动 NLKB 重排序服务 ```bash cd /home/d0ngfq/nlkb/scripts ./start_vllm_reranker.sh ``` ### 3. 诊断环境 ```bash nlkb diagnose ``` ### 4. 摄取 NLKB 自身文档（可选） ```bash nlkb ingest ./docs nlkb ingest ./README.md # 先扫描预估（不实际嵌入） nlkb ingest ./docs --dry-run # 强制重新处理未变更文件 nlkb ingest ./docs --force ``` ### 5. 对话 ```bash nlkb chat ``` ### 6. 启动 Web UI ```bash nlkb web # 访问 http://localhost:8000 # 允许局域网访问 nlkb web --host 0.0.0.0 --port 8080 ``` ## CLI 命令速查 ``` nlkb chat 开始对话 nlkb ingest 摄取文档/目录 nlkb ingest --dry-run 扫描预估（不嵌入） nlkb ingest --force 强制重新处理 nlkb remove 从索引中移除 nlkb search 纯检索 nlkb status 系统状态 nlkb config 显示配置 nlkb config --edit 交互式配置 nlkb diagnose 环境诊断 nlkb web 启动 Web 服务 nlkb mcp-server 启动 MCP Server # 文档前置处理（RAGFlow 导入） nlkb preformat scan Phase 0: 盘点扫描 nlkb preformat normalize Phase 1: 格式标准化 nlkb preformat optimize Phase 2: 内容质量优化 nlkb preformat run --phases 0,1,2 执行 0-2 阶段 nlkb preformat upload Phase 3: 上传到 RAGFlow ``` ### 对话内命令 ``` /search 知识库检索 /sources 查看引用来源 /sessions 会话列表 /clear 清空当前会话 /history 对话历史 /help 帮助 /exit 退出 ``` ## 配置 配置文件位置：`.nlkb/config.yaml`（项目根目录）。程序首次启动会自动生成带注释的默认配置；**若文件已存在则不会覆盖**，避免自定义配置丢失。 ### 关键配置项 | 配置段 | 说明 | |--------|------| | `data_dir` | 运行时数据目录 | | `watch_paths` | 文件监控路径列表 | | `local_llm` | `auto` / `ollama` / `vllm` | | `ollama` | Ollama 地址、对话模型、嵌入模型 | | `local_embed` | 本地 sentence-transformers 嵌入 | | `reranker` | Cross-Encoder 重排序模型 | | `cloud` / `deepseek` / `kimi` | 云端 fallback 配置 | | `ingestion` | 文档切分、嵌入、批量处理 | | `retrieval` | 向量/BM25/重排序参数 | | `agent` | RAG / ReACT / GRAG 参数 | | `chunking` | 按文件类型分块策略 | | `preprocessing` | 文档前置处理（RAGFlow） | | `show_citations` / `stream` | 输出选项 | 完整默认配置见 `.nlkb/config.yaml`。 ## 数据目录 所有数据存储在项目根目录下的 `.nlkb/`： ``` .nlkb/ ├── config.yaml 用户配置 ├── nlkb.db SQLite 数据库（会话、消息、文件注册表） ├── chroma/ ChromaDB 向量存储 ├── whoosh/ Whoosh BM25 索引 ├── embed_cache.jsonl Embedding 本地缓存 ├── logs/ 日志文件 └── cache/ 缓存目录 ``` 整个目录可复制迁移。 ## 文档前置处理（RAGFlow 导入） NLKB 提供独立的文档前置处理流水线，将原始文档处理后输出到 `/home/d0ngfq/docs/pre-format/`，再批量导入 RAGFlow。 ### Phase 0 — 盘点扫描 识别问题文件、排除垃圾文件、生成缺陷清单： ```bash nlkb preformat scan ``` 输出： - `pre-format/phase0_inventory.json` - `pre-format/phase0_report.md` ### Phase 1 — 格式标准化 - `.doc → .docx`、`.xls → .xlsx`、`.ppt → .pptx`（需安装 LibreOffice） - 解压 `.zip/.rar/.7z/.tar.gz` 等压缩包 - 文件名规范化（去除特殊字符、统一分隔符） ```bash nlkb preformat normalize ``` 输出： - `pre-format/phase1_inventory.json` - 标准化后的文件保持原目录结构 ### Phase 2 — 内容质量优化 - **PDF 拆分**：超过页数/大小阈值的 PDF 拆分为 `xxx_part_001.pdf` - **Excel → Markdown**：`.xlsx/.xls/.csv` 转为 Markdown 表格，提升检索效果 - **PDF OCR**：扫描版 PDF 提取为 Markdown（可选，需安装 PaddleOCR） - **目录结构 → 元数据**：每个文件生成 `.metadata.json`，包含分类标签和 RAGFlow 分块方法 ```bash nlkb preformat optimize ``` 输出： - `pre-format/phase2_inventory.json` - 处理后的文件 + `.metadata.json` ### Phase 3 — 批量上传 RAGFlow ```bash export RAGFLOW_API_KEY= export RAGFLOW_BASE_URL=http:// python scripts/ragflow_uploader.py \ --inventory /home/d0ngfq/docs/pre-format/phase2_inventory.json \ --state-file /home/d0ngfq/docs/pre-format/upload_state.json \ --batch-size 16 ``` 特性： - 按顶层目录自动创建/复用 RAGFlow 知识库 - 根据文件类型自动选择 `parser_id`：`naive`、`table`、`laws`、`paper`、`book`、`presentation`、`picture` - 批量上传，支持断点续传 - 上传后自动解析并轮询状态 ## RAGFlow 集成架构 推荐架构（详见 `/home/d0ngfq/ragflow/docs/RAGFlow_ops.md`）： ```text Windows GPU: qwen3.5:9b @ Ollama :11434 ~5.6GB bge-m3:latest @ Ollama :11434 ~0.7GB WSL2 GPU/CPU: bge-reranker-v2-m3 @ NLKB Reranker Server :8002 ~2.2GB GPU RAGFlow (WSL2 Docker): → Ollama (LLM + Embedding) via http://host.docker.internal:11434/v1 → NLKB Reranker Server via http://:8002 ``` ## 重排序模型下载 默认使用 `BAAI/bge-reranker-v2-m3`（约 2.2GB），首次启动 `start_vllm_reranker.sh` 时会自动加载本地缓存。 ### 国内用户 ```bash # 方式一：环境变量 export HF_ENDPOINT=https://hf-mirror.com nlkb diagnose # 方式二：手动下载 huggingface-cli download BAAI/bge-reranker-v2-m3 --local-dir /home/d0ngfq/models/reranker ``` ## Web UI 开发 ```bash cd frontend npm run dev # 开发模式，代理到 localhost:8000 npm run build # 生产构建 ``` FastAPI 会自动托管 `frontend/dist` 中的静态文件。 ## 运行测试 ```bash # 全部测试 pytest tests/ -v # 单个模块 pytest tests/test_preprocessing/ -v pytest tests/test_retrieval/ -v ``` ## 项目结构 ``` NLKB/ ├── frontend/ React + Vite Web UI ├── src/nlkb/ │ ├── cli/ 命令行入口 │ │ ├── main.py typer 主应用 │ │ ├── chat.py 对话循环 │ │ ├── web.py Web 服务启动 │ │ └── preformat.py 文档前置处理 CLI │ ├── core/ 核心引擎 │ │ ├── config.py 配置管理 │ │ ├── constants.py 常量 │ │ ├── engine.py 主引擎 │ │ └── watcher.py 文件监视器 │ ├── config/ 配置模型 │ ├── ingestion/ 文档摄取与解析 │ ├── preprocessing/ 文档前置处理（RAGFlow） │ ├── chunking/ 分块策略 │ ├── retrieval/ 检索层 │ ├── llm/ LLM 网关 │ ├── agent/ Agent 策略 │ ├── storage/ SQLite 数据存储 │ ├── web/api/ FastAPI Web 服务 │ └── mcp/ MCP Server ├── scripts/ 启动脚本与工具 │ ├── reranker_server.py OpenAI 兼容重排序服务 │ ├── start_vllm_reranker.sh │ └── ragflow_uploader.py RAGFlow 批量上传 ├── tests/ 测试 ├── docs/ 文档 ├── pyproject.toml └── README.md ``` ## 技术栈 | 组件 | 选型 | |-------------|---------------------------------------| | CLI 框架 | Typer | | 配置 | Pydantic Settings + YAML | | 向量数据库 | ChromaDB | | 文本索引 | Whoosh + jieba | | Embedding | sentence-transformers / Ollama bge-m3 | | LLM | Ollama qwen3.5 / vLLM / 云端 API | | 重排序 | sentence-transformers BGE v2-m3 | | Agent 策略 | RAG / ReACT / GRAG | | 数据库 | SQLAlchemy + SQLite (WAL) | | Web 后端 | FastAPI + WebSocket | | Web 前端 | React 19 + Vite + TypeScript | | MCP Server | JSON-RPC over stdio/SSE | | 测试 | pytest + pytest-asyncio | ## 许可证 MIT