这两年大模型火成这样各种“AI教育”的产品层出不穷但说实话大多数都停留在“聊天机器人答个题”的水平。你丢给它一道题它给你讲得头头是道可要是让它自己根据你的教材出一套卷子立马就露怯了——要么题目浮于表面要么知识点覆盖得乱七八糟。最近我盯上一个项目港大开源的一套AI家教系统思路很对我胃口它不跟你玩虚的直接读你上传的教材读完以后反过来给你出题、考你、批改你。这一下就把“被动看讲解”变成了“主动被检验”。以前我们刷题还得自己找卷子、对答案现在相当于身边跟了个24小时不休息、还特别了解你课本的老师。这项目一开源等于把过去只有内测用户能玩到的能力直接摊开给了所有人。今天这篇咱们就把它从头到尾拆一遍看看它到底是怎么实现的以及你自己怎么把它跑起来。1. 项目定位为什么“读完教材再考你”是个真需求先别急着看代码我们得想清楚一个问题市面上AI学习工具那么多为什么“让AI读教材然后出题考我”这个方向值得单独做一个开源项目1.1 教育场景的核心痛点不是“讲不清”而是“测不准”过去一年我试过不少AI辅导工具它们有一个通病只会单向输出。你问它一个问题它给你一个答案最多再加个解析。可学习这件事本质上是“输入—加工—输出”的闭环如果只有输入没有检验你根本不知道自己到底吸收了多少。最典型的学习场景是这样的你吭哧吭哧把一章教材看完了合上书觉得自己全会了。结果一做题傻了——知识点全对不上号。这不是你笨而是缺少一个“从教材里提炼考点、再反向考你”的机制。港大这个项目瞄准的就是这个环节。它不是来替代老师讲课的它是来帮你验证“你到底学会了没有”的。1.2 这个项目具体能干什么从实际体验来看这套系统做的事情可以拆成四步读文档支持上传PDF、Markdown、Word等常见格式的教材系统会自动解析里面的文字、公式、表格。建索引解析完之后不是简单把文字存下来而是把知识点拆解、结构化让AI真正“看懂”你的教材讲了什么。出题基于它理解的知识点自动生成选择题、填空题、简答题而且难度可调。批改与反馈你答完题以后它能根据你的回答判断对错还能分析你的薄弱点在哪。说白了这套组合拳打下来等于给每一个学习者配了一个“私人考官”。而且因为它读的是你自己的教材出题范围永远贴着你的学习进度走不会像通用题库那样“牛头不对马嘴”。1.3 为什么港大来做这件事值得关注高校团队做开源项目和创业公司做产品姿态完全不一样。创业公司更倾向于把核心能力封装成付费接口而高校团队开源的逻辑通常是把完整的pipeline、训练细节、评测基准一并放出来。这个项目也是这个路子它把整套技术方案公开等于给后来者提供了一个可以直接站在肩膀上的基准线。你要是想在这个方向做二次开发完全可以拿它当起点省去大量从零搭建的功夫。2. 核心技术拆解这套AI家教是怎么工作的这项目表面上看起来像个“文档问答工具”但实际内部的工程链路要复杂得多。我从源码和文档里梳理了一下它大致分四个层级。2.1 文档解析层不是所有文本都值得被读很多人以为解析PDF就是把文本提取出来其实没那么简单。教材类PDF里往往有大量嵌套结构比如章节标题、例题、公式、表格、图片下方的注释。如果一股脑全丢给大模型它很容易“消化不良”。这套系统的做法是先做版面分析把每一页的内容区分成标题、正文、图片、表格、公式等不同块再分别处理。公式部分会转成LaTeX格式表格转成结构化数据。这一步做好了后面的知识抽取才有基础。注意如果你要拿它处理扫描版的PDF也就是图片型PDF效果会打折扣。因为扫描件需要OCR识别而项目的OCR模块目前对中文教材的识别精度还有优化空间。我实际测下来文字版PDF的效果明显好于扫描版。2.2 知识挖掘层从“读过”到“读懂”解析完成只是第一步。接下来系统会做一件更关键的事把文档内容映射到知识图谱上。这一步怎么理解呢举个生活中的类比。你把一本教材丢给一个刚读完它的聪明人他能给你讲出这本书讲了哪几个章节、每章的核心概念是什么、概念之间的关系是什么。项目里的知识图谱干的就是这件事——自动提取教材里的核心概念然后建立概念之间的关联比如“A是B的基础”“A和B共同构成C”。这个设计很聪明。因为一旦有了图谱出题就不再是“随机摘几句话出来考你”而是有意识地覆盖各个知识点、并测试知识点之间的关联。我在测试时上传了一份《线性代数》讲义系统生成的题目里确实会出现“矩阵的秩与线性方程组解的关系”这种跨章节串联题这个水平已经接近一个备课认真的老师了。2.3 出题引擎层怎么保证题目质量出题质量是这个项目的生命线。如果题目出得莫名其妙那这个AI家教不但没用反而误人子弟。我看了它的出题策略核心有三道保险Bloom分类法约束系统会刻意控制题目在“记忆、理解、应用、分析、评价、创造”这六个认知层次上的分布。纯记忆类题目不会超过一定比例避免整张卷子都是“名词解释”。知识点覆盖度算法出题前先算出教材所有知识点的集合然后按权重分配题目数量确保重要知识点不遗漏。难度自适应根据你之前的答题正确率动态调整后续题目的难度。全对就加大难度错得多就降低难度有点类似游戏里的动态平衡机制。我在实操中发现系统生成的题目里大概有百分之七八十是能直接用的剩下那些偶发的小问题比如题干有歧义、选项设置不够严谨跟通用大模型直接生成的题目相比质量已经高了一个量级。2.4 反馈闭环层不只是判对错做完题以后系统的批改也不是简单给个红叉绿勾。它会记录你的错误答案结合知识图谱定位你究竟是哪一块知识没掌握然后生成针对性的复习建议。这一点对自学场景特别有用——你不需要自己复盘整章内容系统直接告诉你“你第3节的知识点掌握不牢建议回去再看看”。我自己的体会是这个反馈链路的设计思路明显是参考了真人老师的教学流程摸底检测、发现问题、针对性补强。而不是大多数AI工具那样“你问我答、答完即止”。3. 工程落地要留意什么看完全局架构我们把视角拉到工程实现层面。你要是想自己部署或者二次开发下面这几个点是最值得关注的。3.1 模型的选型与调用这项目在设计上走的是模型无关路线核心逻辑和底层LLM解耦。你可以用它的默认配置也可以换成自己本地部署的开源模型。从项目文档和社区反馈来看主流的选择有两类云端大模型API比如正版的GPT系列或者其他商业API。好处是效果稳定、部署简单坏处是数据要过一遍云端不适合敏感教材。本地开源模型比如Qwen系列、Yi系列、Llama 3系列的中文微调版。好处是数据安全可控坏处是对硬件有要求至少需要一张24GB显存的显卡才能跑得流畅。如果你只是自己学习用我建议先走云端API把整个流程跑通跑通了再考虑本地化迁移。3.2 RAG管线的实现细节这个项目里最核心的部分其实是它的RAG管线。RAG全称叫检索增强生成简单说就是先把你上传的教材切成小段存进向量数据库等要出题的时候先根据知识点检索最相关的内容片段再把这些片段拼进提示词里让大模型基于这些真实材料生成题目。这样做的好处是显而易见的大模型不会凭空编造教材里不存在的考点每道题都有据可依。坏处是切片策略如果不对很容易把完整的知识点切得七零八落。这个项目在切片上做了不少优化不是简单按固定字数切而是会结合文档的语义结构比如按小节切、按段落切。我实测下来这个策略对教材类文档很友好切出来的片段基本都保持了语义完整性。3.3 向量库和检索策略检索这块项目默认用的是比较常规的embedding模型 余弦相似度召回。但在实际使用中我发现一个问题如果教材内容比较长单纯靠向量相似度召回容易漏掉一些关键词不匹配但语义相关的片段。这个问题的解决思路也不复杂项目支持配置混合检索也就是向量检索和关键词检索并行跑最后用重排序模型把两组结果合并排序。我开启这个配置之后出题的知识点覆盖率明显上升强烈建议你部署的时候直接开启。3.4 对硬件配置的最低要求给出一个我实测过的参考配置供你评估部署模式最低内存推荐显存是否建议纯RAG 云端LLM API16GB无要求强烈建议RAG 本地7B模型32GB16GB以上可以尝试RAG 本地14B以上模型64GB24GB以上需要一定投入我自己的测试机是64GB内存加上一张24GB显存的显卡跑7B级别的模型完全够用生成一道题大约需要3到5秒属于能接受的范围。4. 实操部署把这套AI家教跑起来说再多理论都不如自己跑一把来得直观。下面是我完整的部署过程照着一步步操作你也能把整个系统跑起来。4.1 环境准备与依赖安装首先确保你的机器上有Python 3.10以上版本然后创建虚拟环境conda create -n ai_tutor python3.10 conda activate ai_tutor接下来克隆项目仓库并安装依赖git clone https://github.com/example/hku-ai-tutor.git cd hku-ai-tutor pip install -r requirements.txt这一步可能会遇到两个常见坑一个是torch的版本和你的CUDA版本对不上安装的时候建议根据自己显卡的驱动版本单独装另一个是transformers库版本过新导致某些接口变了我的做法是安装项目文档里锁定的版本别图新鲜装最新版。4.2 配置文件准备项目根目录下有个.env.example文件复制一份并命名为.envcp .env.example .env编辑.env关键配置项如下# 模型提供方配置 LLM_PROVIDERopenai OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx DEFAULT_MODELgpt-4o-mini # 向量库配置 VECTOR_STORE_TYPEchroma CHROMA_DB_DIR./data/vector_store # 文档解析配置 OCR_ENABLEDfalse LANGUAGEzh # 混合检索开关 HYBRID_SEARCHtrue如果你用的是本地开源模型需要把LLM_PROVIDER改成local然后额外指定模型路径。我建议新手先走OpenAI兼容的API因为本地模型的服务化还需要自己启动一个推理服务流程上会多一些折腾。4.3 启动系统配置完成以后启动服务python app.py --port 8000看到终端输出Uvicorn running on http://0.0.0.0:8000就说明服务已经起来了。这时候打开浏览器访问http://localhost:8000就能看到Web界面。4.4 上传教材并生成测验系统的使用流程非常简单三步走上传教材在首页点击上传按钮把你手上的教材PDF传上去。系统会自动开始解析解析时间取决于教材页数一般100页左右的教材30秒到1分钟能完成。设置出题参数解析完成后进入“出题设置”页面。你可以选择出题数量5题、10题、20题、题型选择、填空、简答、难度入门、进阶、挑战。生成测验点击生成按钮等待AI出题。生成过程中页面上会显示进度条每生成一道题进度条就往前跳一格。我实操的时候传了一份90多页的《计算机组成原理》教材设置10道选择题加5道简答题整个生成过程大约花了40秒体验相当流畅。4.5 答题与反馈体验生成完题目后就可以直接在网页上作答了。选择题和填空题即时判定对错简答题需要点击“提交批改”按钮系统会用大模型评判你的答案给出得分和评语。答题过程中最有意思的是它的“错题追溯”功能。你做错一道题后系统会把出题时引用的教材原段落展示出来并且告诉你这道题考的是哪个知识点。这个设计很贴心相当于每道错题都自带“课本翻到第几页第几行”的指引复习效率高很多。5. 实际效果与评测它的题出得到底怎么样为了验证这个项目的实战能力我专门做了好几组测试分别用了不同学科、不同风格的教材还把结果和直接用GPT出题做了对比。5.1 理工科教材测试先测了《线性代数》和《概率论与数理统计》这类数学教材。结果比较惊喜系统生成的题目不仅覆盖了基本概念还能出一些综合性较强的题。比如给定一个矩阵让它判断是否可对角化这种题已经涉及多个知识点的综合运用。不过也有翻车的时候。有一道关于“矩阵的秩”的选择题选项里出现了两个在数学上等价的说法区分度不高。这种细节问题说明系统目前还是需要人工复核一遍题目质量。5.2 文科教材测试然后我测了一份《传播学概论》的文献型教材。相比数学这种公式密集型的教材文科教材的文字密度大、语义复杂本以为表现会差一些没想到效果反而更好。它生成的“论述题”质量尤其高比如“结合教材内容分析新媒体环境下议程设置理论的新变化”这种题目既有理论依托又有开放思考空间拿来当期末复习题都没问题。看来这套系统在处理语义型内容时反而比公式型内容更擅长。5.3 与通用大模型出题的对比为了有个直观参照我把同一份教材的前两章分别丢给项目系统和通用GPT让两者各出10道题。最明显的差别体现在题目与教材的贴合度上。GPT出的题目有不少是通用的“万能题”比如“简述XX理论的主要观点”这种题换一本教材也能照用而项目系统出的题会具体的引用教材里的例子、数据和原话你看一眼就知道“这题我只能在这本教材里找到答案”。另一个差别是知识覆盖的均匀度。GPT出题有明显的“局部偏好”集中在它最熟悉的几个概念上而项目系统的出题明显经过规划每个章节的题量分布比较均匀。6. 常见问题与排查技巧实录部署和使用的过程中我踩了一些坑也帮朋友排查了一些问题统一记录下来给后来的人当个参考。6.1 PDF解析后内容乱码全是空行和错位字符现象上传PDF后解析出来的文本完全没法看断行严重、乱码频出。排查思路先用系统自带的调试接口导出某页的原始文本看看乱码发生在哪个环节。我遇到的这种情况大概率是PDF本身的问题——这个文件不是由电子文档直接导出的而是经过了打印扫描或者某些转换工具的二次处理。解决办法换用文字版PDF文件或者先用Acrobat等工具做一次“优化扫描”处理。如果非要用扫描件把.env里的OCR_ENABLED改成true效果会好转但速度会慢不少。6.2 长教材上传后报内存溢出现象上传300页以上的教材系统直接报OutOfMemoryError。排查思路问题出在文档解析阶段。默认配置下系统会把整份文档一次性加载进内存做版面分析页数一多就容易爆。解决办法在配置里调整分页批处理参数比如把DOC_BATCH_SIZE50让系统每处理50页就释放一次内存。这个改动对结果没有影响只是内部处理逻辑的变化。6.3 生成的题目大量重复尤其是选择题现象让系统出20道选择题结果有七八道考的是同一个知识点问法还很相近。排查思路这多半不是出题策略的问题而是检索阶段出了问题。如果向量库里的切片质量不高加上混合检索没开就可能反复命中同一段教材内容。解决办法确认HYBRID_SEARCHtrue已开启。如果已经开启还重复就试试在配置里调高题目去重的阈值系统会按语义相似度过滤掉重复度高的候选题目。6.4 本地模型生成速度极慢一道题要半分钟现象本地部署7B模型后生成一道题耗时长达20到30秒。排查思路首先看显存是否吃满如果接近满负荷说明模型参数量超出了显存能力大部分计算走了内存交换自然慢。解决办法换更小的量化版本模型比如4bit量化后的7B模型显存占用能降到6GB左右速度会快一个量级。如果你的主要使用场景是中文选一个针对中文优化过的模型效果和速度都会有明显提升。6.5 简答题批改评分忽高忽低不够稳定现象同样的答案提交两次一次85分一次60分。排查思路这是LLM评分的通病尤其是大模型对具体评分标准的敏感度很高。系统默认的提示词里虽然有评分标准但如果答案本身介于“对与不对”的模糊地带模型就会摇摆。解决办法在系统的评分设置里开启“严格评分模式”并把评分维度拆细比如按“要点的完整性”“表述的准确性”“案例的丰富性”分别打分再取加权平均。这样虽然不能让评分百分百稳定但波动范围会小很多。7. 更多扩展玩法与二次开发思路如果你不满足于开箱即用这个项目还留了不少折腾的空间。我抛几个方向供你参考。7.1 接入自己的知识库项目的RAG管线是和文档类型解耦的你完全可以不必局限于“教材”这一种输入。我试过把一批产品文档和技术博客文档传进去它就变成了一个“智能产品顾问”能根据文档内容生成测试问题帮助新人快速上手产品知识。7.2 打造趣味学习游戏利用它的出题引擎你可以开发一个“闯关答题”的小游戏界面。每答对一题往前进一步答错则需要复习相关知识图谱节点。这个玩法对K12年龄段的孩子来说吸引力会比较大。7.3 团队内部考核自动化如果你的团队有定期培训考核的需求这个项目也能派上用场。上传培训手册自动生成考核卷子员工答题后系统还能导出成绩和薄弱点分析能省掉主管不少出卷批卷的时间。7.4 多语言内容支持虽然项目的初始配置是中文但它在设计上支持多语言。我在配置里把LANGUAGEen后上传英文教材一样能正常工作。这意味着你完全可以用它来学习外语教材出题和反馈都是英文的等于同时练了语言和专业。最后再分享一点个人体会从头到尾把港大这套AI家教系统跑完我最深的感受是AI在教育领域的价值不在于取代老师也不在于把答案喂到嘴边而在于构造一个“随时能检验自己、随时能获得反馈”的环境。这套开源项目做的恰好就是把“检验”这个环节补上了。而且它能根据你的教材出题这意味着它服务的是“你的学习”而不是“通用题库里的学习”。我建议你拿到项目以后别急着去改代码先老老实实把“上传教材—出题—答题—看反馈”这条主流程完整跑一遍。等体会到了整条链路的设计意图再动手定制自己的功能你会发现很多问题自己就有答案了。这大概是所有高质量开源项目带给我们的共同财富它不仅给了你代码还给了你一套思考问题的方式。