【立项背景与目标】
个人与中小团队已积累大量私有文档(制度手册、产品文档、论文笔记、FAQ),但交给通用大模型问答时普遍存在三个问题:模型不了解私有资料、答案容易编造、历史问答无法沉淀复用。
本项目目标是交付一个可自行部署的网页版对话助手:把私有文档转成可检索的私有知识库,让模型在“先查资料、再作答、必要时联网、不确定就直说”的约束下回答,同时为每个用户完整保留其会话、思考过程与知识文件,做到数据可管、过程可见、结论可追溯。
【软件功能与核心模块】
1、账号与会话:注册/登录(bcrypt 密码哈希 + JWT,令牌 3 天有效),全量数据按 user_id 隔离;支持会话创建、切换、删除,消息(正文 + 思考过程 + 时间)持久化,历史消息自动作为多轮上下文。
2、智能对话:DeepSeek flash 模型 + Agent 工具编排,回答前强制检索知识库、按需联网搜索;前端以可折叠面板展示模型思考过程,正文用 markdown-it 渲染并高亮代码。
3、RAG 知识库:上传 md/docx/pdf → Unstructured 解析 → 递归分块(chunk 500 / overlap 50,按标题层级切分)→ bge-large-zh 向量化 → Chroma 持久化;检索先召回 top20 候选、再由 qwen3-reranker-4b 精排取 top5 注入上下文;支持单文件删除(向量、磁盘文件、数据库记录三处同步清理)。
4、提示词定制:每个会话可独立设置 system prompt,实时影响该会话后续全部轮次,便于把同一套模型切换成“严格文档助手 / 通用助理 / 特定业务角色”。
5、工程配套:loguru 结构化日志(含状态码与来源 IP)、后端 SSE 流式回复接口、深色玻璃拟态与纸张主题双套视觉、桌面/平板/手机三档响应式布局。
【业务流程与功能路径】
登录 → 侧栏新建或选择会话 →(可选)在知识库面板上传文档并查看分块数、(可选)在提示词条设置人格 → 输入问题 → 后端先落库用户消息 → Agent 自主调用 retrieve_knowledge_base(必要时再调 web_search)→ 返回带 reasoning 的回答并入库回显 → 侧栏可随时切换会话、删除会话或删除知识文件。
【整体架构和设计思路】
前后端分离三层结构:Vue 3 单页前端(:5173,开发期由 Vite proxy 把 /api 转发到 :8000)— FastAPI 异步服务(:8000)— MySQL 8(aiomysql 异步驱动)+ Chroma 本地向量库。
设计思路上把“对话”与“知识”彻底解耦:对话走 Agent 编排,知识走独立 RAG 服务,二者只通过 LangChain 工具边界连接(用户身份由 InjectedToolArg 从 config.configurable 注入),因此后续替换 embedding 模型或换用其他向量库,业务与前端代码零改动。
鉴权做成依赖注入层统一拦截:get_current_user_id 解析 Bearer 令牌,get_owned_conversation 校验会话归属,业务函数内不再重复做权限判断,越权访问统一返回 404 而非 403,避免泄露资源是否存在。
数据库启动时由 lifespan 自动建表,四张表(users / conversations / messages / knowledge_file)全部继承同一 DeclarativeBase,字段用 SQLAlchemy 2.0 Mapped 风格声明,正文与思考过程用 LONGTEXT 存储。
【我的负责模块和结果】
项目全部由我独立设计与实现:前端 15 个文件约 4900 行(Vue 3 + TS + Vite,状态集中在 App.vue,无 Pinia/Router 依赖;axios 拦截器统一挂 JWT、401 自动清令牌并回登录;markdown-it + highlight.js 按需注册语言),后端 28 个文件约 900 行(FastAPI + SQLAlchemy 2.0 async + Pydantic v2,LangChain create_agent 组合 ChatDeepSeek 与两个异步工具,Chroma + 千帆 bge-large-zh 向量化与 qwen3-reranker-4b 精排,pyjwt + bcrypt,loguru 日志)。
交付结果:13 个 REST 端点、4 张数据表、注册→建会话→上传文档→检索增强问答→删除的完整闭环全部跑通;单进程可同时服务多用户会话、文档上传解析与对话请求。
【我遇到的难点、坑和解决方案】
1、指令被稀释:create_agent 自带默认 system prompt,会话级 SystemMessage 又插在消息首位,两层提示词互相干扰,模型经常跳步直接联网。解决:把“先检索知识库→再判断是否联网→不确定就明确说不确定”同时写进工具 docstring 与 system prompt 两处(工具描述对模型行为的影响往往比提示词更硬),并把 max_tok