PyTorch入门必学：用dir()和help()快速摸清API与环境配置

1. 两个内置函数，凭什么成为PyTorch入门的"探照灯"

很多同学第一次打开 PyTorch 官方文档时，心态基本是崩溃的——满屏的torch.xxx、torch.Tensor.xxx，看两行就想关掉。我当初跟《PyTorch深度学习》这套教程学的时候，第 1 节还在折腾 Python 和 PyTorch 安装，第 2 节作者就直接抛出一个特别"反直觉"的结论：Python 里最该先学透的，不是 numpy，不是 matplotlib，而是自带的dir()和help()。

这两个函数看着不起眼，但它们是打开一切陌生库的钥匙。深度学习框架更新太快，网上博客很容易过时，可你本机安装的这个 torch 版本，它的属性和说明是写在代码里的，永远和当前版本对得上。学会用dir()看"它有什么"，用help()看"它怎么用"，才是真正的一劳永逸。

不信的话，可以对比一下遇到陌生 API 时的几种常见做法：

别小看这个顺序问题。很多人学 PyTorch 卡住，不是因为不够努力，而是因为"找答案"的方法不对。把dir()和help()当成查字典的工具，后面你再遇到Dataset、DataLoader、transforms、nn.Module、optim这些概念时，就不是等着别人喂答案，而是自己动手把它们"翻个底朝天"。

这篇笔记正好对应教程笔记 2 的内容，我会结合自己踩过的坑，把 Python 环境、PyCharm 环境调用、dir()、help()的实用场景完整梳理一遍。所有代码都能直接在 PyCharm 里跑，你不用额外装任何东西。

2. 动手之前：把Python环境、PyCharm和PyTorch的关系理清

2.1 Python解释器、PyCharm、PyTorch到底是什么关系

新手最容易搞混的就是这三者的关系。打个比方：Python 解释器是"发动机"，PyTorch 是装进发动机里的"工具箱"，而 PyCharm 是驾驶室里的仪表盘。仪表盘本身不能当发动机用，它只是调用发动机；如果发动机里没装工具箱，你在仪表盘上按一万次按钮也没用。

这句话翻译成实际报错就是：你在 PyCharm 里运行import torch，结果ModuleNotFoundError: No module named 'torch'，但你在终端用命令pip list又能看到 torch。出现这种矛盾，几乎都是因为 PyCharm 里选中的 Python 解释器，和安装 PyTorch 时用的 Python 解释器不是同一个。

所以环境配置的第一原则是：先确定一个解释器，安装 PyTorch、让 PyCharm 引用，都在同一个解释器上操作。

2.2 一套稳一点的环境搭建顺序

如果你是完全零基础，直接按下面这套来，能避开大部分环境坑：

1. 安装 Python，建议 3.8 到 3.10 这个区间，太老的版本对不上新版 PyTorch，太新的版本有些轮子还没跟上。
2. 安装 PyCharm Community Edition（社区版），去官网下载就行，学习阶段用社区版完全够。
3. 打开 PyCharm 新建项目时，注意看右下角或者弹窗里的"Python Interpreter"选项，不要直接用默认的虚拟环境，尽量选择你刚安装的那个 Python。
4. 在 PyCharm 底部打开 Terminal，执行安装命令安装 PyTorch：

pip install torch torchvision torchaudio

如果电脑没有 NVIDIA 显卡，或者暂时不想折腾 GPU，可以装 CPU 版：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

这里专门解释一下为什么要用--index-url：PyTorch 官网会把 CPU 版和 GPU 版放在不同的 wheel 仓库里，如果你直接pip install torch，默认装的很可能是 GPU 版。等运行torch.cuda.is_available()时输出False，新手容易慌，觉得自己装坏了。其实没坏，只是你没显卡或者没装驱动而已。

如果你愿意用 Anaconda 管理环境，也可以这样建一个独立环境：

conda create -n torchlearn python=3.9 -y conda activate torchlearn conda install pytorch torchvision torchaudio cpuonly -c pytorch

