# AI 知识库助手项目报告 ## 一、项目背景 在 AI 大模型快速发展的背景下，将个人文档资料与 AI 问答能力结合，可以显著提升学习和知识管理效率。本项目旨在构建一个本地 AI 知识库助手原型，探索从文档解析到智能问答的完整链路。 ## 二、项目目标 1. 构建一个基于 Next.js 的 AI 聊天助手，接入 DeepSeek API。 2. 实现文档上传与文本解析，支持多种格式。 3. 实现本地知识库检索与准 RAG 问答流程。 4. 实现多轮追问和学习化输出。 5. 为后期接入 AnythingLLM 等正式 RAG 系统做架构准备。 ## 三、功能设计 ### 已完成功能 - **首页 Dashboard**：项目总览、快捷入口、统计卡片、最近活动 - **普通 AI 聊天**：Markdown 渲染、代码高亮、复制、重新生成、删除 - **DeepSeek API 接入**：Provider 架构、服务端 API Route 调用、API Key 保护 - **流式输出**：NDJSON 流式协议、逐步显示、停止生成 - **Token 统计与成本预估**：请求记录、每日统计、成本预估、使用限制 - **文档上传与解析**：txt/md/docx/pdf 文本提取、chunk 切片、预览 - **本地关键词检索**：关键词匹配、同义词扩展、技术词加权、二次排序 - **准 RAG 问答**：引用来源、可信度判断、回答策略控制 - **多轮追问**：QA 会话管理、四种追问模式、时间线 - **学习中心**：学习卡片、复习题、学习计划、掌握程度 - **主题切换**：浅色/深色/跟随系统 ### 待完成功能 - **AnythingLLM 接入**：正式 RAG、向量检索 - **Cloudflare R2 存储**：文件存储、文档管理 - **服务器部署**：2c4G 服务器、Nginx、域名 ## 四、技术架构 ### 技术栈 - **Next.js 16**（框架）：App Router、API Route、Server Components - **React 19**（前端）：Hooks、Suspense、Server Components - **TypeScript**（语言）：类型安全、接口定义 - **Tailwind CSS v4**（样式）：原子化 CSS、响应式设计 - **Zustand**（状态管理）：轻量级状态管理、Persist 中间件 - **DeepSeek API**（AI）：大模型 API、流式输出 - **mammoth**（文档解析）：DOCX 文本提取 - **pdf-parse**（文档解析）：PDF 文本提取 - **LocalStorage**（存储）：浏览器本地持久化 - **PWA**（增强）：Manifest、Service Worker ### 架构模式 - **Provider 模式**：抽象 AIProvider 接口，支持多 Provider 切换。 - **服务端代理**：API Route 转发 AI 请求，保护 API Key。 - **本地优先**：文档解析和检索在前端完成，减少服务端依赖。 ## 五、关键实现 ### 1. 流式输出 使用 NDJSON 协议实现服务端到前端的流式数据推送。服务端读取 DeepSeek SSE 流，转换为 NDJSON 格式，前端通过 fetch ReadableStream 逐步解析显示。 ### 2. 文档解析 服务端使用 mammoth (DOCX) 和 pdf-parse (PDF) 提取文本，前端执行 chunk 切片。解析结果保存到 localStorage。 ### 3. 本地检索引擎 实现关键词匹配 + 同义词扩展 + 技术词加权 + chunk 去重 + 相邻合并 + 多样性 Reranker 的完整检索管道。 ### 4. 准 RAG 问答 检索 → 引用编号 → 可信度判断 → Prompt 构建 → DeepSeek 生成回答，模拟完整 RAG 链路。 ## 六、项目难点与解决方案 1. **API Key 安全**：通过 Next.js API Route 代理，Key 仅在服务端 process.env 中。 2. **流式输出兼容**：自定义 NDJSON 协议，兼容 Next.js App Router。 3. **文档解析格式**：使用 mammoth 和 pdf-parse，服务端动态 import 避免客户端 bundle 膨胀。 4. **检索质量**：同义词库 + 技术词权重 + 多样性排序，提升关键词检索效果。 ## 七、当前完成情况 - 项目骨架与 UI：Next.js 项目初始化、页面路由、基础组件、Tailwind 样式 - 本地持久化与 Mock 数据：Zustand + localStorage、主题切换、聊天记录保存 - DeepSeek API 接入：Provider 架构、服务端 API Route、API Key 安全 - 流式输出与 Token 统计：NDJSON 流式协议、Token 用量统计、成本预估 - 本地文档解析：txt/md/docx/pdf 解析、chunk 切片、预览 - 本地检索与准 RAG 问答：关键词检索、同义词扩展、引用来源、可信度 - 多轮追问与学习中心：QA 会话、追问模式、学习卡片、复习题 ## 八、当前限制 - 当前仍是本地 Demo，未部署服务器 - 知识库检索基于本地关键词匹配，不是向量检索 - 未接入 AnythingLLM 或其他正式 RAG 系统 - 未接入 Cloudflare R2 或其他云存储 - 未接入真实数据库，数据存储在浏览器 localStorage - PDF 解析不支持扫描版 OCR - Token 估算为近似值，成本为本地预估 - 大量文档时 localStorage 有容量限制 ## 九、后续优化方向 - 接入 AnythingLLM 实现正式 RAG - 接入 Cloudflare R2 实现文件云存储 - 部署到 2c4G 个人服务器 - 配置 Nginx 反向代理和域名 - 完善 PWA 离线支持 - 优化中文分词和检索质量 ## 十、总结 本项目实现了一个从文档上传到智能问答再到学习化的完整本地 Demo，验证了 AI 知识库助手的核心链路。当前基于本地关键词检索的准 RAG 方案可以作为后期接入正式向量数据库的过渡方案。