最近在GitHub上闲逛被一个来自港大的开源项目吸引了——他们把一个“AI家教”整套开源了。这玩意儿不是那种只能回答问题的聊天机器人它最狠的地方在于你丢给它一本教材不管是PDF还是Markdown还是别的格式它会先把内容读一遍然后反过来给你出题、考你、批改最后告诉你哪儿没学会。这个思路一下就戳中我了。绝大多数人学习低效不是因为不够努力而是因为没有“反馈闭环”。看完书翻过去就忘了不知道哪些记住了、哪些理解歪了。这个项目直接把这个痛点给工具化、自动化了。我把代码拉下来实测了两天跑了几个不同格式的教材感觉确实值得写一篇详细的拆解。今天就从项目思路、技术原理到部署实操、进阶玩法一次性讲清楚。1. 这个AI家教做了什么为什么值得关注1.1 一句话说清楚它的核心能力先给个最直白的定义这是一个“输入教材 → 自动出题 → 自动批改 → 输出学习报告”的开源项目。它把过去只有在付费教育产品里才有的“个性化练习闭环”用一套本地化部署的大模型技术栈给复刻了。整个使用流程是这样的你上传一份文档比如一本电子教材、课程讲义、笔记整理的Markdown文件。程序会把文档解析成纯文本然后按语义拆分成知识片段。每个片段被向量化后存入本地向量数据库。出题模块根据向量检索到的内容调用大模型生成选择题、填空题、简答题。你在线作答后批改模块自动判分并给出题目解析和答题点评。最后生成一份学习报告里面包含正确率、薄弱知识点提示、回顾建议。这和传统的刷题软件有本质区别。传统刷题是题库里本来就有题不管你看没看题目都一样。而这个项目是“因材施教”的——你用哪本教材它就围绕哪本教材出题教材内容不同题目就完全不同。教材里重点讲过的细节会被反复抽出来考你而那些一笔带过的内容题目占比也会明显少很多。1.2 我对这个项目的直观判断第一眼看到仓库结构的时候我的反应是“这不像一个学生练手项目”。它内部模块划分得非常清楚文档解析、文本切分、向量化、题目生成、自动批改、前端界面每个模块都有独立的逻辑不是一坨代码塞在一起。说明作者在设计阶段就想清楚了边界这也是我能放心推荐给别人用的原因。从技术选型看它没有硬上复杂架构。后端用Python做服务借助LangChain做流程编排向量库用Chroma这种嵌入式数据库不需要另起一个服务前端用Gradio快速搭建几秒钟就能看到效果。整套方案对部署环境的要求很低有台普通配置的电脑就能跑。这也是“开源项目”最应该有的样子——不炫技把该做的事做好。1.3 适合哪些人用解决什么问题我觉得下面这几类人特别适合关注这个项目自学者自学的最大问题是没有人来考察你的掌握程度这个项目可以充当一个“不知疲倦的考官”。教育行业开发者和产品经理项目提供了完整的代码参考如果你想做一个AI教育产品可以直接复用它的流程设计。备考人群不管是考研、考证还是专业考试只要你有电子版教材就可以用它生成模拟练习题比到处找题刷省力得多。对RAG检索增强生成技术感兴趣的人它是RAG在真实场景下一个非常典型的落地案例学一遍这个项目比看很多抽象教程都有帮助。一句话解决了“如何低成本地验证自己的学习成果”这件事。2. 技术原理拆解它怎么做到“读懂”教材2.1 文档解析与知识抽取这个项目实现的第一件事就是把杂乱的文档转成干净、可用的纯文本。这一步看着简单实际上一本书能不能被有效出题就看这里解析得好不好。项目里对不同文档格式分别做了处理。对纯文本文件和Markdown文件直接读对PDF和Word文档先调用文档解析库抽取文本内容。这里有一个非常关键的设计细节解析完成后程序会按文档的标题层级和段落结构给每个文本块打上“来源标记”。比如一句话是从第3章第2节抽出来的那这句话在生成题目时会被优先跟这一章节的主题绑定。这样做的好处是出题时能保证题目和特定知识点的强相关性考完你也能清楚知道错题对应的章节位置。2.2 RAG不是微调为什么选检索增强生成很多人可能会问为什么不直接拿教材微调一个模型我的看法是在这个场景下微调是一个非常“不划算”的做法。原因是多方面的。微调一个大模型需要足够数量的高质量问答对作为训练数据而你的原始输入可能只是一本几百页的PDF教材还可能随时更新每次更新都要重新训练成本高得离谱。更重要的是微调之后模型学到的是“知识内容”但它并不会告诉你哪道题对应书里的哪一页这对学习者来说其实是很大的损失。这个项目采用的是RAG路线。先把教材切分成一个个文本片段预先做好向量化出题时根据用户设定的知识点范围先从向量库里检索出最相关的教材片段再把这些片段和出题提示词一起交给大模型。这样模型“照着原文出题”生成的题目不仅准确而且能追溯出处。2.3 出题引擎的Prompt设计出题逻辑是这个项目的核心也是我最欣赏的部分。它把出题分成了三种题型每一类用的Prompt策略都不同。选择题生成的时候它要求模型严格依据给定的教材片段先写题干再写正确选项然后另外生成三个“足够迷惑人”的干扰选项。我在实测中发现干扰项质量比正确选项质量更能决定一张卷子的好坏如果干扰项太蠢考试就变成了“排除法游戏”失去考察意义。作者显然知道这一点所以在干扰项生成的指令里做了特别约束要求干扰项必须基于同一个知识点下的常见误解来设计。填空题则要求模型提取片段中的关键概念或术语作为答案并把答案用占位符替换。这里有个小细节生成的填空题答案默认强制要求原文中必须原词出现过避免模型擅自改写术语导致答案对不上。简答题是最复杂的。它不仅要生成问题还要生成“参考答案要点”供后续批改作为评判依据。实测中这部分Prompt写得比较稳生成的问题不会太空泛基本都落在“解释概念、比较异同、推导过程”这几类。2.4 自动批改逻辑批改模块混合了两种策略。选择题和填空题直接比对答案零成本零延迟这没什么好说的。简答题采用了“关键词匹配模型语义判断”的混合方式。程序先提取参考答案里的关键知识点作为关键词列表你的回答里命中越多的关键词基础分越高然后模型再对“回答是否逻辑自洽”做一个语义层面的判断给一个附加分。两种分数加权后再映射到百分制。我在测试时发现了一个细节如果是用本地小模型来完成批改语义判断部分的可靠性会有些波动换成能力更强的GPT模型或者Claude时批改点评质量会明显提升。这个设计思路很值得借鉴——用关键词命中兜底用语义判断加分。既不会因为模型偶尔抽风把全对的答案判错也不会纵容那种“只踩关键词、逻辑不通”的答案拿满分。3. 从拉代码到跑起来完整实操记录3.1 环境准备与依赖安装我实测的环境是Ubuntu 22.04Python 3.10一张8GB显存的显卡内存16GB。如果只是跑默认的模型短时间内不想研究训练、微调实际上不需要太好的显卡CPU也能跑不过速度会慢一些。先把项目克隆到本地然后创建独立的虚拟环境。这一步千万别偷懒别图省事直接装到系统Python里后面依赖冲突会折腾死你。git clone https://github.com/hku-ai-tutor/ai-tutor.git cd ai-tutor python3 -m venv venv source venv/bin/activate pip install -r requirements.txt依赖列表里有几个比较大的包比如torch、langchain、chromadb安装时间跟你的网速和机器性能成正比。建议使用国内镜像源加速能节省非常多的时间。pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple装完后跑一下验证命令确认核心依赖都没有问题再继续。3.2 配置文件详解项目根目录下有一个.env.example文件复制一份改成.env里面有几个关键配置项需要按自己的情况来填。第一个是模型接口配置。默认走OpenAI兼容接口你需要填入API密钥和基础地址。如果你用的是代理或者中转服务这里对应的就是中转地址如果你打算本地部署离线模型这里就填你本地服务的地址。第二个是向量库路径。默认使用一个本地的目录来存放索引文件比如./data/chroma_store如果你想换位置直接改这个配置就行。第三个是语言环境。项目支持中文和英文两种出题语言在配置里可以切换。实测下来中文出题的效果相当不错没有早期那些开源项目常见的“中文一问、英文一答”尴尬情况。3.3 启动与首次使用一切配置就绪后一行命令启动python app.py启动完成后终端会输出一个本地地址比如http://127.0.0.1:7860。用浏览器打开就能看到主界面。界面分为三个区域左侧是知识库管理负责上传和查看教材中间是出题配置区选择题型、题目数量、出题范围右侧是答题区和学习报告展示区。我把手上一本200多页的Python编程书籍PDF传了上去大概等了不到10秒钟页面提示知识库构建完成。从日志来看那一本书被切分成了700多个文本片段向量化索引也自动建好了。之后我选择“随机出10道选择题、5道填空题、2道简答题”点击生成大约过了30秒页面左侧就能看到完整的试卷了。整个过程不需要写一行代码小白也能顺利操作。3.4 核心参数调优建议项目里有些参数默认值是可用的但如果你细心调一下出题质量有明显差别。文本切分的chunk_size默认值是800个字符。如果教材内容偏概念性、前后依赖强建议把chunk_size调大到1000左右如果是技术手册这种一个知识点相对独立的800到600会更合适。过小的chunk会导致一个完整概念被切断生成题目时上下文不全模型容易出“不明白想问什么”的题。温度参数temperature对出题影响很大。选择题建议保持低温度比如0.2到0.3保证题目稳定、答案准确简答题可以提高一些我实测在0.6到0.7之间效果最好生成的题目会更有灵活性而不是像从原文里摘抄一样死板。top_k参数控制检索片段数。默认是5意思是出每道题会参考教材里检索到的5个最相关的片段。这个数值不建议太小否则出题范围太窄题目之间容易重复也不建议太大你不想让一道选择题的内容被上下文干扰。4. 三种进阶玩法把它变成自己的学习系统4.1 用本地离线模型替换默认模型很多人在意数据隐私不愿意把教材内容传到第三方API。这个项目本来就支持OpenAI兼容接口所以接本地开源模型的成本极低。我测试用的是Ollama启动的Qwen2.5模型几行命令就能完成。ollama pull qwen2.5:14b ollama serve然后回到.env配置文件把模型接口地址改成Ollama的默认地址http://localhost:11434/v1模型名称改成qwen2.5:14b重启服务就可以了。整套操作的原理就是程序只认OpenAI接口协议本地服务实现了同样的协议二者对接毫无障碍。实测下来用14B的量化模型生成一道选择题大概需要5到8秒速度可以接受。出题质量方面常识性题目和概念性题目都在线但遇到某些特别专业的垂直领域术语答案准确性会比商用模型弱一些。这个问题的本质是模型本身的知识覆盖面差异不是项目代码的问题。4.2 定制出题风格与考试模式如果你觉得默认的“随机出题”不够劲项目还留了自定义参数的接口。在出题配置里可以设置出题范围比如“指定只看第2章和第5章”也可以设置难度偏好。更进阶的玩法是修改内置的提示词模板文件。项目把每类题型的Prompt模板都单独放在prompts/目录下你可以直接改这些文本文件强行让模型按你的风格出题。我试过把简答题的模板改成“用苏格拉底式提问引导思考”生成的题目风格确实会变化明显从“请解释什么是闭包”变成了“如果一个函数内部定义的变量在外部无法访问这背后是什么机制在起作用”。这种可玩性远超固定题库的软件本质上你面对的是一个能灵活变化出题策略的个性化考官。另外自己做一个定时测试模式也很容易。用浏览器插件或者系统级定时任务每天早上自动触发出题接口生成一份10道题的小测做完自动记录结果。坚持两周你的学习节奏会变得非常规律。4.3 从单教材到个人知识库的扩展项目的知识库支持多份文档同时导入这就意味着你可以不局限于单本教材。把课程讲义、课堂笔记、实验报告和参考书籍一起导入构建一个属于你自己的知识库。出题时系统会在整个知识库里检索与题目最相关的片段考到的知识点覆盖范围会更全面。我还做了一件事在每次出题测试后把生成的学习报告作为新的知识片段导回到知识库里形成一种“在学习记录上再考核”的效果。相当于给自己建立了一个成长档案过一段时间你回头看能看到自己知识漏洞在逐步消失。这种时间线式的学习记录普通刷题软件完全给不到。对于做教育产品或在线课程的人这个功能可以直接用起来。把课程的全部材料加载进去然后给学生生成个人定制的练习。课程更新也不用额外维护题库只要更新知识库内容出题逻辑自动跟着走。5. 踩坑记录与常见问题速查5.1 我踩过的三个坑第一个坑是扫描版PDF。我试过一本从网上下载的旧教材页面显示正常但解析出来的文本全是空行和乱码。这是典型的扫描版PDF需要先做OCR识别之后再导入。项目本身没有集成OCR功能解决办法是先用第三方工具转成可检索的PDF再把处理后的文件导入。第二个坑是切分参数和代码块的关系。我在导入一本Markdown格式的机器学习讲义时很多代码块里的函数被切断成了两半导致后面的出题经常问出“这个函数的功能是____”但答案字段是个残段。后来把chunk_size调大并关闭了跨代码块的切分问题才解决。如果你导出的文档含大量代码记得注意这块。第三个坑是向量库的版本冲突。之前我电脑上拿pip install chromadb装了一个更高版本的向量库结果启动服务时提示索引文件版本不兼容。最后我把项目目录下的data/chroma_store整个删掉重新构建索引才恢复正常。如果是更新版本后启动报错优先考虑清空重建索引。5.2 常见问题排查表问题现象可能原因排查与解决方法上传PDF后解析为空扫描版PDF无文字层先用OCR工具处理PDF再重新上传生成题目速度很慢网络接口延迟或本地模型推理慢检查接口响应时间本地模型考虑换更小的量化版本中文教材生成的题目有英文混杂提示词语言设置未切换在配置文件中将语言参数改成中文重启服务简答题批改分数异常模型语义判断波动调低语义判断权重检查参考答案要点提取是否完整向量库无法读取索引版本不一致备份已有教材文件后清空本地索引目录重建同时导入大量文档时报内存不足文档过大或机器内存有限一次导入一部分按章节拆分成多个文档调大系统Swap最后分享一点我自己的使用心得我最近在用一个比较“笨”但也比较有效的学法——把每天要读的章节丢进这个项目强制自己在读完30分钟后做一套小测。以前我读完就以为自己会了现在才知道“以为会了”跟“真会了”之间差距有多大。出题模型偶尔会有把简单概念复杂化的情况但瑕不掩瑜这个项目最大的价值在于把“主动回忆”这个公认高效的学习方法变成了一个低成本、可持续的工具。如果你对AI教育应用感兴趣或者只是单纯想学得扎实一点非常建议动手跑一下这个项目最好再把出题模板改成适合自己学习习惯的版本。开源项目就是这样拿到手只是开始怎么让它为你所用才是真正有意思的部分。
