DeepTutor 本地部署 5 步跑通指南

DeepTutor 本地部署 5 步跑通指南【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor你手头有几份 PDF 讲义想找一个能照着讲义答题、帮你出练习题、还记得你哪块没学会的 AI 学习伙伴。DeepTutor 本地部署后正好满足整套智能辅导Intelligent Tutoring按学习者水平自适应教学服务跑在你自己的机器上模型、资料、记忆都归你管。先确认它解决什么问题DeepTutor 是一个智能体原生agent-native让 AI 自主调用工具完成任务的学习工作台聊天、解题、出题、深度研究、可视化、掌握度练习共用同一个智能体循环而不是各自独立的页面。与同类项目的差异有三点上下文连通知识库、笔记、记忆在聊天和研究里互相引用记忆是文件化、可审计的三层结构不是黑盒向量库扩展面开放技能、MCP 服务Model Context Protocol给 AI 接外部工具的协议、子智能体都能插进同一套运行时。拆解核心能力四件它替你干的事一个循环干完所有事聊天不是问答框而是思考—调工具—观察—回答的循环同一轮里它能搜网页、查知识库、调用推理工具拿不准时还能暂停下来先问你。比如挂上课本知识库后问傅里叶变换到底在干嘛它会调 rag 工具检索讲义再给出带出处的解释。把讲义变成可引用的上下文知识库支持多个检索引擎LlamaIndex默认本地向量加 BM25、PageIndex、GraphRAG、LightRAG以及直接挂一个 Obsidian 笔记库。一条命令建库聊天、出题、写作时都能指定复用deeptutor kb create my-kb --doc textbook.pdf从聊天里直接进深度学习deep_research带引用的调研报告、deep_solve分步解题、deep_question按知识点出选择题、visualize图表与动画都从同一个入口触发deeptutor run deep_question 线性代数 --config num_questions5 deeptutor run deep_research RAG 的最新进展 --config modereport记忆看得见、改得动记忆分三层L1 原始事件流、L2 按场景整理的事实、L3 跨场景画像上层引用下层每条结论都能追到原始记录。终端里deeptutor memory show直接看 L2/L3 的文件内容记错了就手动改。本地部署五步从 0 到可用前置条件Python 3.11–3.133.14 装不上、Node.js 20。第 1 步 建工作目录并安装PyPI 路线无需 clonemkdir -p my-deeptutor cd my-deeptutor pip install -U deeptutor第 2 步 初始化deeptutor init会依次问你后端端口默认 8001、前端端口默认 3782、LLM 提供商 / Base URL / API key / 模型名以及可选的 embedding向量模型知识库依赖它。第 3 步 启动deeptutor start终端会打印前端地址默认 http://127.0.0.1:3782CtrlC同时停掉前后端。第 4 步 核对配置进 Settings → Models 确认 LLM 已保存。所有配置都是data/user/settings/下的明文 JSON/YAMLmodel_catalog.json管模型system.json管端口和 CORS。第 5 步 验证发一条消息再把一份 PDF 建成知识库试一次检索。想跟源码开发就走第二条路Python 3.11–3.13 Node.js 22 LTSgit clone https://gitcode.com/GitHub_Trending/dee/DeepTutor cd DeepTutor python3 -m venv .venv source .venv/bin/activate python -m pip install -e . (cd web npm ci --legacy-peer-deps) deeptutor init deeptutor start --dev进阶玩法三个高频场景接本地模型把 API 成本降为 0Settings → Models 里把 LLM 指向 Ollamahttp://127.0.0.1:11434/v1或 LM Studiohttp://127.0.0.1:1234/v1embedding 同理。效果答疑和检索全走本地不产生费用跑在 Docker 里时注意把localhost换成host.docker.internal见下文避坑。装一个社区技能技能是SKILL.md格式的 Markdown 手册模型按需读取。不用自己写直接装deeptutor skill search socratic tutor deeptutor skill install socratic-tutor效果聊天里多出苏格拉底式追问的辅导风格装完即用不改动任何代码所有导入都过同一道安全检查被标记的包会被直接拒绝。让别的 agent 驱动 DeepTutor任意run命令加--format json每轮输出 NDJSON每行一个 JSON 事件带 session_iddeeptutor run deep_solve 求 d/dx sin(x^2) --tool reason --format json仓库根部的 SKILL.md 是一份约 150 行的交接文档交给 Claude Code、Codex 这类工具型 agent它就能自己配置并调用 DeepTutor。踩坑清单五个高频问题Python 3.14 上 pip 装失败现象依赖回退源码编译最后报subprocess-exited-with-error。原因faiss-cpu 等编译依赖没有 3.14 的预编译包。解决固定用 3.11–3.13例如conda create -n deeptutor python3.11。Docker 里连不上本机的 Ollama现象容器内访问localhost:11434超时。原因容器里的 localhost 是容器自己。解决启动时加--add-hosthost.docker.internal:host-gatewayLinuxBase URL 改用http://host.docker.internal:11434/v1。浏览器打不开页面现象访问 3781 或 3784 无响应。原因前端默认端口是 3782改过system.json里的端口但没重启。解决以终端打印的实际地址为准改端口后重启服务并同步改容器端口映射。知识库功能不可用现象init 时跳过了 embedding之后建知识库提示缺向量模型。原因embedding 是可选步骤但 RAG 依赖它。解决Settings → Models 补一个 embedding 配置再重建索引。不想让模型生成的代码跑在本机现象生成 docx/pptx 的办公技能依赖沙箱执行模型写的 Python 脚本本地部署时默认直接在宿主机子进程里跑。解决在data/user/settings/system.json把sandbox_allow_subprocess设为false代价是文件生成功能失效compose 部署则默认走独立的 runner 容器。适用边界适合谁不适合谁适合想自托管学习工作台的个人和小组要接入私有资料、本地模型、自己扩展工具链的开发者。不适合只想开箱即用、不碰终端的用户——DeepTutor 没有云端 SaaS只有自部署一条路需要严格多租户生产隔离的场景要谨慎多用户模式默认关闭首个注册用户即管理员账号间可见性按邀请制信任设计。已知限制Python 上限 3.13GraphRAG、LightRAG、Math Animator 均为可选附加安装不装对应功能不可用。技术架构速览DeepTutor 系统架构前端、FastAPI 后端与智能体运行时分层四层前端 Next.js 只负责界面/api/*与/ws/*由中间件转发到容器内后端FastAPI 暴露 REST 与 WebSocket运行时是统一的智能体循环工具deeptutor/tools/和能力deeptutor/capabilities/以插件方式挂载底层服务管 LLM、向量、检索与记忆。一切持久化落在data/目录备份就是拷走一个目录。参与贡献与二次开发贡献入口CONTRIBUTING.md。PR 提给dev分支多用户相关提multi-user不要直接提main提交前先跑pre-commit run --all-files。Issue 中带good first issue标签的是新手任务。加一个工具在deeptutor/tools/里照现有文件的注册方式实现聊天里即可调用。加一个能力新的模式看deeptutor/capabilities/里的 protocol 与 registry。改提示词各智能体的 YAML 提示词集中在deeptutor/agents/和deeptutor/tools/prompting/改完重启即生效。下一步今天就能做两件事pip install -U deeptutor后跑deeptutor init再把你最熟的一份 PDF 建成知识库在聊天里挂上它问一个你一直没搞懂的问题。想装社区技能或贡献代码时从 SKILL.md 和 CONTRIBUTING.md 读起。【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考