compose-anything/apps/deeptutor/README.zh.md

DeepTutor

中文说明 | English

概述

DeepTutor 是一个 AI 驱动的个性化学习助手，通过多智能体系统将任何文档转化为交互式学习体验。它可以帮助您解决问题、生成题目、进行研究、协作写作、整理笔记，并引导您完成学习路径。

项目地址： https://github.com/HKUDS/DeepTutor
许可证： Apache-2.0
文档： https://hkuds.github.io/DeepTutor/

功能特性

• 问题求解 — 提供详细的分步解决方案和可视化图表
• 题目生成 — 根据您的知识水平生成自适应题目
• 研究助手 — 通过多智能体协作进行深度研究
• 协作写作 — 交互式创意生成和写作辅助
• 智能笔记 — 高效组织和检索学习材料
• 引导学习 — 个性化学习路径和进度跟踪
• 多智能体系统 — 针对不同学习任务的专业智能体
• RAG 集成 — 使用 LightRAG 和 RAG-Anything 进行知识检索
• 代码执行 — 内置代码练习环境

快速开始

前置要求

• Docker 和 Docker Compose
• OpenAI API 密钥（必需）
• 可选：Anthropic、Perplexity 或 DashScope API 密钥

安装步骤

1. 克隆仓库

   git clone <your-compose-anything-repo>
   cd apps/deeptutor
   

2. 配置环境变量

   cp .env.example .env
   # 编辑 .env 文件并添加您的 API 密钥
   

   必需配置：

   • OPENAI_API_KEY — 您的 OpenAI API 密钥

   可选配置：

   • ANTHROPIC_API_KEY — 用于 Claude 模型
   • PERPLEXITY_API_KEY — 用于网络搜索
   • DASHSCOPE_API_KEY — 用于阿里云模型
   • 如需调整端口（默认：后端 8001，前端 3782）
   • 云端部署时设置 NEXT_PUBLIC_API_BASE_EXTERNAL

3. 可选：自定义智能体配置

   创建 config/agents.yaml 文件以自定义智能体行为（详见文档）。

4. 启动服务

   docker compose up -d
   

   首次运行需要约 30-60 秒初始化。

5. 访问应用

   • 前端界面： http://localhost:3782
   • 后端 API： http://localhost:8001
   • API 文档： http://localhost:8001/docs

使用方法

创建知识库

1. 访问 http://localhost:3782/knowledge
2. 点击"新建知识库"
3. 上传文档（支持 PDF、DOCX、TXT、Markdown、HTML 等）
4. 等待处理完成

学习模式

• 求解（Solve） — 获取问题的分步解决方案
• 题目（Question） — 基于学习材料生成练习题
• 研究（Research） — 通过多智能体协作进行深度研究
• 协作写作（Co-Writer） — 交互式写作和创意生成
• 笔记（Notebook） — 组织和管理学习材料
• 引导（Guide） — 遵循个性化学习路径

高级功能

• 代码执行 — 在界面中直接练习编码
• 可视化图表 — 为复杂概念自动生成图表
• 导出 — 将您的工作下载为 PDF 或 Markdown
• 多语言支持 — 支持多种语言

配置说明

环境变量

主要环境变量（所有选项见 .env.example）：

变量	默认值	描述
OPENAI_API_KEY	（必需）	您的 OpenAI API 密钥
DEFAULT_MODEL	gpt-4o	默认 LLM 模型
BACKEND_PORT	8001	后端服务器端口
FRONTEND_PORT	3782	前端应用端口
DEEPTUTOR_CPU_LIMIT	4.00	CPU 限制（核心数）
DEEPTUTOR_MEMORY_LIMIT	8G	内存限制

端口说明

• 8001 — 后端 API 服务器
• 3782 — 前端 Web 界面

数据卷

• deeptutor_data — 用户数据、知识库和学习材料
• ./config — 自定义智能体配置（可选）

资源要求

最低配置：

• CPU：1 核心
• 内存：2GB
• 磁盘：2GB + 知识库所需空间

推荐配置：

• CPU：4 核心
• 内存：8GB
• 磁盘：10GB+

支持的模型

DeepTutor 支持多个 LLM 提供商：

• OpenAI — GPT-4、GPT-4 Turbo、GPT-3.5 Turbo
• Anthropic — Claude 3（Opus、Sonnet、Haiku）
• Perplexity — 用于网络搜索集成
• DashScope — 阿里云模型
• OpenAI 兼容 API — 任何与 OpenAI 格式兼容的 API

故障排查

后端启动失败

• 验证 .env 中的 OPENAI_API_KEY 是否正确设置
• 查看日志：docker compose logs -f
• 确保端口 8001 和 3782 未被占用
• 验证数据卷有足够的磁盘空间

前端无法连接后端

• 确认后端正在运行：访问 http://localhost:8001/docs
• 云端部署时，将 NEXT_PUBLIC_API_BASE_EXTERNAL 设置为您的公网 URL
• 检查防火墙设置

知识库处理失败

• 确保有足够的内存（推荐 8GB+）
• 检查文档格式是否支持
• 查看日志了解具体错误

API 速率限制

• 在提供商控制台监控 API 使用情况
• 考虑升级 API 计划
• 为不同任务使用不同模型

安全提示

• API 密钥 — 妥善保管您的 API 密钥，切勿提交到版本控制系统
• 网络暴露 — 生产环境部署时，使用 HTTPS 和适当的身份验证
• 数据隐私 — 用户数据存储在 Docker 卷中，请确保适当的备份和安全措施
• 资源限制 — 设置合适的 CPU 和内存限制以防止资源耗尽

更新

更新到最新版本：

# 拉取最新镜像
docker compose pull

# 重新创建容器
docker compose up -d

更新到特定版本，编辑 .env 中的 DEEPTUTOR_VERSION 并运行：

docker compose up -d

高级用法

自定义智能体配置

创建 config/agents.yaml 以自定义智能体行为：

agents:
  solver:
    model: gpt-4o
    temperature: 0.7
  researcher:
    model: gpt-4-turbo
    max_tokens: 4000

详细配置选项请参见官方文档。

云端部署

云端部署需要额外配置：

1. 在 .env 中设置公网 URL：

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

2. 配置反向代理（nginx/Caddy）以支持 HTTPS

3. 确保适当的防火墙规则

4. 考虑使用特定环境的密钥管理

使用不同的嵌入模型

DeepTutor 默认使用 text-embedding-3-large。要使用不同的嵌入模型，请参考官方文档。

相关链接

• GitHub： https://github.com/HKUDS/DeepTutor
• 文档： https://hkuds.github.io/DeepTutor/
• 问题反馈： https://github.com/HKUDS/DeepTutor/issues
• 讨论区： https://github.com/HKUDS/DeepTutor/discussions

许可证

DeepTutor 使用 Apache-2.0 许可证。详情请参见官方仓库。