DeepTutor 个性化学习助手

一句话说明： DeepTutor 是一个基于 AI Agent 的个性化学习平台，你上传文档建知识库，它就变成你的专属 AI 教练——能对话、出题、写笔记、做深度研究、生成教材，还会记住你的学习进度。

---

为什么要学

和普通问答工具（ChatGPT / AnythingLLM）的本质区别

维度	普通问答工具	DeepTutor
核心定位	"你问我答"的百科全书	"教你学会"的私人教练
文档处理	上传文档后做简单检索	上传后建 RAG 知识库，主动出题、生成教材
学习模式	只有对话一种方式	6 种模式：对话/深度求解/出题/深度研究/数学动画/可视化
记忆能力	关掉窗口就忘了你是谁	持久记忆，记住你学了什么、薄弱点在哪
主动性	被动等你提问	TutorBot 能主动提醒复习、定期检查进度
写作辅助	没有或很弱	Co-Writer 多文档写作工作台
教材生成	不支持	Book Engine 自动把你的材料编成互动教材

对你（生信应届生）的具体价值：

1. 面试准备 — 把文献和笔记导入知识库，让 DeepTutor 针对你的薄弱点出题
2. 项目理解 — 上传宏基因组分析流程文档，随时深度问答，准备答辩
3. 文献阅读 — 论文导入后用 Deep Research 模式做多源综述
4. 知识积累 — 所有学习记录持久保存，不用重复学

---

核心概念白话版

Knowledge Hub（知识中心）

白话： 就是你的"个人图书馆"。把 PDF、Markdown、TXT 文件上传进去，DeepTutor 会把文档切碎、做向量索引（就像给每段话打标签），之后你问问题时它能精准找到相关内容回答你。

它包含四个子功能： - Knowledge Bases（知识库）— 存文档的地方，类似文件夹 - Notebooks（笔记本）— 存你的学习记录，跨会话保留 - Question Bank（题库）— 存所有生成的测验题，方便复习 - Skills（技能）— 自定义 AI 的教学风格，比如"用苏格拉底式提问教我"

TutorBot（私人导师机器人）

白话： 不是普通聊天机器人，而是有"灵魂"的 AI 家教。每个 TutorBot 有自己的名字、性格、记忆和专长。你可以创建一个"严格的生信导师"专门问生信问题，再创建一个"耐心的英语教练"帮你练英语。它们各自独立运转，还能主动给你发复习提醒。

底层基于 nanobot（香港大学的轻量 Agent 引擎）。

Book Engine（教材引擎）

白话： 你给它一个主题和知识库，它就自动帮你"写一本书"。不是那种死板的 PDF，而是互动式教材——里面有文字讲解、知识卡片、测验题、时间线、概念图、代码示例等 14 种内容块。

比如你说"帮我生成一本宏基因组分析入门教材"，它会：规划大纲 → 从知识库检索素材 → 逐章编写 → 嵌入互动元素。

Co-Writer（协作写手）

白话： 一个 AI 驱动的多文档 Markdown 编辑器。选中文字可以让 AI 帮你改写、扩展或缩短，它还能从你的知识库里找相关内容辅助写作。写好的笔记可以保存到 Notebook。

实际用途：写面试笔记、整理知识点、写文献综述草稿。

Deep Solve（深度求解）

白话： 遇到难题时用这个模式。它不是直接给你答案，而是分四步走：规划 → 调查 → 求解 → 验证，每一步都有引用来源。适合攻克复杂的生信分析问题。

Quiz（测验出题）

白话： 基于你的知识库自动生成测验题，还内置答案验证。面试前可以让它针对简历项目出题，检查你到底掌握了多少。

Persistent Memory（持久记忆）

白话： DeepTutor 会持续记住你——你学过什么、哪里薄弱、学习偏好是什么。它有两个维度： - Summary（摘要）— 记录你的学习进度，"他已经学了 Alpha 多样性、正在学 Beta 多样性" - Profile（画像）— 记录你的身份信息，"2026 届毕业生、编程基础薄弱、偏好白话解释"

