DeepTutor教程,手把手搭建你的专属 AI 学习助手

导语：DeepTutor 是一款免费开源的 AI 个性化学习工作空间，由香港大学数据科学实验室开发，能把 AI 辅导、知识库、深度研究、测验练习整合在一起。本文是零基础小白向的完整教程，从”它是什么”到”怎么装、怎么用”，看完你就能拥有一个专属的 AI 学习助手。

项目地址：https://github.com/HKUDS/DeepTutor

一、DeepTutor 是什么？

DeepTutor 是一个基于 AI 的”终身个性化学习工作空间”。通俗地说，它是一个装在你电脑上、用大语言模型驱动的”私人 AI 家教 + 知识管家”。

你可能用过 ChatGPT 问问题，但 ChatGPT 只是一问一答的聊天。DeepTutor 的不同之处在于，它把一整套学习场景都整合进了一个系统里：

• 辅导对话：像家教一样一对一讲解知识点
• 问题求解：帮你解数学题、推理题
• 测验生成：自动出题，帮你检验掌握程度
• 深度研究：围绕一个主题做调研、整理资料
• 可视化：把概念画成图表帮助你理解
• 掌握度练习：根据你的薄弱点反复练习

打个比方：如果 ChatGPT 是一个”聊天窗口”，那 DeepTutor 就是一个”私人书房”——里面有 AI 老师、有你的书架（知识库）、有笔记本、有练习册，还有能帮你查资料的助手，所有东西之间还能互相联动。

它的开发者是香港大学数据科学实验室（HKUDS），这个团队开源过多个知名项目。DeepTutor 诞生后增长极快，是当前最全面的开源个性化学习平台之一。

二、它到底有多火？

DeepTutor 是 GitHub 上增长最快的开源 AI 学习项目之一（以下数据来自项目 README 的官方新闻记录，star 数以 GitHub 实时显示为准）：

• Star 数：约 9 个月时间就突破了 4 万 star（官方记录：2026 年 9 月 20 日达到 40k stars）。作为对照，它在 2026 年 2 月达到 1 万 star 只用了 39 天。
• 更新频率：非常活跃，总提交数超过 3000 次，最近一次更新就在近期（截至本文写作时最新版本为 v1.7.0）。
• 荣誉：曾获得 GitHub 当日趋势榜（Trending Repository of the Day）称号。

能在不到一年的时间里积累这么多用户和 star，说明它确实解决了”如何用 AI 更好地学习”这个真实需求。

三、核心功能有哪些？

DeepTutor 的功能非常丰富，下面列出最实用的几个，每一项后面都附了大白话解释：

• 统一运行时：聊天、问答、测验、研究、可视化、解题、沉浸式阅读等所有模式共享同一套上下文——你在聊天里问过的东西，做题时它还记得。
• 任务看板：像 Trello 一样管理你的学习任务（待办 / 进行中 / 已完成），还能记笔记、拖拽排序。
• 互联学习上下文：知识库、书籍、笔记、收藏、题库、AI 人格、记忆可以跨工作流复用，不用重复录入。
• 沉浸式视频学习：贴一个 YouTube 或 B 站视频链接，就能边看边做笔记、按字幕搜索、定位时间戳提问。
• 多引擎知识库：支持 LlamaIndex、GraphRAG、LightRAG、Obsidian、MarginNote 4、腾讯 IMA 等多种知识引擎，把资料变成可检索的知识。
• 可检视记忆：采用三层记忆架构，还能通过”记忆图谱”可视化查看和编辑 AI 记住了什么。
• AI 伙伴系统：创建持久的 AI 伙伴，每个都有独立人格、记忆，还能接入飞书、Telegram、Slack、钉钉、企业微信等渠道。
• 活书引擎：把知识库、收藏、聊天记录自动生成一本”互动活书”，含章节、测验、闪卡、时间线等。

四、三步上手指南（零基础详细版）

下面我把安装和使用拆得非常细。DeepTutor 提供多种安装方式，对小白来说，推荐用 Docker 方式，一条命令就能跑起来；如果不想用 Docker，用 PyPI 方式也很简单。

方式一：PyPI 安装（推荐，最通用）

这种方式适合大多数用户，需要你的电脑已经装好 Python（版本 3.11 到 3.14）。

第 1 步：创建并进入一个专属文件夹

mkdir -p my-deeptutor && cd my-deeptutor

解释：mkdir -p my-deeptutor 是”新建一个叫 my-deeptutor 的文件夹”，cd my-deeptutor 是”进入这个文件夹”。这样 DeepTutor 的数据都会存在这里。

第 2 步：安装 DeepTutor

pip install -U "deeptutor[full]"

解释：pip install 是 Python 的安装命令，-U 表示”如果有更新就升级”，deeptutor[full] 表示安装完整版（含 Web 界面和命令行工具）。

第 3 步：初始化配置

deeptutor init

解释：这条命令会引导你进行初始设置，包括选择端口、选择用哪家大模型（LLM 提供商）、是否配置嵌入和搜索等。跟着提示一步步选即可。

第 4 步：启动

deeptutor start

解释：启动后端和前端服务。注意：启动后这个终端窗口要保持打开，不要关掉。

