张量传感器

请参阅文章澄清深度学习代码中的异常并可视化张量操作以及TensorSensor实现幻灯片（PDF）。

（截至2021年9月，M1芯片的Mac在使用Anaconda安装的许多张量库时会遇到非法指令错误，因此目前TensorSensor预计仅能在基于Intel的Mac上运行。PyTorch似乎可以正常工作。）

编写实现深度学习网络的代码时，最大的挑战之一，尤其是对于我们这些新手来说，就是确保所有张量（矩阵和向量）的维度正确对齐。在涉及多个张量和张量运算的复杂表达式中，很容易迷失张量的维度信息。即使只是将数据输入到预定义的TensorFlow网络层中，我们也仍然需要确保维度正确。如果请求了不合法的计算，就会遇到一些不太友好的异常信息。

为了帮助自己和其他程序员调试张量代码，我构建了这个库。TensorSensor通过增强异常消息并可视化Python代码来指示张量变量的形状，从而澄清异常（右侧图示为预览）。它支持TensorFlow、PyTorch、JAX和Numpy，以及更高层次的库如Keras和fastai。

TensorSensor目前版本为1.0（2021年12月）。

可视化效果

更多内容请参见colab上的examples.ipynb。（由于某种原因，GitHub渲染无法显示图片：examples.ipynb。）

import numpy as np

n = 200         # 样本数量
d = 764         # 每个样本的特征数
n_neurons = 100 # 该层有多少个神经元？

W = np.random.rand(d,n_neurons)
b = np.random.rand(n_neurons,1)
X = np.random.rand(n,d)
with tsensor.clarify() as c:
    Y = W @ X.T + b

在Jupyter笔记本或单独窗口中显示如下：

而不是默认的以下异常信息：

ValueError: matmul: 输入操作数1的核心维度0不匹配，与通用函数签名 (n?,k),(k,m?)->(n?,m?) 不符（大小764与100不同）

TensorSensor会增强消息，提供更多关于导致问题的操作符的信息，并附上操作数的形状：

原因：@ 运算符作用于形状为(764, 100)的张量W和形状为(764, 200)的X.T

你还可以获取包含所有子表达式形状的完整计算图。

W = torch.rand(size=(2000,2000), dtype=torch.float64)
b = torch.rand(size=(2000,1), dtype=torch.float64)
h = torch.zeros(size=(1_000_000,), dtype=int)
x = torch.rand(size=(2000,1))
z = torch.rand(size=(2000,1), dtype=torch.complex64)

tsensor.astviz("b = W@b + (h+3).dot(h) + z", sys._getframe())

生成带有形状信息的抽象语法树：

安装

pip install tensor-sensor             # 这将仅为您安装库
pip install tensor-sensor[torch]      # 安装PyTorch相关依赖
pip install tensor-sensor[tensorflow] # 安装TensorFlow相关依赖
pip install tensor-sensor[jax]        # 安装JAX及jaxlib
pip install tensor-sensor[all]        # 安装TensorFlow、PyTorch和JAX

这将为您提供模块tsensor。我在以下版本上进行了开发和测试：

$ pip list | grep -i flow
tensorflow                         2.5.0
tensorflow-estimator               2.5.0
$ pip list | grep -i numpy
numpy                              1.19.5
numpydoc                           1.1.0
$ pip list | grep -i torch
torch                              1.10.0
torchvision                        0.10.0
$ pip list | grep -i jax
jax                                0.2.20
jaxlib                             0.1.71

Graphviz用于tsensor.astviz()

要使用tsensor.astviz(...)显示抽象语法树（AST），你需要Graphviz中的dot可执行文件，而不仅仅是Python库。

在Mac上，请在安装TensorSensor之前或之后执行：

brew install graphviz

在Windows上，显然需要：

conda install python-graphviz  # 先执行此命令；会获得dot可执行文件和Python库
pip install tensor-sensor      # 或者选择其他安装方式

局限性

我仅依赖于解析赋值语句或表达式行，因此clarify和explain例程无法处理如下形式的方法调用：

def bar(): b + x * 3

应改为：

def bar():
	b + x * 3

请注意副作用！我不处理赋值操作，但如果你调用的任何函数具有副作用，在我重新评估语句的过程中它们也会被执行。

无法处理反斜杠续行。

使用Python threading包时，不要让多个线程同时调用clarify()。而multiprocessing包应该没有问题。

另外需要注意的是：我构建了自己的解析器，专门用于处理TensorSensor能够处理的赋值和表达式。

部署（parrt的使用）

$ python setup.py sdist upload 

或者下载并在本地安装：

