创新实训团队开发日志（3）

一、项目初期技术选型

1.项目启动初期，我们团队的核心原则是拒绝技术堆砌，所有选型均围绕408考研的业务需求展开，避免后期因架构不合理导致的重构成本与性能瓶颈。我们的核心业务需求既包含用户信息、做题记录、会话管理等结构化数据存储，也需要支撑非结构化的考研笔记解析、RAG智能检索、大模型接入、未来知识图谱构建等AI能力，因此我们对数据库、核心框架做了全维度的选型对比。

2.关系型数据库选型：我们在PostgreSQL与MySQL之间做了深度对比：初期曾倾向于PostgreSQL，核心原因是其pgvector插件可支持向量检索能力，能够减少多数据库维护成本；但深入调研后发现，pgvector本质是关系型数据库的字段扩展，并非原生向量数据库，更适合带复杂业务条件的混合检索，与我们纯语义召回的RAG核心场景匹配度较低；同时团队对MySQL技术栈更为熟悉，其架构更轻量、上手成本更低，针对JSON格式的题库选项、长文本解析等场景的基础操作已完全满足业务需求。 最终我们团队敲定MySQL作为核心关系型数据库，负责用户体系、会话管理、做题记录等核心业务数据的持久化存储。

3.向量数据库选型：针对RAG智能答疑的核心需求，我们在pgvector与ChromaDB之间做了最终选型：pgvector的优势是可与PostgreSQL深度融合，避免多库数据不一致的问题，但其检索逻辑需要在应用层做大量代码开发，维护成本高，不适合纯语义检索场景;ChromaDB是为RAG场景原生设计的轻量向量数据库，查询模式极简，原生支持TopK语义检索，与LangChain框架无缝兼容，完全匹配我们408知识库语义召回的核心目标。 最终我们选定ChromaDB作为专属向量数据库，负责408考研知识点的向量化存储与语义检索。

4.配套技术栈规划：除核心数据库外，我们团队也做了全链路的技术栈预留：缓存层：选定Redis，用于408历年高频真题、热门考点的缓存，降低MySQL数据库压力，计划在项目中后期引入，避免过早优化；图数据库：选定Neo4j，用于后续408知识图谱构建，将知识点作为节点、知识点间的依赖关系作为边，实现考点体系化梳理。

二、框架演进

1.在项目初期，我们团队快速搭建了可跑通基础通信的前后端原型，但随着功能模块的不断扩展，初始版本的代码耦合问题逐渐暴露 —— 接口散落、职责混杂、复用性差，严重影响后续开发效率。为此，我们团队对前后端架构做了全面的重构与标准化，核心目标是实现模块解耦、职责单一，为后续功能扩展预留充足的架构空间。

2.参考领域驱动设计思想，将后端代码做了清晰的分层拆分，重构后的架构如下：
重构的核心是拆分了四大核心职责，彻底解决了初始版本中所有逻辑揉在一个文件的问题。

3.针对初始版本中 UI 与业务逻辑混杂、接口硬编码、鉴权逻辑重复的问题，我们团队引入现代前端模块化与分层设计思想，做了全面的架构优化：

• 新增全局请求拦截器：在utils/request.js中统一实现请求拦截与响应拦截；响应时统一处理 HTTP状态码，实现鉴权逻辑的全局管控。
• 独立服务层拆分：将所有业务请求按领域拆分到api/目录，auth.js负责登录注册、chat.js负责流式对话，视图组件只需导入对应函数即可完成数据请求，实现视图层与数据层的彻底分离。
• 目录结构标准化：补充了router/路由管理、assets/静态资源管理目录，让前端项目结构清晰，团队协作开发效率显著提升。

三、数据库接入
完成架构设计后，我们团队落地了 MySQL 数据库的接入，核心目标是实现数据库连接的安全管理、生命周期可控、操作逻辑标准化，为所有业务功能提供稳定的持久化支撑。

1.数据库连接核心设计
我们在app/db/database.py中实现了数据库连接的核心逻辑，主要包括三大核心组件：

• Engine 数据库引擎：基于环境变量中的数据库连接 URL 创建，负责与数据库建立核心通信；
• SessionLocal 会话工厂：基于 SQLAlchemy
  的sessionmaker创建，每次用户请求到来时，由会话工厂派发一个独立的数据库会话窗口，请求处理完毕后自动关闭，实现连接的按需分配与释放，避免连接泄露；
• Base 基类：所有数据库表模型的父类，通过 ORM 映射实现表结构的自动创建，所有业务表模型均需继承该基类。

同时，我们严格遵循安全开发规范，将数据库账号、密码等敏感信息全部放入.env环境变量，并在.gitignore中屏蔽该文件，避免敏感信息提交到 Git 仓库造成泄露。

2.表结构设计与 CRUD 封装
我们基于业务需求，在app/models/目录下定义了用户表、会话表、消息表、题库表等核心业务表结构，通过 SQLAlchemy 的 ORM 映射实现表结构与 Python 对象的绑定，同时通过relationship实现表之间的关联关系管理。
为了避免数据库操作逻辑散落各处，我们在app/crud/目录下，按业务领域封装了所有增删改查操作，路由层只需调用对应函数即可完成数据操作，无需重复编写 SQL 逻辑，大幅降低了代码冗余与出错概率。

