DeepTutor 本地部署 30 分钟上手：不用云端 API 也能跑离线学习助手
【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor
你有没有过这种顾虑：想让 AI 围绕自己的教材和学习笔记做辅导，却不想把资料发到任何云端 API 上？DeepTutor 是一个开源的 agent 式个性化学习助手，知识库、记忆、对话都落在本地磁盘。这篇就带你走一遍 DeepTutor 本地部署的完整流程：装好它、接上 Ollama 本地模型，全程离线使用。
🔍 一次请求的旅程：Agent 循环到底在转什么
先别管模块清单，把一条消息的完整走法看一遍。你在聊天框里问一句话，系统会先把会话历史、记忆、选中的知识库、persona 这些上下文打包成 UnifiedContext，交给统一入口 ChatOrchestrator 分发。
接下来是一个循环：Think（规划下一步）、Act（决定调工具还是直接回答）、Call Tool（RAG、read_memory、web_fetch 等）、Observe（读回结果），再回到 Think，直到 Respond 输出终稿。每一步事件都通过 StreamBus 同步推给 Web、CLI 和 SDK 三种入口。
关键在于工具是随上下文自动挂载的：你在对话里选中知识库，rag工具自己就出现了，不用手动配。核心路由逻辑可以看 deeptutor/runtime/orchestrator.py，配置则全部写在data/user/settings/下的 JSON 里。
⏱️ 30 分钟最短路径：装包、init、start
准备条件：Python 3.11–3.13、Node.js 20+；想彻底离线就再装好 Ollama。
pip install -U deeptutordeeptutor init是个交互式向导，会问端口（后端 8001、前端 3782）、LLM 提供商、Base URL 和模型名。选 Ollama 的话，Base URL 填http://localhost:11434/v1；要用知识库 RAG，再配一个 embedding 地址http://localhost:11434/api/embed。跑起来只需：
deeptutor init deeptutor start终端打印前端地址，浏览器打开就进界面了。模型提前拉好，后面就不用等下载：
ollama pull qwen2.5:7b ollama pull nomic-embed-text到这里本地部署就算完成。Docker 单容器和源码安装两条路 README 里都有，各只多几行，按文档抄即可。
🧭 跑起来之后能干什么：三个使用场景
知识库，适合备课的老师：把一个学期的教材 PDF 丢进知识库，索引建在本地。问"用学生能听懂的话讲一遍欧姆定律的推导"，回答会基于你自己的教材而不是模型的泛化记忆，答得偏不偏一眼能看出来。
Co-Writer，适合写文献综述的研究生：卡在某一段时，选中文字让它"改得更紧凑"。改动以 diff 形式逐条呈现，你逐条接受或拒绝，LaTeX 公式渲染正常，没点头的东西不会进你的文档。
Memory，适合长期学习的人：记忆是三层纯文件——L1 原始事件、L2 分场景摘要、L3 跨场景综合，都在自己磁盘上，可读可改可审计，L3 里的每条结论都能追溯到 L1 的具体事件。这种"可解释的个性化"是闭源云端产品给不了的。
🕳️ 我踩过的坑：连不上本地模型先查这三处
坑一：Docker 里摸不到宿主机上的 Ollama。容器内的 localhost 是容器自己，不是你的机器。解法是 docker 启动时加--add-host=host.docker.internal:host-gateway，然后把 Base URL 改成http://host.docker.internal:11434/v1。
坑二：打开的端口不对。deeptutor start之后，浏览器该访问的是前端 3782；8001 只是 API 端口，打开它只会看到裸 JSON，别误会成挂了。
坑三：开发模式前端卡死。deeptutor start --dev报端口被占，但实际并没有进程在跑，多半是陈旧锁文件，删掉再启动就行：
rm -f web/.next/dev/lock web/.next/lock deeptutor start --dev顺带一提，终端党可以直接跑deeptutor run chat "Explain Fourier transform" --tool rag --kb my-kb执行单轮任务，加--format json还能输出 NDJSON 事件流，方便接进自己的自动化脚本。
✅ 写在最后
DeepTutor 本质是把一套 agent 循环加本地文件的学习工作区交到你手里，本地部署的价值在于教材、记忆、对话都不出机器。装好之后我的建议是：去项目 issues 里翻翻别人怎么配 Ollama 和知识库的，能帮你少走不少弯路；想贡献代码的话，先读一遍 CONTRIBUTING.md 里的分支策略，PR 要提给dev而不是main。
【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
