DeepTutor完整指南：从安装到精通AI个性化学习助手的5个阶段

【免费下载链接】DeepTutor DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/. 项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor

DeepTutor 是一款 Agent 原生的 AI 个性化学习助手，把对话辅导、解题、出题、研究与可视化整合进同一个工作区，适合自学者与小型团队。本文按真实使用路径带你完成启动配置、核心功能实战与进阶调优，读完即可独立上手。

阶段一 准备工作：环境确认与 DeepTutor 安装方式选择

确认 Python 3.11 运行环境

DeepTutor 后端要求 Python 3.11–3.13，完整 Web 应用还需要 PATH 中可用 Node.js 20+（启动时会拉起打包好的 Next.js 前端）。先运行 python3 --version 确认版本；若版本不符，建议用虚拟环境隔离，避免污染系统解释器。

如果你不想本地装 Python，直接用 Docker 跑预构建镜像即可，这也是新手最省心的路线。

Docker 与本地安装怎么选

两条路线对比：

• Docker（推荐新手）：一条 docker run 起一个自包含容器，只需暴露 3782 端口，配置与数据落在 deeptutor-data 卷里，重启不丢失。
• 本地安装（推荐进阶/开发者）：pip install -U deeptutor 装 PyPI 包，或从源码克隆后 pip install -e .，方便参与开发与定制。源码安装前先克隆仓库：

git clone https://gitcode.com/GitHub_Trending/dee/DeepTutor

选本地的原因：所有能力（CLI、知识库、技能安装）在本地都可直接调试；选 Docker 的原因：环境零依赖，适合部署在服务器上。

阶段二 快速上手：三步启动 DeepTutor 并配置第一个模型

三条命令完成安装与启动

pip install -U deeptutor
deeptutor init      # 依次选择端口、LLM 提供商、API Key、模型
deeptutor start    # 同时启动后端与前端

init 会提示后端端口（默认 8001）、前端端口（默认 3782）、LLM 提供商与模型名；start 之后打开终端打印的前端地址（默认 http://127.0.0.1:3782）即可使用。为什么用 init 而不是跳过它：它会把配置写入 data/user/settings/，后续 Settings 页面读写的是同一份文件。若用 Docker，则改用一条 docker run -p 127.0.0.1:3782:3782 -v deeptutor-data:/app/data ghcr.io/hkuds/deeptutor:latest 启动，模型配置改到 Web 设置页完成。

在 Settings 页填入 API Key 并验证连接

打开左侧导航进入 Settings → Models，添加一条 LLM 配置（Base URL、API Key、模型名），保存前先测试再应用——大部分设置区采用"草稿-应用"流程，方便你先验证提供商可用再提交。若之后要用知识库/RAG，再补一条 Embedding 配置；只聊天问答则不必。

DeepTutor 对话工作区：侧边栏可直达知识库、学习空间、设置等所有功能模块

阶段三 核心功能实战：知识库接入、问题解决与题目生成

知识库配置方法：把学习资料接入 RAG

1. 进入 Knowledge Center，选择新建知识库；
2. 上传 PDF、Markdown 等学习材料，等待解析与索引完成；
3. 索引引擎可多选：默认 LlamaIndex（本地向量 + BM25），也可选 GraphRAG、LightRAG、PageIndex 等知识图谱类检索。

为什么建知识库而不是直接粘文档：文档被解析、切块、建索引后，对话、Co-Writer、Book 生成等所有工作流都能引用同一份资料，且引用可溯源。解析引擎（MinerU、Docling、PyMuPDF4LLM 等）在 Settings → Knowledge Base 中切换。


在知识库页面选择新建或关联已有索引，上传文档后自动完成解析与向量化

问题解决与题目生成：从一个对话开始

DeepTutor 的 Chat、Quiz（出题）、Research（研究）、Solve（解题）、Visualize（可视化）都跑在同一个 Agent 循环上——你切换的是"目标"，不是引擎。实战流程：

1. 在输入框直接提问，系统会先检索你挂载的知识库，再逐步给出解题推理与验证；
2. 需要出题时，从输入区的能力入口选择 Quiz，指定基于某章节或某知识点生成，可调整难度与题量；
3. 生成的题目自动进入 Question Bank，每题保留你的作答、参考答案与解析，之后可反复测验。

