DeepTutor 完整指南：在本地跑一个带知识库的 AI 辅导系统-酒店常州论坛

DeepTutor 完整指南：在本地跑一个带知识库的 AI 辅导系统

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

DeepTutor 是 HKUDS 团队开源的 AI 辅导系统（Apache 2.0），把知识库检索、分步解题、测验生成、文档写作和掌握度跟踪放进同一个 agent 运行时，可以完整部署在本地。它的核心体验一句话说完：把你自己的材料喂进去，之后它基于你的材料来辅导你，而不是给泛泛的通用回答。

它能做什么：先看核心能力

界面左侧的入口就是日常功能：Home（对话）、Partners、My Agents、Co-Writer、Book、Learning Space、Memory、Knowledge Center、Settings。底层的设计点是这些功能跑在同一个 agent 循环上（核心逻辑在 deeptutor/agents/），切换功能时切换的是目标而不是引擎，知识库、笔记本、题库、记忆这些上下文原样跟随。

对话与能力切换：同一会话里可以在 chat、quiz、research（带引用报告的调研）、visualize、分步解题、mastery path 等能力间切换。模型按轮次思考、按需调用工具；信息不足时会用ask_user暂停这一轮，向你提一个结构化的澄清问题，而不是直接猜。
多引擎知识库：Knowledge Center 支持 LlamaIndex（默认，本地向量 + BM25 混合）、PageIndex、GraphRAG、LightRAG，也可以直接挂载已有的 Obsidian vault。文档解析引擎在 Settings 里可选 MinerU、Docling、PyMuPDF4LLM 等。
Book：从知识库、笔记或聊天历史生成一本交互式的"活页书"——先给章节大纲让你确认，再生成内容。每个页面由文本、测验、闪卡、Manim 数学动画、交互式 HTML 等分类型块组成，块可以插入、移动、重新生成或换类型，每页还有独立的页面级聊天。
Co-Writer：分栏 Markdown 工作区，KaTeX 公式和 Mermaid 实时渲染。选中一段文字让它改写、扩写或缩写，它会先取证（可基于知识库或网页），再以 diff 形式展示修改，你逐条接受或拒绝。
Mastery Path：把一个主题拆成若干目标，按概念/流程等类型分别设"硬门槛"，答对对应类型的题才算掌握，界面给出进度条和下一个待复习的题。
Memory：三层文件式记忆——L1 追加式事件轨迹、L2 按功能区的归纳事实、L3 跨区综合。全部是可打开的纯文本，Memory Graph 能把任意结论追溯到来源。
Partners / My Agents：可以创建有独立人格（SOUL.md）、独立记忆和工具策略的常驻伴侣，接入飞书、Telegram、Slack、Discord、钉钉、QQ、企业微信等 IM 渠道；也可以把本机的 Claude Code、Codex、Gemini 等编码 CLI 接进来，在对话轮次里当子代理实时咨询，或把它们的过往会话导入作为可检索的上下文。

📦 3 种方式跑起来

环境要求：Python 3.11–3.13；方式一和三还需要 Node.js 20+。启动后前端默认 3782 端口，浏览器打开 http://127.0.0.1:3782。当前版本 v1.5.8，发布节奏比较密。

方式一：pip 安装（最快）

mkdir -p my-deeptutor && cd my-deeptutor pip install -U deeptutor deeptutor init # 交互式选端口、LLM 提供商、API key；跳过也可，稍后在界面里配 deeptutor start # 同时启动前后端，Ctrl+C 停止

方式二：克隆源码（适合读代码、参与开发）

git clone https://gitcode.com/GitHub_Trending/dee/DeepTutor cd DeepTutor python3 -m venv .venv && source .venv/bin/activate pip install -e . cd web && npm ci --legacy-peer-deps && cd .. deeptutor init deeptutor start --dev # --dev 让前端走 HMR 热更新

方式三：Docker（适合服务器、长期运行）

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

