第 01 章 · 课程说明与环境安装准备

这一章要解决什么：把环境装好，把数据生成出来，跑通第一个脚本。这一章结束时，你手上应该有一个能运行后面所有示例的、干净隔离的 Python 环境。
本章内容比后面几章"琐碎"，但请务必完整走一遍。环境问题占了零基础学员卡壳原因的 80%，而它们全都出现在这一步。

1.1 先说清楚：这一章做完，你应该看到什么

按顺序做完本章，你应该能：

在命令行里运行 python --version，看到 3.10 以上的版本号；
解压下载包，看到 code/ 目录里有 data/battery/ 和 3 个 CSV；
运行 python check_env.py，看到全部 ✅；
自己新建 demos/ch03-types.py，把书里的代码敲进去；
运行它，看到 额定容量 2.5 Ah，电压 3.7 V，温度 25 ℃。

如果这 5 步有任意一步不通过，请在这一章解决掉，不要带着问题往下学。

1.2 三个概念：解释器、包、虚拟环境

在动手之前先把这三个词弄清楚，后面所有命令你都能看懂。

① Python 解释器 —— 那个真正"跑"你代码的程序

你写的 .py 文件是文本，计算机看不懂。解释器负责把它翻译成机器能执行的指令。

bash

python --version      # 查看解释器版本
python hello.py       # 让解释器去跑 hello.py

为什么强调版本：本书的代码用到了 Python 3.9+ 才有的语法（比如 list[float] 这种内置泛型注解）。 3.8 及更早版本会报 TypeError: 'type' object is not subscriptable。

本课程要求 Python 3.10 以上，推荐 3.12 或 3.13。

② 包（package）—— 别人写好的代码库

Python 自带一个"标准库"（os、csv、json、math…），不用装就能用。但 NumPy、Pandas、Matplotlib 这些是第三方包，需要单独安装：

bash

pip install numpy pandas matplotlib

pip 是 Python 的"应用商店"。

中国网络提示：如果下载很慢或超时，可以换国内镜像源：

bash

pip install numpy pandas matplotlib -i https://pypi.tuna.tsinghua.edu.cn/simple

③ 虚拟环境 —— 每个项目一个独立的"包抽屉"

这是最重要、也是新手最容易忽略的概念。

问题：如果你把所有包都装在全局（系统级），那么：

A 项目要 pandas 1.5，B 项目要 pandas 3.0 —— 装哪个？装了 A 就坏 B；
系统自带的 Python 往往被其他软件依赖，装错版本可能弄坏它们；
换一台电脑，你不知道该装哪些、什么版本。

解决：每个项目建一个独立的虚拟环境（就是一个文件夹），里面有自己的 Python 和包：

你的项目/
├── .venv/            ← 虚拟环境（一个目录，可以随时删掉重建）
│   ├── bin/python          这个项目专用的 Python
│   └── lib/…/site-packages 这个项目专用的包
└── code/             你的代码

关键：激活虚拟环境后，python 和 pip 命令指向的都是这个环境里的，不会影响系统和其他项目。

推论：虚拟环境目录不要提交到 git，不要手动改里面的文件，坏了就删掉重建。它只是一堆可以从 requirements.txt 重新装出来的文件而已。

1.3 安装 Python

Windows

打开 https://www.python.org/downloads/windows/，下载 Windows installer (64-bit)；
运行安装包，务必勾选最下面的 Add python.exe to PATH（不勾后面要在命令行里手动配路径，很麻烦）；
点 Install Now，等 1~2 分钟；
打开 PowerShell（按 Win 键，输入 powershell），验证：

powershell

python --version

看到 Python 3.12.x 之类就成功了。

Windows 常见问题：`python` 打开了微软应用商店

这是 Windows 自带的一个"应用别名"，会劫持 python 命令。解决办法：

打开「设置」→「应用」→「高级应用设置」→「应用执行别名」；
把 python.exe 和 python3.exe 两个开关都关掉；
重新打开 PowerShell，再试 python --version。

如果还是不行，用 py --version 也可以（这是 Windows 官方的 Python 启动器）。后面所有命令里的 python 都可以换成 py。

macOS

方式 A（推荐）：官网安装包

