DeepTutor 快速入门指南:10 分钟搭一个个人 AI 学习助手,把课程资料变成互动教材
【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor
周六下午两点,距离线性代数期中考试还有三天。你终于把资料凑齐了:下载文件夹里 40 份课件 PDF、班级群里转发的 2 份讲义,还有备忘录里手敲的一页公式摘要。全塞给通用聊天机器人?它不记得你昨天卡在哪道题,上下文也装不下 40 个文件。DeepTutor 就是为这种局面做的个人 AI 学习助手:开源、本地安装,把你的资料收进知识库,之后它是个知道你学到哪一步的学伴。本文拿"把课程资料变成能复习、能自测的备考包"这个真实任务做主线,从 4 条安装命令带你走到一次完整实战,最后附一张问题速查表。
DeepTutor 本地安装步骤:4 条命令完成部署
DeepTutor 对环境的胃口很温和:需要Python 3.11 及以上(3.11–3.13)和Node.js 20+。不确定就先在终端跑python --version和node -v看一眼。
提示:DeepTutor 的配置、知识库、记忆全部存放在你启动命令所在的工作目录(
data/user/settings/之下)。所以先建一个专属工作区,以后备份、迁移就是整个文件夹拷走的事。
# 1. 建立并进入专属工作区 mkdir -p ~/deeptutor && cd ~/deeptutor # 2. 安装核心包(含 Web 界面 + 命令行工具) pip install -U deeptutor # 3. 交互式向导:依次选端口、LLM 提供商、嵌入模型 deeptutor init # 4. 同时启动后端 API 与前端界面,保持终端不关 deeptutor startdeeptutor start跑完后,浏览器打开终端里打印的地址(默认http://127.0.0.1:3782),看到干净的主界面就算成功了;之后在终端按Ctrl+C,前后端一起停止。
注意:赶时间可以跳过
deeptutor init,界面能起,模型稍后在Settings → Models里补配;没有云端 API 密钥也没关系,向导里选 Ollama 等本地模型方案一样能跑通。
打开 DeepTutor 主界面:认识这个 AI 学习工作台
你面前不只是一个聊天框,而是一张工作台。左侧导航从上到下是 Home、Partners、My Agents、Co-Writer、Book、Learning Space 六个主功能区,底部还有 Memory、Knowledge Center、Settings。中间是聊天区,重点看输入框下方的三个位置:
- 左下的 "Chat" 下拉是能力切换器:Chat(日常对话)、Quiz(自动生成可校验的题)、Research(多代理研究并给出引用)、Visualize(图表 / 图解 / 交互页面),More Capabilities 里还有 Solve(多步推理解题)和 Mastery Path(掌握式辅导);
- "+" 按钮负责挂载一次性引用:文件、历史对话、书、笔记本、题库,只对这一轮生效;
- 底部一排 chip(知识库、子代理、人格、模型、语音)是"粘性"上下文,选中后整个会话都带着走。
模型需要动手时会自动调工具:rag查你的知识库、web_search上网查、write_note往笔记本记一笔;遇到拿不准的地方,ask_user会把对话暂停,用选项卡的形式反问一句,而不是猜。
如何创建知识库:把课程资料导入 DeepTutor Knowledge Center
这个模块解决什么问题:你有一堆散落文档,想让它变成随时可引用、可提问的资料库。适合谁:资料多的备考党和做项目调研的人。
左侧导航进入Knowledge Center,点New knowledge base,弹窗里有两种入口:Create new(上传文档、建全新索引)和Link existing(直接复用别处已建好的索引,比如你的 Obsidian 库或远端 LightRAG 实例,原地读取、不再建索引)。
DeepTutor 创建知识库弹窗:选择检索引擎并上传初始文档
建库时还要选索引引擎(一个知识库绑定一个):
| 引擎 | 特点与适用 |
|---|---|
| LlamaIndex(默认) | 本地向量 + BM25 混合检索,开箱即用,新手首选 |
| PageIndex | 托管服务,按页引用,需要 API key,适合 PDF/Markdown |
| GraphRAG / LightRAG | 知识图谱检索,需额外安装依赖,适合关系复杂的资料 |
| Obsidian | 直接挂你的库,辅导过程原地读写,无需上传 |
文档解析引擎在Settings → Knowledge Base里选:Text-only、PyMuPDF4LLM、MinerU、Docling、markitdown,处理扫描件和公式文档时换引擎往往立竿见影。习惯终端的话,同样的事几条命令就做完:
deeptutor kb create linear-algebra --docs-dir ./downloads/lectures # 建库并批量导入一个文件夹 deeptutor kb list # 看看库里有什么 deeptutor kb search linear-algebra "特征值" # 试搜一条提示:单个文档解析失败或导错了,删掉那个文件就行,不用整库推倒重建;重新索引会写新的版本目录,不会毁掉正在用的旧索引。
如何用 Book 模块:把资料编译成互动教材
适合谁:想系统复习、把"读过一遍"变成"确实学会"的人。解决的问题:对着几十页 PDF 从第一页刷到尾,效率太低。
左侧Book模块点New book,选择资料来源——知识库、笔记本、题库,甚至某次历史对话都可以。接下来它先给出一版章节大纲让你审,确认后才开始生成内容,而不是盲出一稿让你抽卡。每个章节由"带类型的块"拼成:正文、提示框、测验卡、闪卡、时间线、代码块、图表、交互式 HTML、数学动画、概念图,几乎每页还配一个Page Chat,读到哪问到哪。测验卡可以直接作答,翻面看解析;哪个块不满意,单独插入、移动、重生成或换类型,不用整章重写。
DeepTutor 书籍章节内嵌测验卡:作答后展开答案解析
到这里,你的 40 份 PDF 已经变成一本按你的资料生成、边读边考你的教材——哪里不会,点哪里。
用 Mastery Path 跟踪掌握度,用 Memory 沉淀学习进度
Mastery Path适合备考党:输入主题(比如"特征值与特征向量"),它把主题拆成目标清单,顶部是进度条和"待复习"提醒,每个目标明确标记 Mastered / Not started,没过关的目标不能跳过(hard gate)。路径卡片上的New (in Chat)一键把这条路径接回对话继续辅导,学习记录和辅导现场不脱节。
DeepTutor Mastery Path:目标清单、掌握度进度条与待复习提醒
Memory解决的是"每次对话都像初次见面"的问题。它是三层可见记忆:L1 是工作区实时镜像加追加式事件流水,L2 是各模块的事实摘要,L3 是跨模块合成结论。关键点在于——这些都是你能打开编辑的普通文件,不是黑盒向量库,下面的 Memory Graph 还能把任意一条合成结论追溯回它背后的原始事件。所以隔两天再问"我上次学到哪了",它是有依据地答,而不是客套。刷新频率等参数在Settings → Memory调。
DeepTutor 常见问题速查:新手最可能卡住的 6 件事
| 现象 | 可能原因 | 解决步骤 |
|---|---|---|
deeptutor start后前端打不开 | 前端端口被占用,或构建中途报错 | 看终端最后打印的地址和报错;释放占用端口,Ctrl+C停干净再重跑 |
| 能对话但回答说未配置模型 | init 时没配 LLM,或跳过了 init | Settings → Models补一个 Base URL / API key / 模型名,保存即生效 |
| 知识库索引一直卡住没进度 | 嵌入模型未配置或连不通 | init 向导或Settings → Models里配 embedding provider,先确认端点可达 |
| 个别 PDF 导入后内容缺失 | 解析引擎没吃透该格式 | Settings → Knowledge Base换 Text-only 或 PyMuPDF4LLM 重试;坏文件可单独删除,不用重建库 |
| Docker 里连宿主机的 Ollama 失败 | 容器内的 localhost 不是宿主机 | 启动时加--add-host=host.docker.internal:host-gateway,Base URL 填http://host.docker.internal:11434/v1 |
start --dev前端卡住不动 | 残留的 Next.js 锁文件 | 停掉未退出的前端进程,清掉web/.next下的锁文件后重启(见 README.md 的 dev-server troubleshooting) |
提示:任何拿不准的问题,先
deeptutor config show对照一遍端口、模型、密钥,能定位掉一大半。
用熟之后:装社区技能、接子代理、用终端驱动它
装技能:Learning Space → Skills 里可以Import from EduHub,直接浏览社区目录把技能下进你的库;终端里同样顺手,所有导入都会过一道安全校验门:
deeptutor skill search "socratic tutor" deeptutor skill install socratic-tutor # 拉取 → 校验 → 注册自己写的SKILL.md也能deeptutor skill publish发布回社区。
接子代理与 Partner:My Agents 可把你机器上的 Claude Code、Codex 等 CLI 接进来,对话中用 Agent chip(或输@)在回合中途召唤,它们的产出实时流进活动面板;Partners 则是带独立人格、模型和 IM 渠道(飞书、Telegram、Discord 等)的常驻学伴,可以让它在固定时间提醒你复习。
终端驱动:deeptutor chat进多轮 REPL;deeptutor run deep_solve "求 ∫sin(x)cos(x)dx" --kb linear-algebra --tool rag单发一回合;再加--format json,每个回合输出 NDJSON,方便让别的 agent 把 DeepTutor 当工具使。完整命令对照表见 deeptutor_cli/README.md。
容器化:不想装环境的话一条命令起整个应用,只暴露 3782 一个端口,配置和知识库落在deeptutor-data卷里持久化,细节看 CONTAINERIZATION.md。想读源码折腾的,仓库地址是git clone https://gitcode.com/GitHub_Trending/dee/DeepTutor,装法按 README.md 的源码安装部分走。
今天就能做的第一步
还是那个周六下午。打开终端,执行:
deeptutor start然后打开 http://127.0.0.1:3782,把输入框左下的能力切到Quiz,用 "+" 挂上你的linear-algebra知识库,发出第一问:"出 10 道关于特征值与特征向量的中等难度选择题,附解析"。答完之后顺手打开 Memory 页,看看它有没有把你"记下"——从这一刻起,线性代数复习不再每次从零开始。
【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考