只需要暴露 3782 端口——容器内的 Next.js 中间件会把/api/*和/ws/*转发到后端，反向代理也只需指向 3782。配置、API key、知识库、记忆都落在deeptutor-data卷里，重启不丢。

用本地模型的话，在 Settings → Models 里把 Base URL 指向 Ollama、LM Studio、llama.cpp 或 vLLM 即可，无需任何云 API。

方式	适合	备注
PyPI	第一次试用，只用成品	不用克隆仓库，前端随包分发
源码	读代码、贡献、只用 CLI	前端需要 Node.js 构建；`deeptutor init --cli`可跳过 Web 部分
Docker	服务器、无人值守	单容器自包含，只暴露 3782

3 个典型用法

场景一：把散落的 PDF 变成能问答的知识库

一个研究生手里有一堆课程 PDF、课件和论文扫描件，想问问题但不想每次把文件重新贴给聊天机器人。在 Knowledge Center 点 New knowledge base，上传文档，选 LlamaIndex，索引建完就能用。

之后在对话里挂载这个知识库，问某个公式或某段材料的含义，回答会引用来源。两个细节对长期使用很重要：单个文档解析失败时只删那一个文件，不用推倒重建；重建索引是写入新的 version-N 目录，旧索引不会被中途破坏。

场景二：把一套课程资料编译成交互式学习书

一个自学者看完一本教材，想把内容系统地过一遍。在 Book 里以知识库或聊天历史为来源新建一本书：系统先给章节大纲让你确认，再生成章节内容。页面里嵌了测验卡、闪卡、概念图和 Manim 动画（动画需要安装 math-animator 扩展依赖），哪个块不满意就单独重新生成，或者在页面上直接追问。

如果产出需要变成可复用的文档，用 Co-Writer：选中一段让 AI 改写，它给出带取证的修改 diff，公式和代码在右侧实时渲染，你逐条批准后才落盘。

![DeepTutor Co-Writer Markdown 编辑器与公式渲染实时预览](https://raw.gitcode.com/GitHub_Trending/dee/DeepTutor/raw/5a197bd143b8c644b1a33783f39bed40a5329a56/assets/figs/web-1.4.6+/co-writer/01-edit panel.png?utm_source=gitcode_repo_files)

场景三：用 Mastery Path 做有门槛的学习

开始学一个新框架前，在 Learning Space 建一条 Mastery Path。主题被拆成若干目标，分 CONCEPT 和 PROCEDURE 等类型，每类有自己的答题门槛：答不对不标记 mastered，进度条停在原地，界面直接告诉你下一题是什么，也可以点"Continue tutoring in Chat"回到对话里继续。批改过的题目会流入 Question Bank，之后在聊天里 @ 引用或编进书里都能复用。

![DeepTutor Learning Space 掌握度路径进度与目标状态](https://raw.gitcode.com/GitHub_Trending/dee/DeepTutor/raw/5a197bd143b8c644b1a33783f39bed40a5329a56/assets/figs/web-1.4.6+/learning-space/04-mastery path.png?utm_source=gitcode_repo_files)

和一般 AI 聊天工具的区别在哪

记忆是可读、可审计的。三层记忆不是隐藏向量库，L1 就是按日期追加的 jsonl 事件文件，L2、L3 是可编辑的 Markdown。Memory Graph 把三层画出来，任何一条 L3 综合结论都能追到背后那条原始事件——"它为什么这么认为你"这个问题有明确答案。

知识检索引擎可换。同一套知识库管理界面，底下可以是向量、BM25 混合、知识图谱或页级推理检索，核心管道在 deeptutor/services/rag/。材料形态不同（比如需要页级引用的长 PDF，或者本来就是 Obsidian 笔记库），不必迁就一种引擎。

Agent-native 是双向的。CLI 不是 Web 的附属品：任意run命令加--format json就流式输出 NDJSON 事件（每行带 session_id），其他 agent 可以把 DeepTutor 整个当工具用：

deeptutor run deep_solve "Find d/dx[sin(x^2)]" --tool reason --format json

仓库根目录还有一份 SKILL.md 交接文档，给会用工具的编码 agent 读一遍就能覆盖全部命令面。反过来，DeepTutor 也能把 Claude Code、Codex 等接进来当子代理咨询。

本地优先、没有锁定。整个系统一个容器或一台机器就能跑，多用户模式可选：开启认证后每个用户有隔离的工作区，管理员通过 grants 分配模型、知识库和技能，普通用户看到的是脱敏后的设置页。项目方也明确目前没有任何付费线上产品。

下一步

想试的话，按上面方式一装完deeptutor，跑deeptutor init填一个 LLM provider，deeptutor start打开页面。建议先做两件事：用你手头已有的材料建一个知识库，然后挂载它问一个只有你的材料里才有的问题——这一步跑通，就是 DeepTutor 和普通聊天助手的分界线。

想写 skill、接 IM 渠道或改代码，就按方式二克隆源码，pip install -e ".[partners]"之类的可选依赖在 README 里有完整列表。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析