记忆在所有功能和 TutorBot 之间共享，用得越多越懂你。

Skills（技能定义）

白话： 一个 Markdown 文件，定义 AI 教你东西时的"角色扮演"。比如你写一个 bioinformatics-tutor.md，里面定义"你是一个生信导师，用中文白话解释所有概念，遇到英文术语要附带中文翻译"，激活后 DeepTutor 就按这个风格教你。

---

安装配置完整教程

前置条件

工具	最低版本	检查命令	说明
Git	任意	git --version	你已有
Python	3.11+	python --version	conda 环境即可
Node.js	18+	node --version	网页前端需要，纯 CLI 模式不需要
npm	9+	npm --version	随 Node.js 一起装

还需要至少一个 LLM API Key（OpenAI / Anthropic / DeepSeek 等）。

第一步：克隆项目

# 你已经做了这一步，项目在 /home/pweaz/DeepTutor
cd /home/pweaz/DeepTutor
git pull   # 拉取最新代码，当前最新版 v1.3.1

第二步：创建 conda 环境

# 创建专用 conda 环境（Python 3.11）
conda create -n deeptutor python=3.11 -y
conda activate deeptutor

# 检查 Python 版本
python --version
# 应该输出 Python 3.11.x

第三步：安装依赖

# 安装完整版（后端 + Web 前端支持）
pip install -e ".[server]"

# 如果你还想用 TutorBot（推荐）
pip install -e ".[tutorbot]"

# 安装前端依赖
cd web && npm install && cd ..

说明： pip install -e ".[server]" 中的 -e 是"可编辑安装"（editable install），意思是代码改了不用重新装。[server] 是可选依赖组，包含 FastAPI、LlamaIndex 等后端库。

第四步：运行 Setup Tour（引导配置）

python scripts/start_tour.py

这是一个交互式的 7 步配置向导，会自动帮你： 1. 检测系统环境 2. 安装缺少的依赖 3. 配置 LLM 提供商 4. 配置 Embedding 提供商 5. 配置搜索引擎（可选） 6. 设置端口 7. 生成 .env 配置文件

第五步：手动配置 .env（如果 Tour 不好使）

cp .env.example .env
nano .env   # 或者用 vim/code 打开编辑

核心配置项（最少要填的）：

# === LLM 配置（必填） ===
LLM_BINDING=openai          # 选哪个 LLM 提供商
LLM_MODEL=gpt-4o-mini       # 模型名
LLM_API_KEY=sk-xxx           # 你的 API Key
LLM_HOST=https://api.openai.com/v1   # API 地址

# === Embedding 配置（必填，知识库功能需要） ===
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_HOST=https://api.openai.com/v1/embeddings
EMBEDDING_DIMENSION=         # 留空自动检测

第六步：启动服务

# 一键启动后端 + 前端（推荐）
python scripts/start_web.py

# 或者分开启动
# 终端 1：后端
python -m deeptutor.api.run_server
# 终端 2：前端
cd web && npm run dev -- -p 3782

启动成功后打开浏览器访问 http://localhost:3782。

每日启动

Tour 只需运行一次。以后每次使用只需：

conda activate deeptutor
cd /home/pweaz/DeepTutor
python scripts/start_web.py

更新版本

python scripts/update.py
# 会自动拉取远程最新代码，显示版本差异，确认后更新

---

LLM 配置选项

DeepTutor 支持 30+ 个 LLM 提供商，下面列出最常用的几种：

方案一：OpenAI API（推荐新手）

LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini        # 便宜好用，面试准备够了
LLM_API_KEY=sk-proj-xxxxxx
LLM_HOST=https://api.openai.com/v1

费用参考： gpt-4o-mini 约 $0.15/百万 token 输入，日常学习每月几块钱。

方案二：Anthropic API