活页书 Book：把资料变成可交互学习内容

当资料量足够大时，用 Book 模块把知识库、笔记或聊天记录编译成"活页书"：先给出章节大纲让你确认结构，再逐章生成文本、测验卡片、动画、交互组件等分类型内容块。每个页面都带独立 Page Chat，可以边读边问。想深入看 Book 的编译实现，可阅读 deeptutor/book/ 源码目录。


Co-Writer 分栏编辑器：选中文本即可让模型重写、扩写或压缩，改动以 diff 形式等你接受或拒绝

写报告或长文时用 Co-Writer：它采用"外科手术式"编辑——你选中一段文字，要求改写、扩写或润色，模型基于知识库或网页证据修改后，以 diff 展示，你接受后才落盘，避免一次性覆写整个文档。

阶段四 进阶配置：模型参数调整、记忆体系与学习空间

模型参数怎么调：温度与输出长度

进入 Settings → Models 选择提供商与模型后，可在能力级配置中调整温度与 token 上限：

• 温度调低（接近 0）：解题、出题等需要确定性答案的场景更稳；
• 温度调高：头脑风暴、创作类内容更多样；
• 最大输出长度与超时：长报告类 Research 任务适当放宽，避免中途截断。

这些参数最终落在 data/user/settings/ 下的 JSON/YAML 文件中（如 model_catalog.json、agents.yaml），推荐用 Web 设置页编辑，高级用户也可直接改文件后重启生效。


Settings 是统一控制面板：顶部状态条实时显示 Backend、LLM、Embedding、Search 是否就绪，下方按区域分卡片管理

三层记忆与学习空间：让个性化可追溯

DeepTutor 的记忆不是黑盒向量库，而是文件化的三层结构：L1 原始事件轨迹、L2 分面整理的事实、L3 跨面综合画像，且上层引用下层，任何结论都能回溯到原始事件。在 Memory Graph 里你可以看到整张金字塔，并手动编辑或删除不准确的画像。记忆整合的预算参数在 Settings → Memory 调整。

同时，Learning Space 集中存放你的可复用资产：笔记本、题库、Mastery Path（掌握度学习路径）、行为预设 Persona、可安装的技能（Skill）与 MCP 服务。它们都能从 Chat、Partners、Co-Writer、Book 中随时复用——这就是"连接式学习上下文"的含义。


Mastery Path 按知识点规划学习路径，测验结果自动回写掌握度，薄弱项会被持续安排复练

阶段五 问题排查：DeepTutor 卡住时先看这三处

状态条、日志与配置文件三处排查法

遇到"服务没反应"或"模型报错"，按以下顺序排查：

1. 看 Settings 页顶部的状态条：Backend、LLM、Embedding、Search 四盏灯，哪个亮红先查哪个——多数"回答生成失败"其实是 LLM 配置失效；
2. 看日志文件：运行日志写在 data/user/logs/ 下，Docker 部署则用 docker logs -f deeptutor 跟踪容器输出；
3. 核对配置文件：data/user/settings/ 下是纯 JSON/YAML，重点检查 model_catalog.json（API Key 与模型名）与 system.json（端口、CORS）。

两个高频场景：开发模式（--dev）卡死时，终端会提示占用端口的 PID，确认没有残留 Next.js 进程后重试即可；想停止服务，直接在前端终端按 Ctrl+C，后端与前端会一并停止。更多部署细节（含 Podman/rootless 容器）见 CONTAINERIZATION.md，能力与命令的完整清单见 deeptutor_cli/ 目录的 README。

下一步建议

• 跑通第一个知识库后，试试 deeptutor chat --capability deep_solve --kb my-kb --tool rag，体验命令行下的同一套 Agent 循环；
• 在 Learning Space 中导入一个社区技能（Socratic Tutor 等），感受技能如何改变对话风格；
• 关注仓库根目录 README 的 Releases 区块，了解每个版本的变更记录；
• 团队使用时研究 Multi-User 部署：开启认证后首个注册者成为管理员，可按用户授权模型、知识库与技能；
• 想深入原理，阅读 deeptutor/core/agentic/ 中的 Agent 循环实现，以及 deeptutor/services/rag/ 的多引擎 RAG 设计。

【免费下载链接】DeepTutor DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/. 项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor