扁小医中医辅助学习AI大模型项目开发过程整理
扁小医医学辅助软件开发记录
项目路径:
E:\bianxiaoyi\bianxiaoyi99当前版本定位:面向中医学习、资料检索与知识整理的本地知识库增强型医学辅助软件。 技术栈:Vue 3 + Vite + TypeScript + Element Plus + FastAPI + SQLite。
一、项目缘起
“扁小医”最初的目标并不是做一个泛泛的聊天工具,而是做一个能围绕中医学习场景持续沉淀资料、检索依据、辅助辨证、串联方剂和经络腧穴的学习工作台。
中医资料本身具有几个特点:概念体系庞大、古今术语并存、同一证候可能存在多个别名、方剂主治和证候之间并非简单的一对一关系,经络腧穴又需要严格依赖标准名称、定位和治疗学依据。因此,项目从一开始就没有把重点放在“让模型自由发挥”,而是先建设本地知识库,再让问答、辨证、方剂和经穴模块基于这些资料互相联动。
整个开发过程围绕一个核心问题展开:
如何让用户从一个症状描述出发,能够沿着可靠资料一路看到证候、方剂、针灸治疗和标准穴位定位?
现在项目已经形成了一条完整链路:
症状输入 -> 证候候选 -> 方剂参考 -> 针灸治疗与经穴参考 -> 标准穴位详情 -> 证候-方剂关联审核
二、资料准备与知识库清洗
项目早期先完成了 PRD 文档整理,并明确了系统不只是“网页界面”,还需要本地配置、资料入库、检索质量和实际功能闭环。
目前已整理进项目知识体系的资料主要包括:
-
中医基础理论资料
-
中医诊断学资料
-
中医临床诊疗术语相关标准资料
-
方剂学资料
-
第一批古代经典名方资料
-
GB/T 12346-2021《经穴名称与定位》标准文本
-
经络腧穴学教材资料
-
针灸治疗学教材资料
资料入库前做过几类清洗工作:
-
删除重复资料,避免相同段落在检索结果中反复出现。
-
清理“更多学习资源欢迎关注微信公众号”等学习资料水印。
-
删除“记忆口诀”类内容,避免问答和辨证时混入非标准表达。
-
将扫描或复制来的资料整理成可检索文本。
-
对经穴名称、定位、经脉归属、国际代码等内容进行结构化。
-
将针灸治疗学中“病名、证型、治法、处方、方义、随证选穴”等内容抽取为针灸治疗记录。
知识库导入脚本集中放在后端 backend/scripts 中:
import_knowledge.py import_formulas.py import_syndromes.py import_acupoints.py import_acupuncture_treatments.py seed_syndrome_formula_links.py clean_acupuncture_sources.py
其中,经络腧穴闭环相关的两个关键导入脚本是:
-
import_acupoints.py:导入标准经穴名称、定位、经脉、国际代码等信息。 -
import_acupuncture_treatments.py:导入针灸治疗学中的病证处方,并匹配到标准经穴 ID。
经过导入后,针灸治疗库已经形成 89 条可关联记录,并且每条记录都尽量匹配到标准经穴详情。
三、项目架构
项目采用前后端分离结构。
前端目录:
frontend src views services router stores styles
后端目录:
backend app api core db models schemas services scripts
后端使用 FastAPI 提供 API,SQLite 保存本地知识库和结构化数据。前端使用 Vue 3、TypeScript、Element Plus 构建单页工作台。
核心 API 模块包括:
auth.py 登录、注册、短信验证码 knowledge.py 本地知识检索与智能问答 syndromes.py 辨证辅助 formulas.py 方剂查询 acupoints.py 经络腧穴查询 acupuncture_treatments.py 针灸治疗记录查询 syndrome_formula_links.py 证候-方剂关联审核
核心数据模型包括:
auth.py knowledge.py syndrome.py formula.py acupoint.py acupuncture_treatment.py syndrome_formula_link.py
四、登录与短信验证码
项目登录模块完成了三种必要入口:
-
账号密码登录
-
手机号验证码登录
-
手机号验证码注册
短信服务参考了课堂源码中的阿里云短信认证服务配置方式,敏感配置全部放在 .env 文件中,不写入前端,也不写入源码。
环境变量包括:
ALIYUN_ACCESS_KEY_ID= ALIYUN_ACCESS_KEY_SECRET= ALIYUN_SMS_SIGN_NAME=恒创联众 ALIYUN_SMS_TEMPLATE_CODE=100001
后端负责调用短信服务,前端只提交手机号和验证码用途。这样做的好处是:
-
AccessKey 不会暴露到浏览器。
-
本地开发和正式环境可以用同一套接口。
-
验证码登录、注册逻辑可以统一校验。
为了便于本地调试,系统在本地环境中保留了开发模式兜底:如果未配置正式短信密钥,可以返回开发验证码辅助联调;当真实 AccessKey 填写完成后,即可切换到真实短信发送流程。
五、智能问答模块
智能问答模块的目标不是让模型直接凭空回答,而是先从本地知识库中检索依据,再基于依据生成回答。
问答链路如下:
用户问题 -> 结构化知识检索 -> 主知识库片段检索 -> 合并引用来源 -> 外部模型总结或本地摘录兜底 -> 前端展示回答和参考依据
后端关键逻辑位于:
backend/app/api/knowledge.py backend/app/services/knowledge_service.py 外部模型调用服务
实际优化中,智能问答经历了一个重要调整:早期本地检索回答容易直接复制知识库片段,导致回答和“结构化证候标准库”“主知识库”内容雷同。后来将设计改为“检索只负责找依据,生成负责组织表达”,让回答更贴近用户问题。
当前问答结果会显示:
-
回答正文
-
引用依据
-
来源类型
-
安全提示
-
相关方剂或经穴跳转入口
前端不会强调具体模型名称,用户看到的是“智能问答”的学习辅助能力,而不是模型品牌本身。
六、辨证辅助模块
辨证辅助是整个项目的中枢模块。用户输入症状后,系统会从证候标准库中匹配候选证候,并展示:
-
候选证候
-
匹配词
-
证候定义和临床表现
-
病机解释
-
需要补充的信息
-
安全提示
-
参考方剂
-
针灸治疗与经穴参考
后端入口位于:
backend/app/api/syndromes.py
核心服务位于:
backend/app/services/syndrome_service.py
辨证接口在返回候选证候的同时,会继续调用方剂关联和针灸治疗推荐逻辑,让结果页不再停留在“判断一个证候”,而是直接向后延伸到学习链路。
当前辨证结果页已经形成三个层次:
-
证候层:判断可能的证候方向。
-
方剂层:展示与证候相关的参考方剂。
-
经穴层:展示针灸治疗记录,并可跳转到标准穴位定位。
这也是项目从“能检索资料”走向“能串联知识”的关键一步。
七、方剂查询与证候关联
方剂查询模块最初只负责按方名、组成、功效、主治等字段检索。随着辨证功能完善,方剂模块逐渐接入证候关联。
当前方剂库支持:
-
方名检索
-
分类浏览
-
组成查看
-
功效查看
-
主治查看
-
出处查看
-
禁忌和使用提示查看
-
从辨证结果跳转到相关方剂
-
从智能问答延伸到相关方剂
后端核心文件:
backend/app/api/formulas.py backend/app/services/formula_service.py backend/app/models/formula.py
在开发过程中,方剂关联质量做过多轮优化。早期曾出现部分证候无法查询到方剂的问题,后来补充了全量证候关联检索,不再只针对个别用户提到的证候做规则。
此外,还修复过方剂分类栏“有数字但不显示方剂”的问题,区分了“分类统计数字”和“当前筛选结果”之间的状态,避免页面看起来像数据断开。
八、证候-方剂关联审核
为了让自动发现的证候-方剂关系可控,项目加入了关联审核模块。
这个模块的价值在于:系统可以自动发现候选关系,但最终是否确认进入优先结果,需要通过审核流程保留依据。
当前审核模块支持:
-
查看待审核、已通过、已驳回的关联。
-
按证候、方剂、来源依据搜索。
-
按方剂分类筛选。
-
按关联类型筛选。
-
按置信度筛选。
-
查看关联证据和来源。
-
调整置信度并提交审核意见。
后端核心文件:
backend/app/api/syndrome_formula_links.py backend/app/models/syndrome_formula_link.py backend/app/schemas/syndrome_formula_link.py
前端对应实现集中在:
frontend/src/views/WorkspaceView.vue frontend/src/services/syndromeFormulaLinks.ts
这个模块也解决了一个实际体验问题:待审核数量较多时,单纯列表浏览效率很低。加入分类和筛选后,可以按方剂类别、关联类型、置信度快速定位需要处理的关系。
九、经络腧穴模块
经络腧穴模块最初围绕 GB/T 12346-2021《经穴名称与定位》标准文本建设,目标是保证穴位名称、经脉归属、定位描述和国际代码足够标准。
当前模块支持:
-
按穴名检索
-
按国际代码检索
-
按经脉筛选
-
查看标准定位
-
查看所属经脉
-
从智能问答跳转到相关穴位
-
从辨证结果中的针灸治疗记录跳转到穴位详情
后端核心文件:
backend/app/api/acupoints.py backend/app/models/acupoint.py backend/app/services/acupoint_service.py
前端服务文件:
frontend/src/services/acupoints.ts
经穴资料处理过程中遇到过 PDF 文本提取问题。后来通过 Word 版本资料和可复制文本完成整理,保证入库内容可以稳定检索。
十、针灸治疗与经穴闭环
最近完成的是经脉腧穴对应证候资料的接入,也就是项目闭环中的最后一段。
新增的结构化模型是:
backend/app/models/acupuncture_treatment.py
对应接口和服务是:
backend/app/api/acupuncture_treatments.py backend/app/services/acupuncture_treatment_service.py backend/app/schemas/acupuncture_treatment.py frontend/src/services/acupunctureTreatments.ts
针灸治疗记录从《针灸治疗学》资料中抽取,字段包括:
-
病名
-
证型
-
临床表现
-
治法
-
主穴
-
随证选穴
-
方义
-
操作说明
-
来源章节
-
匹配到的标准经穴 ID
真正困难的地方不只是“把资料导进去”,而是让辨证结果能找到合适的针灸治疗记录。
例如用户输入:
恶寒发热,无汗,头身疼痛,咳嗽,脉浮紧
系统辨证候选会出现:
表实证、表寒证、风寒犯肺证、太阳伤寒证
针灸治疗推荐需要进一步归到:
感冒 · 风寒证
并展示相关穴位:
列缺、合谷、迎香、支正、风门、肺俞
再例如用户输入:
胃脘冷痛,喜温喜按,呕吐清水,畏寒肢冷
标准证候可能命中“寒邪犯胃证”“胃实寒证”等,但针灸治疗学资料中对应病名更接近“胃痛”。因此系统加入了病名和症状归一映射:
胃脘冷痛 / 寒邪犯胃 / 胃寒 / 脾胃虚寒 -> 胃痛
这样推荐结果就能回到:
胃痛 · 实证 胃痛 · 虚证
并继续带出足三里、内关、公孙、脾俞、胃俞等标准穴位详情。
为了减少误匹配,推荐逻辑还加入了寒热虚实互斥校验:
-
风寒证不应轻易推荐风热处方。
-
风热咽痛不应被风寒处方挤占。
-
没有鼻部症状时,不优先推荐鼻渊。
-
没有暑湿表现时,不优先推荐暑湿或中暑。
-
没有虚证表现时,虚热或虚证处方降权。
这一步完成后,辨证结果页中的栏目改为:
针灸治疗与经穴参考
每条记录展示病名、证型、治法、方义和穴位按钮。点击穴位按钮后,会跳转到经络腧穴模块中的标准定位详情。
十一、前端工作台体验
前端不是单独做几个页面,而是围绕学习工作台组织。
当前工作台包含:
-
智能问答
-
辨证辅助
-
方剂查询
-
经络腧穴
-
关联审核
模块之间通过按钮和状态联通:
-
问答结果可以跳到相关方剂。
-
问答结果可以跳到相关穴位。
-
辨证结果可以查相关方剂。
-
辨证结果可以查针灸治疗与经穴参考。
-
方剂详情可以回到问答继续追问方解。
-
穴位按钮可以打开标准定位详情。
-
关联审核确认后的关系会影响方剂检索优先级。
前端还完成了几轮体验修复:
-
修复“今日路径”遮挡右侧内容的问题。
-
修复方剂分类栏溢出问题。
-
修复审核筛选栏溢出问题。
-
加入 logo 和背景图。
-
调整背景图可见度,避免完全被界面遮住。
-
移除前端中不必要的大模型名称展示。
-
优化辨证结果页的信息密度和结果解释。
十二、本地开发与运行
项目当前主路径使用英文目录:
E:\bianxiaoyi\bianxiaoyi99
这样做是为了减少中文路径在云仓库、服务器部署、虚拟环境、PyCharm 解释器配置中可能带来的兼容问题。
本地默认端口:
前端:http://127.0.0.1:5173 后端:http://127.0.0.1:8003 健康检查:http://127.0.0.1:8003/api/health
前端构建在 Windows 下使用:
.\node_modules\.bin\vite.cmd build --configLoader runner
这是为了避开某些环境中 Vite 临时文件权限导致的问题。
常用验证命令:
cd E:\bianxiaoyi\bianxiaoyi99\backend .\.venv\Scripts\python.exe -m compileall app scripts cd E:\bianxiaoyi\bianxiaoyi99\frontend .\node_modules\.bin\vue-tsc.cmd --noEmit --incremental false .\node_modules\.bin\vite.cmd build --configLoader runner
最近一次验证结果:
-
后端编译通过。
-
前端类型检查通过。
-
前端生产构建通过。
-
后端健康检查返回
status: ok。 -
前端
/workspace页面返回 200。
十三、闭环测试样例
为了验证辨证链路是否真正可用,做过几组典型样例。
1. 风寒外感样例
输入:
恶寒发热,无汗,头身疼痛,咳嗽,脉浮紧
辨证候选:
表实证、表寒证、风寒犯肺证、太阳伤寒证
针灸治疗与经穴参考:
感冒 · 风寒证 列缺、合谷、迎香、支正、风门、肺俞
2. 风热咽痛样例
输入:
发热重,微恶风,咽喉肿痛,口渴,脉浮数
辨证候选:
风热犯表证、暑犯肺卫证、热重于风证、风热上犯证
针灸治疗与经穴参考:
感冒 · 风热证 咽喉肿痛 · 风热证
3. 胃脘冷痛样例
输入:
胃脘冷痛,喜温喜按,呕吐清水,畏寒肢冷
辨证候选:
寒邪犯胃证、胃实寒证、里寒证、胃寒痰逆证
针灸治疗与经穴参考:
胃痛 · 实证 胃痛 · 虚证
这说明系统已经不是单点检索,而是可以从症状出发,经过证候识别,继续联动方剂和针灸治疗资料。
十四、开发过程中遇到的问题与解决
项目推进过程中,真正耗时的地方并不只在写页面和接口,而是在资料质量、环境路径、接口联通、检索准确性和前端体验之间不断校正。下面整理的是开发中已经遇到并处理过的主要问题。
1. 医学资料来源复杂,直接入库会影响检索质量
最早整理资料时,部分 Markdown 和 PDF 内容带有学习资料水印、重复段落、记忆口诀和非标准表述。如果直接入库,智能问答和辨证检索会把这些内容当成正式依据,导致回答不够严谨。
处理方式是先做资料清洗,再入库:
-
删除重复内容,降低检索结果中的重复引用。
-
清理公众号引流、水印、页眉页脚等无关文本。
-
删除记忆口诀类内容,避免系统把口诀当作标准医学表述。
-
将资料按理论、诊断、证候、方剂、经穴、针灸治疗等类别拆分。
-
对结构化价值高的资料单独建表,而不是全部混进普通文本知识库。
这个处理让后面的问答、辨证和关联检索稳定了很多。
2. PDF 提取存在乱码和不可复制问题
经穴标准资料和部分教材资料来自 PDF。开发中遇到过 PDF 字符映射异常、扫描件识别不稳定、复制文本错乱等情况。尤其是《经穴名称与定位》PDF,一开始尝试修复 CMap 问题,但 PDF 提取仍不够可靠。
最终解决方式是改用 Word 版本和可复制文本作为主来源,再整理成 Markdown 入库。这样比强行从异常 PDF 中抽取文本更稳,也减少了穴位名称、国际代码、定位描述出现错字的风险。
3. 中文路径导致虚拟环境和工具配置容易失效
项目曾经经历过目录重命名,本地 PyCharm 报过类似问题:
Cannot run program "E:\扁小医医学辅助软件项目\venv\Scripts\python.exe" 系统找不到指定的文件
原因是项目主目录改名后,PyCharm 仍然记录着旧虚拟环境路径。路径中包含中文时,虽然本地运行通常可行,但在云仓库、服务器、脚本、虚拟环境和部分工具链里更容易出现兼容问题。
最终处理方式是将主项目固定到英文路径:
E:\bianxiaoyi\bianxiaoyi99
并让 PyCharm、Codex 工作区、云仓库和服务器部署都基于这个路径。这样减少了“同一项目两份路径”“虚拟环境指向旧目录”“脚本找不到解释器”等问题。
4. 前后端端口存在,但接口仍可能请求失败
项目开发中出现过网站打不开、请求失败、点击分析后返回 Not Found 等问题。排查时发现,单纯看到前端端口和后端端口在监听,并不代表接口路径一定正确,也不代表当前页面加载的是最新前端代码。
处理方式包括:
-
用
GET /api/health验证后端是否真实可用。 -
检查前端请求路径是否和 FastAPI 路由一致。
-
区分前端 5173 页面正常、后端 8003 接口正常、具体业务 API 正常这三件事。
-
在修改后端接口后确认当前服务是否需要重启。
-
在修改前端源码后确认 Vite 开发服务是否加载了当前项目目录。
这个排查思路后来多次用于定位“页面能打开但业务请求失败”的问题。
5. 当前运行的前端不一定是最新代码
在经穴闭环完成后,前端源码里已经有“针灸治疗与经穴参考”面板,但实际浏览器里一开始没有明显看到。排查后发现,Vite 开发服务可能仍在提供旧转换结果,或者用户看到的栏目名称和开发时描述不一致。
处理方式是:
-
检查
frontend/src/views/WorkspaceView.vue源码。 -
检查 Vite 服务返回的运行时代码中是否存在对应面板。
-
将标题从“经络腧穴参考”改为更明确的“针灸治疗与经穴参考”。
这样避免了“后端已经有数据,但用户以为前端没有接上”的误解。
6. 智能问答早期回答过于接近知识库原文
智能问答最初以本地检索为主,回答容易变成资料片段拼接,看起来和主知识库、结构化证候标准库内容雷同。这种结果虽然有依据,但不够像针对用户问题的解释。
后来将问答逻辑调整为:
先检索依据 -> 再围绕问题组织回答 -> 保留引用来源 -> 外部生成不可用时再降级为本地摘录
这样既能保留资料出处,又能让回答更贴近问题本身。前端也不再突出具体模型名称,而是强调“智能问答”和“本地依据”。
7. 方剂查询曾出现分类有数量但列表不显示
方剂查询模块开发中出现过一个体验问题:分类栏显示某个分类有数量,但点击后列表没有正常展示方剂。这个问题容易让人误以为知识库断开。
排查后将问题拆成两类:
-
分类统计是否正确。
-
当前筛选条件下的列表请求是否正确。
处理后,方剂分类、关键词、分页和当前列表状态之间的关系更清晰,避免了“数字显示有数据,但页面看不到”的错觉。
8. 证候到方剂的关联不能只补个别样例
早期用户发现某些证候无法查到方剂时,曾针对具体证候补过关联检索。但这样只能解决单点问题,其他证候仍可能查不到方剂。
后来改为面向全部证候建立关联检索和审核机制:
-
从证候名称、别名、定义、临床表现中提取关联词。
-
从方剂主治、功效、组成、方解中寻找候选关系。
-
给候选关系分配置信度。
-
通过关联审核模块确认或驳回。
-
已确认关系进入普通检索的优先结果。
这样比为单个证候硬写规则更稳,也便于继续沉淀知识库。
9. 针灸治疗推荐存在病名和证候表达不一致
经络腧穴闭环中最关键的问题是:证候标准库和针灸治疗学教材的表达方式并不完全一致。
例如:
症状:胃脘冷痛,喜温喜按,呕吐清水,畏寒肢冷 证候候选:寒邪犯胃证、胃实寒证 针灸治疗学病名:胃痛
如果只按字面检索,“寒邪犯胃证”未必能直接命中“胃痛”处方。为了解决这个问题,后端增加了症状和病名归一映射:
胃脘冷痛 / 寒邪犯胃 / 胃寒 / 脾胃虚寒 -> 胃痛 咽痛 / 咽喉肿痛 -> 咽喉肿痛 鼻塞 / 流涕 -> 鼻渊、感冒 风寒 / 表寒 / 脉浮紧 -> 感冒 风热 / 脉浮数 / 咽喉肿痛 -> 感冒、咽喉肿痛
同时加入寒热虚实互斥规则,避免风寒问题推荐风热处方、风热问题推荐风寒处方、没有鼻部症状却推荐鼻渊等情况。
10. 前端布局多次出现遮挡和溢出
随着功能越来越多,工作台中出现过几类典型布局问题:
-
方剂查询右侧内容被“今日路径”遮挡。
-
经络腧穴详情右侧内容显示不完整。
-
方剂分类栏在窄宽度下溢出。
-
关联审核筛选栏内容过多,导致横向溢出。
-
背景图存在感过弱,看起来像没有显示。
处理方式主要是调整布局约束:
-
给主内容区和右侧路径区留出明确边界。
-
分类栏改为可滚动或可换行布局。
-
筛选栏按控件宽度重新排布。
-
背景图透明度和覆盖层重新调整。
-
避免重要内容被固定侧栏或浮层遮挡。
这部分优化让项目从“功能可用”更接近“实际可用”。
11. 终端乱码影响阅读,但没有破坏源码
开发过程中 PowerShell 输出偶尔出现乱码,尤其是中文路径、中文文件名、Git 状态和部分命令输出。排查后确认,大多数情况是终端编码显示问题,不代表源码文件损坏。
处理方式是:
-
源码和 Markdown 文档保持 UTF-8。
-
避免用错误编码重写资料文件。
-
对关键文档用内容读取和检索确认。
-
对终端输出中的乱码不直接作为数据来源。
这样可以避免“看起来乱码”进一步变成“文件真的被写坏”。
12. 启动和验证需要固定流程
项目涉及前端、后端、数据库、短信服务、本地知识库和外部生成服务,手动启动时容易遗漏某一步。开发中逐渐形成固定检查顺序:
确认项目路径 -> 启动后端 -> 检查 /api/health -> 启动前端 -> 打开 /workspace -> 登录 -> 测试问答、辨证、方剂、经穴、审核链路 -> 运行类型检查和构建
这个流程让问题定位更可控,也减少了“页面打不开时不知道先查哪里”的情况。
十五、项目特点
这个项目目前最核心的特点有四个。
第一,资料优先。 项目不是先做一个聊天界面再随意回答,而是先清洗本地资料,再围绕资料建立检索、引用和结构化字段。
第二,结构化和非结构化结合。 中医基础理论、诊断学等资料适合做主知识库检索;方剂、证候、经穴、针灸治疗则适合结构化入库。两者合在一起,问答和辨证才更稳。
第三,功能之间互相联通。 智能问答、辨证辅助、方剂查询、经络腧穴和关联审核不是孤立模块。它们通过证候、方剂、穴位和来源依据互相跳转,形成一个学习闭环。
第四,保留人工审核入口。 中医知识之间存在复杂映射,完全依赖自动关联容易出错。关联审核模块让系统既能自动发现关系,又能保留人工确认和证据追踪。
十六、当前完成状态
截至当前版本,项目已经完成:
-
前后端分离项目骨架。
-
登录、注册、短信验证码认证。
-
阿里云短信服务环境变量接入。
-
本地知识库清洗与入库。
-
智能问答与本地检索增强。
-
证候标准库检索与辨证辅助。
-
方剂库检索、详情和分类浏览。
-
证候-方剂关联检索与审核。
-
经络腧穴标准库检索与详情。
-
针灸治疗记录入库。
-
辨证结果到针灸治疗和标准穴位详情的联动。
-
前端工作台模块间跳转。
-
本地启动、健康检查、类型检查和构建验证。
现在,“扁小医”已经具备一个中医学习辅助软件的完整基础形态:用户可以输入问题或症状,系统基于本地资料给出依据,展示证候方向,关联方剂与针灸治疗,并进一步查看标准穴位定位。
这条链路完成后,项目不再只是一个资料查询页面,而是一个能把中医基础理论、辨证思路、方剂学习和经络腧穴学习串起来的辅助工作台。
更多推荐
所有评论(0)