深入掌握深度学习框架 API：以《动手学深度学习》lookup-api 章节为核心的文档查阅指南

• 文档
• 教程
• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习

导读

在使用 PyTorch、TensorFlow、MXNet 与 JAX 等深度学习框架进行开发时，最大的障碍往往不是算法本身，而是"记不清某个函数叫什么、参数怎么传"。本篇文章以《动手学深度学习》（D2L）预备知识章节中的lookup-api（文档查阅）一节为骨架，系统讲解如何通过 Python 内置的dir与help工具，快速定位框架模块中的函数与类、读懂其用法文档，并结合仓库源码与d2l工具库的实际实现进行纵深拓展。读完本篇，你将掌握一套不依赖搜索引擎的"自给自足"式 API 探索方法论，能够在任何深度学习框架中快速查询、验证并复用函数与类。

本文对应仓库文档位置为 chapter_preliminaries/lookup-api.md，属于《动手学深度学习》预备知识章节的收尾小节，与 ndarray.md（数据操作）、linear-algebra.md（线性代数）等章节共同构成后续学习的技术底座。

为什么需要专门的"查文档"技能

深度学习框架的 API 规模极为庞大，官方文档虽然完备，但存在两个现实问题：

1. 信息更新快：API 会随版本迭代频繁变化，很多网上教程往往滞后于框架版本；
2. 信息密度高：官方文档追求全面覆盖，但缺乏针对具体使用场景的指引。

因此，《动手学深度学习》在预备知识章节特意安排了这一节（对应 chapter_preliminaries/index.md 中的lookup-api条目），其核心观点是：与其死记硬背每一个函数，不如掌握一套主动探索 API 的方法。本节强调"重要的使用场景优先于覆盖的完备性"，并鼓励读者在遇到问题时：

• 用dir快速浏览某个模块提供了哪些可调用的对象；
• 用help获取某个具体函数/类的详细用法；
• 用?/??在 Jupyter 中即时查看文档与源码；
• 最后通过实际运行一次小测试来验证自己的理解。

这种"先猜测、后验证、再实践"的流程，正是本节要传递给读者的核心方法论，也是后续所有章节中高频使用的技能。

多框架环境下的章节代码组织方式

需要说明的是，该章节在仓库中采用多框架并列的写法（对应 chapter_preliminaries/lookup-api.md 开头），通过tab.interact_select(['mxnet', 'pytorch', 'tensorflow', 'jax'])提供了 MXNet、PyTorch、TensorFlow 与 JAX 四种后端代码。各框架对应的导入语句分别为：

from mxnet import np # MXNet（注意：mxnet 已停止维护，建议优先使用其余三种框架） import torch # PyTorch import tensorflow as tf # TensorFlow import jax # JAX

这一设计贯穿全书：仓库中的d2l工具包同样提供了四个后端实现文件，分别为 d2l/mxnet.py、d2l/torch.py、d2l/tensorflow.py 与 d2l/jax.py，其导入方式在 d2l/init.py 中有明确说明：

from d2l import mxnet as d2l # Use MXNet as the backend from d2l import torch as d2l # Use PyTorch as the backend from d2l import tensorflow as d2l # Use TensorFlow as the backend from d2l import jax as d2l # Use Jax as the backend

无论你选择哪个后端，本节介绍的dir与help用法都是通用的——这正是该技能价值所在：方法论跨框架通用，细节差异只需靠查询补齐。

用dir探索模块：先看"有什么"

dir是 Python 的内置函数，它返回对象所有属性的名字列表。在深度学习场景中，最常见的用法是查询某个模块暴露了哪些函数与类。

模块级探索：以随机数模块为例

原文档以"随机数生成"为例，分别对四种框架的随机数模块执行了dir查询：

print(dir(np.random)) # MXNet print(dir(torch.distributions)) # PyTorch print(dir(tf.random)) # TensorFlow print(dir(jax.random)) # JAX

以 PyTorch 的torch.distributions为例，输出会包含诸如Uniform、Normal、Multinomial等分布类，以及大量以__开头和结尾的特殊对象（如__all__、__builtins__）和以下划线开头的内部函数。

如何解读dir的输出

原文档给出了两条非常实用的过滤规则：

1. 忽略以__开头和结尾的名字——这些是 Python 的特殊对象（dunder 方法），属于解释器内部机制，如__init__、__repr__，一般无需关注；
2. 忽略以单个_开头的名字——这些通常是框架内部的私有函数，虽然可以调用，但不在公共 API 承诺范围内，后续版本可能变更。

过滤掉这两类名字后，从剩余的函数名（如uniform、normal、multinomial）就可以合理推断：该模块提供了从均匀分布、正态分布与多项分布中采样的方法。这种"由命名推断功能"的能力，是快速上手新框架的重要技巧。

从源码看dir的实际应用

值得注意的是，dir不仅能用于框架 API，在仓库自身的d2l工具库实现中也被大量使用。例如在 d2l/mxnet.py 中，HyperParameters与相关类通过dir(self)遍历对象的全部属性，用于模型参数的收集与管理。而在 chapter_linear-classification/classification.md 的 MXNet 实现中，get_scratch_params方法正是利用dir(self)遍历模型的所有属性，再通过getattr取出那些是np.ndarray或d2l.Module的属性并汇总为参数列表：

@d2l.add_to_class(d2l.Module) def get_scratch_params(self): params = [] for attr in dir(self): a = getattr(self, attr) if isinstance(a, np.ndarray): params.append(a) if isinstance(a, d2l.Module): params.extend(a.get_scratch_params()) return params

