项目工作总结项目中华心法问答系统整理时间2026-11-03一、项目概览中华心法问答系统是一套面向传统文化问答场景的检索系统Web 端Jinja2 原生 JS、uni-app 小程序H5 / 微信小程序、Flask MySQL 后端支持四种语义向量模型、语音输入与播报、知识库回收站以及面向运维的部署与打包方案。维度现状后端Flaskapp-factory Blueprint138 路由MySQL 8/9前端Jinja2 原生 JS设计系统static/css/app.css宣纸 / 朱砂小程序uni-app8 个页面H5 与微信小程序双端可构建知识库1529 条已入库问答用户18 个user / admin / superadmin向量模型BERT-base768、LAUR 混合权重76811 档比例、BGE-large-zh-v1.51024、Conan-embedding-v11792模型切换异步 进度百分比 完成后自动刷新缓存命中约 3–5 秒语音Web Speech ASR Vosk 离线兜底edge-tts Windows SAPI 兜底部署腾讯云 宝塔 Nginx Gunicornapp / bert / bge / conan 四个部署包主版本服务http://127.0.0.1:5000检索实验环境F:\mdqa\xinfa-bhttp://127.0.0.1:5001独立库xinfa_db_b二、界面统一与小程序统一全站视觉以原有 mdqa 模板为参考建立统一设计令牌--cinnabar #8C3A1E、--paper #F5F0E8、--card #FFFDF9、--ink #241C18、--line #E2D6C6统一组件页头.page-head、卡片.card、按钮.btn、徽标.badge、表格.table-wrap、空状态.empty-state所有页面继承templates/base.html统一导航、表单、表格与空状态整理目录结构清理历史备份与临时文件小程序重写重写 8 个页面首页、搜索、详情、标签、提交、留言板、个人中心、登录H5 与 mp-weixin 两端构建通过接口与 Web 端对齐文档docs/小程序功能对齐PRD.md、docs/小程序后端接口对齐.md截图docs/screenshots/uniapp/*.png三、语音输入与播报能力语音输入浏览器 Web Speech API 优先失败时走/api/asrVosk 离线模型vosk-model-small-cn-0.22语音播报/api/ttsedge-tts失败自动降级 Windows SAPI支持音色、语速设置并按页面持久化搜索结果卡片动态生成「朗读」按钮做过的稳定性修复问题根因处理朗读没有声音stop()把audioEl置空保留元素只清src动态按钮点不动事件只绑首屏节点改为 document 捕获阶段事件委托前端修改不生效Jinja 模板缓存 静态缓存重启后端、资源加?v版本号切换音色/点击闪退语音对象状态竞争播放令牌 停止旧实例 异常兜底edge-tts 503 / 0 字节缓存服务偶发失败、半成品写入重试、超时、.part原子替换、最小字节校验四、云服务器部署打包脚本scripts/package_for_deploy.ps1-IncludeVosk带离线语音模型-IncludeBge带 BGE 模型-IncludeConan带 Conan 模型-SkipModel只打代码包部署配置deploy/nginx.conf、deploy/xinfa_qa.service、gunicorn_config.pygunicornworkers1、gthread、threads8、timeout300、bind 127.0.0.1:8000指南deploy/部署指南-腾讯云宝塔.mdPython 3.11、MySQL、Nginx、COS、systemd、升级 SQLrequirements.txt的 20 个依赖在 Python 3.11 下校验通过BGE / Conan 依赖拆分为requirements-bge.txt、requirements-conan.txt当前部署包xinfa_qa_app_20261031_1251.zip 85.1 MB 代码 四模式向量缓存 xinfa_qa_bert_20261029_1446.zip 364.5 MB xinfa_qa_bge_20261029_1446.zip 721.6 MB xinfa_qa_conan_20261031_1251.zip 732.0 MB五、知识库治理超级管理员删除搜索结果卡片新增「移入回收」仅role superadmin渲染后端POST /admin/delete-content/type/id二次校验角色非超管返回 403布局朗读在左、移入回收在右危险色描边 二次确认软删除与回收站question / video / article增加is_deleted、deleted_at、deleted_by_id通过 SQLAlchemydo_orm_executewith_loader_criteria全局过滤删除后全站不可见删除问答时从内存向量索引移除并刷新缓存新增「已删除数据」页面仅超管恢复 / 永久删除恢复时重新加入索引批量、筛选与操作日志批量恢复 / 批量永久删除/admin/deleted-content/batch单次 ≤200按类型、删除时间区间筛选operation_log表记录 delete / restore / purge操作人、对象、IP、时间回收站页展示最近 30 条日志迁移 SQL 写入 README 与部署指南六、小助手仅首页 / 问答页加载默认右下角可拖拽并本地持久化位置尺寸随视口自适应clamp(76, min(7vw, 26vh), 240)2560 分辨率下不再过小三态动画待机assistant-anim.webpstand.gif71 帧5.68 秒循环搜索后assistant-search.webpsearch.gif90 帧7.2 秒循环切换用 160ms 淡入淡出统一画布 420×690、人物高度 618px切换不跳大小双击播报「今天有什么想问的」右键复位位置透明背景干净搜索态约 77% 透明无白边七、模型体系与切换体验默认模型默认模式改为 BGEMODEL_MODE默认bge.env可覆盖切换成功后 1.6 秒自动刷新页面并提示「页面即将刷新…」按模式缓存缓存按模式拆分data/embeddings/vectors_{bert,laur,bge}.npz指纹包含问题集合、模式、维度、权重、模型路径数据或配置变化才重建旧版单文件缓存首次启动自动迁移切换改为后台线程 轮询/api/model_switch_progress进度示例读取问答数据 241/1529 6%正在生成向量 600/152940%载入向量缓存… 60%✅ 已切换到 XXX 模式页面即将刷新…LAUR 混合比例滑块范围BERT 0.0 : 1.0 LAUR至1.0 : 0.0共 11 档异步切换 同一进度接口按比例分文件缓存加速技巧LAUR 向量 normalize(BERT 向量 × 权重矩阵)直接由 BERT 缓存推导3.2–3.8 秒完成此前约 70 秒缓存误判修复问题指纹含hybrid_ratio在 LAUR 下调过比例后切 BGE 会被判缓存失效重新编码约 12 分钟修复BERT / BGE 模式对 0.0–1.0 共 11 个比例逐一比对指纹结果LAUR(0.4) ↔ BGE 来回切换 2.8–3.1 秒Conan-embedding-v1 集成结构BERT-large 中文24 层 / 1024 mean pooling Dense 1024→1792懒加载1.24GB切到 CONAN 才加载独立缓存vectors_conan.npz9.7MB与其它模式对齐按钮、进度、自动刷新、失败回滚首次构建 472 秒热切换 3.7–5.2 秒性能对比1529 条CPU模式维度单条编码单次检索文档吞吐热切换缓存内存BERT76846.4 ms65 ms13.3 条/s4.33 s4.2 MB963 MBLAUR76829.8 ms38 ms13.1 条/s3.80 s4.2 MB977 MBBGE1024399.2 ms198 ms1.9 条/s4.47 s5.6 MB984 MBConan1792132.8 ms102 ms3.5 条/s5.19 s9.7 MB2168 MBC-MTEB论文 Table 3Conan72.62BGE-large-zh-v1.5 官方约 64.5。详细报告docs/Conan模型集成与性能对比.md八、标注与检索优化方案产出docs/检索与标注优化方案.md现状诊断120 条扰动 query 自检索BERT Recall1 0.55、BGE 0.95、Conan 0.92缺少固定评测集标注难的四层解法L0 自动弱标签LLM 改写问法、答案反推问题、难负例L1 隐式反馈点击、停留、换词、无结果L2 LLM 预标注 人工抽检成本约为全人工的 1/8L3 主动学习只标模型最不确定的 100–200 条检索四阶段路线混合检索BM25 向量 RRF、多路召回、置信度阈值、去重查询改写、意图分类、答案分块重排bge-reranker微调 / 蒸馏 / RAG 摘要A/B/C 方案对比1 周轻量 / 3 周标准 / 6 周完整九、检索实验混合检索与重排为避免影响线上版本单独建立了隔离环境目录F:\mdqa\xinfa-b代码副本模型只读引用主目录数据库xinfa_db_b完整复制1529 条问答、18 用户端口 5001主版本 5000 不受影响混合检索BM25jieba 分词问题权重 3、关键词 2、答案 1k11.5、b0.75向量 Top100 BM25 Top50 → RRFk60w_dense1.0w_bm250.7近似问题去重字符 Jaccard ≥0.9低置信标记Top1 相似度 0.5/search与/api/search均已接入开关RETRIEVAL_MODEhybrid|dense评测集与脚本scripts/eval/build_eval_set.py自动生成 300 条扰动 query截断 / 丢字 / 口语前缀 / 关键词式正例已知100 条 test、200 条 devscripts/eval/run_eval.pydense / hybrid / hybridrerank 对比指标 Recall1、Recall10、MRR、nDCG10、低置信率、P95 延迟重排模型bge-reranker-baseCrossEncoder1.06GBCPU对 RRF 融合后的 Top5 精排只对问题文本打分5 条约 0.11 秒开关RERANK1、RERANK_TOP_K5低置信兜底后端返回low_confidence前端提示条「 这条问题没有找到特别匹配的答案去提问留言板…」标注后台/admin/search-eval管理员 / 超管导航栏「检索评测」展示 query Top6 候选问题 / 答案 / 相似度 / 正例标记三档标注2 相关 / 1 部分 / 0 不相关保存后自动跳下一条表relevance_labelquery question 唯一记录标注人与时间接口POST /admin/search-eval/label评测结果100 条 testBGE指标densehybridhybridrerankTop5hybridrerankTop10Recall10.9000.9300.9500.960Recall100.9800.9900.9900.990MRR0.9270.9540.9640.973nDCG100.9400.9630.9700.977P95 延迟328ms502ms755–902ms1844ms结论Top5 重排以约 0.2 秒换 Recall1 2ptTop10 再多 1pt 但延迟翻倍默认取 Top5。十、查询改写实验未采用实现了规则式改写去口语前缀、口语词归一啥 / 咋 / 为啥 / 能否、去语气词、长查询关键词提取、15 组领域同义词扩展向量检索使用归一化 queryBM25 使用原始 归一化 关键词 同义词四路 RRF前端显示「 已按「xxx」理解你的问题」评测结果指标不改写改写Recall1普通集0.9500.950Recall1口语集0.9330.933MRR口语集0.9490.945P95口语集951ms1050ms结论规则改写对「BGE hybrid rerank」没有增益同义词扩展还略降 MRR、增加约 100ms。已完整回退该功能删除模块、还原检索链路、移除接口字段与前端提示、清理相关评测数据环境恢复到「混合检索 重排 低置信 标注后台」状态。十一、关键指标检索100 条 testdenseRecall1 0.900 / MRR 0.927 / nDCG10 0.940 / P95 328mshybrid0.930 / 0.954 / 0.963 / 502mshybrid rerank Top50.950 / 0.964 / 0.970 / 755–902msBERT 基线下 hybrid 提升更明显Recall1 0.570 → 0.76019pt模型切换操作耗时BERT → LAUR缓存5.8sLAUR → BGE缓存2.8–4.2sBGE → Conan缓存3.7–5.2sLAUR 比例切换缓存 / 推导3.2–3.8s首次构建 BERT / LAUR / BGE / Conan77s / 148s / 753s / 472s向量缓存文件大小说明vectors_bert.npz4.2MB768 维vectors_bge.npz5.6MB1024 维vectors_laur_*.npz各 4.2MB11 档比例0.0–1.0步长 0.1vectors_conan.npz9.7MB1792 维vectors_laur_0.00.npz显示 0MB实际为 20KB 高度可压缩文件内容完整。十二、产物清单核心代码模块路径作用app/modules/qa/__init__.py搜索、问答、回收站、删除、历史等主路由app/modules/admin/__init__.py模型切换、比例、配置、评测路由app/modules/api/__init__.pyH5 / 小程序 APIapp/qasystem.py四模型加载、缓存、异步切换、比例推导app/modules/voice/、app/modules/asr/TTS / ASRstatic/js/voice.js语音输入与朗读static/js/assistant.js小助手三态、拖拽、双击语音templates/deleted_content.html已删除数据回收站models.pyQuestion / PendingQuestion / OperationLog / EvalQuery 等检索实验新增路径作用app/modules/retrieval/__init__.pyBM25 RRF 去重 重排 低置信templates/search_eval.html标注后台scripts/eval/build_eval_set.py生成 300 条评测集scripts/eval/run_eval.pydense / hybrid / rerank 跑分B-方案说明.md检索实验全记录文档README.md界面、小程序、语音、部署、检索、模型deploy/部署指南-腾讯云宝塔.mddocs/项目技术栈与团队协作指南.mddocs/小程序功能对齐PRD.md、docs/小程序后端接口对齐.mddocs/Conan模型集成与性能对比.mddocs/检索与标注优化方案.mddocs/项目工作总结.md十三、当前运行状态服务地址说明主版本http://127.0.0.1:5000稳定版本检索实验期间未改动检索实验http://127.0.0.1:5001混合检索 重排 低置信 标注后台实验数据库xinfa_db_b与主库隔离模型主目录models/只读BERT / BGE / Conan / reranker实验数据300 条评测 query100 test / 200 dev、1 条人工标注、33 条检索日志。健康检查GET / 200 POST /search 200hybrid POST /api/search 200modehybrid、rerankedtrue GET /admin/search-eval 200管理员十四、经验与坑类别问题结论编码PowerShell 写中文变 GBK 乱码统一 UTF-8写入工具 / Python脚本尽量 ASCII文件系统exFAT 原子写报EISDIR新建文件先建空文件再写入Flask改模板 / 静态后不生效Jinja 模板缓存需重启后端静态加?vSQLAlchemy新增deleted_by_id导致submitted_by外键歧义显式foreign_keys[submitted_by_id]SQLAlchemy列名query覆盖Model.query改为query_text软删除多处查询需要过滤do_orm_executewith_loader_criteria全局过滤缓存指纹含hybrid_ratio导致 BGE 误重建非混合模式对比例容错匹配缓存中断写入产生 0 字节缓存启动校验大小 / 维度失败自动重建重排FlagReranker与 transformers 5 不兼容改用sentence-transformers.CrossEncoder重排打分返回 ndarray长度判断失效list(scores)归一化重排答案全文拼入 pair 太慢只对问题文本打分Top5 精排数据测试期误删 1 条真实问答1530→1529永久删除需更严格二次确认定期备份进程重启偶发端口占用先按端口杀进程、确认释放后再启动十五、后续建议标注 → 训练重排先用标注后台标 50–100 条再用relevance_label训练或蒸馏小重排模型。LLM 查询改写仅在低置信 / 长查询时触发避免全量 100ms 开销。检索方案投产把retrieval模块合并回主版本加开关灰度重排只对首屏 Top5 生效。长答案分块对 500 字以上答案切块检索再聚合提升细粒度问题命中。数据安全MySQL 每日备份 回收站保留策略 永久删除二次确认输入标题 / 密码。监控检索 P95、低置信率、模型切换耗时、缓存命中率接入看板。十六、截图索引主题截图首页 / 登录 / 个人中心docs/screenshots/{home,login,profile}.png审核 / 评分 / CSV 导入docs/screenshots/{review,rating_stats,csv_import}.png小程序 8 页docs/screenshots/uniapp/*.png语音docs/screenshots/voice/*.png删除 / 回收站docs/screenshots/ui/{superadmin-delete,deleted-page,recycle-page}.png小助手docs/screenshots/ui/{assistant-idle,assistant-search-pose}.png模型切换 / 比例docs/screenshots/ui/{switch-progress,ratio-progress,conan-active}.png检索实验F:\mdqa\xinfa-b\docs\screenshots\b\{search-eval,low-conf,rewrite-hint}.png