打开 https://www.python.org/downloads/macos/，下载 macOS 64-bit universal2 installer；
双击运行，一路继续（会自动装好证书和 PATH）；
打开「终端」（Command + 空格 输入 terminal），验证：

bash

python3 --version

方式 B：Homebrew（如果你已经装了 Homebrew）

bash

brew install python@3.12

macOS 注意：命令是 python3 不是 python

macOS 系统自带的 /usr/bin/python3 是 Apple 给开发者工具用的版本，不要动它。

习惯上 macOS 里写 python3。如果你想让 python 也能用，可以在 ~/.zshrc 里加一行别名：

bash

echo 'alias python=python3' >> ~/.zshrc && source ~/.zshrc

本课程后面的命令统一写 python。macOS 用户请自行替换成 python3。

Linux（Ubuntu / Debian）

bash

sudo apt update
sudo apt install -y python3 python3-pip python3-venv
python3 --version

1.4 拿到配套数据包

★ 先明确一件事：本课程不提供示例代码和练习答案

下载包里只有数据和环境工具，没有代码。

这是有意设计的：

直接跑别人写好的代码	自己敲一遍
结果出来了，但不知道每行在干什么	每一行你都写过了
遇到报错不知道从哪查	报错是你自己触发的，你知道触发点在哪
改一个地方就崩	你知道哪里能改、改了会怎样
收益接近于零	形成肌肉记忆

对零基础来说，敲代码本身就是学习。

代码在书里：

每章的「可运行示例」小节给了完整代码 + 真实输出，照着敲即可；
练习答案在每章末尾是折叠的 —— 先自己写，跑出结果，再点开对照；
卡住时先看那一章的「常见坑」，那里列了报错信息和修法。

"照着书敲"也算抄，但这是有价值的抄 —— 因为你会亲手打出每一个括号、看到每一个输出、撞上每一个坑。

下载数据包

请下载 ai-python-quick-start-code.zip（约 400 KB），解压后结构如下：

ai-python-quick-start/
└── code/                    ← 你的工作目录（后面所有命令都在这里执行）
    ├── README.md            依赖说明 / 数据字段与公式 / 校验和 / 常见问题
    ├── requirements.txt     需要装哪些包
    ├── check_env.py         环境自检
    └── data/
        └── battery/
            ├── cycle_raw.csv   干净数据（13,967 行）
            ├── dirty.csv       脏数据（含缺失与异常）
            ├── cells.csv       电芯级真值
            └── README.md       字段 / 公式 / 量纲 / 局限

注意：包里没有 demos/、exercises/、src/。这三个目录要你自己边学边建：

code/
├── demos/                   ← 第 03 章起，你自己敲的示例
│   ├── ch03-types.py
│   └── …
├── exercises/               ← 你自己敲的练习
│   └── ex04-03-types/
│       ├── exercise.py
│       └── solution.py
└── outputs/                 ← 脚本产出的图和报告（会自动创建）

1.5 创建虚拟环境并安装依赖

打开终端，cd 到 code/ 目录，然后按你的情况选一条路。

路线一：标准 venv + pip（推荐给所有人，最通用）

bash

cd code

# ① 创建虚拟环境（只需要做一次）
python -m venv .venv

# ② 激活它
#    macOS / Linux：
source .venv/bin/activate
#    Windows PowerShell：
.venv\Scripts\Activate.ps1
#    Windows CMD：
.venv\Scripts\activate.bat

# ③ 激活成功后，命令行前面会出现 (.venv) 字样
#    确认一下 python 指向的是虚拟环境里的
python -c "import sys; print(sys.executable)"
#    应该输出 .../code/.venv/bin/python 或 ...\code\.venv\Scripts\python.exe

# ④ 安装依赖
pip install -r requirements.txt

# ⑤ 验证
python check_env.py

Windows PowerShell 报错：无法加载文件 ... Activate.ps1，因为在此系统上禁止运行脚本

这是 PowerShell 的执行策略限制。以管理员身份打开 PowerShell，运行：

powershell

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

输入 Y 确认，然后回到普通 PowerShell 重新激活。

或者改用 CMD（命令提示符），用 .venv\Scripts\activate.bat 激活，不会有这个问题。

python -m venv .venv 报错 No module named venv

Linux 上常见，说明缺 python3-venv 包：

bash