我个人比较推荐新手用 Anaconda，因为环境隔离做得清楚，装坏了直接删掉重建，不污染系统 Python。

2.3 安装完之后怎么验证

在 PyCharm 里新建一个 Python 文件，比如check_env.py，写这几行：

import torch print("PyTorch 版本:", torch.__version__) print("CUDA 是否可用:", torch.cuda.is_available())

如果能打印出版本号，说明解释器、IDE、库已经全部打通。这一步你以后每次新建项目都要做一遍，不要嫌烦，这是排查"装完却调不起来"最快的方法。

2.4 关于 pip 报 ResolutionImpossible 的经验

搜索结果里经常能看到这样一条报错：

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/to...

我第一次看到也愣了半天，翻译过来就是：pip 在你指定的这些包约束里，找不到一组能同时满足所有要求的版本组合。

出现这个问题主要有两种情况。一种是你在一个已经有很多包的环境里硬装某个旧版本，比如pip install torch==1.13.1，但环境里又有 numpy、pillow 等高版本包，彼此要求冲突，pip 解析器直接放弃。另一种是混用了多个镜像源，比如一部分包来自默认 PyPI，一部分来自镜像，导致解析时版本对不上。

处理办法不是去跟 pip 搏斗，而是直接新建一个干净环境，然后只装必要包：

python -m venv .venv

如果是 Windows，激活：

.venv\Scripts\activate

如果是 macOS 或 Linux：

source .venv/bin/activate

激活后升级一下 pip，再单独安装 PyTorch。这样基本不会再遇到 ResolutionImpossible。

下面这张表，是我见过的高频安装报错汇总，建议直接收藏：

3. dir()：把模块翻个底朝天，找出你想用的东西

3.1 dir() 到底返回什么

dir()的作用很简单：把某个对象的属性名全部罗列出来。它可以作用在模块上、类上、对象上，甚至是函数上。

先看最直观的例子：

import torch # 去掉下划线开头的内容，看起来更清爽 public = [name for name in dir(torch) if not name.startswith('_')] print("torch 公共接口数量:", len(public)) print(public)

运行后你会看到一长串名字，里面包含add、cat、conv2d、rand、tensor之类的内容。这就是 torch 模块对外暴露的"家门谱"，你想知道这个模块能干什么，先扫一眼这个列表比什么都强。

不过老实说，直接打印整个列表还是有点吓人，因为太多了。这时候可以用过滤条件缩小范围。

3.2 用关键词过滤，精准定位候选函数

比如我现在想"创建一个随机张量"，但记不住到底是rand、random还是randn。那就直接把带rand的名字全过滤出来：

import torch rand_related = [name for name in dir(torch) if name.startswith('rand')] print(rand_related)

输出会是类似：

['rand', 'rand_like', 'randint', 'randn', 'randperm']

看到这一小撮候选人，心里就有底了：

• torch.rand生成 0 到 1 之间均匀分布的随机数
• torch.randn生成标准正态分布的随机数
• torch.randint生成整数随机数
• torch.randperm生成 0 到 n-1 的随机排列

还没看官方文档，光凭命名习惯，你就能猜个八九不离十。接下来再用help()去确认细节就行。

这个"按关键词过滤"的思路非常通用。以后你想找和均值相关的：

mean_related = [name for name in dir(torch) if 'mean' in name.lower()] print(mean_related)

想找和拼接相关的：

cat_related = [name for name in dir(torch) if 'cat' in name.lower()] print(cat_related)

你会发现dir()不是一个死板的列表，它更像一个"本地搜索引擎"。参数里的关键词就是你的搜索词。

3.3 在张量和模型对象上使用 dir()

dir()不止能查模块，还能查具体的张量对象。比如：

import torch x = torch.tensor([1.0, 2.0, 3.0]) methods = [name for name in dir(x) if not name.startswith('_')] print(methods)

你会看到abs、add、cpu、cuda、mean、numpy、reshape、sum等方法。这会告诉你：这个张量对象本身能做哪些事，不需要额外调别的函数。

在定义完一个模型之后，这个技巧更有用：

