DeepTutor：开源自托管个性化辅导系统

把一本教材、一篇论文、一门网课的录像丢进文件夹，然后合上电脑。一周后还能想起多少？问题往往出在材料进来之后：没有地方追问，没人出题检查，也看不到自己卡在哪一章。DeepTutor 要补的是这一段。

DeepTutor 是 HKUDS 开源的个性化辅导系统，用 Python 与 TypeScript 编写，输入教材、论文、网页、EPUB、GitHub 仓库等学习材料，输出可对话、可出题、可追踪进度的个人学习工作区。

仓库由三块组成：deeptutor/ 是后端与智能体逻辑，deeptutor_web/ 与 web/ 是前端界面，deeptutor_cli/ 是命令行入口。材料先进知识库做解析与索引，再由检索、对话、掌握路径、练习这些模块消费，用户既可以走浏览器，也可以走 CLI。

基础用法

安装与依赖

仓库地址是 https://github.com/HKUDS/DeepTutor，许可证为 Apache License 2.0，主要语言 Python（占 63.7%），前端 TypeScript 占 35.8%。截至抓取时 Star 40458、Fork 5108、Watcher 191、开放 Issue 211，最近一次提交是 2026-09-27。

官方主推容器化部署。仓库根目录同时留着多份编排文件：docker-compose.yml、compose.yaml、docker-compose.ghcr.yml（走预构建镜像）、docker-compose.dev.yml（开发环境）、compose.codex-oauth.yaml。Issue 历史里「Official Docker deployment support (Compose + prebuilt images)」这条需求已经关闭，说明 Compose 加预构建镜像是被正式支持的路径。

不想用容器时，仓库提供 pyproject.toml、requirements.txt 与 requirements/ 目录作为 Python 依赖声明，根目录另有 start_deeptutor.command 启动脚本。这个脚本适用于哪些系统，仓库里没有说明。

模型侧需要自备供应商密钥。多个版本说明里都提到 provider 与 API 能力配置，v1.5.16 还专门修过「经过网关时代理下的工具调用 id、embedding 与温度上限」相关的问题。

最短能跑通的示例

下面是由仓库结构能确认的最小骨架。仓库的 Get Started 章节没有出现在本次可用的事实节选中，具体必填项以 .env.example 与官方文档 deeptutor.info 为准。

git clone https://github.com/HKUDS/DeepTutor
cd DeepTutor
cp .env.example .env
docker compose up

.env.example 只有 1.1 KB，说明它列出的是最核心的几项环境变量，模型供应商、密钥、端口这类信息大概率都在里面，逐项填完再启动比较稳妥。走预构建镜像时换成 docker-compose.ghcr.yml，本地改代码调试时换成 docker-compose.dev.yml。

确认它跑起来了

启动后打开 Web 界面，如果后端没连上，页面会直接显示 backend service is offline。这条报错在 Issue 里出现过（NAS 部署场景），已解决，但它说明前端与后端是两个独立的服务，看到离线提示时先去查后端容器日志，不要在前端反复刷新。

命令行侧可以跑 deeptutor doctor 做一次自检。这个命令在 v1.5.17 引入，用来检查运行环境与依赖是否就绪。另外 v1.6.5 起 Settings 页面本身会给出 readiness 评分，配置完模型和知识库后可以在那里确认状态。

这些自检通过之后，新建一个工作区、上传一份 PDF、问一个关于该文档的问题，能得到带来源引用的回答，就算这一跑成功了。

主要功能

知识库与检索

• 工作区知识库：每个工作区可以自己放置和移动知识库，v1.6.12 开始支持，学习材料不再被锁死在全局的一个库里。
• 离线档案接入：v1.6.12 接入了可搜索的 Kiwix 档案，适合没有公网或需要随身携带资料集的场景。
• 多来源接入：GitHub 仓库可作为知识源（v1.5.17），此外还接入了 WeKnora、MarginNote 4 的库与批注内容（v1.5.16），网页来源支持有界同步（v1.6.0）。
• 检索引擎与解析：v1.6.1 起使用自研的原生 LightRAG 引擎，v1.6.10 给它配了独立角色模型，并让已发布的索引记录自己是用什么构建的。文档解析支持 MinerU 多格式，PDF 附件会跟随用户选定的解析引擎。

这一组的限制集中在解析环节：扫描版 PDF 会被跳过并报 Skipped empty document（该 Issue 目前待解决），大文件 PDF 也出现过提取到 0 个内容块的情况。

学习、阅读与练习