LLM_BINDING=anthropic
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=sk-ant-xxxxxx
LLM_HOST=https://api.anthropic.com/v1

方案三：Ollama 本地模型（零成本、数据不出机）

前提：你已经在本地安装了 Ollama 并拉取了模型。

# 先确保 Ollama 在运行
ollama serve &
ollama pull qwen3:8b          # 拉一个中文友好的模型

LLM_BINDING=ollama
LLM_MODEL=qwen3:8b
LLM_API_KEY=                  # 本地模型不需要 key，留空
LLM_HOST=http://localhost:11434/v1

优点： 完全免费、数据不出机、离线可用。 缺点： 8B 模型质量比 GPT-4o-mini 差不少，深度分析可能不够用。

方案四：DeepSeek API（中国大陆友好、便宜）

LLM_BINDING=deepseek
LLM_MODEL=deepseek-chat
LLM_API_KEY=sk-xxxxxx
LLM_HOST=https://api.deepseek.com

方案五：自定义兼容 API

任何兼容 OpenAI API 格式的服务都能用：

LLM_BINDING=custom
LLM_MODEL=your-model-name
LLM_API_KEY=your-key
LLM_HOST=https://your-api-endpoint/v1

适用于：SiliconFlow、通义千问（DashScope）、月之暗面（Moonshot）、智谱（Zhipu）等国产大模型平台。

---

Embedding 配置选项

Embedding（向量嵌入）是知识库功能的核心。它把文本转换成数字向量，让 AI 能"理解"文档内容的语义相似度。

白话比方： 把每段话变成一个"GPS 坐标"，意思相近的话坐标也相近，这样搜索时就能找到最相关的段落。

方案一：OpenAI Embedding（推荐）

EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-proj-xxxxxx
EMBEDDING_HOST=https://api.openai.com/v1/embeddings
EMBEDDING_DIMENSION=          # 留空自动检测（默认 3072 维）

方案二：Jina Embedding（免费额度大）

EMBEDDING_BINDING=jina
EMBEDDING_MODEL=jina-embeddings-v3
EMBEDDING_API_KEY=jina_xxxxxx
EMBEDDING_HOST=https://api.jina.ai/v1/embeddings
EMBEDDING_DIMENSION=          # 默认 1024 维

Jina 有免费层级，适合预算紧张的学生。

方案三：Ollama 本地 Embedding（完全免费）

ollama pull nomic-embed-text    # 先拉取 embedding 模型

EMBEDDING_BINDING=ollama
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_API_KEY=              # 留空
EMBEDDING_HOST=http://localhost:11434/api/embed
EMBEDDING_DIMENSION=768

方案四：SiliconFlow / 阿里通义

EMBEDDING_BINDING=custom
EMBEDDING_MODEL=BAAI/bge-large-zh-v1.5
EMBEDDING_API_KEY=sk-xxxxxx
EMBEDDING_HOST=https://api.siliconflow.cn/v1/embeddings
EMBEDDING_DIMENSION=1024

重要提示（v1.3.0+）： EMBEDDING_HOST 必须填写完整的 API 端点 URL（含路径），不是 base URL。比如 OpenAI 要写 https://api.openai.com/v1/embeddings 而不是 https://api.openai.com/v1。

---

使用教程

1. 导入文档建知识库

Web 界面方式： 1. 打开 http://localhost:3782 2. 点击左侧 Knowledge（知识）标签 3. 点击 Create Knowledge Base（创建知识库） 4. 取名，比如 metagenomics-papers 5. 上传 PDF / TXT / Markdown 文件 6. 等待索引完成（文档会被切块、向量化）

CLI 方式：

# 从单个文件创建
deeptutor kb create metagenomics --doc /path/to/paper.pdf

# 从文件夹批量导入
deeptutor kb add metagenomics --docs-dir /home/pweaz/papers/

# 设为默认知识库
deeptutor kb set-default metagenomics

# 搜索测试
deeptutor kb search metagenomics "Alpha多样性计算方法"

