企业官网建设流程全解析

这两年大模型火成这样，各种“AI+教育”的产品层出不穷，但说实话，大多数都停留在“聊天机器人答个题”的水平。你丢给它一道题，它给你讲得头头是道，可要是让它自己根据你的教材出一套卷子，立马就露怯了——要么题目浮于表面，要么知识点覆盖得乱七八糟。

最近我盯上一个项目，港大开源的一套AI家教系统，思路很对我胃口：它不跟你玩虚的，直接读你上传的教材，读完以后反过来给你出题、考你、批改你。这一下就把“被动看讲解”变成了“主动被检验”。以前我们刷题还得自己找卷子、对答案，现在相当于身边跟了个24小时不休息、还特别了解你课本的老师。这项目一开源，等于把过去只有内测用户能玩到的能力，直接摊开给了所有人。今天这篇，咱们就把它从头到尾拆一遍，看看它到底是怎么实现的，以及你自己怎么把它跑起来。

1. 项目定位：为什么“读完教材再考你”是个真需求

先别急着看代码，我们得想清楚一个问题：市面上AI学习工具那么多，为什么“让AI读教材然后出题考我”这个方向，值得单独做一个开源项目？

1.1 教育场景的核心痛点，不是“讲不清”而是“测不准”

过去一年我试过不少AI辅导工具，它们有一个通病：只会单向输出。你问它一个问题，它给你一个答案，最多再加个解析。可学习这件事，本质上是“输入—加工—输出”的闭环，如果只有输入没有检验，你根本不知道自己到底吸收了多少。

最典型的学习场景是这样的：你吭哧吭哧把一章教材看完了，合上书，觉得自己全会了。结果一做题，傻了——知识点全对不上号。这不是你笨，而是缺少一个“从教材里提炼考点、再反向考你”的机制。港大这个项目，瞄准的就是这个环节。它不是来替代老师讲课的，它是来帮你验证“你到底学会了没有”的。

1.2 这个项目具体能干什么

从实际体验来看，这套系统做的事情可以拆成四步：

1. 读文档：支持上传PDF、Markdown、Word等常见格式的教材，系统会自动解析里面的文字、公式、表格。
2. 建索引：解析完之后，不是简单把文字存下来，而是把知识点拆解、结构化，让AI真正“看懂”你的教材讲了什么。
3. 出题：基于它理解的知识点，自动生成选择题、填空题、简答题，而且难度可调。
4. 批改与反馈：你答完题以后，它能根据你的回答判断对错，还能分析你的薄弱点在哪。

说白了，这套组合拳打下来，等于给每一个学习者配了一个“私人考官”。而且因为它读的是你自己的教材，出题范围永远贴着你的学习进度走，不会像通用题库那样“牛头不对马嘴”。

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 对硬件配置的最低要求

给出一个我实测过的参考配置，供你评估：

我自己的测试机是64GB内存加上一张24GB显存的显卡，跑7B级别的模型完全够用，生成一道题大约需要3到5秒，属于能接受的范围。

4. 实操部署：把这套AI家教跑起来

说再多理论，都不如自己跑一把来得直观。下面是我完整的部署过程，照着一步步操作，你也能把整个系统跑起来。

4.1 环境准备与依赖安装

首先确保你的机器上有Python 3.10以上版本，然后创建虚拟环境：

conda create -n ai_tutor python=3.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文件，复制一份并命名为.env：

cp .env.example .env

编辑.env，关键配置项如下：

# 模型提供方配置 LLM_PROVIDER=openai OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx DEFAULT_MODEL=gpt-4o-mini # 向量库配置 VECTOR_STORE_TYPE=chroma CHROMA_DB_DIR=./data/vector_store # 文档解析配置 OCR_ENABLED=false LANGUAGE=zh # 混合检索开关 HYBRID_SEARCH=true

如果你用的是本地开源模型，需要把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 上传教材并生成测验

系统的使用流程非常简单，三步走：