• Mastery Path 掌握路径：v1.6.9 起有了独立的 WebUI，路径模式可以门控智能体能用哪些工具（v1.6.5），v1.6.4 补上了来源完整的路径与对话交接。
• 沉浸式阅读：支持 EPUB 的忠实渲染与批注、YouTube 视频学习、阅读文件夹、聊天内的选区操作，来源中的图表也会被带进回答（v1.6.11 与 v1.6.12）。
• 课程与练习：Courses 带 Little Tutor 与提问入口，v1.6.9 加入每日练习循环，v1.6.12 加入 Task Board 用来追踪任务。
• 多人协作：Partners 为每个成员维护独立会话与可关联的聊天账号（v1.5.17），v1.6.3 加入学习者与监护人两种账号角色。
• CLI 入口：deeptutor_cli/ 提供面向智能体原生的命令行界面，适合把学习流程脚本化。

参数与配置

常用参数

• deeptutor doctor：环境自检命令，排查依赖与运行状态时先跑它。
• 编排文件选择：docker-compose.yml / compose.yaml 是默认路径，docker-compose.ghcr.yml 用预构建镜像，docker-compose.dev.yml 用于开发，compose.codex-oauth.yaml 面向 Codex 登录场景。
• 模型相关：供应商、embedding、温度上限、工具调用等能力在 Web 的 Settings 里配置。v1.6.7 提到「按模型显式声明 API 能力」，v1.6.10 放开了供应商列表的过滤。
• 界面语言：v1.6.11 加入法语与乌克兰语，v1.6.12 加入德语，语言项在界面设置里切换。

配置文件

根目录的 .env.example 是环境变量模板，复制成 .env 后填值。容器相关配置写在 compose.yaml、docker-compose.yml 及其变体里。Python 依赖与打包声明在 pyproject.toml、requirements.txt、requirements/ 与 MANIFEST.in 中。.importlinter、.pre-commit-config.yaml、.secrets.baseline 属于开发与提交检查用，普通部署不需要动。

.env 里每一个变量的名称与含义，仓库的这份节选中没有列出，需要对照官方文档或直接读 .env.example 的注释。

实际使用中的坑

• 扫描版 PDF 无法入库：现象是知识库处理扫描件时提示 Skipped empty document，本质是这类 PDF 没有文本层可提取。该 Issue 目前待解决，没有现成的绕过说明。
• 大 PDF 提取出 0 个内容块：报错形如 Extracted 0 content blocks，随后 Parsing failed: No content was extracted。这条已经解决，遇到时先升级版本。
• LM Studio 下 Guided Learning 不工作：Docker 部署并接 LM Studio 时引导式学习失效。该 Issue 已解决，评论数 24，是本仓库讨论最集中的一条。
• NAS 部署显示 backend service is offline：容器跑起来了但前端连不上后端。该 Issue 已解决，排查方向是后端服务与端口映射，而不是前端本身。
• 其他已修复项：Smart Solver 因模型输出三引号字符串导致 JSON 校验失败、GPT Luna/Terra/Sol 无法调用工具、TutorBot 输入延迟、CORS 报错，这几条都已关闭。

同类项目对比

只想把本地文档接成问答，AnythingLLM 的开箱路径比 DeepTutor 短，后者的仓库有 266 MB、多份编排文件、还需要在 Settings 里逐项配模型与解析引擎，配置面明显更大。deepresearch 只做主题报告生成，边界窄，容易嵌进已有的 Spring 服务，而 DeepTutor 要单独跑一套带前端与知识库的服务。判断标准很简单：需要学习路径、练习和多人协作就用 DeepTutor，只需要一条问答链路就用前两者。

合规边界

DeepTutor 会抓取并同步网页来源、接入搜索引擎，还会把知识库内容送进第三方模型供应商的 API。使用时只处理自有资料或已获授权的材料，不要用它抓取需要登录或绕过付费墙的内容，那类操作在多数平台的服务条款里都是禁止的，也可能触及著作权与数据保护相关法律。

接第三方模型接口意味着上传的资料会离开本机，涉及个人隐私、内部课件或未公开研究的场景，要么换成本地模型部署，要么在上传前做脱敏。多人协作环境里，Partners 的成员权限与知识库可见范围需要提前划清，知识库一旦共享，内容就不再只对你可见。

适合谁

适合已经有一堆自己的学习材料、想长期沉淀成可检索可练习工作区的人；适合需要多成员共享知识库又要保留各自学习记录的团队；也适合愿意自己配模型密钥、接受容器化部署的开发者，因为他们可以用 CLI 把流程脚本化。

不适合只想把一份文档接成问答就收工的人，那类需求有更轻的选择；不适合没有任何模型供应商密钥、也不打算申请的用户，DeepTutor 本身不提供模型能力；不适合主要材料是扫描版 PDF 的人，这类文件当前会在解析环节被跳过。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。