"DeepTutor: Agent-Native Personalized Learning Assistant"
📖 README
DeepTutor: Agent-Native Personalized Tutoring[](https://www.python.org/downloads/)
[](https://nextjs.org/)
[](LICENSE)
[](https://github.com/HKUDS/DeepTutor/releases)
[]()[](https://discord.gg/eRsjPgMU4t)
[](./Communication.md)
[](https://github.com/HKUDS/DeepTutor/issues/78)Features · Get Started · Explore · TutorBot · CLI · Community🇨🇳 中文 · 🇯🇵 日本語 · 🇪🇸 Español · 🇫🇷 Français · 🇸🇦 العربية · 🇷🇺 Русский · 🇮🇳 हिन्दी · 🇵🇹 Português---
📰 News> [2026.4.4] Long time no see! ✨ DeepTutor v1.0.0 is finally here — an agent-native evolution featuring a ground-up architecture rewrite, TutorBot, and flexible mode switching under the Apache-2.0 license. A new chapter begins, and our story continues!> [2026.2.6] 🚀 We've reached 10k stars in just 39 days! A huge thank you to our incredible community for the support!> [2026.1.1] Happy New Year! Join our Discord, WeChat, or Discussions — let's shape the future of DeepTutor together!> [2025.12.29] DeepTutor is officially released!📦 Rele...
📊 Project Info
- Language
- Python
- Stars
- ⭐ 12,136
- Forks
- 1,663
- Today
- +168
- Ranking
- #8
- Collection
- Overall
- Trending Date
- April 7, 2026
- Last Push
- 4/7/2026
🏷️ Topics
ai-agentsai-tutorclawdbotcli-tooldeepresearchinteractive-learninglarge-language-modelsmulti-agent-systemsrag
📸 Screenshots
5分钟快速开始DeepTutor
DeepTutor是一个原生智能体驱动的个性化学习助手，通过AI代理提供交互式学习体验。
🖥️ OS
macOSWindowsLinux
⚙️ Runtime
Python3.11+
Node.js18+
🔧 Tools
Git— 克隆项目仓库
pip— 安装Python依赖
npm— 安装前端依赖
📝 Steps
1
克隆项目并进入目录
从GitHub克隆DeepTutor仓库到本地。
克隆项目
$ git clone https://github.com/HKUDS/DeepTutor.git进入项目目录
$ cd DeepTutor✓Expected: 项目文件下载到DeepTutor文件夹中。
💡确保网络连接正常。
2
运行设置向导（推荐）
使用交互式脚本自动安装依赖和配置环境。
启动设置向导
$ python scripts/setup_tour.py✓Expected: 脚本提示选择Web模式或CLI模式，并引导完成安装和配置。
💡选择Web模式以在浏览器中打开DeepTutor。
3
配置API密钥
在向导中或手动编辑.env文件，设置LLM和嵌入模型API密钥。
复制环境变量模板
$ cp .env.example .env编辑.env文件（或使用其他编辑器）
$ nano .env✓Expected: .env文件包含LLMBINDING、LLMAPIKEY等字段，并已填写您的API密钥。
💡至少填写LLMBINDING、LLMMODEL、LLMAPIKEY、EMBEDDINGBINDING、EMBEDDINGMODEL、EMBEDDINGAPIKEY等必填字段。
4
启动DeepTutor
如果使用向导，它会自动启动服务；否则手动启动。
启动后端服务
$ python -m deeptutor启动前端服务（在web目录中运行）
$ npm run dev✓Expected: 后端运行在localhost:8001，前端运行在localhost:3782。
💡确保端口8001和3782未被占用。
✅ 验证安装成功
打开浏览器访问DeepTutor界面，确认服务正常运行。
- ✓浏览器打开http://localhost:3782并显示DeepTutor界面
- ✓可以开始聊天或上传文档
⚡ Quick Tips
部署使用Docker部署可避免本地环境问题，运行docker compose up -d
故障排除如果遇到依赖错误，尝试运行pip install -r requirements.txt和npm install
高级配置在.env中设置NEXTPUBLICAPIBASEEXTERNAL用于云部署
🔍 Troubleshooting
❓ 端口冲突导致服务启动失败
→ 修改.env中的BACKENDPORT或FRONTENDPORT，或关闭占用端口的程序
❓ API密钥无效或未设置
→ 检查.env文件中的LLMAPIKEY和EMBEDDINGAPIKEY是否正确填写
❓ Python版本低于3.11
→ 升级Python到3.11或更高版本
🎯 Next Steps
1
上传PDF或Markdown文件到知识库
在界面中上传文档，启用RAG功能进行个性化学习
2
创建TutorBot
设置自主导师代理，用于特定学习场景
3
探索CLI工具
使用deeptutorcli命令进行高级操作和自动化