这一真实案例说明：dir+getattr的组合是深度学习中动态收集属性、参数与子模块的通用模式，从框架探索到模型构建都离不开它。

用help查看具体函数与类的用法

dir回答"模块里有什么"，而help回答"某个函数怎么用"。help是 Python 内置函数，会输出对象的 docstring、参数签名、返回值等说明信息。原文档以张量的ones函数为例：

help(np.ones) # MXNet help(torch.ones) # PyTorch help(tf.ones) # TensorFlow help(jax.numpy.ones) # JAX

从ones的文档中我们能读到什么

以 PyTorch 的torch.ones为例，help输出大致包含：

• 函数签名：torch.ones(*size, *, out=None, dtype=None, layout=torch.strided, device=None, requires_grad=False)；
• 功能描述：创建一个形状为size的新张量，所有元素初始化为 1；
• 参数说明：size可以是整数序列或torch.Size；dtype指定数据类型（如torch.float32）；device指定张量所在设备（CPU/GPU）；requires_grad决定是否跟踪梯度；
• 示例代码：多数框架文档会附带一两个最小的使用示例。

阅读之后，原文档强调的关键习惯是："Whenever possible, you should run a quick test to confirm your interpretation"——无论文档写得多么清楚，都应该立刻跑一小段代码验证自己的理解是否正确。

运行测试验证理解

np.ones(4) # MXNet → array([1., 1., 1., 1.]) torch.ones(4) # PyTorch → tensor([1., 1., 1., 1.]) tf.ones(4) # TensorFlow → tf.Tensor([1. 1. 1. 1.], shape=(4,), dtype=float32) jax.numpy.ones(4) # JAX → Array([1., 1., 1., 1.], dtype=float32)

四种框架的ones(4)都创建了一个长度为 4、元素全为 1 的张量，行为一致。这一小步验证的意义在于：文档可能与版本存在偏差，实际运行结果才是最可靠的事实依据。

在 Jupyter 中使用?与??

原文档还介绍了一个 Jupyter 特有的高效查询方式：

• 在 cell 中输入list?，会在新窗口（或弹出面板）中显示与help(list)几乎相同的内容；
• 输入list??，则额外显示该函数/类的 Python 源码实现。

对于想要深入理解框架内部机制（例如想知道torch.ones底层如何分配内存、list的append到底做了什么）的读者来说，??是比help更进一步的利器——它直接把实现代码摆在眼前。这也呼应了原文档的另一个重要建议：鼓励读者研读所使用库的源码，从中学习高质量生产代码的写法，既能成为更好的工程师，也能成为更好的科学家。

官方文档之外的探索路径

原文档明确指出，本节的定位是"提供如何探索 API 的引导"，而不是替代官方文档——官方文档提供了远超本书范围的大量描述与示例。同时，它还给出了两条延伸建议：

1. 查阅官方 API 文档与教程：各框架的官方文档是权威来源，遇到书中未覆盖的函数应优先查阅；
2. 阅读库的源码：源码是最忠实的文档，??或直接浏览 GitHub 仓库都是可行的方式。

在本书仓库中，这一建议同样适用：d2l工具包的全部实现都以明文 Python 源码的形式存放在 d2l/ 目录下，例如 d2l/torch.py 中定义了Module（模型基类，包含forward、training_step、validation_step、configure_optimizers等方法）、DataModule（数据基类，提供train_dataloader与val_dataloader）、Trainer（训练器）等贯穿全书的核心抽象。读者可以直接阅读这些文件，观察save_hyperparameters如何借助inspect模块自动保存超参数，或者ProgressBoard如何实现训练过程的动态绘图——这正是"从源码学习工程实践"的最佳范例。

仓库中的"API 文档"资源

更进一步，本书还在 chapter_appendix-tools-for-deep-learning/d2l.md 中提供了完整的d2l包 API 文档页，按字母序列出了d2l.torch/d2l.mxnet中的全部类（如Module、Trainer、LeNet、RNN、TransformerEncoder等）与函数（如add_to_class、corr2d、try_gpu、masked_softmax等），并标注了每个符号在书中对应章节的位置，方便读者反向定位详细实现。这份"官方文档"本身就是使用dir/help方法论的成果展示。

组合技能：一套完整的 API 探索工作流

将上面的工具组合起来，就形成了一套在任何深度学习框架中都通用的 API 探索工作流：

这套流程正是本节标题"lookup-api"（查询 API）的完整内涵。无论日后切换框架、升级版本，还是使用从未接触过的新库，这套方法论都能让你快速站稳脚跟。

小结

• dir用于探索模块提供了哪些可调用对象；解读时过滤掉__包围的特殊对象和单下划线开头的内部对象，剩余的函数名通常足以推断模块功能；
• help用于查看具体函数/类的详细用法，包括签名、参数与返回值说明；
• Jupyter 中的?显示文档、??额外显示源码实现，是快速深入细节的利器；
• 无论文档如何详尽，都应通过一次实际运行来验证理解；
• 官方文档追求覆盖面，本书则聚焦高频使用场景；两者结合，再加上对库源码的研读，是成为更好的工程师与科学家的有效路径。

本节内容位于 chapter_preliminaries/lookup-api.md，是预备知识章节（chapter_preliminaries/index.md）中关于"存储数据、处理数据、线性代数、微积分、自动求导、概率论"之外的最后一项生存技能——当你在学习过程中遇到任何陌生的 API，随时回到这里，用dir与help找到答案。

• 文档
• 教程
• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习