DeepTutor 上手：港大开源 AI 家教，从 pip 安装、接模型到命令行出题的完整流程

01它能做什么

可以把它理解成一个自己部署的“AI 家教 + 资料库”。上传教材、讲义或指定 GitHub 仓库、文档站，它建成知识库；之后在同一个会话里让它讲概念、一步步解题、按资料出测验、写带引用的研究报告，或生成图表和讲解视频。学习记录会写进分三层的 Memory，可以直接查看和修改，不是黑箱。

适合想用自己的资料备考、自学一门课，或给学生、团队搭一个私有学习助手的人。它本身免费，但所有回答都调用你自己配置的大模型 API，费用由模型服务商收取。

02先选安装方式

1.7.0 起，pip 包分成两档：裸装 deeptutor 只有核心聊天、命令行和 SDK；deeptutor[full] 才包含 Web 界面和常用功能模块。官方一共给了四条路径：

03方法一：Docker 一条命令试用

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

浏览器打开 http://127.0.0.1:3782，在 Settings → Providers 填模型服务商的地址和 Key，再到 Language models 添加并选中模型。设置和数据保存在名为 deeptutor-data 的卷里，Ctrl+C 停止后下次还在。只需映射 3782 一个端口。（此方法按官方 README，本站沙箱没有 Docker，未实测。）

04方法二：pip 安装完整版

1. 建一个专用目录当“运行目录”，DeepTutor 的设置、密钥、会话都会放在它下面的 data/ 里。
2. 在虚拟环境里安装：pip install -U "deeptutor[full]"。
3. 运行 deeptutor init，按提示填后端端口（默认 8001）、前端端口（默认 3782）、模型服务商、Base URL、API Key 和模型名；嵌入模型和搜索服务可选，用知识库才需要嵌入模型。
4. 运行 deeptutor start，保持终端开着，浏览器打开 http://127.0.0.1:3782。

mkdir -p my-deeptutor && cd my-deeptutor
python3 -m venv .venv && source .venv/bin/activate
pip install -U "deeptutor[full]"
deeptutor init
deeptutor start

05不想交互式填写：用 config apply

给脚本或 AI 编程助手配置时，官方推荐写一个 setup.json，Key 不写进文件，只写环境变量名：

{
  "llm": {
    "provider": "openrouter",
    "model": "你选的模型 ID",
    "api_key_env": "DEEPTUTOR_SETUP_LLM_KEY"
  }
}

deeptutor init --non-interactive
export DEEPTUTOR_SETUP_LLM_KEY=你的Key
deeptutor config apply setup.json --check   # 只校验，不写入
deeptutor config apply setup.json
deeptutor doctor                            # 检查是否可用
deeptutor doctor --online                   # 真发一次小请求测连通

deeptutor config providers 会以 JSON 列出支持的服务商和默认地址，1.7.0 里包括 OpenRouter、硅基流动、AIHubMix 等网关，也能填 custom 接任意 OpenAI 兼容接口，或接本机的 Ollama、LM Studio。官方说明项目根目录的 .env 不会被读取，配置都在 data/user/settings/ 下。

06本站实跑结果

环境：Linux（aarch64）、Python 3.12.15、全新虚拟环境，DeepTutor 1.7.0，核对日期 2026 年 10 月 29 日。

本站没有真实的模型 Key，用占位 Key 跑 deeptutor run chat 时请求已发到 OpenRouter，返回 401 认证失败，所以没有测到实际回答质量；Web 界面也因上面的编译问题没有启动。表中只是单次、单环境的结果。

07常见报错

• 装 [full] 时 Building wheel for pystemmer 失败、提示找不到 gcc：说明当前平台没有现成的二进制包，需要先装编译工具（Debian/Ubuntu 上是 build-essential），或改用 Docker。
• doctor 显示 No active LLM model is configured：还没选中模型，回到 init、config apply 或 Settings → Language models。
• config apply 提示环境变量为空：setup.json 里写的是变量名，要在同一个终端 export 之后再运行。
• Docker 里连不上本机 Ollama：容器内的 localhost 是容器自己，Base URL 要写 http://host.docker.internal:11434/v1，Linux 上运行时加 --add-host=host.docker.internal:host-gateway。
• 知识库功能显示不可用：core 版不含 knowledge 模块，需要 [full]，并配置嵌入模型。

08命令行和给其他 Agent 调用

不打开网页也能用。deeptutor chat 进入交互式对话；deeptutor run 跑一轮就退出，加 --format json 会按行输出 JSON 事件，方便脚本或 Claude Code、Codex 之类的助手把它当工具调用。下面的命令按官方 README，本站未接通模型，未实测输出：

deeptutor kb create my-kb --doc textbook.pdf      # 用 PDF 建知识库
deeptutor run chat "解释傅里叶变换" --kb my-kb
deeptutor run deep_solve "Solve x^2 = 4" --kb my-kb
deeptutor run deep_question "按这本书出 5 道题" --kb my-kb
deeptutor memory show                            # 查看学习记忆
deeptutor module list                            # 看装了哪些模块

09使用前要知道的限制

• 费用：软件免费，但每次对话都会消耗你配置的模型额度。本站那次失败的请求，日志里单轮聊天的提示词预估约 5589 token（系统提示、工具说明等），实际用量取决于模型和功能，深度研究、生成书籍会更多。
• 默认单用户、无登录：要给多人用，需要在 auth.json 里开启认证，第一个注册的账号成为管理员。
• 代码执行：Office 文档类技能会运行模型生成的 Python 代码，官方提供 runner 容器和 bubblewrap 隔离，最后才退回受限子进程；对安全敏感的话可在 system.json 里把 sandbox_allow_subprocess 设为 false。
• 版本迭代很快：从 7 月到 10 月几乎每周一个版本，1.7.0 又改了安装方式，跟教程操作时以官方文档为准。