DeepTutor

DeepTutor 快速入门：先让讲解有出处，再建立学习闭环

这是什么？适合谁？

DeepTutor 是 HKUDS 开源的学习工作区，不只是把聊天框换成老师头像。Chat、Quiz、Book、Knowledge Center 和 Memory 等入口共享运行上下文，可以把材料、讲解、问题与后续练习连接起来。

适合有明确学习材料、愿意核对出处的自学者，也适合希望探索教学 Agent 的开发者。对老师而言，它可以协助准备讲解和练习草稿，但不应代替教师判断题目是否正确、难度是否适当。

与通用应用开发平台 Dify 相比，它把使用界面直接组织成学习场景；与侧重检索引擎的 LightRAG 相比，它还提供面向学习者的交互层。两者的定位不同，不能据此宣称辅导效果更好。

本文核验日期为 2026-10-16，安装指引依据官方 README。界面截图可能属于旧版本，实际导航以当前版本为准，不把旧截图上的位置当作固定菜单。

准备工作

• 准备一台自己管理的电脑，以及一个不含机密资料的学习目录。
• PyPI 完整应用路径要求 Python 3.11–3.14、PATH 中可调用的 Node.js 20+；源码开发路径另推荐 Node.js 22 LTS。
• 准备所选模型服务的账号与密钥；先确认其调用额度。开源软件许可不包含第三方推理、嵌入或搜索费用。
• 先用普通文字进行首轮问答；需要教材知识库时，再配置嵌入模型和对应检索引擎。
• 如不希望维护本机 Python 与 Node 环境，可以参考官方 Docker 路径；它仍需要模型配置和持久化数据。

不要把 API Key 粘到聊天记录、截图或仓库里。DeepTutor 的私有设置与可供 Agent 读取的 Content Workspace 不是同一个概念，授权范围要分别核对。

三步快速上手

第一步：在独立目录安装

在已准备好的 Python 虚拟环境中执行：

mkdir my-deeptutor
cd my-deeptutor
python -m pip install -U deeptutor
deeptutor --help

这里的 python 必须指向满足版本要求的解释器。Windows 用户可在创建虚拟环境后激活它，避免包安装在一个环境、命令却从另一个环境启动。

预期结果是能够显示命令帮助。此时尚未证明模型连接成功，也不代表任何教材已经进入知识库。

第二步：初始化模型并启动

deeptutor init
deeptutor start

初始化向导会询问服务端口、模型供应商、接口地址、密钥和模型名；嵌入与搜索配置是按需项。官方默认后端端口为 8001，前端端口为 3782。

启动后打开终端实际打印的前端地址；默认可在浏览器访问 http://127.0.0.1:3782。保持启动终端开启，停止服务使用 Ctrl+C。

也可以在 Web 的 Settings → Providers 与 Language models 中补配置。能打开页面只是第一层成功判定，接下来还要确认一次模型请求正常完成。

第三步：完成一次可核对的辅导

进入 Chat，先输入一个范围明确、不依赖额外工具的问题：

请辅导我理解一元一次方程 3x + 5 = 20。
先问我应该先去掉哪一项，不要立即给最终答案。
我回答后再解释这一步为什么等式两边都要做，
最后出一道结构相同的练习，并等我作答后批改。

这是本文设计的练习请求，不是产品固定命令，也不保证每次都按同样方式回应。

成功判定：模型有响应、追问与后续回答能继续在同一会话进行、练习的答案可以手工复算。若算式或解释出错，保留原对话并纠正，不要把“有输出”当作“讲对了”。

接着再试材料约束：在 Knowledge Center 配置好检索引擎并导入一份自己有使用权的短文，等待处理完成，在支持知识库的会话中选择它。

仅依据选中的材料解释本节核心概念。
每个结论标出材料中的依据；找不到就说找不到。
先列出两个能从原文直接核对的事实，再问我一道理解题。

第二层成功判定是引用能回到所选材料、内容与原文相符。没有材料依据时应缩小问题或检查索引，不应靠换一种语气掩盖缺证据。

常见踩坑

以下是依据安装与功能前提整理的排查路径，不是本站故障复现实录。

踩坑 1：网页能开，但发消息失败

• 症状：界面正常，首个问题没有可用回复。
• 原因：界面启动与模型授权独立，空模型配置也可以启动应用。
• 排查：回到 Settings → Providers 与 Language models，核对供应商地址、模型权限和额度，先只发一条文字请求。

踩坑 2：安装成功却找不到命令

• 症状：包已安装，终端仍提示 deeptutor 不存在。
• 原因：虚拟环境未激活，或 pip 与当前解释器不是同一套环境。
• 排查：确认当前解释器与虚拟环境，使用 python -m pip 安装；不要在不了解原因时重复向系统环境安装。

