3. 环境搭建：Python环境配置、安装ONNX、Netron、Graphviz等工具

3.1 核心原理：为什么需要一套“可复现”的工具链

模型结构可视化并非单一工具能完成的任务，而是一条由多个环节组成的链路。ONNX本身只是模型的一种中间表示格式，它不提供图形化界面；Netron负责将ONNX文件解析为交互式结构图，但它无法输出矢量化的拓扑图；Graphviz则擅长将ONNX导出的点边关系渲染为静态图片。三者各司其职，缺一不可。此外，Python环境是所有操作的基座——无论是安装onnx、onnxruntime，还是运行转换脚本，都依赖一个干净、版本可控的解释器环境。

理解这条链路的关键在于：ONNX文件是“数据源”，Netron是“交互式浏览器”，Graphviz是“批量化渲染器”。在实际工程中，你可能需要快速查看某个节点的输入输出维度（用Netron），也可能需要将整个模型的拓扑结构嵌入到技术文档或论文中（用Graphviz）。因此，环境搭建的目标不是安装单一工具，而是让这些工具在同一套Python生态中协同工作。

3.2 方法流程：从零搭建可视化环境

环境搭建遵循“先建隔离环境，再逐层安装工具，最后验证连通性”的流程。推荐使用Python 3.9或3.10，这两个版本对ONNX生态的兼容性最好。以下步骤在Windows/macOS/Linux上均适用，仅激活虚拟环境的命令略有差异。

步骤一：创建并激活虚拟环境

# 使用 venv（Python 3.3+ 内置）
python -m venv onnx_env
# Windows 激活
onnx_env\Scripts\activate
# macOS / Linux 激活
source onnx_env/bin/activate

步骤二：安装核心Python库

pip install --upgrade pip
pip install onnx onnxruntime
pip install netron
pip install graphviz pydot

其中，onnx提供模型解析与操作API，onnxruntime用于推理验证，netron是Python版的Netron启动器，graphviz是Graphviz的Python封装，pydot则负责将ONNX图转换为DOT语言描述。

步骤三：安装系统级Graphviz引擎

Graphviz的Python包只是接口，真正的渲染引擎需要单独安装。若缺失，调用graphviz.Source.render()时会报ExecutableNotFound错误。

步骤四：验证安装是否成功

python -c "import onnx; print('ONNX', onnx.__version__)"
python -c "import onnxruntime; print('ORT', onnxruntime.__version__)"
python -c "import netron; print('Netron OK')"
python -c "import graphviz; print('Graphviz', graphviz.__version__)"

若输出类似ONNX 1.16.0、ORT 1.17.1、Netron OK、Graphviz 0.20.1，则说明核心库已就绪。此时可运行netron.start('model.onnx')启动交互式界面，或使用onnx.tools.net_drawer生成静态图。

3.3 案例/场景：用一段代码串联整个工具链

下面以一个简单的PyTorch线性模型为例，演示从模型导出到Graphviz静态图渲染的完整流程。该案例覆盖了环境搭建后最常用的操作路径。

import torch
import torch.nn as nn
import onnx
from onnx.tools.net_drawer import GetPydotGraph, GetOpNodeProducer

# 1. 定义并导出ONNX模型
class SimpleNet(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc = nn.Linear(4, 2)

    def forward(self, x):
        return self.fc(x)

model = SimpleNet()
dummy_input = torch.randn(1, 4)
torch.onnx.export(model, dummy_input, "simple.onnx",
                  input_names=["input"], output_names=["output"],
                  opset_version=17)

# 2. 验证模型完整性
onnx_model = onnx.load("simple.onnx")
onnx.checker.check_model(onnx_model)
print("模型校验通过")

# 3. 使用Netron启动交互式视图
import netron
netron.start("simple.onnx")  # 浏览器自动打开

# 4. 使用Graphviz生成静态PNG
pydot_graph = GetPydotGraph(
    onnx_model.graph,
    name=onnx_model.graph.name,
    rankdir="TB",
    node_producer=GetOpNodeProducer("color", "white", "black", "none", "filled")
)
pydot_graph.write_png("simple_graph.png")
print("静态图已保存为 simple_graph.png")

执行上述代码后，你会得到两个可视化结果：Netron的交互式页面支持点击节点查看算子属性、输入输出张量形状；而simple_graph.png则是一张自上而下的拓扑图，适合直接插入文档。值得注意的是，GetPydotGraph默认只显示算子节点，不显示初始器（权重），若需展示权重需额外处理。

3.4 误区/复盘：环境搭建中的常见陷阱

误区一：混淆“Python包”与“系统程序”。很多初学者安装完pip install graphviz后，直接调用dot命令失败，便以为安装不成功。实际上，Python包只是提供API接口，真正的dot可执行文件来自系统级安装。同理，Netron的Python包也依赖系统是否安装了合适的浏览器内核。

误区二：忽略opset版本兼容性。在导出ONNX时，opset_version参数决定了算子集版本。若设置过高（如opset 20），而onnxruntime版本较旧，推理时会报Unsupported operator错误。建议在requirements.txt中固定版本组合，例如：

onnx==1.16.0
onnxruntime==1.17.1
netron==7.6.0
graphviz==0.20.1
pydot==2.0.0

误区三：在Jupyter Notebook中直接调用netron.start()会阻塞内核。Netron启动后默认开启一个HTTP服务并阻塞当前线程。在Notebook中应使用threading.Thread(target=netron.start, args=("model.onnx",), daemon=True).start()，否则后续单元格无法执行。

误区四：Graphviz中文标签乱码。ONNX模型中的节点名称若包含中文（自定义算子时常见），生成的PNG会出现方框。解决方案是在GetPydotGraph后手动设置字体：

pydot_graph.set_graph_defaults(fontname="Microsoft YaHei")
pydot_graph.set_node_defaults(fontname="Microsoft YaHei")

复盘整个搭建过程，最核心的经验是：先验证最小闭环，再扩展功能。建议首次搭建时，先跑通“导出ONNX → Netron查看”这条最短路径，确认环境无虞后，再引入Graphviz等静态渲染工具。这样能快速定位问题出在哪个环节——是模型导出失败，还是可视化工具配置错误。

最后，建议将上述安装命令整理为一个setup.sh或requirements.txt脚本，放入项目仓库。当需要在新机器上复现环境时，只需执行一条命令即可完成全部配置，这也是工程化协作的基本要求。