- 示例工程
【免费下载链接】reasoning-from-scratch
Implement a reasoning LLM in PyTorch from scratch, step by step
本篇指南面向reasoning-from-scratch仓库（一本从零用 PyTorch 实现推理大模型的实战教程）的读者，完整覆盖两条主流的 Python 环境搭建路径（内置的pip与现代包管理器uv），说明各章代码所需的 Python 版本选型与依赖清单，并给出 Lightning Studio 与 Google Colab 两类云端 GPU 平台的具体操作步骤。读完本篇，你将能在本地或云端顺利运行ch02及后续章节的 Notebook、Python 脚本与对话式推理界面。
一、环境需求概览：依赖极少，但 Python 版本有讲究
本仓库代码整体自包含，作者刻意将外部依赖压到最少，全书仅依赖少量必需的 Python 包。仓库根目录的 pyproject.toml 声明了项目元信息与运行期依赖，其dependencies字段（pyproject.toml）列出了核心依赖：
dependencies = [ "jupyterlab>=4.4.7", "torch>=2.10,<3", # 2.10.0 is the version originally used in the book "tokenizers>=0.21.2", "nbformat>=5.10.4", "setuptools>=61.0", "sympy>=1.14.0", # For verifier in ch03 "matplotlib>=3.10.7", ]其中sympy服务于第 3 章的数学验证器（verifier），matplotlib用于训练指标绘图（如第 6、7 章），jupyterlab与nbformat支撑 Notebook 运行，tokenizers则被第 2 章的 Qwen3 分词器实现所依赖。
Python 版本选型：本书写作时使用 Python 3.12，但 pyproject.toml 将支持范围放宽为requires-python = ">=3.10,<3.15"，即 Python 3.10～3.14 均可，前提是所选版本获得 PyTorch 官方支持（PyTorch 通常比最新 Python 发行晚几个月才提供对应版本支持，因此刚发布的新 Python 版本不建议立即使用）。可用以下命令查看当前版本：
python --version一个例外：附录 G 的聊天界面（chG/01_main-chapter-code）必须使用 Python 3.13。原因在于该界面基于 Chainlit 实现（见 chG/01_main-chapter-code/qwen3_chat_interface.py 中的import chainlit），而 Chainlit 目前不支持 Python 3.14。这一点在 pyproject.toml 的 optional-dependencies 中也有限制性标记："chainlit>=2.8.3; python_version < '3.14'"。若你在 Python 3.14 下安装仓库的extra依赖，Chainlit 会被自动跳过。
如果本地 Python 版本过旧（3.9 及以下），建议从 python.org 安装新版，或用pyenv这类版本管理工具切换，但务必先到 PyTorch 官网确认该 Python 版本已被 PyTorch 支持。
二、方案一：用内置pip安装（通用且简单）
pip是 Python 自带的标准安装器，几乎在所有环境都能用。按需安装核心包：
pip install torch jupyterlab也可以一次性安装本书用到的全部依赖。仓库根目录提供了一份 requirements.txt，其内容与pyproject.toml的依赖清单一致：
reasoning-from-scratch >= 0.1.2 setuptools>=61.0 sympy>=1.14.0 # For verifier in ch03 torch >= 2.10, < 3 tokenizers >= 0.21.2使用方式：
pip install -r https://raw.githubusercontent.com/rasbt/reasoning-from-scratch/refs/heads/main/requirements.txtrequirements.txt同时声明了reasoning-from-scratch >= 0.1.2这一自引用包依赖，即把仓库自身的代码包安装进环境；当前仓库的 reasoning_from_scratch/init.py 中定义的版本号为__version__ = "0.2.0"，满足该约束。安装后即可直接以包形式导入各章节代码，例如第 2 章对话脚本（ch02/05_use_model/chat.py）通过from reasoning_from_scratch.ch02 import get_device, generate_stats与from reasoning_from_scratch.qwen3 import Qwen3Model调用仓库实现。
三、方案二：使用uv（更快、更现代，官方推荐）
uv是新一代 Python 包管理器，能自动完成虚拟环境创建、快速安装、lockfile 可复现安装，并兼容pip风格的命令。它是本项目作者推荐并亲自使用的工具。
3.1 安装uv
macOS / Linux：
curl -LsSf https://astral.sh/uv/install.sh | shWindows（PowerShell）：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"安装完成后，可用uv pip install复刻上述pip用法：
uv pip install torch jupyterlab不过既然使用uv，更推荐直接用uv的原生命令工作流，而不是uv pip。
3.2 推荐的uv原生工作流
克隆仓库并进入目录：
git clone https://github.com/rasbt/reasoning-from-scratch.git cd reasoning-from-scratch仓库根目录的 pyproject.toml 已声明所有必需依赖。uv会在首次运行脚本或打开 Jupyter Lab 时，自动为项目创建一个默认隐藏的虚拟环境目录.venv，并把全部依赖装入其中，无需手动venv激活操作。
仓库没有.python-version文件（已核对仓库根目录）。如需为本地uv环境固定 Python 3.13（例如为附录 G 做准备），执行：
uv python pin 3.13 uv sync一般情况下不必额外安装包；若确需添加不在pyproject.toml里的包，使用uv add，它会同时把包写入虚拟环境与pyproject.toml：
uv add llms_from_scratch3.3 通过uv运行代码
打开 Jupyter Lab：
uv run jupyter lab运行 Python 脚本：
uv run python script.py仓库已提交的 uv.lock 将 PyTorch 锁定为 2.10.0（即本书最初编写代码所用的版本），因此常规uv run默认使用 PyTorch 2.10.0。lockfile 是跨平台可用的：uv会按运行平台自动挑选合适的包与二进制（从 uv.lock 可以看到，Linux aarch64 平台会解析到torch 2.10.0+cu130的 CUDA 构建，其余平台解析到 PyPI 的torch 2.10.0）。pyproject.toml同时允许更新的 PyTorch 2.x 版本，如需升级本地 lockfile 中的 PyTorch：
uv lock --upgrade-package torch该命令只需执行一次，之后的uv run都会使用更新后的版本（注意它会修改本地的uv.lock）。想恢复仓库自带的版本：
git restore uv.lock uv sync3.4 JupyterLab 滚动显示异常的规避
若在 JupyterLab（而非 VSCode）中查看 Notebook，需要注意近期版本默认设置下存在滚动显示 bug。建议通过Settings -> Settings Editor将 "Windowing mode" 改为 "none"，可有效规避该问题。这也是在本仓库环境下阅读ch02、ch03等各章 Notebook（如 ch02/01_main-chapter-code/ch02_main.ipynb）时的实用建议。
四、云端 GPU：无需本地显卡也能加速跑完全书
本书代码在普通笔记本、台式机（无独立 GPU）上均可运行，但第 5～7 章的预训练与微调任务耗时显著，接入 NVIDIA GPU 的云平台能大幅缩短运行时间。以下是官方推荐的两类云端方案。
4.1 Lightning Studio：持久化环境，CPU/GPU 自由切换
Lightning AI Studio 提供持久化云开发环境，同时支持 VSCode 与 Jupyter Lab，可在云端 CPU 与 GPU 上运行。启动新 Studio 后，在终端执行：
git clone https://github.com/rasbt/reasoning-from-scratch.git cd reasoning-from-scratch pip install -r requirements.txt与 Google Colab 不同，Lightning Studio 环境是持久化的——即使在 CPU 与 GPU 机器之间切换，上述命令也只需执行一次。之后即可导航到要运行的 Python 脚本或 Jupyter Notebook；可选地挂载 GPU 加速代码运行，例如第 5 章预训练 LLM、第 6、7 章微调时。
4.2 Google Colab：零门槛上手
使用 Colab 时，前往 colab.research.google.com，从 GitHub 菜单打开对应章节的 Notebook，或直接把 Notebook 拖入Upload上传区域。关键一步：除 Notebook 本身外，还必须把 Notebook 所依赖的数据集文件与.py文件（如 Notebook 内import的模块）一并上传到 Colab 环境，否则运行会因找不到文件而失败。可选操作：通过Runtime设置切换 GPU 运行时。
五、常见问题与排查路径
- 本地机器跑不动？普通 CPU 即可运行全书代码，只是第 5～7 章耗时长；需要加速时再按上文接入云端 GPU。
- Python 版本不匹配？优先使用 3.10～3.13；附录 G 强制 Python 3.13；新发布的 Python 版本需等待 PyTorch 跟进支持。
uv命令报错？若pyproject.toml中的[tool.uv] exclude-newer配置（其值为 "7 days"）无法被当前uv解析，先执行uv self update升级uv再重试。- 安装验证：环境就绪后，可运行第 2 章的对话脚本（ch02/05_use_model/chat.py）做冒烟测试，脚本支持
--device（自动检测cuda/mps/xpu/cpu）与--max_new_tokens（默认 2048）等参数；get_device()的实现（reasoning_from_scratch/ch02.py）会按 CUDA GPU、Apple Silicon MPS、Intel GPU、CPU 的顺序自动选择设备，并自动启用 TF32 张量核加速。
两条安装路径（pip与uv）与两类云平台（Lightning Studio 与 Colab）覆盖了从纯新手到资深用户的使用场景；官方鼓励在仓库的 Discussions 论坛提问交流。选择最适合你的方案，即可无缝开始从零构建推理模型的实践旅程。
- 示例工程
【免费下载链接】reasoning-from-scratch
Implement a reasoning LLM in PyTorch from scratch, step by step
相关推荐
reasoning-from-scratch 项目 Python 环境搭建指南：从 pip 到 uv 的完整安装与运行方案
reasoning from scratch 项目 Python 环境搭建指南：从 pip 到 uv 的完整安装与运行方案 本指南以《Build a Reaso
示例工程reasoning-from-scratch 云 GPU 环境搭建指南：用 Lightning Studio 与 Google Colab 跑通推理与训练
reasoning from scratch 云 GPU 环境搭建指南：用 Lightning Studio 与 Google Colab 跑通推理与训练 本篇
示例工程LLMs-from-scratch 环境搭建全攻略：本地（uv/Conda/Docker）与云端（Colab/Lightning/SageMaker）多方案详解
LLMs from scratch 环境搭建全攻略：本地（uv/Conda/Docker）与云端（Colab/Lightning/SageMaker）多方案详解
示例工程大模型人工智能
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
