DeepTutor 本地部署指南

DeepTutor 本地部署指南（Windows 源码部署）

港大数据智能实验室（HKUDS）· 终身个性化 AI 辅导框架 · 2026-08

一、概述

DeepTutor 是香港大学数据智能实验室（HKUDS）开源的终身个性化 AI 辅导框架，支持本地私有化部署，数据不出本机。本文记录 Windows 环境下源码部署（Option 2） 的完整步骤，适用于开发/查看源码场景。

项目地址：https://github.com/HKUDS/DeepTutor

部署前置条件：
① Python 3.11–3.13（推荐 3.11）
② Node.js 20+（npm ci 需要）
③ Git（已 clone 源码到本地）
④ 可选：Ollama（本地大模型/Embedding）、自建 SearXNG 实例（搜索）

二、源码部署步骤（严格按顺序）

打开全新 PowerShell，进入源码根目录，依次执行：

第 1 步：创建并激活虚拟环境

cd 你的DeepTutor源码目录
py -3.11 -m venv .venv
..venvScriptsActivate.ps1
python -m pip install --upgrade pip</code></pre>

<div class="note">使用 <code>py -3.11</code> 指定 Python 3.11 创建虚拟环境，避免系统默认 Python 版本不匹配。</div>
<h3>第 2 步：以开发模式安装后端依赖</h3>
<pre><code>python -m pip install -e .</code></pre>
<p>这一步会把 DeepTutor 后端及全部依赖安装到虚拟环境（约 124 个依赖）。</p>
<h3>第 3 步：安装前端依赖（重点）</h3>
<pre><code>cd web

npm ci --legacy-peer-deps
cd ..</code></pre>

<div class="warn"><strong>易错点</strong>：之前「node 命令找不到」就是卡在这一步——npm 依赖安装失败会中断整个流程。<code>--legacy-peer-deps</code> 参数用于解决 Next.js 生态的 peer 依赖冲突，必须保留。</div>
<h3>第 4 步：初始化配置</h3>
<pre><code>deeptutor init</code></pre>
<p>初始化向导共 5 步，关键选择如下：</p>

<table>
<tr><th>步骤</th><th>选项</th><th>推荐</th></tr>
<tr><td>Step 1/5 · LLM 供应商</td><td>OpenAI / Anthropic / DeepSeek / SiliconFlow / 本地 Ollama 等</td><td><strong>推荐 SiliconFlow（10B以下免费）</strong>；本地推理可选 Ollama</td></tr>
<tr><td>Step 2/5 · LLM 模型</td><td>所选供应商支持的模型列表</td><td>选择已配置的模型</td></tr>
<tr><td>Step 3/5 · Embedding</td><td>OpenAI / Gemini / DashScope / SiliconFlow / Ollama 等 10 种</td><td><strong>本地 Ollama（nomic-embed-text）</strong>，无需 API Key</td></tr>
<tr><td>Step 4/5 · Web search</td><td>Brave / Tavily / Jina / SearXNG / DDG 等 8 种</td><td><strong>自建 SearXNG 实例</strong>（免费、私有）</td></tr>
<tr><td>Step 5/5 · 确认</td><td>汇总显示所有配置</td><td>确认无误</td></tr>


</table>
<h3>第 5 步：启动服务</h3>
<pre><code>deeptutor start</code></pre>
<p>启动成功后，浏览器打开：<code>http://127.0.0.1:3782</code></p>
<div class="info">如需前端热更新开发模式，使用 <code>deeptutor start --dev</code>。</div>
<h2>三、配置详解</h2>
<h3>1. LLM 供应商选择（省钱方案）</h3>
<p>LLM 是日常使用中最主要的成本来源。按 token 计费的商业 API（如 DeepSeek、OpenAI）跑长文本分析成本不低——一本书/一篇长文分析可能花掉数元。推荐使用 <strong>免费模型</strong> 控制成本。</p>
<div class="note"><strong>免费方案：硅基流动（SiliconFlow）——10B 以下模型免费</strong>：<br>
注册：<code>https://cloud.siliconflow.cn/</code><br><br>
<strong>可用免费模型</strong>（2026-08 实测）：<br>
✅ <code>Qwen/Qwen2.5-7B-Instruct</code>——通用对话，性价比高<br>
✅ <code>Qwen/Qwen3-8B</code>——新一代 Qwen3，推荐<br>
❌ <code>THUDM/glm-4-9b-chat</code>——<strong>已下架</strong>（不要再填）<br><br>
init 时选择 SiliconFlow 供应商，填入 API Key 和上述模型名即可。免费额度适用于 10B 以下模型，长文本分析基本零成本。</div>
<h3>2. Embedding 选择（RAG/知识库用）</h3>
<p>DeepTutor 的 RAG 知识库功能需要 Embedding 模型把文档向量化。可选供应商：</p>