import torch.nn as nn model = nn.Linear(4, 2) model_attrs = [name for name in dir(model) if not name.startswith('_')] print(model_attrs)

你会看到train、eval、parameters、state_dict、forward这些方法。后边训练模型的时候，经常要调用model.train()、model.eval()、model.state_dict()，如果你早就用dir()瞄过一眼，后面看代码就不会觉得陌生。

3.4 一个小建议：把接口清单导出成文件

dir()返回的是字符串列表，所以你可以非常方便地把它写进文本文件里，方便随时翻：

import torch with open('torch_api.txt', 'w', encoding='utf-8') as f: f.write('\n'.join([name for name in dir(torch) if not name.startswith('_')]))

这样你以后看到某个函数名，想查它是干嘛的，直接在文本编辑器里搜索就行，比每次运行代码打印更快。这个小技巧帮我省了不少时间。

4. help()：把函数签名和参数说明读到懂

4.1 help() 给你的是"当前版本的说明书"

dir()告诉你有什么，help()告诉你这个东西怎么用。它显示的内容其实就是对象的__doc__文档字符串，外加函数的完整签名。

比如查torch.tensor：

import torch help(torch.tensor)

你会看到一个非常典型的输出：

Help on built-in function tensor in module torch: tensor(data, *, dtype=None, device=None, requires_grad=False, pin_memory=False) -> Tensor Constructs a tensor with data.

第二部分不用全看，重点看第一行签名。这一行会告诉你：

• 第一个参数是data，必填，可以是列表、numpy 数组等
• dtype是可选参数，用来指定张量类型，比如torch.float32
• device是可选参数，指定放到 CPU 还是 GPU
• requires_grad是布尔值，如果设为True，PyTorch 会自动记录参与梯度计算的操作，这是后续反向传播的基础

有了这行签名，你至少知道怎么构造一个张量了，也大概知道梯度是怎么打开的。比较半天博客，不如本地敲一次help(torch.tensor)来得准。

4.2 同名函数没关系，help() 能帮你对比差异

PyTorch 里有个容易困扰新手的地方：同一个功能，既有函数式写法，也有方法式写法。比如torch.max和torch.Tensor.max：

help(torch.max)

输出会提示torch.max有三种用法：

max(input) -> Tensor max(input, dim, keepdim=False, *, out=None) -> (Tensor values, LongTensor indices) max(input, other) -> Tensor

这个信息太关键了。很多人一开始只会用torch.max(x)获取最大值，却不知道加上dim参数后，它会返回两个值：一个是最大值，一个是对应的下标。做分类任务时，我们经常要拿到预测类别下标，用的就是这个带dim的版本。如果你不看help()，很难从名字猜到这个细节。

再比如：

help(torch.Tensor.reshape) help(torch.reshape)

两者签名差不多，都是把张量形状改成目标形状，但一个是张量对象直接调用，一个是独立函数调用。你实际用哪个都行，但明白它们的等价关系，看别人代码时就不会被两种写法绕晕。

4.3 help() 内容太长怎么办

help()有时候输出特别长，比如查torch.nn.Module，几屏都翻不完。这很正常，不要硬看。新手只需要抓两个重点：第一行签名和每个参数的意思。

如果你只想快速瞄一眼第一段说明，可以直接打印文档字符串，还能用切片控制长度：

print(torch.Tensor.reshape.__doc__)

或者只看前 300 个字符：

print(torch.Tensor.reshape.__doc__[:300])

不过我自己的习惯是：遇到复杂 API，先help()看签名，然后去 PyCharm 里随便造一个最小样本跑一下，看看输入输出形状。跑出来的结果比看十行文字都直观。

4.4 在 PyCharm 控制台里体验更丝滑

如果你使用的是 PyCharm 底部的 Python Console，其实还有个更方便的方式。在控制台输入：

torch.tensor?

回车后，它和help(torch.tensor)效果类似，但展示方式更友好，签名和文档会直接列出来。如果输入两个问号：

torch.tensor??