2. 六种学习模式

所有模式共享同一个对话上下文，可以在同一个会话里自由切换。

Chat（对话模式）： 日常问答，可选开启 RAG 检索、Web 搜索、代码执行等工具。

你：什么是 Shannon 多样性指数？
AI：（从知识库找到相关内容，用白话解释）

Deep Solve（深度求解）： 面对复杂问题时使用，AI 会分步规划→调查→求解→验证。

你：为什么我的 Kraken2 分类结果中 unclassified 比例超过 60%？
AI：（分 4 步分析，引用文献和知识库内容）

Quiz Generation（出题）： 基于知识库生成测验题。

你：针对宏基因组 binning 出 5 道选择题
AI：（生成 5 道题目，含答案和解析）

Deep Research（深度研究）： 多 Agent 协作的研究模式，自动分解子话题、并行检索。

你：2型糖尿病与肠道菌群的关系综述
AI：（拆成多个子话题，分别搜索 RAG/Web/论文，合成完整报告）

Math Animator（数学动画）： 将数学概念转化为 Manim 动画。

Visualize（可视化）： 用自然语言描述，生成 SVG 图表、Chart.js 图表或 Mermaid 流程图。

你：画一个宏基因组分析流程图，从原始数据到 MAGs 提取
AI：（生成 Mermaid 流程图）

3. 创建 TutorBot

Web 界面： 在 TutorBot 页面点击创建，设定名称和性格。

CLI 方式：

# 创建一个生信导师
deeptutor bot create bioinfo-tutor \
  --persona "严格的生物信息学导师，用中文白话解释概念，遇到重要术语标注英文原文"

# 创建一个面试教练
deeptutor bot create interview-coach \
  --persona "面试模拟教练，针对生信工程师岗位出题，给出评分和改进建议"

# 查看所有 Bot
deeptutor bot list

# 启动/停止
deeptutor bot start bioinfo-tutor
deeptutor bot stop bioinfo-tutor

4. Book Engine 生成教材

在 Web 界面中： 1. 进入 Book 页面 2. 输入主题，比如"宏基因组 Binning 与 MAGs 提取完全指南" 3. 选择要引用的知识库 4. 等待多 Agent 流水线工作：规划大纲 → 检索素材 → 编写章节 → 组装互动元素 5. 生成的"活教材"包含文字、卡片、测验、代码块、概念图等 14 种内容块

CLI 方式：

deeptutor book list              # 列出已有教材
deeptutor book health <book_id>  # 检查教材与知识库是否同步

5. Quiz 测验

# CLI 一键出题
deeptutor run deep_question "宏基因组质控与组装" --config num_questions=10

# 在 Web 界面中，切换到 Quiz 模式，输入出题要求即可
# 所有题目会自动保存到 Question Bank，下次可以复习

6. Co-Writer 写笔记

1. 在 Web 界面进入 Co-Writer
2. 新建文档，比如"面试知识点整理"
3. 写内容时选中文字，可以让 AI：
4. Rewrite — 改写得更通顺
5. Expand — 扩展更多细节
6. Shorten — 压缩成要点
7. AI 可以从知识库拉取相关内容辅助写作
8. 写好后保存到 Notebook

---

CLI 命令行使用速查

# === 对话 ===
deeptutor chat                                      # 交互式对话
deeptutor chat --capability deep_solve --kb my-kb   # 指定模式和知识库
deeptutor run chat "解释 PCoA 分析"                  # 一次性提问

# === 知识库 ===
deeptutor kb list                                   # 列出所有知识库
deeptutor kb create my-kb --doc paper.pdf           # 创建知识库
deeptutor kb add my-kb --docs-dir ./papers/         # 批量添加文档
deeptutor kb search my-kb "关键词"                  # 搜索知识库
deeptutor kb set-default my-kb                      # 设为默认
deeptutor kb delete my-kb --force                   # 删除知识库

