企业官网建设流程全解析

最近在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.04，Python 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 常见问题排查表

最后分享一点我自己的使用心得

我最近在用一个比较“笨”但也比较有效的学法——把每天要读的章节丢进这个项目，强制自己在读完30分钟后做一套小测。以前我读完就以为自己会了，现在才知道“以为会了”跟“真会了”之间差距有多大。

出题模型偶尔会有把简单概念复杂化的情况，但瑕不掩瑜，这个项目最大的价值在于把“主动回忆”这个公认高效的学习方法，变成了一个低成本、可持续的工具。如果你对AI教育应用感兴趣，或者只是单纯想学得扎实一点，非常建议动手跑一下这个项目，最好再把出题模板改成适合自己学习习惯的版本。开源项目就是这样，拿到手只是开始，怎么让它为你所用才是真正有意思的部分。