sudo apt install python3-venv

Windows/macOS 官方安装包默认自带，一般不会遇到。

路线二：uv（更快，如果你已经熟悉命令行）

uv 是新一代 Python 包管理器，比 pip 快 10~100 倍，还能自动管理 Python 版本。

bash

# 安装 uv（macOS / Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell：
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

cd code
uv venv                      # 创建 .venv
uv pip install -r requirements.txt
uv run python check_env.py   # uv run 会自动用 .venv 里的解释器

用 uv 的话，不需要手动激活虚拟环境 —— 加 uv run 前缀就行，它会自动找到 .venv。

后面的示例命令都可以这样写：

bash

uv run python demos/ch03-types.py

本书其余部分统一写 python xxx.py。uv 用户自行在前面加 uv run。

依赖清单（`requirements.txt`）

numpy>=2.0
pandas>=2.0
matplotlib>=3.8

为什么是这三个包？版本下限怎么来的？

包	作用	为什么要求这个版本
NumPy	数值数组、向量化计算	2.0 起统一了 `np.float64` 的 repr，本书输出示例按 2.x 编写
Pandas	表格数据（DataFrame）	2.0 起支持 `pd.cut` 的 `observed` 语义；3.0 起整表 `interpolate()` 会报错（第 30 章会讲，这是好事）
Matplotlib	画图	3.8 起 `ax.set_xticks(ticks, labels)` 的参数形式才稳定（第 35 章用）

实践中不必死守版本号：新一点通常更好。但如果某章输出和你看到的不一样，先回来对一下版本。

bash

python -c "import numpy, pandas, matplotlib; print(numpy.__version__, pandas.__version__, matplotlib.__version__)"

1.6 安装编辑器：VS Code

任何文本编辑器都能写 Python，但好的编辑器能省掉大量时间。推荐 VS Code（免费、跨平台）。

下载安装：https://code.visualstudio.com/
打开 VS Code，点左侧「扩展」（Ctrl+Shift+X / Cmd+Shift+X），搜索并安装：
- Python（Microsoft 官方，必装）
- Pylance（类型检查与自动补全，装 Python 扩展时会自动带上）
- Ruff（代码风格检查，可选但强烈推荐）
用 VS Code 打开 code/ 目录（File → Open Folder）；
关键一步：选择解释器。按 Ctrl+Shift+P（macOS Cmd+Shift+P），输入 Python: Select Interpreter，选择路径里带 .venv 的那一个。

VS Code 最该学会的 5 个操作

操作	快捷键	用途
运行当前文件	`Ctrl+F5` / `Ctrl+Shift+P → Run Python File`	跑整个脚本
在终端运行	右上角 ▶ 旁边下拉 → Run in Terminal	推荐，能直接看到输入输出和报错
打断点调试	行号左边点一下（出现红点），然后 `F5`	单步执行、查看每个变量的值 —— 比 print 快得多
格式化文档	`Shift+Alt+F`	自动排版成 PEP 8 风格
转到定义	`F12`	跳到函数/变量的定义处，读别人代码必备

断点调试是本节最有价值的技能。第 13 章会专门讲怎么用它定位问题。

用 Jupyter Notebook 还是 .py 脚本？

两种都值得会：

	`.py` 脚本	Jupyter Notebook（`.ipynb`）
适合	可复用的程序、要提交的代码	探索性分析、写报告、上课演示
优点	可导入、可测试、可版本管理	分块运行、结果（含图）就地显示
缺点	探索时反复改、反复跑不方便	执行顺序混乱（"重启内核再全跑"是纪律）

本书的策略：主体用 .py 脚本 —— 因为本章的示例都要求"从头跑到尾结果一致"，这能逼你把数据处理写成可复现的流程。等你熟练了，探索阶段用 Jupyter，固化下来的流程再落成 .py。

VS Code 装好 Python 扩展后，直接新建 .ipynb 文件就能用 Jupyter，不需要额外安装。

1.7 确认数据就位

数据已经生成好了，就在下载包里，你不需要运行任何脚本去生成它。

先确认一下它在那儿、并且和书上一致：

bash

cd code/data/battery
ls -la                    # 应该看到 3 个 CSV + README.md
wc -l *.csv               # 行数对照：13968 / 13968 / 13

