Jupyter Notebook导出PDF/HTML：方便传播PyTorch学习资料
在高校实验室、企业培训现场或开源项目仓库中，你是否曾遇到这样的尴尬：精心编写的 PyTorch 教程发给学生或同事后，对方却因为环境不一致跑不通代码？又或者，花了一整天画出漂亮的训练曲线和模型结构图，最后只能靠截图贴进 Word 文档，排版错乱、无法搜索、更新一次就得重做一遍？
这并不是个例。随着深度学习教学与协作的日益频繁，如何让“可运行的实验”变成“可传播的知识”，已成为 AI 工程实践中一个不容忽视的问题。
而答案，其实早已藏在我们每天都在用的工具里——Jupyter Notebook 配合容器化环境，不仅能写代码、看结果，还能一键生成专业级 PDF 或 HTML 教材，真正实现“实验即文档”。
设想这样一个场景：一位研究生完成了 MNIST 手写数字分类实验，她在 Jupyter 中写了完整的模型定义、训练流程和可视化分析，并用 Markdown 详细解释了每一步原理。现在她需要提交一份报告给导师，同时把教程分享给课题组新人。
如果采用传统方式，她得复制代码到 Word、手动插入图片、调整格式……耗时不说，下次模型一改，一切又要重来。
但若使用pytorch-cuda:v2.7这类预配置镜像，在容器内完成实验后，只需一条命令：
jupyter nbconvert --to pdf --execute mnist_tutorial.ipynb几秒钟后，一份包含完整代码、输出图像、数学公式和文本说明的 PDF 报告就自动生成了。再执行一句：
jupyter nbconvert --to html *.ipynb --output-dir=docs/整个项目的多篇笔记瞬间转为可浏览网页，上传 GitHub Pages 即可对外发布。
这一切之所以能无缝衔接，背后依赖的是两个关键技术的成熟融合：容器化的 PyTorch-CUDA 开发环境和Jupyter 的 nbconvert 导出机制。
先看开发环境。过去搭建一个支持 GPU 的 PyTorch 环境堪称“玄学”——操作系统版本、CUDA 驱动、cuDNN 兼容性、Python 包冲突……任何一个环节出问题都会导致“在我机器上能跑”的经典难题。而现在，通过 Docker 容器技术，我们可以将整套环境打包成一个镜像，比如名为pytorch-cuda:v2.7的基础镜像，它已经预装了 PyTorch 2.7、CUDA 11.8、NumPy、Matplotlib、Jupyter Lab 等常用组件，甚至包括 SSH 服务以便远程接入。
启动这个环境也极为简单：
docker run -it --gpus all \ -p 8888:8888 \ -p 2222:22 \ -v $(pwd):/workspace \ pytorch-cuda:v2.7这条命令做了几件事：
---gpus all让容器直接调用主机的所有 NVIDIA 显卡；
--p 8888:8888暴露 Jupyter 服务端口，浏览器访问即可进入编程界面；
--v $(pwd):/workspace将当前目录挂载进容器，实现代码持久化；
- 整个过程无需安装 Anaconda、不用手动 pip install，几分钟内就能在任何支持 Docker 的设备上重建完全一致的开发环境。
这种标准化带来的好处是显而易见的。对于教学而言，所有学生都运行在同一环境下，避免了因环境差异导致的代码报错；对于团队协作，新成员加入时不再需要花半天时间配环境，拉取镜像即可开工；更重要的是，实验的可复现性得到了根本保障。
有了稳定的运行环境，下一步就是如何把交互式笔记本转化为适合传播的静态文档。这就是 Jupyter 的nbconvert工具登场的时候了。
nbconvert是 Jupyter 内置的格式转换引擎，它能够读取.ipynb文件中的每一个单元格——无论是代码、Markdown 文本还是执行后的输出（如图表、表格）——然后根据目标格式进行渲染。常见的输出包括 HTML、PDF、LaTeX、Markdown、Python 脚本等。
以导出 PDF 为例，其流程分为两步：
1..ipynb → .tex：nbconvert将笔记本内容转换为 LaTeX 源码；
2..tex → .pdf：调用本地 LaTeX 引擎（如 xelatex）编译成最终 PDF。
这意味着，如果你的系统没有安装完整的 LaTeX 环境（比如缺少 TeX Live 或 TinyTeX），PDF 导出会失败。因此，在实际使用中建议在容器内预装轻量级 LaTeX 发行版，例如通过以下命令安装 TinyTeX：
tlmgr init-usertree tlmgr install xecjk # 支持中文排版特别是处理中文内容时，若未启用xeCJK宏包，导出的 PDF 很可能出现方块乱码。解决方法是在导出时指定支持中文的模板，或在配置文件中设置字体映射。
相比之下，HTML 导出则更加友好，因为它仅依赖 Web 渲染引擎，且能保留部分交互特性，如折叠代码块、高亮语法、响应式布局等。生成的 HTML 文件可以直接部署到 GitHub Pages、内网服务器或邮件发送，读者无需安装任何软件即可在线查看。
而且，这些导出操作完全可以自动化。你可以编写一个简单的 Makefile 或 Python 脚本，批量处理多个.ipynb文件：
export: jupyter nbconvert --to html --execute *.ipynb --output-dir=docs/ jupyter nbconvert --to pdf --execute *.ipynb --output-dir=papers/每次模型更新后，运行make export，就能一键生成全套最新文档，极大提升了知识沉淀的效率。
从系统架构来看，整个工作流形成了一个闭环：
+------------------+ +----------------------------+ | | | | | Host Machine |<----->| PyTorch-CUDA-v2.7 | | (Linux/Windows) | | Docker Container | | | | | +------------------+ +---------+------------------+ | +---------------v------------------+ | | | Jupyter Notebook Server | | - 编写与调试 PyTorch 代码 | | - 实时查看训练可视化结果 | | | +----------------+-----------------+ | +-------------v--------------+ | | | nbconvert + Export | | -> HTML / PDF 输出 | | | +-------------+---------------+ | +-------------v--------------+ | | | Distribution Platform | | - GitHub Pages (HTML) | | - Email/PDF Report | | | +-----------------------------+开发者在容器中完成实验后，导出为多种格式，分别用于不同用途：HTML 用于在线展示，PDF 用于正式提交或打印讲义，原始.ipynb文件则作为可复现的研究记录存档。
这一模式不仅解决了“环境不一致”、“文档不同步”、“传播效率低”等常见痛点，更推动了一种新型工作范式的形成：文档不再是事后的总结，而是实验过程的自然产物。
当然，在落地过程中也有一些细节需要注意。例如：
- 使用--memory=8g限制容器内存，防止大模型训练时主机崩溃；
- 在导出前清理敏感信息，避免 API Key 或绝对路径被暴露在 HTML 中；
- 对.ipynb文件使用 Git 管理，并结合nbdime工具进行差异对比，提升版本控制体验；
- 若需频繁导出中文 PDF，建议构建自定义镜像，内置中文字体和 LaTeX 中文支持包。
未来，随着 MLOps 和 AI Engineering 的演进，“可执行文档”将成为标准实践的一部分。就像现代软件工程中测试覆盖率被视为质量指标一样，未来的 AI 项目评估可能会问：“你的实验能否一键导出为可读文档？”、“别人能否基于同一环境复现你的结果？”
掌握 Jupyter 的导出能力，熟悉容器化开发流程，已不再只是“加分项”，而是每一位 AI 工程师必须具备的基本功。
当你下一次准备写教程、做汇报或整理研究成果时，不妨试试这条路：从一个干净的容器开始，写下你的第一个 cell，最后用一行命令把它变成一份专业的学习资料——你会发现，最好的文档，从来都不是写出来的，而是跑出来的。