还能尝试展开源码。PyTorch 底层很多是 C++ 实现的，Python 层可能只能看到签名，看不到具体实现，不过对使用来说已经足够了。

还值得一提的是，help()不仅对 torch 有效，对你自己写的函数同样有效。你只要在函数里写了文档字符串：

def my_loss(pred, target): """计算预测值和真实值之间的均方误差。""" return ((pred - target) ** 2).mean() help(my_loss)

就会输出你写的那行"""..."""注释。这能帮你养成写注释的习惯，也让你的代码更规范。

5. PyCharm实战：用一套"查字典"流程搞定陌生API

5.1 打开 Python Console，先别急着写完整代码

我不建议你一上来就对着项目文件写大段脚本。遇到不认识的 API，先在 PyCharm 的 Python Console 里试。

在 PyCharm 里，Python Console 就像一个交互式解释器，你输入一行代码，它立刻执行并返回结果，非常适合做 API 探测。比如我想搞清楚 torch 里和loss相关的函数都有哪些：

import torch candidates = [x for x in dir(torch) if 'loss' in x.lower()] print(candidates)

然后挑一个重点看：

help(torch.nn.functional.mse_loss)

就这样，一步一步把范围从"整个模块"缩小到"某个具体函数"，再缩小到"函数签名"，整个过程不超过两分钟。

5.2 建议的查字典流程

以后你碰到任何陌生模块，都可以用同一套固定流程，不用动脑子想下一步干什么：

1. 根据名字猜意图。比如看到transforms，猜它和数据预处理有关。
2. 用dir(模块)找到候选函数或候选类。
3. 用help(候选对象)看签名和关键参数。
4. 造一个最小例子，跑一遍看输入输出。
5. 如果还不行，再跳到官方文档，或者 Ctrl+点击函数名看源码。

这套流程的价值在于：它把"我要搜索一个问题"变成了"我要执行一套本地侦察动作"。搜索是发散且看运气的，而本地侦察是确定性的，结果永远来自你的当前版本。

5.3 完整演示：用 dir/help 看懂 transforms.Compose

我拿教程后面必然遇到的transforms来演示一遍完整流程。

先在控制台输入：

from torchvision import transforms names = [x for x in dir(transforms) if 'Compose' in x or 'Resize' in x] print(names)

输出类似：

['Compose', 'Resize']

再查Compose：

help(transforms.Compose)

你会看到它的核心说明：这个类会把多个 transform 按顺序组合成一个整体。于是你立刻明白，一段典型代码为什么是这么写的：

from torchvision import transforms from PIL import Image img = Image.new('RGB', (64, 64)) t = transforms.Compose([ transforms.Resize((32, 32)), transforms.ToTensor(), ]) out = t(img) print(out.shape)

运行后，如果输出torch.Size([3, 32, 32])，就说明你的猜测完全正确：输入是一张 HWC 的图像，经过组合变换后变成了 CHW 的张量，尺寸也变成了 32×32。

整个过程里，我没有查任何网页，全部答案都来自本机的dir()、help()和小实验。遇到新版本 API 变更时，这种方法永远不会因为博客过时给你错误信息。

5.4 在编辑器里用快捷键辅助

除了手写dir()和help()，PyCharm 本身也提供了几条捷径：

• 在编辑器中输入torch.后，按Ctrl + Space，会自动弹出属性列表。这相当于一个实时的dir()。
• 把鼠标悬停在某个函数名上，PyCharm 会浮窗显示它的文档摘要，相当于轻量版help()。
• 把光标放在某个函数名上，按Ctrl + Q，会弹出完整的 quick documentation，比悬停信息更详细。
• 按住Ctrl再点击函数名，会跳转到这个函数的源码或类型存根文件。

这里特别说一下最后一条。很多时候你 Ctrl+点击torch.cat，看到的不是传统 Python 源码，而是一个.pyi文件，内容只有函数签名和注释。不要慌，这不是装错了，.pyi是类型存根文件，就是给 IDE 和开发者看接口用的。PyTorch 大部分底层是 C++ 或 CUDA 实现，Python 层只是一个封装外壳，所以你能看到的最细致 Python 信息往往就是这些签名。