3.表结构变更方案选型
在开发过程中，我们针对表结构变更做了方案对比：初始计划使用 Alembic 工具实现表结构的自动检测与更新，该工具可自动生成表结构变更的迁移脚本。但在实践中我们发现，Alembic 无法识别字段重命名等操作，会误判为 “删除旧字段、新增新字段”，极易造成生产环境的数据丢失，且配置与维护成本较高。
综合考量后，我们团队最终选择手动维护表结构：在表结构发生变更时，通过数据库可视化工具手动修改表结构，同步更新后端对应的模型代码，虽然牺牲了一定的自动化能力，但保证了数据安全，也更适配我们中小规模的项目迭代节奏。

四、RAG 构建
我们完成了从数据爬取、清洗、多模态解析、智能切块、向量化到向量库入库的全链路构建，核心目标是打造一个贴合 408 考研大纲、知识点完整、检索精准的专业知识库。

1.数据爬取
我们通过 BeautifulSoup 解析导航页 DOM 树，按数据结构、计算机组成原理、操作系统、计算机网络四大科目做分类，自动提取对应笔记链接，实现了链接的结构化归集；
针对 CSDN 博客的反爬机制，我们解决了原生 requests 请求频繁触发 521 状态码的问题，引入cloudscraper模块绕过 521 防护盾，补充了逼真的请求头参数，并加入 2-5 秒的随机休眠机制模拟真人阅读节奏，实现了稳定的批量爬取；
爬取过程中，我们只提取博客正文核心内容，自动剔除侧边栏、广告、推荐链接等冗余内容，转换为纯净的 Markdown 格式保存，按科目自动创建文件夹，为后续的切块与检索提供了规整的基础语料。

2.数据清洗
爬取的原始语料存在大量噪音，我们设计了 “粗清洗 + 人工复检 + 多模态图片解析” 的全流程清洗方案：

• 粗清洗：通过正则表达式清除自动生成的目录、多余的格式符号、连续空行，实现标题层级归一化；同时针对公式图片做了还原处理，将防盗版包装的公式图片还原为
  LaTeX 文本公式，避免知识点丢失。
• 人工复检：针对程序无法统一处理的标题层级混乱、作者冗余引言等问题，做了人工校准与清理，保证语料的标题层级规整。
• 多模态图片解析：针对笔记中的流程图、结构图、表格等图片内容，我们摒弃了 “直接删除图片” 的简单方案，采用多模态 RAG思路，接入阿里云通义千问 Qwen3-VL-Plus 视觉大模型，自动生成图片的专业解析文本。定制了 408 考研专属的解析prompt，约束模型严格遵循考研标准答案规范，用标准术语解析图片内容，转换为结构化的 Markdown 表格与文本，并用【图表解析开始/结束】标签包裹，让图片内容也成为 “可检索的文本”，彻底解决了传统 RAG 无法理解图片的痛点。

在这个过程中，我们也踩坑并解决了两大核心问题：一是 403 权限报错，通过匹配 API Key 与地域的 base_url 解决；二是 API 入参格式错误，修正了适配 OpenAI 的入参格式，改为阿里云 dashscope 平台的标准格式，最终实现了图片内容的批量、精准解析。

3.智能切块
数据清洗完成后，我们基于 LangChain 框架，设计了“结构化标题切块 + 递归兜底切块” 的双层智能切块逻辑，核心目标是保证每个知识块都是完整的 408 考点，同时控制块大小适配向量化模型，避免语义碎片化。

具体实现逻辑如下：

• 图表内容保护：通过正则匹配将【图表解析开始/结束】标签内的标题符号临时替换为特殊标记，避免结构化切块时将图表解析内容从中间切开，切块完成后再还原符号，保证图表内容的完整性；
• 第一层结构化切块：使用 LangChain的MarkdownHeaderTextSplitter，按二级标题、三级标题做结构化切分，严格遵循408笔记的知识点层级，保证每个切块都是一个完整的考点，同时自动为切块绑定标题元数据，方便后续检索；
• 第二层递归兜底切块：使用RecursiveCharacterTextSplitter做兜底切分，设置chunk_size=450（字符上限），分割优先级为“四级标题→五级标题→图表边界→段落→换行→句号→空格”，对于结构化切块后超长的内容，优先按知识点边界切分，最大程度避免语义断裂；
• 元数据注入：为每个切块注入学科分类、来源文件等元数据，后续可实现按科目精准检索，进一步提升检索准确率。

最终，我们完成了 7947 个 408 知识点切块的生成。

4.向量化与向量库入库
向量化是 RAG 检索的核心，其本质是将人类可理解的文本，转换为计算机可运算的高维数值向量，让计算机能够通过数学计算判断两段文本的语义相似度。我们针对向量化模型做了深度选型，核心考量中文适配性、408 专业术语理解能力、上下文长度、使用成本四大维度。
最终我们确定了开发阶段用 bge-small-zh-v1.5，最终部署阶段再根据需要切换的方案，既保证了团队开发过程中零成本、无限制、离线可用，又为最终上线的检索精度预留了优化空间。
检索时，用户的问题会被编码为同一个向量空间中的一条向量，通过计算余弦距离筛选出 TopN 最相关的知识点，实现精准的语义召回。

5.RAG 效果调优
针对知识库可能存在的碎片化问题，我们优化了大模型提示词，核心约束包括：优先使用知识库内容回答，主动整合碎片化知识点，串联形成系统连贯的讲解；严格贴合 408 考研大纲，术语规范准确，符合考研答题规范等。