# === TutorBot ===
deeptutor bot list                                  # 列出所有 Bot
deeptutor bot create mybot --persona "描述"         # 创建
deeptutor bot start mybot                           # 启动
deeptutor bot stop mybot                            # 停止

# === 会话管理 ===
deeptutor session list                              # 列出历史会话
deeptutor session open <id>                         # 恢复会话
deeptutor session delete <id>                       # 删除会话

# === 记忆 ===
deeptutor memory show all                           # 查看记忆
deeptutor memory clear --force                      # 清除记忆

# === 笔记本 ===
deeptutor notebook list                             # 列出笔记本
deeptutor notebook create "面试笔记"                # 创建
deeptutor notebook add-md <id> notes.md             # 导入 Markdown

# === 配置 ===
deeptutor config show                               # 查看当前配置
deeptutor plugin list                               # 查看可用工具和能力

# === 输出格式 ===
deeptutor run chat "问题" -f rich                   # 彩色终端输出（人看）
deeptutor run chat "问题" -f json                   # JSON 输出（程序用）

---

和 AnythingLLM 的对比

对比维度	DeepTutor	AnythingLLM
定位	个性化学习助手（教你学）	通用 RAG 文档问答工具
学习模式	6 种模式（对话/求解/出题/研究/动画/可视化）	仅对话
持久记忆	有，记住学习进度和用户画像	无
TutorBot	有，可创建多个独立 AI 导师	无
出题功能	有，基于知识库自动出题	无
教材生成	有（Book Engine，14 种互动内容块）	无
协作写作	有（Co-Writer 多文档编辑器）	无
CLI 支持	完整 CLI，支持 JSON 输出	有 API，CLI 较弱
Embedding 支持	7 种提供商	多种提供商
LLM 支持	30+ 提供商	多种提供商
部署方式	本地 / Docker / 纯 CLI	本地 / Docker / Cloud
适合场景	系统学习、考试准备、深度研究	企业文档检索、快速问答
安装难度	中等（需要 Python + Node.js）	低（有桌面安装包）
社区活跃度	GitHub 20k+ stars，迭代极快	GitHub 30k+ stars，成熟稳定

结论： 如果你只是想"问文档问题"，AnythingLLM 更简单。如果你想"系统性学习"——出题、记忆进度、生成教材、多模式学习——DeepTutor 是更好的选择。两者可以共存，不冲突。

---

常见报错与解决

报错 1：API Key 被拒（401 / API blocked）

Error: 401 Unauthorized - Invalid API key

原因： API Key 无效、过期、或余额用完了。

解决：

# 1. 检查 .env 文件中的 key 是否正确（注意不要有多余空格）
cat .env | grep LLM_API_KEY

# 2. 用 curl 测试 key 是否能用
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-你的key"

# 3. 如果返回 401，去 https://platform.openai.com/api-keys 重新生成 key
# 4. 检查余额：https://platform.openai.com/usage

报错 2：Embedding 连接失败

Error: Connection refused / Embedding endpoint unreachable

原因： Embedding API 地址写错了，或者本地 Ollama 没启动。

解决：

# 检查 1：v1.3.0+ 要求写完整 URL
# 错误写法：EMBEDDING_HOST=https://api.openai.com/v1
# 正确写法：EMBEDDING_HOST=https://api.openai.com/v1/embeddings

# 检查 2：如果用 Ollama embedding
# 正确写法：EMBEDDING_HOST=http://localhost:11434/api/embed
# 确保 Ollama 正在运行：
ollama serve &

# 检查 3：curl 测试连通性
curl -X POST http://localhost:11434/api/embed \
  -d '{"model":"nomic-embed-text","input":"test"}'

报错 3：Embedding 维度不匹配

Error: Embedding dimension mismatch detected

原因： 知识库建立时用的 Embedding 模型和当前配置的不一样，向量维度对不上。

解决：

