各位 CSDN 的朋友们，大家好。
之前在调研开源学习类项目时，偶然发现了香港大学团队开源的一款 AI 学习系统。它最吸引我的地方不是简单的“AI 问答 + 资料库”，而是设计了一套基于原生 Agent 架构的个性化学习闭环，把知识库、错题集、学习节奏预测这些概念真正串了起来。网上关于这个项目的介绍大多是功能和新闻层面的宣传，缺少从技术实现角度展开的拆解。本文将围绕该项目，梳理 Agent 架构下的学习系统设计思路，给出本地部署、知识库构建与个性化学习配置的完整教程，并分析常见的工程坑点与二次开发方向。
无论你是想做教育类 AI 产品，还是想在个人知识库项目中引入 Agent 机制，这篇文章都值得收藏备用。
1. 港大 AI 学习系统解决的是什么问题？
在进入技术细节之前，先明确这个项目的定位：它是一套面向个性化学习的 AI 系统，核心目标不是“给你一个能聊天的模型”，而是“构建一个能伴随你持续成长的学习引擎”。
1.1 传统 AI 问答在学习场景中的不足
现在很多学习工具都接入了大模型，但你实际用下来会发现几个问题：
- 回答内容泛化，无法针对你的薄弱点调整讲解方式。
- 同样的内容反复推荐，没有记忆，更谈不上温故知新。
- 不会主动发现你哪里没掌握，只能被动回答问题。
- 缺少长期跟踪机制，无法形成真正的错题成长曲线。
这些问题说明了一个事实：仅有大模型是不够的，必须用 Agent 架构把记忆、复习、测试、反馈这些环节连接起来。
1.2 Agent 架构如何改变学习流程
Agent 架构的核心在于“自主决策”和“工具调用”。放在学习系统中，它的作用可以这样理解：
- Agent 不是直接输出答案，而是先分析你的知识状态。
- Agent 可以根据需要调用知识库检索、错题记录、题目生成等工具。
- Agent 能够基于历史交互数据动态调整学习计划。
换句话说，传统问答是“单轮生成”，而 Agent 学习系统是“多轮规划 + 执行 + 反思”。
港大开源的这个项目，正是把这一整套机制以工程化方式落地。它开源的意义在于：你不仅可以部署一套学习系统，还能读懂并修改里面 Agent 的实现逻辑，甚至把它迁移到自己的业务场景中。
1.3 适合谁学习和使用
从使用和二次开发两个角度，这个系统适合以下人群：
- 学习者：想用 AI 建立个性化错题集和知识库，提升复习效率。
- AI 开发者：想研究 Agent 架构在教育场景的落地方式。
- 教育产品团队：想基于开源项目快速搭建 MVP，验证产品逻辑。
- 知识管理爱好者：需要一套能自动关联、沉淀、复盘的知识库机制。
2. 环境准备与项目部署
项目本身的部署过程并不复杂，但需要注意的是，它依赖的组件比较多，尤其是向量数据库和模型服务。不同环境下，版本差异会带来不少问题，所以本文会按“基础环境 → 依赖组件 → 项目配置”的顺序说明。
2.1 软硬件环境要求
建议的部署环境如下：
| 组件 | 说明 |
|---|---|
| 操作系统 | Linux（Ubuntu 20.04 及以上）、macOS、Windows WSL2 |
| CPU | 4 核及以上 |
| 内存 | 16 GB 及以上（包含向量数据库与模型推理） |
| Python | 3.10 及以上 |
| Node.js | 18 及以上（如果前端需要单独构建） |
| 数据库 | PostgreSQL + pgvector 或 SQLite + 向量扩展 |
| 模型服务 | OpenAI 兼容接口或本地推理服务（如 vLLM、Ollama） |
如果你的机器只有 8 GB 内存，建议不要本地加载大模型，而是使用外部 API 兼容服务，避免 OOM。
2.2 获取项目源码
由于项目名称可能随版本调整，建议在 GitHub 搜索 “HKU AI Learning System” 或相关关键词，以官方仓库地址为准。克隆命令如下：
git clone https://github.com/[官方仓库地址].git cd ai-learning-system注意：不同分支的依赖差异较大。如果项目有 main 和 dev 分支，建议优先 clone main 分支。
2.3 后端环境配置
创建虚拟环境并安装依赖：
python -m venv venv source venv/bin/activate # Windows 下使用 venv\Scripts\activate pip install -r requirements.txt依赖安装过程中常见的问题是pydantic与langchain版本不兼容。如果你遇到类似报错，可以尝试固定版本：
pip install "pydantic==2.7.4" "langchain==0.2.11"这里给你一个最小可用的requirements.txt参考：
fastapi==0.111.0 uvicorn[standard]==0.30.1 sqlalchemy==2.0.30 pydantic==2.7.4 langchain==0.2.11 langchain-openai==0.1.22 pgvector==0.3.5 psycopg2-binary==2.9.9 python-dotenv==1.0.1注意：以上版本号是本文写作时的常见组合，实际安装时以项目 requirements.txt 为准。不要盲目固定版本，应根据项目测试结果调整。
2.4 前端环境配置
如果项目包含前端页面，则需要进入前端目录安装依赖：
cd frontend npm install npm run dev前端一般使用 React 或 Vue。如果你只是调用 API 接口测试功能，可以不启动前端，使用 Swagger 文档或 Postman 即可。
2.5 配置环境变量
项目根目录下一般会有一个.env.example文件。复制为.env后，按实际环境填写关键配置：
cp .env.example .env典型的配置项如下：
# 数据库连接 DATABASE_URL=postgresql://yourusername:yourpassword@localhost:5432/ai_learning # 向量数据库连接 VECTOR_DB_URL=postgresql://yourusername:yourpassword@localhost:5432/ai_learning_vector # 模型 API 配置 OPENAI_API_BASE=http://localhost:8000/v1 OPENAI_API_KEY=your-api-key EMBEDDING_MODEL=text-embedding-3-small LLM_MODEL=gpt-4o-mini # Agent 配置 AGENT_MEMORY_SIZE=20 AGENT_MAX_ITERATIONS=10需要注意：
OPENAI_API_BASE如果是空字符串，系统会默认使用 OpenAI 官方地址。EMBEDDING_MODEL决定知识库的向量化效果。AGENT_MEMORY_SIZE控制 Agent 记忆短期对话的数量，设置太大会增加 token 消耗。
2.6 初始化数据库
项目一般会提供初始化脚本。执行以下命令：
python init_db.py该脚本主要完成：
- 创建用户表、课程表、错题表、知识点表。
- 创建向量存储表，并建立向量索引。
- 插入预置的学科知识点数据。
如果提示relation "nodes" does not exist，多半是初始化脚本没有执行成功。可以检查数据库连接配置，或手动执行 SQL 文件。
2.7 启动服务
后端服务启动命令一般如下：
python main.py或者使用 uvicorn 启动：
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload启动成功后，终端会输出类似内容：
INFO: Uvicorn running on http://0.0.0.0:8000 INFO: Application startup complete.此时访问http://localhost:8000/docs可以看到 FastAPI 自动生成的 Swagger 接口文档，这是验证后端是否正常的快捷方式。
3. Agent 学习系统的核心架构拆解
这一部分重点关注系统的内部实现。理解了架构，才能知道部署后该如何配置，以及二次开发时该改哪里。
3.1 整体模块划分
系统大致分为五个核心模块：
| 模块 | 职责 |
|---|---|
| Agent 调度引擎 | 决策下一步动作，协调其他模块 |
| 知识库模块 | 文档上传、切片、向量化、检索 |
| 学习记录模块 | 保存学习轨迹、答题记录、错题信息 |
| 练习生成模块 | 根据知识掌握程度生成练习题 |
| 用户画像模块 | 计算知识点掌握度，生成学习建议 |
每个模块都可以单独替换或扩展。比如，知识库模块可以替换为更专业的 RAG 方案，练习生成模块可以替换为题库 API。
3.2 Agent 调度引擎的工作流程
Agent 调度引擎是整个系统的“大脑”。它使用一个大模型作为决策核心，配合工具函数完成具体操作。
这里给出一个简化的调度伪代码：
# 简化示例，展示 Agent 调度思路 from typing import List from dataclasses import dataclass @dataclass class AgentStep: action: str params: dict class LearningAgent: def __init__(self, llm, memory, tools): self.llm = llm self.memory = memory self.tools = {tool.name: tool for tool in tools} def run(self, user_input: str) -> str: # 1. 从记忆库中取出历史上下文 context = self.memory.get_recent(10) # 2. 将用户输入与历史状态交给 LLM 做意图识别 decision = self.llm.plan( user_input=user_input, context=context, available_tools=list(self.tools.keys()) ) # 3. 根据决策执行动作 if decision.action in self.tools: result = self.tools[decision.action].execute(**decision.params) else: result = self.llm.answer(user_input, context) # 4. 将本轮交互写入记忆 self.memory.add(user_input, result) return result核心思路：
- LLM 负责输出结构化决策，而不是直接回答所有问题。
- 工具函数负责执行检索、插入错题等可靠操作。
- 记忆模块负责维护对话历史、知识状态和错题记录。
实际项目中，这个决策过程一般通过 few-shot prompting 或 function calling 实现。也就是说，你要给 LLM 提供工具描述列表，让它决定调用哪个工具、传什么参数。
3.3 知识库模块的 RAG 实现
知识库模块采用的是经典 RAG（Retrieval-Augmented Generation）流程：文档预处理 → 内容切片 → 向量化 → 相似度检索 → 结合上下文生成回答。
切片是影响检索质量的关键环节。项目中推荐的结构化切片逻辑大致如下：
def split_document(text: str, max_chunk_size: int = 500) -> List[str]: # 按段落切分 paragraphs = text.split("\n\n") chunks = [] current_chunk = [] for para in paragraphs: if len("\n".join(current_chunk)) + len(para) <= max_chunk_size: current_chunk.append(para) else: chunks.append("\n".join(current_chunk)) current_chunk = [para] if current_chunk: chunks.append("\n".join(current_chunk)) return chunks切片原则：
- 不要超过 embedding 模型的 token 上限。
- 尽量保留完整的语义单元，比如段落优先于句子。
- 包含标题信息的切片，检索效果更好。
向量化后的数据会写入向量数据库，并为向量字段建立 HNSW 索引，以提升检索性能。
3.4 错题集与学习记忆机制
错题集模块是这个系统另一个吸引人的地方。它不是简单保存“哪道题做错了”，而是把错题与知识点关联起来，反向更新用户画像。
当用户做错一道题时，系统会执行类似如下的逻辑：
def record_wrong_answer(user_id: str, question: dict, user_answer: str): # 记录错题 wrong_question = { "user_id": user_id, "question_id": question["id"], "knowledge_points": question["knowledge_points"], "user_answer": user_answer, "correct_answer": question["answer"] } save_to_wrong_book(wrong_question) # 更新知识点掌握度（降低对应知识点分数） for kp in question["knowledge_points"]: mastery = get_mastery(user_id, kp) new_mastery = mastery * 0.7 # 错题后掌握度降低 update_mastery(user_id, kp, new_mastery) # Agent 触发后续动作：生成例题或调整复习计划 agent.trigger("learning_plan_adjustment", user_id)这个机制的关键在于“知识点 → 错题 → 复习计划”的闭环。
3.5 用户画像与学习计划生成
系统基于用户答题结果和知识点掌握度，生成个性化学习计划。掌握度通常用一个 0 到 1 的分数表示：
- 0.8 以上：已掌握，进入间隔复习。
- 0.5 ~ 0.8：建议强化练习。
- 0.5 以下：需要重新学习知识点。
学习计划的生成并不复杂，但难点在于何时安排复习、复习哪类题目。项目中通常使用遗忘曲线的简化模型来决定复习时机：
def should_review(mastery: float, last_review_days: int) -> bool: # 掌握度越低，复习间隔越短 if mastery < 0.5: return last_review_days >= 1 elif mastery < 0.8: return last_review_days >= 3 else: return last_review_days >= 7这套机制保证了“伴随成长”的效果：系统不是一次性给你推一堆内容，而是根据你的遗忘曲线不断安排合适的复习内容。
4. 知识库构建全流程实战
要让学习系统真正为自己所用，你必须构建自己的知识库。这一节给出完整操作流程。
4.1 准备学习资料
支持的知识格式一般包括：
- Markdown 文件（推荐）
- PDF 文件
- Word 文件
- 纯文本文件
建议优先使用 Markdown，因为切片效果好，特别是带有标题结构的文档，切片时能够保留层级信息。
4.2 上传与预处理
将资料放入项目指定目录，然后调用知识库导入接口。
接口示例：
curl -X POST http://localhost:8000/api/knowledge/upload \ -H "Content-Type: multipart/form-data" \ -F "file=@./my_notes.md" \ -F "subject=计算机基础"导入完成后，可以通过状态接口查看向量化进度：
curl http://localhost:8000/api/knowledge/status预期返回类似：
{ "total_chunks": 128, "embedded_chunks": 128, "status": "completed" }4.3 验证知识检索效果
导入完成后，可以通过以下接口测试检索：
curl -X POST http://localhost:8000/api/knowledge/search \ -H "Content-Type: application/json" \ -d '{"query": "什么是TCP三次握手", "top_k": 5}'返回结果是相似度最高的几个文本片段。如果结果不相关，你需要检查：
- 切片大小是否合适。
- 是否选择了正确的 embedding 模型。
- 文档中是否有大量噪声内容。
4.4 将知识库接入 Agent 问答
配置好知识库后，Agent 在回答问题时就会自动检索相关知识。这里有一个关键配置项：检索结果是否作为上下文注入提示词。
在.env中对应配置：
RAG_USE_SEARCH_RESULTS=true RAG_SEARCH_TOP_K=4这里的RAG_SEARCH_TOP_K建议设置在 3 到 6 之间。太小会导致上下文不足，太大会引入噪声且增加 token 消耗。
5. 错题集与个性化学习实战
知识库解决的是“获取知识”的问题，错题集解决的是“诊断问题”和“针对性训练”的问题。
5.1 创建训练任务
通过接口创建一次知识点测试：
curl -X POST http://localhost:8000/api/training/start \ -H "Content-Type: application/json" \ -d '{ "user_id": "user001", "knowledge_points": ["TCP协议", "三次握手"], "question_count": 5 }'系统会返回一组测试题：
{ "task_id": "task_123", "questions": [ { "id": "q1", "type": "choice", "content": "TCP三次握手中，第二次握手的标志位是？", "options": ["SYN", "ACK", "SYN+ACK", "FIN"] } ] }5.2 提交答案并记录错题
提交答案：
curl -X POST http://localhost:8000/api/training/submit \ -H "Content-Type: application/json" \ -d '{ "task_id": "task_123", "user_id": "user001", "answers": [ {"question_id": "q1", "answer": "SYN"} ] }'如果答错，系统会自动：
- 将题目写入错题集。
- 更新对应知识点的掌握度。
- 触发 Agent 生成新学习计划。
5.3 查看错题集
curl http://localhost:8000/api/wrong-book/user001返回结果示例：
{ "wrong_questions": [ { "id": "q1", "knowledge_point": "TCP协议", "wrong_times": 2, "last_wrong_time": "2025-04-01 12:00:00" } ] }这里的wrong_times很关键。当一个知识点下的错题次数超过阈值，Agent 会建议重新学习该知识点，而不是继续盲目刷题。
5.4 获取个性化复习计划
curl http://localhost:8000/api/learning-plan/user001系统会返回按优先级排序的复习内容：
{ "plan": [ { "knowledge_point": "TCP协议", "priority": "high", "reason": "错题次数较多且掌握度低于0.5", "action": "重学知识点并完成3道基础题" }, { "knowledge_point": "HTTP状态码", "priority": "medium", "reason": "距离上次复习已超过7天", "action": "间隔复习" } ] }这实际上就是 Agent 根据用户画像做出的“行动决策”。你会发现，Agent 在这里并不是输出一句话，而是输出一个可执行的计划。
6. 常见问题与排查思路
部署和使用的过程中，有几个问题很多朋友都遇到过。这里整理成一张排查表。
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 服务启动失败，端口被占用 | 8000端口已被其他程序占用 | 使用lsof -i:8000查看进程，换端口启动 |
| 数据库表缺失，查询报错 | 未执行数据库初始化脚本 | 执行python init_db.py，确认数据库连接配置 |
| 中文检索效果差 | embedding 模型对中文支持不足 | 换用支持中文的 embedding 模型，并增加中文停用词过滤 |
| Agent 调用工具超时 | 网络原因或模型服务响应慢 | 检查模型服务状态，增加超时时间配置 |
| 内存不足导致崩溃 | 向量库与模型同时占用内存过高 | 将模型服务独立部署，或使用小尺寸量化模型 |
| 上传 PDF 后检索不到内容 | PDF 是扫描图片，没有文本层 | 先使用 OCR 工具提取文字，再导入系统 |
| 错题集没有更新 | 提交答案的接口参数格式不对 | 检查 answers 字段是否为数组，以及 question_id 是否存在 |
| 复习计划一直不变 | 用户画像未随答题结果更新 | 确认答题提交接口是否完整执行了“更新掌握度”逻辑 |
6.1 关于依赖版本的补充说明
很多 AI 项目都存在“昨天能跑，今天拉取新代码后跑不起来”的情况。这通常与 langchain、pydantic 等库的版本升级有关。
建议做两件事：
- 使用虚拟环境隔离项目依赖，避免全局环境污染。
- 记录当前可运行环境的版本组合。比如，找到一份能稳定运行的 requirements，就固定住版本，后续升级要单独测试。
如果你使用 Poetry 或 uv 管理依赖，锁定版本会更方便。
6.2 模型服务连接问题
系统的大模型和 embedding 模型可以来自不同服务。如果模型服务地址配置错误，通常会出现：
ConnectionError: HTTPConnectionPool ...排查步骤：
- 用 curl 测试模型服务是否可访问。
- 确认 API key 是否符合服务要求。
- 查看项目日志中记录的实际请求地址。
如果是本地模型服务，注意 base URL 中是否包含/v1路径。格式不匹配也会导致认证失败。
7. 最佳实践与工程建议
部署和使用只是第一步。如果你想把系统真正用于学习或者二次开发，下面这些建议会很有帮助。
7.1 知识库构建的最佳实践
- 按学科/目录拆分文档，不要让一个知识库包含所有内容。比如“计算机网络”和“操作系统”建议分开管理。
- 统一文档格式，建议全部使用 Markdown，并规范标题层级。切片质量直接决定检索质量。
- 定期更新知识库内容，避免过时内容进入上下文。
- 清洗原始资料，去掉无关页眉页脚、广告、重复段落。脏数据进入向量库后很难清理干净。
7.2 Agent 提示词与工具设计的工程建议
如果你要修改 Agent 的行为，重点关注提示词和工具描述。
- 工具描述要写清楚“什么时候调用”和“传入什么参数”。LLM 不是程序员，它需要靠描述来理解工具用途。
- 设置最大迭代次数，防止 Agent 陷入死循环。比如配置
AGENT_MAX_ITERATIONS=10。 - 为关键操作增加人工确认机制。比如“删除错题记录”不能仅靠 Agent 一个动作完成，应要求二次确认。
- 记录 Agent 每一步的动作日志，方便回溯问题。建议以结构化 JSON 写入日志文件。
7.3 数据安全与隐私
学习系统记录了大量用户学习数据，尤其是错题集，属于个人敏感数据。生产环境中要注意：
- 数据库密码不要硬编码在代码或配置文件中，使用环境变量或密钥管理工具。
- 用户学习数据导出和删除功能要完善，满足数据合规要求。
- 如果使用外部大模型 API，避免在提示词中携带不必要的隐私信息。
- 定期备份数据库，特别是向量化数据和错题记录。
7.4 性能与成本优化
- 在
RAG_SEARCH_TOP_K和AGENT_MEMORY_SIZE之间找到平衡，减少 token 消耗。 - 高频查询可以增加缓存层，比如相同问题直接返回上一次结果。
- 向量数据库建议使用独立实例，避免与应用争抢内存。
- 批量导入知识文档时，可以采用异步任务队列，避免前端长时间等待。
8. 总结与二次开发方向
港大开源的这套 AI 学习系统，最大的价值不在于“又一个 AI 应用”，而在于它示范了如何用 Agent 架构把大模型、知识库、错题集、用户画像组合成一套可运行的学习闭环。
通过本文的实战，你已经可以：
- 在本地部署这套学习系统。
- 构建自己的知识库并优化检索效果。
- 使用错题集机制诊断知识薄弱点。
- 理解 Agent 调度引擎的核心实现思路。
如果你想进一步做二次开发，可以优先尝试以下方向：
- 接入更多题型：比如填空题、简答题、编程题，丰富训练维度。
- 引入间隔重复算法：把简单的
should_review逻辑替换为成熟的间隔重复算法（如 SM-2）。 - 增强学习可视化：开发前端图表，展示知识点掌握度的变化趋势。
- 多 Agent 协同：让“题库生成 Agent”和“复习规划 Agent”并行工作，进一步提升个性化程度。
学习系统这类项目的核心调优点，通常不在模型本身，而在知识的组织方式和反馈闭环设计上。如果你在部署过程中遇到了其他问题，欢迎在评论区交流。动手把系统跑起来，再根据自己的学习习惯调整 Agent 策略，你会对这个项目有更深的理解。码字不易，觉得有用的话可以先收藏，方便后续查阅。