行数对照表：

文件	行数（含表头）	数据行数
`cycle_raw.csv`	13,968	13,967
`dirty.csv`	13,968	13,967
`cells.csv`	13	12

三个文件分别用在哪

文件	内容	用在哪
`cycle_raw.csv`	干净的逐循环时序	第 12、22、23 章起的大部分示例
`dirty.csv`	在干净数据上注入 2% 缺失 + 1% 异常	第 23、30、32、33、34、39 章
`cells.csv`	电芯级真值（真实寿命、β、γ）	用来对照"模型猜的和真值差多少"
`README.md`	字段、公式、量纲、局限	需要时查阅

校验一致性（可选，但建议做一次）

bash

# macOS / Linux
shasum -a 256 cycle_raw.csv dirty.csv cells.csv

# Windows PowerShell
Get-FileHash cycle_raw.csv, dirty.csv, cells.csv -Algorithm SHA256

应该得到：

fa936625215be7b9247873c76776192007ab3ee12b87128a45adee7d2660c683  cycle_raw.csv
eef88c7584fdd184190f820e9aea2b765dcdd45c1d86e719a30ffa46c20b6647  dirty.csv
4b75611eaa8bcea893f21cd40dba4806a8fd04c1134c0bc107ae48e6c9ac8a7b  cells.csv

为什么要校验：本书所有输出都是基于这同一份数据的。校验通过 = "我看到的数字和你书上的一样"，之后任何不一致都是代码问题，不是数据问题。这能省掉大量"到底是数据不同还是我写错了"的排查时间。

数据是怎么造出来的？为什么必须"造假"？

必须造假的原因：真实的电池产线数据属于企业机密，不可能公开；而且真实数据无法保证"任何人在任何机器上跑出同样的结果"，这对一本教程来说是致命的——你的输出和书上不一样，就分不清是"你错了"还是"数据不同"。

怎么做假的：所有字段都由公开的退化公式现场计算。核心三行：

python

c   = n / n_cycles                    # 归一化循环进度 0 → 1
soh = 1.0 - 0.20 * c ** beta          # SOH：到 c=1 时恰好等于 0.80（退役线）
res = 40.0 * (1.0 + gamma * c ** 1.5) # 内阻：指数 1.5 → 上升滞后于容量下降

其中 beta（衰退指数）和 gamma（内阻上升系数）每支电芯不同（由 numpy.random.default_rng(42) 生成）。

这个公式本身也值得读一遍 —— 上面三行已经写全了。理解了它，你就知道数据里为什么会有相关性、为什么内阻"滞后"于容量，这些都是后面做特征工程和建模时的物理依据。

（数据包里不含生成这段数据的程序，也不需要你自己造数据；公式只作理解用。）

为什么这个设计很重要：三条信号（容量、内阻、温升）的上升速率不同，所以只看 cycle 一个变量不足以精确预测 SOH —— 这正是后面要讲"多特征建模""特征工程"的动机。

局限要记住：单调退化、无随机跳水、无工况切换、无传感器漂移。真实电池的容量跳水（knee point）、批次不一致性都没有模拟。 结论：方法可迁移，模型不可直接上线。

字段、单位、以及"做分析时会遇到的正常现象"，都写在 data/battery/README.md 里 —— 动手前建议先读一遍（5 分钟，能省掉不少困惑）。

1.8 环境自检

bash

python check_env.py

全部通过时你应该看到：

============================================================
《面向 AI 开发的 Python 快速入门》环境自检
============================================================
✅ Python 版本：CPython 3.13.13  (/path/to/.venv/bin/python)
✅ numpy       2.x.x
✅ pandas      3.x.x
✅ matplotlib  3.x.x
✅ 数据文件：/path/to/code/data/battery
   cycle_raw.csv, dirty.csv, cells.csv（共 1450 KB）
------------------------------------------------------------
✅ 全部通过。下一步：从第 03 章开始，把代码敲进 demos/ 里跑起来。

自检项逐一说明（不通过时怎么修）

检查项	不通过的表现	修复
Python 版本	`❌ Python 版本过低`	装 3.10+；或确认虚拟环境用的是新解释器
numpy / pandas / matplotlib	`❌ xxx 未安装`	`pip install -r requirements.txt`（先确认虚拟环境已激活）
数据文件	`⚠️ 数据文件缺失`	重新解压下载包，确认 `data/battery/` 下有 3 个 CSV

