RAG-LLM-知识库系统搭建

AI 知识库平台 · AI Knowledge Base Platform简体中文 English一句话独立设计并实现的生产级 AI 知识库平台打通RAG真实语义嵌入 两阶段重排序、ReAct 智能体、多模型 LLM、上下文记忆、知识图谱五大能力支持在Web 端接入 / 切换大模型密钥并脱密保护前后端分离 分层架构Docker 一键部署。本项目覆盖现代 AI 产品「文档摄取 → 向量检索 → 提示工程 → 智能体编排 → 多轮记忆 → 知识图谱 → 前端交互」的完整链路是一个可运行、可测试、可扩展的工程作品集。为保证可演示性嵌入内置离线确定性 Mock零密钥即可跑通整条 RAG 链路生产可一键切换为真实语义嵌入bge-m3。 English IntroductionAproduction-grade AI Knowledge Base Platform, independently designed and built, integrating five core capabilities:RAG (real semantic embeddings two-stage reranking), a ReAct agent, multi-provider LLMs, contextual memory, and a knowledge graph. LLM / embedding / rerankerAPI keys can be configured and hot-switched from the Web UI with secret masking— keys never leave the page. Decoupled frontend/backend with a layered architecture, one-command Docker deployment.It covers the full modern-AI pipeline —document ingestion → vector retrieval → prompt engineering → agent orchestration → multi-turn memory → knowledge graph → web interaction— as a runnable, testable and extensible engineering showcase. A built-inoffline deterministic mock embedderlets the entire RAG chain run withzero keys(ideal for demos, CI and the 49 offline unit tests); switch toreal semantic embeddings (bge-m3)for production.️ 系统架构 · Architecture前后端分离 后端四层依赖方向自上而下核心能力层不感知上层。Decoupled frontend/backend with a four-layer backend; dependencies point downward and the core layer is framework-agnostic.☁️ 外部服务 External · OpenAI 兼容️ 基础设施 Infrastructure⚙️ 后端 Backend · FastAPI · Python 3.11 网关 Gateway️ 前端 Frontend · React 18 Vite TypeScript核心能力层 app/coreHTTP / SSE凭据单一事实来源Chat / Documents / Graph / Agent / Memory / Prompt / Settings 面板Nginx 静态托管 /api 反代生产Vite Proxy开发main.py · CORS / 全局异常 / lifespan / 路由注册API 路由层 app/apidocuments · chat · agent · memory · models · graph · settings服务编排层 app/servicesContainer 组合根 · Document / Chat / Agent / Graph ServiceLLM 抽象 工厂RAG 两阶段检索ReAct AgentMemory 记忆知识图谱RuntimeConfigStore运行时配置 脱密numpy 向量库SQLite文件系统 / 上传DeepSeek / 小米 MiMoEmbedding bge-m3Reranker bge-reranker-v2-m3更详细的分层职责与模块深剖见docs/system-overview.md。✨ 核心功能模块能力RAG 检索增强多格式文档PDF/Word/TXT/Markdown上传 → 解析 → 递归分块 → 向量化入库两阶段语义检索向量召回 重排精排相关性阈值过滤无据不编造多模型 LLM统一抽象层封装 DeepSeek / 小米 MiMo均兼容 OpenAI 协议工厂模式 实例缓存运行时一键切换模板化提示工程SSE 流式输出ReAct 智能体复杂任务自动拆解规划→ 工具调用计算器/时间/知识库检索→ 结果汇总 → 自我反思迭代全过程可视化上下文记忆多轮会话上下文维护长期记忆持久化主题 重要度 TTL跨会话历史检索过期自动清理知识图谱LLM 抽取「实体-关系-实体」三元组 → 并发限流 → 聚合去重加权 → cytoscape 可视化系统设置Web 端配置 / 切换 LLM、嵌入、重排序密钥脱敏展示热重载免重启前端界面深色主题、响应式布局SSE 流式打字机效果检索来源展示Agent 执行轨迹时间线实时健康状态️ 技术栈后端Python 3.11 · FastAPI · Pydantic v2 · pydantic-settings · asyncio · openai SDK · httpx · 本地 numpy 向量库 · SQLite模型 / 服务DeepSeek · 小米 MiMoOpenAI 兼容可运行时切换嵌入 bge-m3重排序 bge-reranker-v2-m3前端React 18 · Vite 5 · TypeScriptstrict· 原生 SSE 流式解析 · cytoscape部署Docker · Docker Compose · Nginx静态托管 API 反向代理测试pytest · pytest-asyncio49 例全离线架构、API、部署的详细文档见docs/目录架构设计API 文档部署指南 快速开始方式一Docker推荐一键启动前置安装 Docker 与 Docker Compose。# 在项目根目录执行dockercompose up-d--build启动后访问前端界面http://localhost后端 API 文档Swaggerhttp://localhost:8000/docs健康检查http://localhost:8000/api/health嵌入与向量检索开箱即用离线对话/Agent 需在backend/.env中填入 DeepSeek 或 MiMo 密钥见下方「配置模型密钥」。方式二本地开发需要本机安装Python 3.11与Node.js 18。1) 启动后端cdbackend python-mvenv .venv# Windows PowerShell.venv\Scripts\Activate.ps1# macOS / Linux# source .venv/bin/activatepipinstall-rrequirements.txt copy .env.example .env# WindowsmacOS/Linux 用 cpuvicorn app.main:app--reload--port80002) 启动前端另开一个终端cdfrontendnpminstallnpmrun dev前端开发服务器默认运行在 http://localhost:5173并通过 Vite 代理将/api转发到后端http://localhost:8000。 配置模型密钥编辑backend/.env从.env.example复制而来填入 DeepSeek 或小米 MiMo 的密钥# 默认提供商deepseek / mimo DEFAULT_LLM_PROVIDERdeepseek # DeepSeekOpenAI 兼容 DEEPSEEK_API_KEYsk-xxxxxxxx # 或小米 MiMo MIMO_API_KEYxxxxxxxx重启后端即可。前端顶部的「模型选择器」会自动识别已配置密钥的提供商并允许运行时切换。 运行测试cdbackend pipinstall-rrequirements.txt# 已包含 pytest / pytest-asynciopytest-v测试覆盖核心模块全部离线运行无需 API Key 或外部服务test_embeddings.py嵌入的确定性、归一化、语义相似度排序test_splitter.py文本分块的大小约束与边界条件test_parsing.pyLLM 输出的健壮 JSON 抽取test_memory.py会话生命周期、历史检索、长期记忆与 TTL 清理test_tools.pyAgent 工具含计算器安全校验与注册中心test_llm.pyOpenAI 兼容提供商DeepSeek/MiMo的构造校验 工厂的切换与缓存test_retriever.py索引构建、语义检索、按文档删除、上下文拼接使用内存版假向量库test_vectorstore.py本地 numpy 向量库的增删、相似度检索、元数据过滤与持久化 项目结构our-project/ ├── backend/ # FastAPI 后端 │ ├── app/ │ │ ├── main.py # 应用入口生命周期、CORS、异常、路由 │ │ ├── config.py # pydantic-settings 配置离线嵌入默认开箱即用 │ │ ├── api/ # 路由层documents / chat / agent / memory / models │ │ ├── core/ # 核心能力 │ │ │ ├── llm/ # LLM 抽象、各提供商、工厂、提示模板 │ │ │ ├── rag/ # 加载/分块/嵌入/向量库/检索器 │ │ │ ├── agent/ # 工具/规划/执行/反思 │ │ │ └── memory/ # SQLite 存储 记忆管理器 │ │ ├── services/ # 服务编排层依赖容器 业务服务 │ │ ├── models/ # Pydantic 请求/响应 Schema │ │ └── utils/ # 日志、异常、解析工具 │ ├── tests/ # pytest 测试 │ ├── requirements.txt │ ├── Dockerfile │ └── .env.example ├── frontend/ # React Vite TS 前端 │ ├── src/ │ │ ├── App.tsx # 根组件导航、模型选择、健康状态 │ │ ├── api/client.ts # REST 客户端 SSE 流式 │ │ ├── components/ # Chat/Documents/Agent/Memory/Prompt 面板 │ │ └── types.ts # 与后端对齐的 TS 类型 │ ├── Dockerfile │ └── nginx.conf ├── docs/ # 架构 / API / 部署文档 └── docker-compose.yml # 一键编排 设计亮点依赖倒置与组合根所有子系统在services/container.py统一装配路由通过依赖注入获取便于测试与替换实现。离线可演示MockEmbedder哈希词袋 L2 归一化 本地 numpy 向量库让整条 RAG 链路在零依赖、零密钥下也能真实运行对话/Agent 填入 DeepSeek 或 MiMo 密钥即可启用。嵌入与向量库解耦自行计算嵌入并向本地向量库写入预计算向量可自由切换嵌入实现。健壮性LLM 输出 JSON 的容错解析、Agent 规划失败的兜底计划、计算器工具的字符白名单防注入、全局异常处理器。完整中文注释所有模块均含函数说明、参数、返回值与关键逻辑解释。项目链接https://github.com/Chun556699/RAG-KnowledgeBase 许可 · License本项目基于 MIT License 开源可自由使用、修改与商用保留版权声明即可。Licensed under the MIT License — free to use, modify and distribute with attribution.