开发环境:从零搭好一套可复现的工具链

开发环境:从零搭好一套可复现的工具链

本节摘要:你的工具塑造你的思考——把它们一次性装对,后面 200 多节课都不再和工具打架。大多数人在环境上偷懒,然后花几十个小时去排查 import 报错、版本冲突、缺失的 CUDA 驱动。本节要把这件事一次做对:从一个干净的系统出发,自底向上搭起 AI 工程环境的四层栈(系统底座 → 包管理器 → 语言运行时 → AI/ML 库),用 uv、pnpm、cargo、juliaup 这些现代包管理器保证可复现的构建,在 NVIDIA CUDA 与 Apple Silicon MPS(Metal Performance Shaders)上各跑一遍 GPU 张量运算来验证。读完本节,你会有一套能在每节课直接复用的开发环境,以及一段帮助 AI 助手诊断环境问题的可复用提示。

对应原课程:Phase 00 · Lesson 01 · dev-environment(原英文 phases/00-setup-and-tooling/01-dev-environment/docs/en.md)。本节为全章首节,也是整本教程的起点,前置依赖为「无」。

学习目标

阅读完本节,你应当能够:

1. 从零安装 Python 3.11+、Node.js 20+、Rust(以及可选的 Julia)四套工具链。
2. 用 uv、pnpm 等现代包管理器配置虚拟环境,保证构建可复现。
3. 用 nvidia-smi、torch.cuda、torch.backends.mps 等手段验证 GPU 访问,并跑通一次张量运算。
4. 说清 AI 工程环境的四层栈(系统底座、包管理器、语言运行时、AI/ML 库)及其依赖方向。

一、问题与直觉

接下来的 200 多节课里,你会用到 Python、TypeScript、Rust,偶尔还有 Julia。如果环境是坏的,每一节课都会变成一场和工具链的拉锯战——本来该学 AI,结果一晚上都在调包。

很多人图省事跳过环境配置,然后陷入 ImportError、版本冲突、CUDA driver not found 这类问题的泥潭。本节的主张是:这件事做一次,做对。

AI 工程环境有清晰的四层结构,自底向上叠加:

安装顺序是自底向上的——每一层都依赖它下面那一层。系统底座没装好,上面的运行时就装不稳;运行时不一致,装再多 AI 库也是空中楼阁。

💡 这张四层图是本节的心智模型。后面每遇到「为什么装不上」,都回到这张图去找断点在哪一层。

二、从零实现

下面按四层栈自底向上搭建。完整命令与验证脚本见原课程 phases/00-setup-and-tooling/01-dev-environment/code/,本节给出关键步骤与设计要点。

Step 1 系统底座

按操作系统装好编译工具链、Git、curl、wget。Windows 用户走 WSL2 路线,不要在原生 cmd 里硬撑:

# macOS
xcode-select --install
brew install git curl wget

# Ubuntu / Debian
sudo apt update && sudo apt install -y build-essential git curl wget

# Windows(用 WSL2)
wsl --install -d Ubuntu-24.04
​

Step 2 Python(用 uv)

本课程全程使用 uv 而非裸 pip——它比 pip 快 10~100 倍,且自动处理虚拟环境:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12
uv venv
source .venv/bin/activate      # Windows 用 .venv\Scripts\activate
uv pip install numpy matplotlib jupyter
​

设计要点:用 uv venv 生成的 .venv 目录,是「可复现构建」的最小单位。本课程每章(或每个项目)建议各开一个独立 venv,互不污染。

装完用一段最小验证脚本确认 Python 与 NumPy 就位:打印版本号,做一个向量点积,看结果是不是 14(1²+2²+3²)。

Step 3 Node.js(用 pnpm)

TypeScript 那部分课(Agent、MCP 服务器、Web 应用)需要 Node。推荐用 fnm 管 Node 版本,再用 pnpm 装包:

curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22 && fnm use 22
npm install -g pnpm
​

⚠️ Apple Silicon 用户注意:若安装卡在 Cannot install under Rosetta 2 in ARM default prefix,说明你的终端跑在 Rosetta 2 下(运行 arch 会输出 i386),而 Homebrew 是原生 arm64 版。解决办法是强制走 arm64 装 fnm 并写进 shell 配置:arch -arm64 brew install fnm,再 echo 'eval "$(fnm env --use-on-cd)"' >> ~/.zshrc,然后重跑上述命令。

