# local_kb **Repository Path**: llhelei/local_kb ## Basic Information - **Project Name**: local_kb - **Description**: 基于Ollama模型实现RAG-LLM本地知识库搭建 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-13 - **Last Updated**: 2026-03-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 本地知识库系统 - Backend 基于 FastAPI + RAG (Ollama + FAISS + BGE Embedding + LangChain) 的本地离线知识库系统，支持 PDF、Markdown、TXT 等文档加载和智能问答。 ## 系统架构 ``` 本地知识库系统 ├── 后端 (FastAPI + Python) │ ├── RAG 系统：Ollama (LLM) + BGE (Embedding) + LangChain │ ├── 向量数据库：FAISS │ ├── 文档处理：支持 PDF、Markdown、TXT、DOCX │ └── API 接口：RESTful API └── 前端 (Vue 3) ├── 问答对话界面 ├── 文档管理界面 └── 系统统计界面 ``` ## 核心技术栈 ### 后端 - **Web 框架**: FastAPI - **LLM**: Ollama (本地大语言模型) - **Embedding**: BGE (Beijing Academy of Artificial Intelligence) - **向量数据库**: FAISS - **编排框架**: LangChain - **文档处理**: LangChain Document Loaders ### 前端 - **框架**: Vue 3 - **UI 组件库**: Element Plus - **状态管理**: Pinia - **路由**: Vue Router - **HTTP 客户端**: Axios ## 功能特性 ### 后端功能 - ✅ 支持多种文档格式加载（PDF、Markdown、TXT、DOCX） - ✅ 文档智能分块（Chunk） - ✅ BGE 中文向量嵌入 - ✅ FAISS 高效向量检索 - ✅ LangChain RAG 流程编排 - ✅ RESTful API 接口 - ✅ 流式查询响应（SSE） - ✅ 文档上传/删除 - ✅ 智能问答 - ✅ 来源文档引用 ### 前端功能 - ✅ 问答对话界面 - ✅ 流式回答展示 - ✅ 实时检索结果显示 - ✅ 文档上传管理 - ✅ 文档列表查看 - ✅ 系统状态监控 - ✅ 统计信息展示 - ✅ Markdown 渲染 ## 📁 项目结构 ``` backend/ ├── app/ # 应用核心代码 │ ├── __init__.py │ ├── main.py # FastAPI 应用主文件 │ ├── dependencies.py # 依赖注入模块 │ ├── core/ # 核心配置和模型 │ │ ├── __init__.py │ │ ├── config.py # 系统配置 │ │ └── models.py # Pydantic 数据模型 │ ├── api/ # API 路由 │ │ ├── __init__.py │ │ ├── health.py # 健康检查路由 │ │ ├── documents.py # 文档管理路由 │ │ ├── query.py # 问答路由 │ │ └── stats.py # 统计路由 │ ├── services/ # 业务逻辑服务 │ │ ├── __init__.py │ │ ├── rag_system.py # RAG 系统 │ │ ├── vector_store.py # 向量数据库 │ │ └── embeddings.py # 嵌入模型 │ ├── loaders/ # 文档加载器 │ │ ├── __init__.py │ │ ├── document_loader.py # 通用文档加载器 │ │ └── mdx_parser.py # MDx 词典解析器 │ └── utils/ # 工具模块 │ ├── __init__.py │ └── async_helpers.py # 异步辅助函数 ├── data/ # 数据目录 │ ├── uploads/ # 上传的文档 │ ├── faiss_db/ # 向量数据库 │ └── models/ # 下载的模型 ├── main.py # 旧的入口文件（已废弃） └── run.py # 新的启动脚本 ├── frontend/ # 前端代码 │ ├── src/ │ │ ├── api/ # API 接口 │ │ ├── stores/ # Pinia 状态管理 │ │ ├── views/ # 页面组件 │ │ ├── router/ # 路由配置 │ │ ├── App.vue # 根组件 │ │ └── main.js # 入口文件 │ ├── package.json # Node 依赖 │ ├── vite.config.js # Vite 配置 │ └── index.html # HTML 模板 └── README.md # 项目说明 ``` ## 🚀 快速开始 ### 1.安装后端依赖 ```bash cd backend pip install -r requirements.txt ``` ### 启动服务 ```bash python run.py ``` 或使用 uvicorn 直接运行： ```bash uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload #### Node.js 环境 ```bash # 安装前端依赖 cd frontend npm install ``` ### 2. 安装 Ollama #### Windows ```bash # 下载并安装 Ollama # 访问: https://ollama.com/download # 下载 Windows 版本并安装 ``` #### Linux/Mac ```bash # 安装 Ollama curl -fsSL https://ollama.com/install.sh | sh ``` #### 拉取模型 ```bash # 拉取 LLM 模型（推荐 qwen2.5） ollama pull qwen2.5:7b # 或者使用其他模型 ollama pull llama3.2:3b ollama pull mistral:7b # 验证安装 ollama list ``` ### 3. 配置系统 #### 后端配置 编辑 `backend/config.py`，根据需要调整配置： ```python # Ollama 配置 OLLAMA_BASE_URL = "http://localhost:11434" OLLAMA_MODEL = "qwen2.5:7b" # BGE Embedding 配置 BGE_MODEL_NAME = "BAAI/bge-small-zh-v1.5" BGE_DEVICE = "cpu" # 或 "cuda" # 文档处理配置 CHUNK_SIZE = 512 CHUNK_OVERLAP = 128 # 检索配置 RETRIEVAL_TOP_K = 4 SIMILARITY_THRESHOLD = 0.6 ``` ### 4. 启动服务 #### 启动后端服务 ```bash cd backend python run.py ``` 服务将在 `http://127.0.0.1:8000` 启动 #### 启动前端服务 ```bash cd frontend npm run dev ``` 前端将在 `http://localhost:5173` 启动 ### 5. 访问系统 打开浏览器访问：`http://localhost:5173` API 文档：`http://127.0.0.1:8000/docs` ## 使用说明 ### 上传文档 1. 进入"文档管理"页面 2. 点击"上传文档"按钮 3. 选择要上传的文档（支持 PDF、MD、TXT、DOCX） 4. 等待文档处理完成 ### 问答对话 1. 进入"问答"页面 2. 在输入框中输入问题 3. 点击发送按钮（或按 Ctrl+Enter） 4. 系统将基于知识库生成答案并显示参考来源 ### 高级设置 在问答页面点击设置按钮，可以调整： - 返回文档数量（1-10） - 生成温度（0.0-1.0） - 是否使用 RAG ### 访问 API 文档 启动后访问以下地址查看 API 文档： - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc ### 📚 API 端点 ### 系统端点 - `GET /health` - 健康检查 - `GET /stats` - 获取系统统计信息 ### 文档管理端点 - `POST /documents/upload` - 上传文档 - `GET /documents` - 获取文档列表 - `DELETE /documents` - 删除文档 ### 问答端点 - `POST /query` - 执行问答查询 - `GET /query/stream` - 流式问答查询 ## 🔧 配置 配置文件位于 `app/core/config.py`，主要配置项包括： - Ollama 配置（模型、温度、上下文长度等） - BGE Embedding 配置（模型名称、设备等） - API 配置（主机、端口、CORS 等） - 文档处理配置（支持的文件类型、最大文件大小、分块参数等） ## 📝 支持的文档格式 - PDF (`.pdf`) - Markdown (`.md`) - 纯文本 (`.txt`) - Word 文档 (`.docx`) - MDx 词典 (`.mdx`, `.mdd`) ## 🛠️ 开发指南 ### 添加新的 API 路由 1. 在 `app/api/` 目录下创建新的路由文件 2. 定义 FastAPI Router 并添加路由 3. 在 `app/main.py` 中注册新路由 ### 添加新的服务 1. 在 `app/services/` 目录下创建新的服务文件 2. 实现业务逻辑 3. 通过依赖注入使用服务 ### 添加新的文档加载器 1. 在 `app/loaders/` 目录下创建新的加载器 2. 实现加载器逻辑 3. 在 `document_loader.py` 中注册 ## 📊 性能优化 - 使用线程池执行耗时操作，避免阻塞事件循环 - 异步保存向量数据库 - 后台任务处理文档上传 - 使用锁防止并发保存 ## 🔄 从旧版本迁移 如果你从旧版本迁移： 1. 旧的 `main.py` 文件已被拆分到多个模块 2. 使用新的启动脚本 `run.py` 替代 `python main.py` 3. 所有配置和数据路径保持不变，无需额外配置 ## 常见问题 ### 1. Ollama 无法连接 - 确保 Ollama 已正确安装并运行 - 检查 Ollama 服务状态：`ollama ps` - 确认配置中的 OLLAMA_BASE_URL 正确 ### 2. BGE 模型加载失败 - 首次加载需要下载模型，请确保网络连接正常 - 检查模型缓存目录权限 - 可以使用镜像源加速下载 ### 3. 文档上传失败 - 检查文件大小限制（默认 50MB） - 确认文件格式是否支持 - 查看后端日志获取详细错误信息 ### 4. 删除文档时其他请求阻塞 - 此问题已完全修复，使用线程池实现真正的并发 - 所有耗时操作（上传/删除/查询/统计）都在后台线程执行 - 使用锁机制防止并发保存，保证数据一致性 - 其他请求（健康检查、问答）不受影响 ### 5. 查询速度慢 - 减少返回的文档数量（top_k） - 降低 chunk_size - 使用 GPU 加速（修改 BGE_DEVICE 为 "cuda"） - 启用流式响应，提升用户体验 ### 6. 流式响应不工作 - 确认浏览器支持 EventSource（现代浏览器都支持） - 检查网络连接，确保可以访问后端 - 查看浏览器控制台错误信息 ## 性能优化建议 1. **使用 GPU**: 如果有 NVIDIA GPU，安装 CUDA 并设置 `BGE_DEVICE = "cuda"` 2. **调整分块**: 根据文档特点调整 `CHUNK_SIZE` 和 `CHUNK_OVERLAP` 3. **模型选择**: - BGE-small: 速度快，适合资源受限环境 - BGE-base: 平衡性能和速度 - BGE-large: 效果最好，但需要更多资源 4. **缓存策略**: 向量数据库已持久化，重启后无需重新索引 5. **并发优化**: 所有耗时操作都在线程池中执行，支持真正的并发 6. **线程池配置**: 根据服务器资源调整 `max_workers`（默认 4） ## 扩展功能 ### 支持更多文档格式 在 `document_loader.py` 中添加新的加载器： python from langchain_community.document_loaders import YourLoader # 在 load_document 方法中添加 elif file_path.suffix.lower() == '.ext': loader = YourLoader(str(file_path)) ### 自定义提示模板 在 `rag_system.py` 中修改 `_create_prompt_template` 方法。 ### 添加更多 API 路由 在 `main.py` 中添加新的路由处理函数。 ## 技术参考 - [Ollama 官方文档](https://ollama.com/docs) - [BAAI/bge-embedding](https://github.com/FlagOpen/FlagEmbedding) - [LangChain 文档](https://python.langchain.com/) - [FAISS 文档](https://faiss.ai/) - [FastAPI 文档](https://fastapi.tiangolo.com/) - [Vue 3 文档](https://vuejs.org/) ## 示例 ![输入图片说明](ded068e9bec3aaa831736995bcbc1c74.png) ## 联系方式 如有问题，请联系项目维护者。