6. 我踩过的三个坑，以及给你的一套入门练法

6.1 坑一：装完 torch，PyCharm 却报 ModuleNotFoundError

有一次我在系统 Python 里用pip install torch装好了库，然后新建 PyCharm 项目，一运行import torch就报错。我折腾了大半天，重装了好几次，最后才发现 PyCharm 默认给新项目创建了一个全新的虚拟环境，根本不是我装 torch 的那个解释器。

正确的做法是：在 PyCharm 里打开File -> Settings -> Project -> Python Interpreter，看一眼当前选中的解释器路径。如果不是你安装 torch 的那个解释器，点右上角的齿轮选择 "Add Interpreter"，然后选 "Existing" 或 "Conda Environment"，指向正确的环境。

排查的时候，最快的方法是先打印当前解释器路径：

import sys print(sys.executable)

再在终端里用同样的解释器去检查 torch：

python -c "import torch; print(torch.__version__)"

如果这行命令输出正常，而 PyCharm 里运行报错，那问题一定出在解释器匹配上，不要再重装 torch 了。

6.2 坑二：在终端执行 pip install，但装的不是当前环境

Windows 下特别容易遇到这种情况：你在任意文件夹打开命令行，输入pip install torch，结果它安装到了系统的某个 Python 环境里，而 PyCharm 项目使用的是 Anaconda 环境，两边根本不通。

我现在的习惯是不直接用裸pip，而是用python -m pip：

python -m pip install torch torchvision torchaudio

这样能够保证安装到当前激活环境对应的 Python 里。如果你用 Anaconda，更稳妥的是先激活环境再安装：

conda activate torchlearn python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

6.3 坑三：在终端输入 help() 后卡住，不知道怎么退出

如果你在自己电脑的终端里运行：

python >>> help(torch)

进去以后，屏幕可能停在一大段文档里，按什么键都没反应，你以为死机了。其实它是在分页显示文档，按一下q就能退出。在 PyCharm 的 Python Console 里一般不会这样，但如果你习惯了在终端操作，这个q一定要记住。

还有，如果你只在终端输入了：

help()

没带参数，它会进入交互式帮助模式，提示符变成help>。想退出的话，直接输入q然后回车，或者按Ctrl + C。

6.4 一套只靠 dir/help 完成的入门小练习

光看不练没效果。我提供一个练习，要求很简单：不许查网页，不许用搜索引擎，只准用dir()、help()和少量打印代码，完成下面四个任务：

1. 创建一个形状为[3, 4]的均匀分布随机张量。
2. 把它变换成[4, 3]的形状。
3. 计算所有元素的平均值。
4. 找出沿dim=1方向的最大值及对应下标。

如果你卡住了，就按这个线索走：

import torch # 先找随机函数 rand_names = [x for x in dir(torch) if x.startswith('rand')] print(rand_names) # 再找形状变换和方法 print([x for x in dir(torch.Tensor) if 'reshape' in x or 'view' in x]) # 最后查看 max 的帮助 help(torch.max)

参考答案可以是这样：

import torch x = torch.rand(3, 4) print("随机张量:", x.shape) y = x.reshape(4, 3) print("变换后的形状:", y.shape) print("所有元素的均值:", y.mean()) values, indices = y.max(dim=1) print("dim=1 方向最大值:", values) print("dim=1 方向最大值下标:", indices)

练完这套，你会发现一个明显变化：看到陌生 API 的第一反应不再是到处搜，而是直接在本地敲两行代码自己看。这个习惯一旦养成，后面学Dataset、DataLoader、nn.Module、optim全都顺很多。

我个人学完这套笔记后的体会是，真正让入门速度差出几倍的，不是谁记的函数多，而是谁更会"查"。PyTorch 的函数成千上万，你不可能全记住，但只要你掌握dir()和help()这两个最基础的 Python 内置函数，任何一个新出的模型库，你都有能力自己把它拆开、看清楚、再用起来。这就是教程里反复强调"两大法宝"的原因。