最常见的坑：以为装了包，其实装到了全局 Python 而不是虚拟环境里。验证方法：

bash

python -c "import sys; print(sys.executable)"
# 必须包含 .venv，否则你现在根本没在虚拟环境里

如果显示的是 /usr/bin/python3 或 C:\Python312\python.exe，说明环境没激活，或者 VS Code 选错了解释器。

1.9 敲通你的第一个文件

现在开始写代码。 打开 VS Code，在 code/ 下新建 demos/ 目录，然后新建文件 demos/ch03-types.py，把第 03 章 3.8 节的那段代码敲进去：

python

cap_rated = 2.5      # 额定容量（Ah）
voltage = 3.7        # 标称电压（V）
temp = 25            # 温度（℃）

print(f"额定容量 {cap_rated} Ah，电压 {voltage} V，温度 {temp} ℃")

运行它（两种方式选一种）：

bash

# 方式一：终端里跑
cd code
python demos/ch03-types.py

# 方式二：VS Code 里按右上角的 ▶（选 "Run Python File"）

你应该看到：

额定容量 2.5 Ah，电压 3.7 V，温度 25 ℃

这一步的四个"小目标"（别只是跑通就过）

目标一：亲手打出 f-string 的花括号

f"...{cap_rated}..." —— 花括号、f 前缀、引号的配对，都要你自己敲。 这比看十遍都管用。

目标二：故意制造一个报错

把 cap_rated 改成 cap_reate（少个 d），再运行：

NameError: name 'cap_reate' is not defined

看这个报错长什么样、在哪一行、怎么修。 —— 第 03 章的"常见坑"里列了它。

目标三：确认输出和书上完全一致

额定容量 2.5 Ah，电压 3.7 V，温度 25 ℃

一个字都不差。这就是"数据一致 + 环境正确"的证据。

目标四：改点东西看会发生什么

python

cap_rated = 3.0        # 改成 3.0 会怎样？
temp = 26.5            # 温度带小数呢？
print(f"温度 {temp:.1f} ℃")   # 加个 .1f 呢？

"改一改看结果"是最高效的学习动作。 看别人代码只能知道"能这样写"，自己改了才知道"为什么必须这样写"。

1.10 常见报错速查表

环境问题基本都在这张表里。先在这里找，找不到再查搜索引擎。

点开查看：12 个高频报错与修复

找不到命令

报错	原因	修复
`'python' 不是内部或外部命令`	Windows 装 Python 时没勾 `Add to PATH`	重装并勾选，或用 `py` 代替 `python`
`command not found: python`	macOS 只有 `python3`	用 `python3`，或加别名
`command not found: pip`	pip 未装或不在 PATH	用 `python -m pip ...` 代替 `pip ...`

模块找不到

报错	原因	修复
`ModuleNotFoundError: No module named 'numpy'`	虚拟环境没激活，或没装包	`source .venv/bin/activate` 后 `pip install -r requirements.txt`
`ModuleNotFoundError: No module named 'common'`	不在 `code/` 目录下运行	`cd code` 再运行
`ModuleNotFoundError: No module named 'matplotlib'`	只装了 numpy/pandas	`pip install matplotlib`

文件找不到

报错	原因	修复
`FileNotFoundError: data/battery/cycle_raw.csv`	相对路径是相对"当前工作目录"，不是脚本文件；或解压不完整	`cd code` 再运行；或用 `__file__` 反推路径（第 12 章）；确认 `data/battery/` 下有 CSV
`[Errno 2] No such file or directory: 'demos/ch03-types.py'`	当前目录不对	确认 `pwd`（`cd`）在 `code/` 下

编码与版本

报错	原因	修复
`UnicodeDecodeError: 'gbk' codec can't decode`	Windows 默认 GBK，读 UTF-8 文件	`open(..., encoding="utf-8")`
`SyntaxError: invalid character '（'`	用了中文全角括号/引号	换成英文半角 `()` `""`
`SyntaxError: invalid syntax` 指向 f-string	Python < 3.12 的 f-string 引号限制	升级 Python，或把引号错开
`ValueError: cannot reshape array`	元素总数对不上	检查 `reshape` 的两个数乘积