$ cd ~/github/tensor-sensor
$ pip install .

待办事项

• 是否可以在调试器中调用pyviz？

Tensor Sensor 快速上手指南

Tensor Sensor 是一个用于调试深度学习代码的 Python 库，旨在帮助开发者理清张量（矩阵/向量）的维度匹配问题。它能通过增强异常报错信息和可视化代码执行过程，直观地展示张量形状，适用于 TensorFlow、PyTorch、JAX 和 NumPy 等主流框架。

环境准备

• 操作系统：
  • 推荐 Intel 架构的 macOS、Linux 或 Windows。
  • ⚠️ 注意：截至 2021 年 9 月，通过 Anaconda 安装的许多张量库在 M1 Mac 上会出现非法指令错误，导致 Tensor Sensor 无法正常工作（尽管 PyTorch 本身可能正常）。
• Python 版本：兼容主流 Python 3.x 版本。
• 前置依赖：
  • 基础功能仅需安装本库。
  • 若需使用 tsensor.astviz() 生成抽象语法树可视化图像，必须安装系统级的 Graphviz 工具（不仅仅是 Python 包）：
    • macOS: brew install graphviz
    • Windows: 建议先执行 conda install python-graphviz 获取可执行文件，再安装 Python 库。
    • Linux: sudo apt-get install graphviz (Ubuntu/Debian) 或对应发行版命令。

安装步骤

使用 pip 进行安装，可根据需要选择安装特定的深度学习框架依赖。国内用户建议使用清华或阿里镜像源加速下载。

# 仅安装核心库
pip install tensor-sensor -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 PyTorch 相关依赖
pip install tensor-sensor[torch] -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 TensorFlow 相关依赖
pip install tensor-sensor[tensorflow] -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 JAX 相关依赖
pip install tensor-sensor[jax] -i https://pypi.tuna.tsinghua.edu.cn/simple

# 一次性安装所有框架依赖 (TensorFlow, PyTorch, JAX)
pip install tensor-sensor[all] -i https://pypi.tuna.tsinghua.edu.cn/simple

开发测试参考版本：TensorFlow 2.5.0, PyTorch 1.10.0, JAX 0.2.20, NumPy 1.19.5

基本使用

1. 增强异常报错信息 (Clarify Exceptions)

当张量维度不匹配时，原生报错往往晦涩难懂。使用 tsensor.clarify() 上下文管理器可以捕获错误并输出包含具体操作符和张量形状的清晰提示。

import numpy as np
import tsensor

n = 200         # 样本数量
d = 764         # 特征数量
n_neurons = 100 # 神经元数量

W = np.random.rand(d, n_neurons)
b = np.random.rand(n_neurons, 1)
X = np.random.rand(n, d)

# 使用 clarify 上下文包裹可能出错的代码
with tsensor.clarify() as c:
    # 此处故意制造维度错误：W (764, 100) @ X.T (764, 200) 无法相乘
    Y = W @ X.T + b

效果对比：

• 原生报错：ValueError: matmul: Input operand 1 has a mismatch in its core dimension 0...
• Tensor Sensor 增强后：

  Cause: @ on tensor operand W w/shape (764, 100) and operand X.T w/shape (764, 200)
  

  (在 Jupyter Notebook 中还会自动弹出可视化的矩阵运算示意图)

2. 可视化计算图与张量形状 (AST Visualization)

使用 tsensor.astviz() 可以生成包含所有子表达式形状的抽象语法树（AST），帮助理解复杂表达式的计算流程。

import torch
import tsensor
import sys

W = torch.rand(size=(2000, 2000), dtype=torch.float64)
b = torch.rand(size=(2000, 1), dtype=torch.float64)
h = torch.zeros(size=(1_000_000,), dtype=int)
x = torch.rand(size=(2000, 1))
z = torch.rand(size=(2000, 1), dtype=torch.complex64)

# 将表达式作为字符串传入，并传递当前帧对象
tsensor.astviz("b = W@b + (h+3).dot(h) + z", sys._getframe())

执行后将生成一张 SVG 图片，清晰展示每个运算节点的输入输出形状。

⚠️ 使用限制与注意事项

1. 代码格式：解析器仅支持独立的赋值语句或表达式。请勿将表达式写在单行函数定义中（如 def bar(): b + x），应将其放在函数体内部多行书写。
2. 副作用：库会通过重新评估语句来工作，请避免在 monitored 代码块中调用具有副作用（side effects）的函数。
3. 续行符：不支持使用 \ 进行代码换行。
4. 多线程：在使用 Python threading 模块时，不要在多个线程中同时调用 clarify()；使用 multiprocessing 通常没有问题。