# zbs_agent **Repository Path**: sz5343/zbs_agent ## Basic Information - **Project Name**: zbs_agent - **Description**: 本地知识库demo：本地文档->清洗分块-> 向量化 ->向量库存储->用户提问->向量化->语义检索->上下文拼接->Prompt 注入 LLM->生成答案 - **Primary Language**: Unknown - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-08-05 - **Last Updated**: 2025-11-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 知识库管理系统 (zbs_agent) 一个功能完善的知识库管理系统，支持文档上传、自动处理、片段管理和智能问答，基于大语言模型和向量数据库构建，帮助用户高效管理和利用文档知识。 ## 项目概述 `zbs_agent` 是一个集文档管理、文本处理和智能问答于一体的知识库系统，主要功能包括： - 多格式文档上传与自动处理（解析、切片、向量存储） - 文档全生命周期管理（查看、删除、片段预览） - 基于知识库的智能问答（结合大语言模型生成精准回答） - 灵活的系统配置（支持不同嵌入模型、向量数据库和LLM） 技术栈： - 前端：Streamlit（快速构建交互式Web应用） - 后端：FastAPI（高性能API服务） - 文档处理：LangChain（文档加载、文本分割） - 向量存储：ChromaDB/FAISS/Milvus（支持多种向量数据库） - 嵌入模型：**BGE-small-zh-v1.5**（中文优化嵌入模型）、HuggingFace/OpenAI（文本向量化） - 大语言模型：支持DeepSeek/OpenAI/Ollama等（问答生成） ## 功能特点 ### 1. 文档上传与处理 - 支持多种格式：PDF、TXT、DOCX、MD等（可通过配置扩展） - 自动去重：基于文件内容哈希避免重复上传 - 智能处理：自动解析文档、切割为语义片段、通过**BGE-small-zh-v1.5模型**生成向量并存储 ### 2. 文档管理 - 文档列表：展示所有上传的文档信息（名称、时间、切片数量等） - 片段查看：可查看文档切割后的具体片段内容 - 文档删除：支持彻底删除（同时清理文件、向量和元数据） ### 3. 智能问答 - 基于知识库内容回答问题，答案严格参考文档片段 - 可配置检索参数（如相关文档数量） - 展示回答依据的参考片段，确保可解释性 ### 4. 系统配置 - 路径配置：文档存储、向量库、元数据库的路径管理 - 处理参数：文本切片长度、重叠率等 - 服务配置：API地址、支持文件格式等 ## 环境要求 - Python 3.8+ - 操作系统：Windows - 推荐配置：8GB以上内存（处理大文档和向量计算需要） ## 安装步骤 ### 1. 克隆项目（若使用版本控制） ```bash git clone <项目仓库地址> cd zbs_agent ``` ### 2. 创建并激活虚拟环境 #### Windows ```powershell # 创建虚拟环境 python -m venv .venv1 # 激活虚拟环境 .venv1\Scripts\activate ``` #### macOS/Linux ```bash # 创建虚拟环境 python3 -m venv .venv1 # 激活虚拟环境 source .venv1/bin/activate ``` ### 3. 安装依赖 ```bash pip install -r requirements.txt ``` > 若缺少`requirements.txt`，可手动安装核心依赖： > ```bash > pip install streamlit fastapi uvicorn requests langchain chromadb transformers pydantic python-dotenv > ``` ### 4. 配置环境 1. 复制`.env.example`为`.env`（若存在），或直接修改`.env`文件： ```env # 模型类型（使用API：deepseek_api；本地模型：deepseek） LLM_MODEL_TYPE=deepseek_api # DeepSeek API配置（关键：填写你的密钥） DEEPSEEK_API_KEY=sk-5036***************************df7 # 你的API密钥 DEEPSEEK_API_BASE_URL=https://api.deepseek.com DEEPSEEK_TEMPERATURE=0.7 DEEPSEEK_MAX_NEW_TOKENS=1024 # 嵌入模型配置（核心：BGE-small-zh-v1.5） EMBEDDING_MODEL_NAME=BAAI/bge-small-zh-v1.5 # 中文优化嵌入模型 EMBEDDING_DEVICE=auto # 自动选择设备（CPU/GPU） # 向量数据库配置 VECTOR_DB_TYPE=chroma # chroma/faiss/milvus VECTOR_DB_PATH=./vector_stores/chroma COLLECTION_NAME=zbs_agent_kb # 文档处理配置 CHUNK_SIZE=500 CHUNK_OVERLAP=50 SUPPORTED_EXTENSIONS=.pdf,.txt,.docx,.md # 日志配置 LOG_LEVEL=INFO LOGS_PATH=./logs # 禁用SSL验证（已配置，无需修改） DEEPSEEK_SSL_VERIFY=False ``` 2. 配置文件位于`config/`目录下，可根据需求修改： - `app_config.py`：核心应用配置 - `embedding_config.py`：嵌入模型参数（包含BGE-small-zh-v1.5的加载配置） - `llm_config.py`：大语言模型参数 - `vector_db_config.py`：向量数据库配置 ## 核心模型说明：BGE-small-zh-v1.5 下载地址：https://www.modelscope.cn/models/BAAI/bge-small-zh-v1.5 下载后放在.\zbs_agent\models\embeddings\bge-small-zh-v1.5 本项目默认使用**BAAI/bge-small-zh-v1.5**作为文本嵌入模型，专为中文场景优化，具有以下特点： ### 模型优势 - **中文性能优异**：在中文语义理解、文本匹配等任务上表现突出，远超通用多语言模型的中文效果。 - **轻量级部署**：参数规模小（约100M），无需高性能GPU即可本地运行，适合资源有限的环境。 - **高效向量生成**：将文本转换为384维向量，平衡语义表达能力和计算效率，支持快速检索。 - **长文本支持**：原生支持长文本输入（最长512 tokens），适配知识库中常见的长文档片段。 - **开源免费**：可完全本地部署，无需API调用，保护数据隐私。 ### 在项目中的作用 - 将文档片段转换为向量，存储到向量数据库中，为后续的“相似性检索”提供基础。 - 问答时，将用户问题转换为向量，与知识库中的文档向量比对，快速找到最相关的片段。 - 相比通用嵌入模型（如all-MiniLM-L6-v2），对中文术语、语法的理解更精准，检索结果更符合中文语境。 ## 使用指南 ### 1. 启动后端服务 ```bash # 通过main.py启动FastAPI服务 python main.py # 或使用uvicorn直接启动（推荐） uvicorn src.api.fastapi_app:app --host 0.0.0.0 --port 11111 --reload ``` 后端服务默认运行在 `http://localhost:11111` ### 2. 启动前端界面 ```bash # 在新终端激活虚拟环境后运行 streamlit run src/frontend/app.py ``` 前端界面默认运行在 `http://localhost:8501`，会自动在浏览器打开 ```bash # 在新终端激活虚拟环境后运行,仅启动用于问答的界面，启动后会输出一个Network URL，这个可以在局域网中分享给其他人使用，包括移动端 streamlit run src/frontend/qa_only.py ``` ### 3. 功能使用 #### 文档上传 1. 在左侧导航选择「文档上传」 2. 点击「浏览文件」选择一个或多个支持格式的文档 3. 点击「开始处理」，系统会自动解析、切片，并通过**BGE-small-zh-v1.5**生成向量后存储 4. 处理完成后可查看成功/失败列表，或直接跳转到「文档列表」 #### 文档管理 1. 在左侧导航选择「文档列表」 2. 查看所有文档的基本信息（文件名、上传时间等） 3. 操作按钮： - 「查看」：展示文档的切割片段，支持分页浏览 - 「删除」：删除文档（需确认，操作不可恢复） 4. 点击「刷新」按钮可更新文档列表 #### 知识库问答 1. 在左侧导航选择「知识库问答」 2. 在输入框中填写问题（例如："如何使用文档上传功能？"） 3. （可选）展开「高级参数设置」调整检索文档数量 4. 点击「获取答案」，系统会通过**BGE-small-zh-v1.5**将问题转为向量，检索相关片段后生成回答，并展示参考依据 #### 系统配置 1. 在左侧导航选择「系统配置」 2. 查看当前系统的核心配置参数，包括： - 路径配置：文档、向量库、元数据库的存储位置 - 处理参数：文本切片长度、重叠率等 - 服务配置：API地址、支持的文件格式 ## 项目结构 ``` zbs_agent/ ├── config/ # 配置文件目录 │ ├── app_config.py # 核心应用配置 │ ├── embedding_config.py # 嵌入模型参数（含BGE-small-zh-v1.5配置） │ └── ... ├── data/ # 数据存储目录 │ ├── raw_docs/ # 原始文档存储 │ ├── vector_db/ # 向量数据库（存储BGE生成的向量） │ └── metadata/ # 元数据存储 ├── src/ │ ├── api/ # 后端API │ │ ├── endpoints/ # 接口端点（文档管理、问答等） │ │ └── schemas/ # 数据模型定义 │ ├── document_processing/ # 文档处理 │ │ ├── document_loader.py # 文档加载器 │ │ └── text_splitter.py # 文本切割器 │ ├── embedding/ # 嵌入模型（含BGE-small-zh-v1.5加载逻辑） │ ├── frontend/ # 前端Streamlit应用 │ │ └── app.py # 前端入口 │ ├── llm/ # 大语言模型接口 │ ├── management/ # 文档管理服务 │ │ └── services/ # 文档服务、元数据服务 │ ├── qa_chain/ # 问答链实现 │ ├── utils/ # 工具函数 │ └── vector_db/ # 向量数据库接口 ├── models/ │ └── vector_db/ │ └── embeddings/ │ └── bge-small-zh-v1.5/ # 嵌入模型下载后放在这里面 ├── .env # 环境变量配置 ├── main.py # 后端启动入口 └── requirements.txt # 项目依赖 ``` ## 常见问题 ### 1. 文档上传失败？ - 检查文件格式是否在支持列表（可在「系统配置」查看） - 文件大小是否超过限制（默认10MB，可在`DocumentService`中修改`max_text_length`） - 查看终端日志，确认是否有解析错误（如损坏的PDF） ### 2. 点击「查看/删除」按钮无反应？ - 确保后端服务正常运行（`http://localhost:11111`可访问） - 检查浏览器控制台是否有错误（F12打开开发者工具） - 尝试刷新页面或重启前端应用 ### 3. 问答功能无结果？ - 确认已上传并成功处理文档（BGE模型已生成向量） - 检查后端日志，确认LLM和向量数据库连接正常 - 问题是否与知识库内容相关（尝试更具体的问题） ### 4. 删除文档后仍在列表显示？ - 点击「刷新」按钮更新列表 - 检查元数据是否正确删除（可查看`metadata_db`的实现） ## 扩展建议 - 增加用户认证：添加登录功能，支持多用户管理 - 扩展文档格式：在`document_loader.py`中添加更多格式的加载器 - 优化切片策略：根据文档类型（如代码、表格）调整切割逻辑 - 增加批量操作：支持批量删除、批量导入文档 --- 如有其他问题或建议，欢迎联系项目维护者。