DeepTutor 离线部署指南：Ollama 本地模型，四步跑通-编程实验室

DeepTutor 离线部署指南：Ollama 本地模型，四步跑通

【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor

DeepTutor 是一个开源的 AI 学习助手，主打终身个性化辅导。它的痛点解决得很具体：普通聊天机器人不了解你在学什么、建不起自己的知识库、也没有持续记忆。这篇文章带你把 Ollama 本地模型装好、把 DeepTutor 指过去，得到一个完全离线可用的学习助手，全程不需要任何云端 API key。

DeepTutor 本地能干什么

部署完成后的日常用法主要是三件事：在 Chat 工作区里就某个知识点和它辅导式对话，模型会自己调用 RAG、代码执行等工具；把课件文档上传到 Knowledge Center 建成知识库，让回答有据可查；用 Co-Writer、Book、Learning Space 处理写作、结构化笔记和掌握度练习。底层的聊天、出题、解题、调研跑在同一个 Agent 循环里，上下文跨模式共享，换模式不用换引擎。

动手前，先看这份清单

项目	要求
系统	Linux / macOS / Windows
Python	3.11–3.13
Node.js	20 及以上（构建前端需要）
内存	至少 8GB，推荐 16GB（7B 模型吃内存）
磁盘	20GB 以上空闲（模型 + 依赖 + 运行数据）

必备工具就 Git、pip 和 Ollama 三样，前两个大多已装。Ollama 在 Linux 上一条命令装好：

curl https://ollama.ai/install.sh | sh

从零到第一次启动

把项目拉到本地

源码部署需要仓库在工作目录里，clone 下来即可：

git clone https://gitcode.com/GitHub_Trending/dee/DeepTutor cd DeepTutor

如果不想碰源码，也可以用pip install -U deeptutor从 PyPI 直接装完整应用，跳过 clone 这一步。

装好 Ollama 并拉取模型

Ollama 是本地模型引擎，推理全靠它。启动服务后拉两个模型：一个 7B 对话模型负责回答（qwen2.5 中文表现好），一个嵌入模型负责知识库向量化。模型下载是全程唯一需要联网的环节，拉完即可断网使用。

ollama serve # 服务常驻，建议放 tmux 或后台 # 新终端执行 ollama pull qwen2.5:7b ollama pull nomic-embed-text

让 init 指向本地模型

deeptutor init是引导式配置，跟着提示走：后端端口默认 8001、前端 3782；LLM 提供商选 Ollama，Base URL 填http://localhost:11434/v1，模型名填qwen2.5:7b；嵌入选nomic-embed-text。配置最终写在data/user/settings/（主要是model_catalog.json），之后随时可以在网页 Settings → Models 页微调，不必重复 init。

装依赖并起服务

创建虚拟环境，装后端与前端依赖，然后启动：

python3 -m venv .venv && source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e . ( cd web && npm ci --legacy-peer-deps ) deeptutor start

首次启动会构建一次web/前端，多花几分钟属正常；之后启动就快了。端口被占用时重新跑deeptutor init改端口即可，终端里Ctrl+C同时停掉前后端。

首次访问后做什么

启动后浏览器打开http://127.0.0.1:3782，第一屏就是聊天工作区：左侧栏挂着 Memory、Knowledge Center、Settings 等入口。先随便问一句，确认本地模型响应正常；再上传一份 PDF 到 Knowledge Center 建库，在输入栏选中它提问，就能看到"读过你的材料"和"没读过"的区别。不满意一个答案时，切换到 Quiz 或 Research 能力，本地模型也能出题和带引用地调研。

大概率会踩的坑

找不到模型或连接失败：多半是 Ollama 服务没起，或 Base URL 漏了/v1后缀。确认ollama serve在跑，把地址改成http://localhost:11434/v1。
回答慢、机器卡：7B 模型要吃约 8GB 内存，内存紧张就换成qwen2.5:3b重跑 init。
前端端口被占用：deeptutor init里改前端端口，启动日志会打印新地址。
Docker 里连不上本机 Ollama：容器内的 localhost 指向容器自己。Base URL 改为http://host.docker.internal:11434/v1，Linux 下启动时加--add-host=host.docker.internal:host-gateway。