第 5 步：打开浏览器访问

启动后，打开浏览器，访问默认地址：

http://127.0.0.1:3782

看到界面就说明安装成功了。

方式二：Docker 安装（一条命令试用，最省事）

如果你已经装了 Docker，这是最快的试用方式：

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

解释：这条命令会从镜像仓库拉取并运行 DeepTutor 的最新版，映射到本地的 3782 端口，并把数据保存在 deeptutor-data 这个数据卷里。运行后同样访问 http://127.0.0.1:3782。

方式三：仅命令行（CLI，无网页界面）

如果你只想在终端里用，可以从源码安装后使用 CLI。核心命令如下：

deeptutor chat                                          # 进入交互式聊天
deeptutor run chat "Explain Fourier transform"           # 让 AI 解释傅里叶变换
deeptutor run deep_solve "Solve x^2 = 4" --kb my-kb      # 结合知识库解题
deeptutor kb create my-kb --doc textbook.pdf             # 导入 PDF 创建知识库
deeptutor memory show                                    # 查看 AI 的记忆
deeptutor config show                                    # 查看当前配置

（更详细的源码安装步骤，请以项目 README 为准。）

关键：如何配置大模型

DeepTutor 本身不提供大模型，需要你接入一个 LLM。有两种选择：

• 用云端模型：在启动后的 Web 界面里，进入 Settings → Providers，填入你已有的大模型 API（比如 OpenAI、DeepSeek 等）的密钥。
• 用本地模型（免费、离线）：先在本机装好 Ollama 或 LM Studio，然后在 DeepTutor 的 Settings → Providers 里，把 Base URL 指向本地服务（如 Ollama 通常是 http://127.0.0.1:11434/v1）。这样就能离线使用，数据也不出本机。

五、哪些人适合用？

• 学生和自学者：需要个性化辅导、知识管理、测验练习、沉浸式阅读的人，DeepTutor 相当于一个 24 小时在线的 AI 家教。
• 教育工作者：可以创建互动教材、管理学习路径、追踪学生的掌握度。
• 研究人员：利用深度研究、文献管理（支持 Zotero、论文搜索）、知识图谱构建来辅助科研。
• 开发者：喜欢命令行、想自定义技能/工具、接入各种代理（Claude Code、Codex、DeepSeek 等）的人。
• 注重隐私的本地 LLM 用户：支持 Ollama、LM Studio、llama.cpp、vLLM 等本地模型，数据不出本机。

六、哪些人不建议用 / 需要避坑

这一节帮你判断自己是否适合，以及避免踩坑。

• 完全没接触过 Python / 命令行的纯小白：虽然本文已经把步骤拆得很细，但安装过程仍涉及命令行操作，需要一定的动手意愿。若只想”打开即用”，可以优先考虑 Docker 一条命令的方式。
• 需要稳定网络和模型密钥：如果用云端大模型，需要你自己准备 API 密钥并可能产生费用；如果用本地模型，则需要有一定性能的电脑。
• 硬件要求：本地跑大模型对内存和显卡有一定要求，配置较低的电脑可能体验不佳。
• 升级注意：升级到 1.7.0 前需要先备份数据，若装过旧的 deeptutor-cli 要先卸载（python -m pip uninstall deeptutor-cli）。
• 配置误区：项目根目录的 .env 文件不是配置文件，模型要在 Web 界面的 Settings → Providers 里配置，这个点很多人会搞错。

七、常见问题排查（新手必看）

问题 1：pip 安装报错或提示版本不符

含义：通常是 Python 版本不在 3.11 – 3.14 范围内。

解决办法：先用 python --version 确认版本，如果太旧就升级 Python。

问题 2：启动后浏览器打不开页面

含义：可能是服务没启动成功，或者端口被占用。

解决办法：确认启动命令的终端窗口还开着、没有报错；确认访问的是 http://127.0.0.1:3782（注意是 127.0.0.1，不是 localhost 也可以，但要一致）。

问题 3：AI 不回复、提示缺少模型

含义：还没配置大模型提供商。

解决办法：进入 Settings → Providers，配置云端 API 或本地模型（Ollama/LM Studio）的地址和密钥。

问题 4：Docker 里连不上本机的 Ollama

含义：Docker 容器里的 localhost 指向容器本身，不是你的电脑。

解决办法：连接宿主机服务要用 host.docker.internal 这个地址，并在运行 Docker 时加上 --add-host=host.docker.internal:host-gateway。

八、总结

DeepTutor 是目前功能最全面的开源 AI 学习工作空间，把 AI 辅导、知识管理、深度研究、测验练习整合在一个系统里，支持多种安装方式和云端/本地大模型。它适合学生、教育工作者、研究人员和开发者；虽然安装涉及一点命令行操作，但只要跟着本文一步步来，就能搭建起属于自己的”私人 AI 书房”。

如果你还想了解其他实用的开源工具，可以看看本站的《yt-dlp 视频下载教程》，同样是小白的完整上手指南。

最后提醒一句：如果用云端大模型，注意保护好你的 API 密钥，避免泄露；如果追求隐私，推荐接入本地模型，让数据完全留在自己的电脑上。