中文显示

现象	原因	修复
图上中文变成"豆腐块"（□□□）	matplotlib 默认字体不含汉字	用 `common/plots.py` 的 `setup_style()`（第 35 章）
中文乱码	文件编码不是 UTF-8	保存为 UTF-8；CSV 给 Excel 看时用 `utf-8-sig`

1.11 本章检查清单

读完这一章，请逐条确认（勾选状态会存在你自己的浏览器里，下次打开还在）：

已勾选 0 / 0 项

全部打勾了？ 你已经有了一台可以运行本书所有代码的"工作台"，而且已经写出了第一个文件。

下一章我们看看这张地图，然后从第 03 章正式开始写代码。

本章练习

本章的练习是动手确认，不涉及编程：

练习 1：确认你的 Python 到底在哪

在 code/ 目录（已激活虚拟环境）里运行：

bash

python -c "import sys; print(sys.executable)"
python -c "import numpy; print(numpy.__file__)"

要求：两条输出里都应该出现 .venv 这个路径片段。如果没有，说明你现在用的不是虚拟环境里的 Python。

参考答案

正常输出类似：

/path/to/code/.venv/bin/python                          ← 出现 .venv ✅
/path/to/code/.venv/lib/python3.13/site-packages/numpy/__init__.py   ← 出现 .venv ✅

如果第一行显示的是 /usr/bin/python3 或 C:\Python312\python.exe：

忘记激活 → 运行 source .venv/bin/activate（Windows 用 .venv\Scripts\Activate.ps1）

激活了但还不对 → 说明 .venv 创建时用的就是错的解释器，删掉重建：

bash

rm -rf .venv          # Windows: rmdir /s .venv
python3 -m venv .venv # 确认这条命令用的 python3 版本 >= 3.10
source .venv/bin/activate
pip install -r requirements.txt

在 VS Code 里跑却不对 → Ctrl+Shift+P → Python: Select Interpreter → 选带 .venv 的那个

练习 2：理解虚拟环境隔离的效果

分别做两次，观察区别：

bash

# 在虚拟环境里（命令行前面有 (.venv)）
pip list | grep -i numpy        # Windows: pip list | findstr /i numpy

# 退出虚拟环境
deactivate
pip list | grep -i numpy

要求：解释为什么两次结果可能不同。

参考答案

激活状态下，pip list 列的是 .venv 里装的包（应该有 numpy / pandas / matplotlib）；
deactivate 之后，pip 指向系统的 Python，那里很可能没装 numpy（grep 无输出），或者装的是完全不同版本。

这正说明"虚拟环境是隔离的"：在里面装包不会污染系统，系统里的包也不会被项目看到。

这也是为什么虚拟环境能解决"两个项目要不同版本"的问题： A 项目的 .venv 里装 pandas 1.5、B 项目的 .venv 里装 pandas 3.0，两者互不干扰。

注意：日常开新终端窗口时，虚拟环境不会自动激活，每次都要重新激活一次（uv 用户用 uv run 可以免去这一步）。

练习 3：亲手制造并修复一个报错

不要直接看答案。先依次尝试下面三个命令，记下报错信息，再想办法修好：

bash

# ① 在 code/ 目录下运行，看看会怎样
python demos/ch03-types.py

# ② 退到上一级目录后再运行
cd ..
python code/demos/ch03-types.py

# ③ 退回 code/，故意用一个不存在的模块
python -c "import numpyy"

要求：说出每个报错的类型名和触发原因。

参考答案

① 会成功（如果环境装好了）。这条只是基线，确认正常路径能跑。

② 报 ModuleNotFoundError: No module named 'common'（或 FileNotFoundError）

原因：ch03-types.py 里用 Path(__file__).resolve().parent.parent 反推项目根，所以它自己找得到 common 和数据。但如果 __file__ 推导结果不对（比如复制到别处），就会失败。
更常见的对应情况是：你自己写的脚本里用了相对路径 pd.read_csv("data/battery/cycle_raw.csv")，它相对的是当前工作目录，不是脚本文件 —— 换目录运行就找不到。
修复：用 Path(__file__).resolve().parent / "data" / ...，或者永远在 code/ 下运行。

