技术分享 | 本地部署 DeepTutor避坑指南

type

status

date

slug

summary

🧠

作者：龚老师 | 更新于 2026 年 1 月

大家好，我是龚老师。

最近在尝试本地部署 DeepTutor（基于 LightRAG 构建的智能教学系统）时，遇到了各种“看似简单却卡半天”的问题。记录一下一次成功地完成本地部署和踩的坑。

💡 核心结论提前说：
别用 Python 3.13或Python 3.14！，直接选 Python 3.12.8！
PATH 变量要精简，系统和用户路径必须分开！

🔥 问题复现：为什么 `pip install -e ".[api]"` 总是失败？

我本地的Pythonm的环境：

Windows 11

Python 3.13（最新版）

执行 python -m pip install -e ".[api]" 时报错：

表面看是“缺少编译器”，但根本原因不是没装 Visual Studio，而是：

✅ NumPy 1.26.4 尚未为 Python 3.13 以上的版本提供预编译 wheel 包
→ pip 被迫从源码编译 → 需要 C++ 编译环境 → 失败

即使你手动升级到 NumPy 2.4.1（支持 3.13），LightRAG 的 pyproject.toml 却锁死了 numpy<2.0.0，导致 pip 仍会尝试安装旧版——死循环！

✅ 正确姿势一：坚决使用 Python 3.12

📌 龚老师建议：
除非你是 Python 核心开发者，否则永远不要在新项目中使用刚发布的 Python 主版本！

截至 2026 年初：

Python 3.13 有些包不支持

NumPy / Pandas / PyTorch / TensorFlow 等核心库 官方仅支持到 Python 3.12

大量依赖库尚未提供 cp313 的 wheel 包

✔️ 操作步骤：

卸载 Python 3.13（控制面板 → 程序和功能）

下载 Python 3.12.8 官方安装包，记得下载Windows版本：👉 https://www.python.org/downloads/release/python-3128/

安装时务必勾选 “Add Python to PATH”

验证：

✅ 安装后，pip install -e ".[api]" 将直接下载预编译的 NumPy wheel，秒级完成，零编译！

✅ 正确姿势二：彻底清理并优化 PATH 环境变量

我的 PATH 长达 3000+ 字符，包含大量重复项（如 cursor、WindowsApps 出现 4 次）、用户路径混入系统变量、甚至错误地加入了 .exe 文件（如 msedgedriver.exe）。

这会导致：

系统启动变慢

命令冲突（比如两个 python.exe）

触发 Windows PATH 2047 字符限制（GUI 无法编辑）

🧹 龚老师推荐的 PATH 分离原则：

类型	应包含内容	示例
系统 PATH	全局工具、系统目录	`C:\Python312\`, `C:\Windows\system32`, `C:\Program Files\Git\cmd`
用户 PATH	个人软件、开发工具	`D:\PyCharm\bin`, `C:\Users\Miro\AppData\Roaming\npm`, `D:\ffmpeg\bin`

🔧 精简后的系统 PATH（仅 10 项）：

💡 用户 PATH 保留你的 VS Code、PyCharm、FFmpeg、npm 等，绝不放入系统变量！

这样既干净，又避免权限和兼容性问题。

✅ 正确姿势三：一键启动脚本（告别多终端切换）

官方部署教程：

上面两个命令一个是在powershell中运行，一个是在cmd终端运行，不过其实完全可以用一个脚本搞定！

创建 `start_deep_tutor.ps1`（PowerShell 版）：

使用方法：

将文件放在 DeepTutor/ 根目录

右键 → “使用 PowerShell 运行”

自动安装 + 启动，一站式完成！

⚠️ 首次运行需允许脚本执行（管理员权限非必需）：

🎯 总结：龚老师的“三不原则”

不追新：不用 Python 3.13，选 3.12

不混杂：系统 PATH 和用户 PATH 严格分离

不手动：用脚本自动化安装与启动

按照以上方法，你可以在 10 分钟内完成 DeepTutor 的本地部署，无需折腾编译器、无需反复开关终端。

💬 最后的话

技术探索的路上，踩坑是常态。但聪明的开发者，会把坑变成路标。希望这篇文章能帮你少走弯路，更快体验到 DeepTutor 的强大能力。

如果你成功部署了，欢迎在评论区分享你的经验！也欢迎关注我的 Notion 技术专栏，我会持续更新 AI 教育工具的实战指南。

—— 龚老师 · 2026 年 1 月于三亚

🧠