# 方案 1：把 Embedding 配置改回建库时的模型
# 方案 2：删除知识库重建（会丢失已有索引）
deeptutor kb delete old-kb --force
deeptutor kb create old-kb --doc your-docs.pdf

# 查看当前配置
deeptutor config show

报错 4：Node.js 版本过低

Error: Node.js version 16.x is not supported. Minimum required: 18.x

解决：

# 安装 nvm（Node 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18
node --version   # 应该显示 v18.x.x

# 重新安装前端依赖
cd /home/pweaz/DeepTutor/web && npm install

报错 5：端口被占用

Error: Address already in use :::8001

解决：

# 查看占用端口的进程
lsof -i :8001
# 或者
ss -tlnp | grep 8001

# 杀掉占用进程
kill -9 <PID>

# 或者改端口：编辑 .env
BACKEND_PORT=9001
FRONTEND_PORT=4000

报错 6：Python 依赖安装失败（llama-index / numpy）

Error: Failed building wheel for xxx

解决：

# 确认 Python 版本是 3.11+
python --version

# 升级 pip 和构建工具
pip install --upgrade pip setuptools wheel

# 如果 numpy 报错，固定版本
pip install "numpy>=1.24.0,<2.0.0"

# 重新安装
pip install -e ".[server]"

# 如果还不行，清理缓存重装
pip cache purge
pip install -e ".[server]" --no-cache-dir

---

速查表

架构概览

DeepTutor
├── Chat Workspace（6 种模式共享上下文）
│   ├── Chat         — 日常对话 + 工具
│   ├── Deep Solve   — 多步推理求解
│   ├── Quiz         — 自动出题
│   ├── Deep Research — 多 Agent 研究
│   ├── Math Animator — 数学动画
│   └── Visualize    — 图表生成
├── Co-Writer        — AI 协作写作
├── Book Engine      — 互动教材生成
├── Knowledge Hub    — 文档/笔记/题库/技能
├── TutorBot         — 自治 AI 导师
└── Memory           — 持久学习记忆

默认端口

服务	默认端口
后端 API（FastAPI）	8001
前端 Web（Next.js）	3782
Ollama（如果用本地模型）	11434

关键文件位置

文件	路径	作用
环境配置	/home/pweaz/DeepTutor/.env	所有配置项
用户数据	data/user/	设置、会话、日志
记忆文件	data/memory/	SUMMARY.md、PROFILE.md
知识库	data/knowledge_bases/	文档和向量索引

推荐配置组合（学生预算版）

# LLM：DeepSeek（便宜、中文好）
LLM_BINDING=deepseek
LLM_MODEL=deepseek-chat
LLM_API_KEY=sk-xxx
LLM_HOST=https://api.deepseek.com

# Embedding：Jina（有免费额度）
EMBEDDING_BINDING=jina
EMBEDDING_MODEL=jina-embeddings-v3
EMBEDDING_API_KEY=jina_xxx
EMBEDDING_HOST=https://api.jina.ai/v1/embeddings

# 搜索：DuckDuckGo（免费、不需要 key）
SEARCH_PROVIDER=duckduckgo

---

延伸资源

• GitHub 项目主页： https://github.com/HKUDS/DeepTutor
• 中文 README： 项目 assets/README/README_CN.md
• Discord 社区： https://discord.gg/eRsjPgMU4t
• nanobot（TutorBot 底层引擎）： https://github.com/HKUDS/nanobot
• LightRAG（同团队的 RAG 项目，未来将集成）： https://github.com/HKUDS/LightRAG
• LlamaIndex 文档（RAG 底层框架）： https://docs.llamaindex.ai/
• Ollama 本地模型（配合使用）： 参考本知识库 01_Ollama本地大模型部署与使用.md

---

最后提醒： DeepTutor 迭代极快（2026 年 4 月就发了 10+ 个版本），遇到问题先 python scripts/update.py 更新到最新版。配置出问题时跑一遍 python scripts/start_tour.py 重新走向导，比手动改 .env 更不容易出错。