踩坑 3：重启后像换了一套设置

• 症状：模型或学习内容没有出现在原位置。
• 原因：私有运行目录依启动位置或显式 home 设置确定，换目录启动可能使用另一处数据。
• 排查：固定运行目录；需要显式路径时按官方 --home 或 DEEPTUTOR_HOME 文档配置，备份原数据后再迁移。

踩坑 4：传了教材却没有可靠引用

• 症状：回答过于泛化，或来源与材料对不上。
• 原因：知识库处理、嵌入配置、引擎选择及会话选择是不同步骤。
• 排查：确认处理完成与当前选库，用原文一句明确事实做检索对照，再决定是否需要重建索引。

踩坑 5：以为“本地部署”就不会向外发送数据

• 症状：将私人教材或学生信息直接交给云模型。
• 原因：应用位置与模型、搜索、嵌入服务的位置不同。
• 排查：分别梳理服务供应商、Workspace 权限和启用工具；先用公开材料验证，涉个人资料须取得相应许可。

踩坑 6：照旧截图寻找已经改名的入口

• 症状：教程图上的位置与本机不同。
• 原因：官方 README 也提示部分截图仍为较早版本参考。
• 排查：按功能名与当前官方文档找入口；记录实际版本，不盲目复制旧设置文件。

初级用法

1. 追问式讲解：先陈述自己理解到哪一步，让 Chat 每轮只处理一个卡点，再核对推导。
2. 材料内问答：选中已就绪知识库，要求区分原文事实与补充解释，对照真实出处。
3. 小规模自测：用 Quiz 或聊天练习生成少量题目，先人工核答案与题意，再保存可用题。

高级玩法

1. 用 Book 把知识库与笔记组织成章节草稿，先审提纲再生成，不把自动成书当作已审教材。
2. 用 Co-Writer 选择一小段笔记进行扩写或改写，核对事实后再接受替换；保留可撤销的编辑路径。
3. 在 Memory 中查看个性化内容是否正确，错误记忆及时修正，避免一次误解长期影响后续辅导。

知识库扩展还可以研究 LightRAG 等不同引擎，但要分别看可选依赖与兼容条件；不要一次安装所有扩展，把依赖问题与教学问题混在一起。

小技巧

1. 第一轮只接一个模型，先证明基本问答可用，再逐步增加检索与搜索。
2. 每次只导入一份短材料，用已知答案的问题核对索引与引用。
3. 明确要求“先问再答”，并在模型抢答时重申节奏。
4. 把材料事实与自己猜想分开记录，便于检查生成内容是否越界。
5. 升级前备份运行数据与设置，尤其不要误把 Docker 命名卷当成随容器自动清空的数据。

常见问题 FAQ

Q1：DeepTutor 免费吗？

A：仓库使用 Apache-2.0 许可，可按许可条件使用代码；模型、嵌入、搜索和硬件成本另算。本文不承诺每次辅导费用，依据见官方仓库。

Q2：它与 Dify 或 LightRAG 有什么不同？

A：Dify 主要面向 AI 应用构建，LightRAG 侧重检索增强，DeepTutor 提供学习交互入口。选择取决于要搭应用、提供检索还是直接组织学习，不据此推断质量胜负。见Dify、LightRAG。

Q3：不配置嵌入模型能试吗？

A：可以先进行基础模型问答；需要知识库时再补齐所选引擎要求。跳过可选配置不代表 RAG 自动可用，见安装与功能说明。

Q4：可以给孩子独立使用吗？

A：不能仅凭“教学 Agent”名称认定内容适龄或答案正确。应由监护人核对服务条款、数据授权与题目，本站没有进行儿童使用效果实测。

Q5：为什么没有给出固定月费或学习提升幅度？

A：代码许可、服务账单和学习效果属于不同问题。官方接入方式允许多种模型，本站没有统一任务与长期教学试验，不能把功能清单换算成费用或成绩承诺。

学习路径：从材料检索到交互式笔记

先在 Knowledge Center 做单材料检索，再把已核对事实交给 Book 组织提纲，最后在 Co-Writer 中只修改有问题的段落。这个顺序能把“索引有问题”和“写作没表达清楚”分开定位。

随后再研究 Memory 的可检查层次与 Mastery Path 的练习组织。每次扩展只增加一种能力，并保留原材料与自己的核对记录。

使用边界与声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。没有实际安装、教学效果、长期运行或安全审计结论；界面与依赖可能随版本更新，生成内容需要人工检查。

参考链接

• 官方主页
• 官方代码与安装说明
• 官方 Agent 安装指南
• 官方推理与来源排查
• Dify 官方仓库
• LightRAG 官方仓库