DeepTutor 的安裝，是整個使用體驗裡唯一「技術門檻相對高一點」的地方——裝好了，後面就只是學習的事了。

這篇的目標很簡單：讓你在讀完之前，把 DeepTutor 跑起來。不管你是第一次自架服務的人，還是裝過很多東西的工程師，找到對應你情況的那個段落，按步驟走。

環境需求

在開始之前，確認你的機器符合這些最低需求：

項目	最低需求	建議
作業系統	Windows 10 / macOS 12 / Ubuntu 20.04	macOS 或 Linux
RAM	8GB	16GB 以上
儲存空間	10GB 可用	20GB 以上
Docker（方法一需要）	Docker Desktop 24+	最新版
Python（方法二需要）	Python 3.10+	Python 3.11
Node.js（方法二需要）	Node.js 18+	Node.js 20

LLM 後端另外需要 API Key（OpenAI、Anthropic 等），或是本地執行 Ollama 的環境。

安裝方法一：Docker（推薦新手）

Docker 安裝是最快的方式——幾個指令，不需要手動管理依賴套件。

Step 1：Clone 專案

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

Step 2：複製環境變數範本

cp .env.example .env

Step 3：設定 LLM 後端

用文字編輯器打開 .env，找到這幾個欄位：

# 選擇你的 LLM Provider（openai / anthropic / ollama）
LLM_PROVIDER=openai
 
# 填入對應的 API Key
OPENAI_API_KEY=sk-你的-api-key-在這裡
 
# 選擇模型
LLM_MODEL=gpt-4o

如果你用 Anthropic：

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-你的-key
LLM_MODEL=claude-3-5-sonnet-20241022

如果你想用本地 Ollama（完全不需要 API Key）：

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
LLM_MODEL=llama3.2

Step 4：啟動服務

docker compose up -d

第一次啟動會需要下載映像檔，視網路速度大約 3-10 分鐘。啟動完成後，打開瀏覽器前往：

http://localhost:3000

看到 DeepTutor 的歡迎畫面就代表成功了。

安裝方法二：原生安裝（適合開發者）

不想用 Docker、想直接跑 source code 的方式。

Step 1：Clone 並進入目錄

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

Step 2：安裝後端依賴

# 建立虛擬環境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
 
# 安裝 Python 套件
pip install -r requirements.txt

Step 3：安裝前端依賴

cd frontend
npm install
cd ..

Step 4：設定環境變數

cp .env.example .env
# 同上，編輯 .env 填入你的 LLM 設定

Step 5：啟動後端和前端

開兩個 terminal，分別執行：

# Terminal 1：後端
python main.py
 
# Terminal 2：前端
cd frontend && npm run dev

前端預設跑在 http://localhost:3000，後端 API 在 http://localhost:8000。

初始設定：第一次進入介面

裝好之後，有幾個地方建議在開始學習前先設定好。

1. 建立你的學習檔案

第一次登入後，DeepTutor 會引導你填寫基本的學習偏好：

學習目標：你想學什麼？（例如：「精通 Python 資料分析」、「準備英文 IELTS 7.0」）
目前程度：自我評估初級 / 中級 / 進階
學習風格偏好：偏好直接解說 vs 引導式提問（Socratic）

這些資訊會存入 DeepTutor 的持久記憶，影響後續所有互動的基調。寫仔細一點，後面少校正很多次。

2. 選擇 LLM 模型

在設定介面可以調整使用的模型。建議：

日常對話和測驗：gpt-4o-mini 或 claude-3-5-haiku（快、便宜）
Deep Solve 和 Deep Research：gpt-4o 或 claude-3-5-sonnet（準確度高）
本地優先：llama3.2（隱私，但效能較低）

3. 建立第一個 Knowledge Base（可選）

如果你手邊有學習材料，可以在這個階段就先建立知識庫。上傳 PDF 或 Markdown 文件，DeepTutor 會在背景做語義索引，通常幾分鐘內完成。

詳細的 Knowledge Base 使用方式會在系列第五篇專門講。

常見問題排查

Q：Docker 啟動後 localhost:3000 打不開

先看 container 有沒有正常跑：

docker compose ps

如果 backend 或 frontend 的狀態不是 Up，看 log：

docker compose logs backend
docker compose logs frontend

最常見的原因是 .env 裡的 API Key 填錯或留空。

Q：上傳 PDF 之後沒有反應

知識庫索引是非同步的，大檔案可能需要等幾分鐘。如果超過十分鐘還沒完成，在設定頁面重新觸發索引。

Q：使用 Ollama 但對話速度很慢

確認你的 Ollama 在正確的 port 跑起來，且 OLLAMA_BASE_URL 設定正確。如果是 macOS 並且有 Apple Silicon，確認 Ollama 有用上 Metal 加速。

Q：Windows 上的 Docker 遇到權限問題

確認 Docker Desktop 已啟用 WSL 2 後端，並且你的工作目錄在 C:\Users\ 下，而不是其他磁碟。

更新 DeepTutor

DeepTutor 開發活躍，建議定期更新：

# Docker 方式
git pull
docker compose pull
docker compose up -d
 
# 原生安裝方式
git pull
pip install -r requirements.txt  # 有新依賴時才需要

裝好之後

環境跑起來了，下一步是認識它的五種學習模式——Chat、Deep Solve、Quiz、Research、Math Animator，每一種有不同的使用時機和策略。

延伸閱讀：DeepTutor 五種模式完整解析：Chat、Deep Solve、Quiz、Research、Math Animator