各位 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 软硬件环境要求建议的部署环境如下组件说明操作系统LinuxUbuntu 20.04 及以上、macOS、Windows WSL2CPU4 核及以上内存16 GB 及以上包含向量数据库与模型推理Python3.10 及以上Node.js18 及以上如果前端需要单独构建数据库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 pydantic2.7.4 langchain0.2.11这里给你一个最小可用的requirements.txt参考fastapi0.111.0 uvicorn[standard]0.30.1 sqlalchemy2.0.30 pydantic2.7.4 langchain0.2.11 langchain-openai0.1.22 pgvector0.3.5 psycopg2-binary2.9.9 python-dotenv1.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_URLpostgresql://yourusername:yourpasswordlocalhost:5432/ai_learning # 向量数据库连接 VECTOR_DB_URLpostgresql://yourusername:yourpasswordlocalhost:5432/ai_learning_vector # 模型 API 配置 OPENAI_API_BASEhttp://localhost:8000/v1 OPENAI_API_KEYyour-api-key EMBEDDING_MODELtext-embedding-3-small LLM_MODELgpt-4o-mini # Agent 配置 AGENT_MEMORY_SIZE20 AGENT_MAX_ITERATIONS10需要注意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_inputuser_input, contextcontext, available_toolslist(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 实现知识库模块采用的是经典 RAGRetrieval-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_RESULTStrue RAG_SEARCH_TOP_K4这里的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, SYNACK, 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_ITERATIONS10。为关键操作增加人工确认机制。比如“删除错题记录”不能仅靠 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 策略你会对这个项目有更深的理解。码字不易觉得有用的话可以先收藏方便后续查阅。