1. 上传教材：在首页点击上传按钮，把你手上的教材PDF传上去。系统会自动开始解析，解析时间取决于教材页数，一般100页左右的教材，30秒到1分钟能完成。
2. 设置出题参数：解析完成后，进入“出题设置”页面。你可以选择出题数量（5题、10题、20题）、题型（选择、填空、简答）、难度（入门、进阶、挑战）。
3. 生成测验：点击生成按钮，等待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_SIZE=50，让系统每处理50页就释放一次内存。这个改动对结果没有影响，只是内部处理逻辑的变化。

6.3 生成的题目大量重复，尤其是选择题

现象：让系统出20道选择题，结果有七八道考的是同一个知识点，问法还很相近。

排查思路：这多半不是出题策略的问题，而是检索阶段出了问题。如果向量库里的切片质量不高，加上混合检索没开，就可能反复命中同一段教材内容。

解决办法：确认HYBRID_SEARCH=true已开启。如果已经开启还重复，就试试在配置里调高题目去重的阈值，系统会按语义相似度过滤掉重复度高的候选题目。

6.4 本地模型生成速度极慢，一道题要半分钟

现象：本地部署7B模型后，生成一道题耗时长达20到30秒。

排查思路：首先看显存是否吃满，如果接近满负荷，说明模型参数量超出了显存能力，大部分计算走了内存交换，自然慢。

解决办法：换更小的量化版本模型，比如4bit量化后的7B模型，显存占用能降到6GB左右，速度会快一个量级。如果你的主要使用场景是中文，选一个针对中文优化过的模型，效果和速度都会有明显提升。

6.5 简答题批改评分忽高忽低，不够稳定

现象：同样的答案提交两次，一次85分一次60分。

排查思路：这是LLM评分的通病，尤其是大模型对具体评分标准的敏感度很高。系统默认的提示词里虽然有评分标准，但如果答案本身介于“对与不对”的模糊地带，模型就会摇摆。

解决办法：在系统的评分设置里，开启“严格评分模式”，并把评分维度拆细，比如按“要点的完整性”“表述的准确性”“案例的丰富性”分别打分，再取加权平均。这样虽然不能让评分百分百稳定，但波动范围会小很多。

7. 更多扩展玩法与二次开发思路

如果你不满足于开箱即用，这个项目还留了不少折腾的空间。我抛几个方向供你参考。

7.1 接入自己的知识库

项目的RAG管线是和文档类型解耦的，你完全可以不必局限于“教材”这一种输入。我试过把一批产品文档和技术博客文档传进去，它就变成了一个“智能产品顾问”，能根据文档内容生成测试问题，帮助新人快速上手产品知识。

7.2 打造趣味学习游戏

利用它的出题引擎，你可以开发一个“闯关答题”的小游戏界面。每答对一题往前进一步，答错则需要复习相关知识图谱节点。这个玩法对K12年龄段的孩子来说，吸引力会比较大。

7.3 团队内部考核自动化

如果你的团队有定期培训考核的需求，这个项目也能派上用场。上传培训手册，自动生成考核卷子，员工答题后系统还能导出成绩和薄弱点分析，能省掉主管不少出卷批卷的时间。

7.4 多语言内容支持

虽然项目的初始配置是中文，但它在设计上支持多语言。我在配置里把LANGUAGE=en后，上传英文教材一样能正常工作。这意味着你完全可以用它来学习外语教材，出题和反馈都是英文的，等于同时练了语言和专业。

最后再分享一点个人体会

从头到尾把港大这套AI家教系统跑完，我最深的感受是：AI在教育领域的价值，不在于取代老师，也不在于把答案喂到嘴边，而在于构造一个“随时能检验自己、随时能获得反馈”的环境。这套开源项目做的，恰好就是把“检验”这个环节补上了。而且它能根据你的教材出题，这意味着它服务的是“你的学习”，而不是“通用题库里的学习”。

我建议你拿到项目以后，别急着去改代码，先老老实实把“上传教材—出题—答题—看反馈”这条主流程完整跑一遍。等体会到了整条链路的设计意图，再动手定制自己的功能，你会发现很多问题自己就有答案了。这大概是所有高质量开源项目带给我们的共同财富：它不仅给了你代码，还给了你一套思考问题的方式。