<table>
<tr><th>选项</th><th>服务</th><th>说明</th></tr>
<tr><td>[1]</td><td>OpenAI</td><td>需要 OpenAI API Key</td></tr>
<tr><td>[2]</td><td>Gemini</td><td>Google 服务，需要 Key</td></tr>
<tr><td>[3]</td><td>Aliyun DashScope</td><td>国内可用，需阿里云 Key</td></tr>
<tr><td>[4]</td><td>SiliconFlow</td><td>国内模型聚合平台</td></tr>
<tr><td>[5]</td><td>Jina</td><td>多模态 Embedding</td></tr>
<tr><td>[6]</td><td>Cohere</td><td>海外服务</td></tr>
<tr><td>[7]</td><td>OpenRouter</td><td>模型聚合</td></tr>
<tr><td>[8]</td><td>Azure OpenAI</td><td>微软云</td></tr>
<tr><td>[9]</td><td>vLLM / LM Studio</td><td>本地推理框架（localhost:8000）</td></tr>
<tr><td><strong>[10]</strong></td><td><strong>Ollama</strong></td><td><strong>本地部署推荐</strong>（localhost:11434），无需 Key</td></tr>
<tr><td>[s]</td><td>Skip</td><td>跳过，稍后配置</td></tr>
<tr><td>[c]</td><td>Custom</td><td>自定义 API 地址</td></tr>


</table>
<div class="note"><strong>本地 Ollama + nomic-embed-text 配置</strong>：<br>
① 先安装 Ollama 并拉取模型：<code>ollama pull nomic-embed-text</code><br>
② init 时选 [10] Ollama，填入 <code>http://localhost:11434</code> 和模型名<br>
③ 知识库向量化完全在本地完成，数据不出机</div>
<h3>3. Web Search 选择（联网搜索）</h3>

<table>
<tr><th>选项</th><th>服务</th><th>说明</th></tr>
<tr><td>[1]</td><td>Brave Search</td><td>独立索引，付费档</td></tr>
<tr><td>[2]</td><td>Tavily</td><td>LLM 友好，免费档</td></tr>
<tr><td>[3]</td><td>Jina Reader</td><td>返回完整页面内容</td></tr>
<tr><td>[4]</td><td>Serper</td><td>Google 结果，付费</td></tr>
<tr><td>[5]</td><td>Perplexity</td><td>答案式搜索</td></tr>
<tr><td>[6]</td><td>DuckDuckGo</td><td>无需 API Key</td></tr>
<tr><td><strong>[7]</strong></td><td><strong>SearXNG</strong></td><td><strong>自建实例推荐</strong>——填自己的实例 URL</td></tr>
<tr><td>[8]</td><td>Disable</td><td>禁用搜索</td></tr>
<tr><td>[s]</td><td>Skip</td><td>跳过，稍后配置</td></tr>


</table>
<div class="note"><strong>自建 SearXNG 配置</strong>：<br>
① 在服务器部署 SearXNG（pip/Docker 均可）<br>
② init 时选 [7] SearXNG，填入实例 URL（如 <code>http://你的服务器地址/searxng</code>）<br>
③ DeepTutor 自动调用 <code>/search?q=...&format=json</code> API 获取结果</div>
<h2>四、验证与使用</h2>

<ol>
<li>启动 <code>deeptutor start</code> 后访问 <code>http://127.0.0.1:3782</code></li>
<li>在设置页确认 LLM / Embedding / Search 三项均已配置</li>
<li>测试对话：问一个需要联网搜索的问题，确认 Web Search 生效</li>
<li>测试知识库：上传 PDF 文档，确认 RAG 检索正常</li>


</ol>
<div class="warn"><strong>注意事项</strong>：<br>
① 首次启动会初始化前端构建产物，耗时数分钟属正常<br>
② 数据默认存储在项目 <code>data/</code> 目录，可整体备份迁移<br>
③ 项目迭代快（每周发版），如遇问题以官方 README 为准：<code>https://github.com/HKUDS/DeepTutor</code></div>
<h2>五、部署架构示意</h2>
<pre><code>┌──────────────┐     ┌──────────────┐     ┌──────────────┐

│  浏览器访问   │────▶│  DeepTutor   │────▶│  LLM API /    │
│  :3782       │     │  (本地)      │     │  Ollama       │
└──────────────┘     └──────┬───────┘     └──────────────┘


│
├────▶ Embedding（本地 Ollama）
│
└────▶ Web Search（SearXNG 实例）</code></pre>

<div class="note"><strong>技术栈</strong>：Python 3.11+（后端）· Next.js 16（前端）· 三层记忆（L1 轨迹 / L2 摘要 / L3 综合）· LlamaIndex RAG · Agent 运行时</div>
</div>