DeepTutor 入门：Agent-Native 个性化学习助手实战部署

入门级 | 约 20 分钟 | 你将掌握 DeepTutor 的核心架构、两种部署方式（Setup Tour + Docker）、五模式工作区使用，以及 TutorBot 基础配置

---

项目简介

DeepTutor 是一个面向学习的 AI Agent 平台，核心定位是「让 AI 真正辅助学习，而不只是聊天」。它由香港大学数据智能实验室（HKUDS）开发，2026 年 1 月开源后 39 天内斩获 10k Star，目前已是 GitHub 上最受关注的 AI 教育科技项目之一。

它的独特之处在于Agent-Native 架构：不是把 AI 塞进一个聊天界面，而是围绕学习这个目标，设计了一整套可协作的 Agent 工具链。你上传教材，它帮你规划学习路径、生成测验、追踪记忆薄弱点，甚至可以把数学公式变成动画。TutorBot 则更进一步——每个助教都是独立的 AI Agent，有自己的记忆和个性，能主动提醒你复习。

如果你正在找一款本地部署、功能完整、扩展性强的 AI 学习助手，DeepTutor 值得一试。

---

目标读者画像

• 1-3 年经验的开发者，对 AI Agent 和 LLM 应用感兴趣
• 教育科技爱好者，想本地部署个性化 AI 学习工具
• 希望构建持久化 AI 助教（RAG + 记忆）的用户

核心依赖与环境

• Python 3.11+、Node.js 18+
• LLM API Key（OpenAI / Anthropic / DeepSeek 等）
• Embedding API Key（用于 RAG 向量检索）
• Docker（可选，Docker 部署时使用）

完整项目结构树

DeepTutor/
├── deeptutor/              # 核心后端
│   ├── capabilities/        # 五大能力（chat, deep_solve, deep_question 等）
│   ├── tools/              # 工具层（rag, web_search, code_execution 等）
│   ├── tutorbot/            # TutorBot 持久化助教
│   ├── api/                 # FastAPI 服务
│   └── runtime/             # 插件注册与调度
├── deeptutor_cli/           # CLI 入口（Typer）
├── web/                     # Next.js 16 前端
├── scripts/start_tour.py    # 交互式引导安装脚本
└── docker-compose.yml       # Docker 部署

---

手把手步骤

第 1 步：克隆仓库并创建 Python 环境

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# 创建 Python 虚拟环境（推荐 conda）
conda create -n deeptutor python=3.11 && conda activate deeptutor
# 或使用 venv
python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate                          # Windows

第 2 步：Setup Tour 交互式安装（推荐）

DeepTutor 提供了一个交互式引导脚本，自动处理依赖安装、配置填写和连接测试，你不需要手动编辑 .env 文件：

python scripts/start_tour.py

脚本会询问你选择哪种使用模式：

• Web 模式（推荐） — 安装前后端所有依赖，启动临时服务器并打开浏览器引导你完成 LLM、Embedding、Search 的配置，每步都有实时连接测试。配置完成后 DeepTutor 自动重启。
• CLI 模式 — 全程在终端完成，适合无图形界面的服务器环境。

配置完成后访问 http://localhost:3782 即可。

第 3 步：备选 — 手动配置 .env 环境变量

如果你想手动控制配置，先复制示例文件：

cp .env.example .env

然后编辑 .env，至少填写以下必填项（以 Defapi 为例）：

# LLM 配置 — 以 Defapi 为例，半价接入 Claude/GPT
LLM_BINDING=anthropic
LLM_MODEL=claude-sonnet-4-20250514
LLM_API_KEY=sk-defapi-xxxxx
LLM_HOST=https://api.defapi.com/v1

# Embedding 配置 — 用于 RAG 向量检索
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-defapi-xxxxx
EMBEDDING_HOST=https://api.defapi.com/v1
EMBEDDING_DIMENSION=3072

# 可选：网页搜索
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-xxxxx

支持的 LLM Provider 完整列表见下表：

第 4 步：安装依赖并启动服务

Web 模式（前后端分离）：

# 安装后端依赖
pip install -e ".[server]"

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

# 启动后端（终端 1）
python -m deeptutor.api.run_server
# 服务运行在 http://localhost:8001

# 启动前端（终端 2）
cd web && npm run dev -- -p 3782
# 服务运行在 http://localhost:3782

打开 http://localhost:3782 即可使用。

Docker 一键部署（无需安装 Python/Node.js）：

# 先配置 .env（参考第 3 步）
cp .env.example .env
# 编辑 .env 填入 API Key

# 拉取官方镜像并启动
docker compose -f docker-compose.ghcr.yml up -d

# 查看日志
docker compose logs -f

第 5 步：五模式工作区快速上手

DeepTutor 的核心是一个统一聊天工作区，支持五种模式切换，所有模式共享同一个对话上下文：

Chat（默认模式） — 流畅的对话，支持 RAG 检索、网页搜索、代码执行、深度推理等工具组合：

你是大学生，正在复习线性代数。在 Chat 模式下启用 rag 工具，
DeepTutor 会从你的知识库中检索相关教材内容来回答问题。

Deep Solve（深度求解） — 多 Agent 问题解决流水线：规划 → 调查 → 求解 → 验证，每步都有精确来源引用：