Step 4 Rust

性能关键课(推理引擎、底层系统)用 Rust。一条 rustup 命令搞定,顺带把 cargo(包管理器/构建工具)也装上。

Step 5 Julia(可选)

数学密集的课里 Julia 表现很好,可装可不装。用官方 julialang.org 安装脚本即可,包管理器是内置的 Pkg。

Step 6 GPU 配置(如果有)

NVIDIA(Linux / Windows):先 nvidia-smi 确认驱动在,再按 CUDA 版本(本课程用 cu124)装 PyTorch:

uv pip install torch torchvision torchaudio \
    --index-url https://download.pytorch.org/whl/cu124
​

macOS / Apple Silicon(M1~M4):Mac 上没有 CUDA,这是预期行为,不是故障。不要再加 --index-url .../cuXXX(那些 wheel 只为 Linux/Windows 构建,Mac 上必装失败),装默认构建即可,它会自动带上 Apple 的 MPS 后端:

import torch
print(torch.cuda.is_available())          # macOS 上为 False —— 预期
print(torch.backends.mps.is_available())   # Apple Silicon 上为 True
​

💡 没有 GPU 也不要紧。本课程大部分课在 CPU 上能跑;少数训练密集的课,可以用 Google Colab 或租云端 GPU(见第 03 节)。

Step 7 一次性验证

跑原课程提供的验证脚本,一把校验上述四层都通:

python phases/00-setup-and-tooling/01-dev-environment/code/verify.py
​

三、框架对比:四种语言各司其职

环境装好后,四种语言在整个课程里有明确的分工——选错语言等于把工具用错地方:

💡 注意这条规律:研究/建模用 Python,工程/编排用 TypeScript,性能瓶颈用 Rust。这也是当下工业界 AI 系统的主流分工。第 03 节会专门讲 GPU 配置与云端,第 06 节会深入 Python 环境管理。

四、可复用产物

本节产出两个可复用文件(位于原课程 outputs/):

• prompt-env-check.md:一个提示词,喂给 AI 助手,让它根据你贴报错信息诊断环境问题,并给出修复命令。把本节装好的版本号、操作系统、报错堆栈贴进去,就能拿到针对性建议。
• verify.py(code/ 目录):一个独立验证脚本,任何机器上一跑就知道哪一层断了。可作为新机器初始化后的自检。

五、练习

1. (Easy) 跑 verify.py,把所有失败的检查项修绿;若机器没有 GPU,确认脚本能在纯 CPU 模式通过。
2. (Medium) 为本课程单独建一个 Python 虚拟环境(用 uv venv),在里面装好 PyTorch,写一个在 CPU/CUDA/MPS 三个后端中自动选可用后端的小函数,返回所用设备名。
3. (Hard) 用四种语言各写一个「hello world」并跑通;进一步,在 Rust 里写一个返回前 N 个斐波那契数的函数,用 cargo bench 跑基准,再写一个等价的 Python/NumPy 版本对比耗时,体感「性能关键用 Rust」到底快多少。

本节要点回顾

1. 环境是地基:AI 工程环境是四层栈(系统底座 → 包管理器 → 语言运行时 → AI/ML 库),自底向上安装,断点总在底层。
2. 一次做对:跳过环境配置省下的 1 小时,会变成后面几十个小时的排错时间。
3. Python 用 uv 而非裸 pip:快 10~100 倍,自动管虚拟环境,构建可复现。
4. GPU 区分平台:NVIDIA 走 --index-url .../cuXXX,Apple Silicon 走默认构建(自带 MPS);Mac 上没 CUDA 是预期行为。
5. 没有 GPU 也能学:大部分课在 CPU 上跑得动,训练密集课用 Colab 或云端。
6. 语言分工:Python 做研究建模,TypeScript 做工程编排,Rust 做性能瓶颈,Julia 可选做数学。
7. 可复用产物:verify.py 自检脚本与 prompt-env-check.md 诊断提示,任何机器复用。

下一节,我们将进入「Git 与协作」——把这套环境纳入版本控制,为团队协作与可复现实验打下第二块地基。