③ 报 ModuleNotFoundError: No module named 'numpyy'

注意 Python 会原样回显你打错的模块名（numpyy），这是排查拼写错误最快的线索。
也检查一下：会不会是"包名和导入名不一样"？比如 pip install scikit-learn，但代码里写 import sklearn。

修复这一类问题的通用三步：

看报错最后一行（异常类型 + 消息），那是真正的错误；
看倒数第二段 File "..."，那是出错的位置（文件 + 行号）；
看中间的 ^ 箭头，它指向具体的字符位置。

记住：Python 的报错信息是从下往上看的 —— 最后一行最重要，最上面那段 Traceback 只是调用栈。

面向 AI 开发：为什么环境隔离在 AI 项目里尤其重要

AI 项目的依赖比普通项目复杂得多，环境管理的收益也更大：

① 依赖冲突是 AI 项目的常态。 PyTorch、TensorFlow、CUDA 驱动、NumPy 之间版本耦合极紧。 "装错一个 NumPy 小版本导致 GPU 不可用"是真实发生过很多次的事故。虚拟环境是唯一的隔离手段。

② 实验记录必须包含环境版本。 学术论文和工业项目都要求"可复现"。你的实验结果里，"用了什么版本"和"超参数"一样重要：

bash

pip freeze > requirements-lock.txt     # 记录精确版本（含间接依赖）

③ CPU / GPU 环境要分开。 同一个项目，本地开发用 CPU 版本（小、快装），服务器训练用 CUDA 版本。两个环境完全隔离，靠的就是虚拟环境。

④ 容器化和虚拟环境是同一思路的不同层级。

层级	工具	隔离粒度
包级	venv / conda / uv	一个项目一个包抽屉
系统级	Docker 容器	一个项目一个完整操作系统

理解了 venv 解决"两个项目要不同 pandas 版本"，你就理解了 Docker 解决"两台机器要不同 Python 版本"。 思路完全一样，只是粒度不同。

下一章：第 02 章 · 学习路线与知识地图 —— 搞清楚这 38 章之间的关系，再开始动手。

第 01 章 · 课程说明与环境安装准备 ​

1.1 先说清楚：这一章做完，你应该看到什么 ​

1.2 三个概念：解释器、包、虚拟环境 ​

1.3 安装 Python ​

Windows ​

macOS ​

Linux（Ubuntu / Debian） ​

1.4 拿到配套数据包 ​

★ 先明确一件事：本课程不提供示例代码和练习答案 ​

下载数据包 ​

1.5 创建虚拟环境并安装依赖 ​

路线一：标准 venv + pip（推荐给所有人，最通用） ​

路线二：uv（更快，如果你已经熟悉命令行） ​

依赖清单（requirements.txt） ​

1.6 安装编辑器：VS Code ​

1.7 确认数据就位 ​

三个文件分别用在哪 ​

校验一致性（可选，但建议做一次） ​

1.8 环境自检 ​

1.9 敲通你的第一个文件 ​

1.10 常见报错速查表 ​

找不到命令 ​

模块找不到 ​

文件找不到 ​

编码与版本 ​

中文显示 ​

1.11 本章检查清单 ​

本章练习 ​

面向 AI 开发：为什么环境隔离在 AI 项目里尤其重要 ​

第 01 章 · 课程说明与环境安装准备

1.1 先说清楚：这一章做完，你应该看到什么

1.2 三个概念：解释器、包、虚拟环境

1.3 安装 Python

Windows

macOS

Linux（Ubuntu / Debian）

1.4 拿到配套数据包

★ 先明确一件事：本课程不提供示例代码和练习答案

下载数据包

1.5 创建虚拟环境并安装依赖

路线一：标准 venv + pip（推荐给所有人，最通用）

路线二：uv（更快，如果你已经熟悉命令行）

依赖清单（`requirements.txt`）

1.6 安装编辑器：VS Code

1.7 确认数据就位

三个文件分别用在哪

校验一致性（可选，但建议做一次）

1.8 环境自检

1.9 敲通你的第一个文件

1.10 常见报错速查表

找不到命令

模块找不到

文件找不到

编码与版本

中文显示

1.11 本章检查清单

本章练习

面向 AI 开发：为什么环境隔离在 AI 项目里尤其重要