deeptutor run deep_solve "证明 √2 是无理数" -t reason

Quiz Generation（出题模式） — 基于知识库生成测评题目，支持自动验证：

deeptutor run deep_question "热力学" --kb physics --config num_questions=5

Deep Research（深度研究） — 将主题分解为子话题，并行调度 RAG、网页和学术论文 Agent，生成带完整引用的研究报告：

deeptutor run deep_research "Transformer 中的 Attention 机制"

Math Animator（数学动画） — 将数学概念转化为可视化动画（需要安装 Manim 依赖）：

pip install -r requirements/math-animator.txt
deeptutor run math_animator "Visualize a Fourier series"

第 6 步：构建第一个 RAG 知识库

知识库是 DeepTutor 的核心——上传 PDF、Markdown、文本文件，构建可检索的向量知识库：

通过 CLI 创建知识库：

# 创建知识库并上传文档
deeptutor kb create textbook --doc ./data/physics_ch1.pdf --doc ./data/physics_ch2.pdf

# 向已有知识库追加文档
deeptutor kb add textbook --doc ./data/physics_ch3.pdf

# 搜索知识库
deeptutor kb search textbook "梯度下降的收敛条件"

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

通过 Web 界面操作：

1. 进入「知识管理」页面
2. 点击「新建知识库」，命名（如 my-textbook）
3. 上传 PDF 或 Markdown 文件
4. 在 Chat 中启用 RAG 工具并选择该知识库

第 7 步：创建你的第一个 TutorBot

TutorBot 是 DeepTutor 的杀手级功能——每个 Bot 都是一个持久化、多实例的 AI 助教，有独立记忆、个性和技能：

# 创建数学助教（Socratic 苏格拉底式提问风格）
deeptutor bot create math-tutor \
  --name "数学助教" \
  --persona "Socratic math teacher who uses probing questions"

# 创建写作教练
deeptutor bot create writing-coach \
  --name "写作教练" \
  --persona "Patient, detail-oriented writing mentor"

# 查看所有 Bot
deeptutor bot list

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

TutorBot 支持多渠道接入（Telegram、Discord、飞书、邮件等），可以在你不在的时候主动发起学习提醒和复习任务。

第 8 步：CLI 日常使用命令一览

# 交互式 REPL（终端聊天）
deeptutor chat --capability deep_solve --kb textbook --tool rag

# 单次执行
deeptutor run chat "解释傅里叶变换" -t rag --kb textbook -l zh

# 管理会话
deeptutor session list
deeptutor session open <session-id>

# 查看 / 清除记忆
deeptutor memory show summary
deeptutor memory show profile
deeptutor memory clear summary --force

# 查看当前配置
deeptutor config show

# 列出所有插件和工具
deeptutor plugin list

---

常见问题排查

1. LLM 连接失败（401 Unauthorized 或 403 Forbidden）

# 检查 API Key 是否正确
cat .env | grep LLM_API_KEY

# 检查网络连通性（以 Defapi 为例）
curl -s https://api.defapi.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" | head -c 200

常见原因：API Key 填写错误、环境变量未生效（重启服务）、网络无法访问境外 API。

2. Embedding 检索无结果

# 检查 Embedding 配置
deeptutor config show | grep EMBEDDING

# 确认知识库已成功索引
deeptutor kb info textbook

可能原因：文档上传后索引未完成、向量维度设置错误（需与 Embedding 模型匹配）、查询语句与文档内容不匹配。

3. 端口被占用

# 查找占用端口的进程
lsof -i :8001  # 后端端口
lsof -i :3782  # 前端端口

# 或在 Windows 上
netstat -ano | findstr :8001

解决方式：结束占用进程，或在 .env 中修改 BACKEND_PORT 和 FRONTEND_PORT。

4. Docker 容器健康检查失败

# 查看容器详细日志
docker compose logs --tail=100

# 检查 .env 文件是否存在且包含有效 API Key
cat .env

5. 前端无法连接后端 WebSocket

远程部署时确保设置了正确的外部地址：

NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

然后重启服务使配置生效。

6. TutorBot 不响应消息

检查 Bot 状态并确保已启动：

deeptutor bot list
deeptutor bot start <bot-id>

多渠道 Bot（如 Telegram）还需要检查对应平台的 Webhook 配置是否正确。

---

扩展阅读 / 进阶方向

TutorBot Soul 模板自定义：通过编辑 Bot 的 Soul 文件，可以定义教助的性格、语气和教学哲学，打造完全个性化的 AI 导师。参考 deeptutor/tutorbot/souls/ 目录下的内置模板。

插件开发：DeepTutor 采用两层插件架构（Tools 层 + Capabilities 层），你可以通过编写 manifest.yaml + BaseCapability 子类来扩展任意功能。详细开发指南见 AGENTS.md。

多渠道接入：TutorBot 支持 Telegram、Discord、飞书、企业微信、邮件等渠道接入，可以将 AI 助教连接到任何你常用的平台。

nanobot 引擎：TutorBot 的底层由 nanobot 驱动，这是一个超轻量级 AI Agent 引擎，值得深入研究其 Agent Loop 实现。

LightRAG 集成（Roadmap 中）：下一代知识库引擎 LightRAG 即将集成，届时知识检索能力将大幅提升。