TDB

*注意：该项目已不再积极维护。请查看官方的 tfdbg 调试器

TensorDebugger (TDB) 是一个用于深度学习的可视化调试器。它通过断点和对计算图中流动数据的实时可视化，扩展了 TensorFlow（Google 的深度学习框架）的功能。

视频演示

具体来说，TDB 是由一个 Python 库和一个 Jupyter Notebook 扩展组成的，基于 Google 的 TensorFlow 框架构建。它们共同为 TensorFlow 增加了以下功能：

• 断点：可以在图中的 Op 和 Tensor 上设置断点。当遇到断点时，图的执行会被暂停，用户可以通过 tdb.c() 来恢复执行。调试功能可以单独使用，也可以与可视化前端结合使用。
• 任意摘要绘图：在网络训练过程中，实时可视化高层次信息（例如直方图、梯度大小、权重饱和度等）。支持用户自定义的绘图函数。
• 灵活性：可以将用户自定义的 Python 函数和绘图函数与 TensorFlow 节点混合使用。这些函数接收 tf.Tensor 作为输入，并输出占位符节点，以便插入到 TensorFlow 节点中。下图展示了 TDB 节点如何与 TensorFlow 图混合使用。

动机

现代机器学习模型在参数上非常复杂，需要大量的直觉才能正确地进行调优。

特别是深度学习方法，虽然功能强大，但在理解其能力和学习到的表示方面却非常困难。

我们能否在不修改模型代码或牺牲性能的情况下，更好地理解神经网络的学习过程呢？我还能按时完成论文吗？

TDB 通过提供神经网络的运行时可视化工具来应对这些挑战。实时可视化调试能够更早地发现训练中的错误，从而减少构建正确模型所需的迭代时间。

安装

要安装 Python 库，

pip install tfdebugger

要安装 Jupyter Notebook 扩展，请在 Python 终端中运行以下命令（您需要先安装 IPython 或 Jupyter）

import notebook.nbextensions
import urllib
import zipfile
SOURCE_URL = 'https://github.com/ericjang/tdb/releases/download/tdb_ext_v0.1/tdb_ext.zip'
urllib.urlretrieve(SOURCE_URL, 'tdb_ext.zip')
with zipfile.ZipFile('tdb_ext.zip', "r") as z:
    z.extractall("")
notebook.nbextensions.install_nbextension('tdb_ext',user=True)

教程

要开始使用，请查看 MNIST 可视化演示。更多示例和可视化内容即将推出。

用户指南

调试

启动

status,result=tdb.debug(evals,feed_dict=None,breakpoints=None,break_immediately=False,session=None)

debug() 的行为与 TensorFlow 的 Session.run() 完全相同。如果命中断点，则 status 会被设置为 'PAUSED'，result 会被设置为 None。否则，status 会被设置为 'FINISHED'，result 则是一个包含所有评估值的列表。

继续

status,result=tdb.c()

继续执行已暂停的会话，直到下一个断点或结束。行为与 debug 相同。

单步

status,result=tdb.s()

评估下一个节点，然后立即暂停以等待用户输入。除非已经到达执行队列的末尾，否则 status 将保持为 'PAUSED'。result 会被设置为刚刚评估的节点的值。

查看剩余节点

q=tdb.get_exe_queue()

返回值：按顺序排列的待评估节点列表。

打印节点值

val=tdb.get_value(node)

返回已评估节点的值（字符串名称或 tf.Tensor）。

自定义节点

TDB 支持两种类型的自定义 Op：

Python

以下是一个将 tdb.PythonOps 与 TensorFlow 混合使用的示例。

定义如下函数：

def myadd(ctx,a,b):
	return a+b

a=tf.constant(2)
b=tf.constant(3)
c=tdb.python_op(myadd,inputs=[a,b],outputs=[tf.placeholder(tf.int32)]) # a+b
d=tf.neg(c)
status,result=tdb.debug([d], feed_dict=None, breakpoints=None, break_immediately=False)	

当 myadd 被评估时，ctx 是它所属的 PythonOp 实例。您可以使用 ctx 来存储状态信息（例如累计损失历史）。

绘图

PlotOps 是一种特殊的 PythonOp，它可以将图形输出发送到前端。

目前仅支持 Matplotlib，但其他绘图后端（Seaborn、Bokeh、Plotly）也将很快推出。

def watch_loss(ctx,loss):
  if not hasattr(ctx, 'loss_history'):
    ctx.loss_history=[]
  ctx.loss_history.append(loss)
  plt.plot(ctx.loss_history)
  plt.ylabel('loss')

ploss=tdb.plot_op(viz.watch_loss,inputs=[loss])

更多示例请参阅 MNIST 可视化演示。您还可以在 tests/ 目录中找到更多示例。

常见问题

TDB 是否隶属于 TensorFlow？

不是，但它构建在 TensorFlow 之上。

TDB 适合用于什么场景？

TDB 在模型原型设计阶段以及以直观的方式验证正确性时特别有用。它也适用于在训练过程中对隐藏层进行高层次的可视化。

TDB 与 TensorBoard 有何不同？

TensorBoard 是 TensorFlow 自带的一套可视化工具。TDB 和 TensorBoard 都会在 TensorFlow 图上附加辅助节点来检查数据。

TensorBoard 不能与正在运行的 TensorFlow 图同时使用；必须先写入日志文件。而 TDB 则可以直接与 TensorFlow 图的执行交互，并允许逐个节点地单步执行。

开箱即用时，TensorBoard 目前仅支持几种预定义数据格式的日志记录。

TDB 之于 TensorBoard，正如 GDB 之于 printf。两者在不同的场景下都很有用。

许可证

Apache 2.0

TDB 快速上手指南

注意：本项目已不再积极维护。如需生产环境调试，建议参考官方 tfdbg debugger。本指南仅供学习或遗留项目参考。

TDB (TensorDebugger) 是一个专为深度学习设计的可视化调试器，它扩展了 TensorFlow，支持断点调试和计算图中数据流的实时可视化。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：推荐 Python 2.7 或 Python 3.5+（取决于你的 TensorFlow 版本）
• 前置依赖：
  • TensorFlow
  • Jupyter Notebook 或 IPython
  • matplotlib (用于绘图功能)
  • pip 包管理工具

安装步骤

1. 安装 Python 库

使用 pip 安装核心库：

pip install tfdebugger

(国内用户如遇下载缓慢，可尝试指定清华镜像源：pip install tfdebugger -i https://pypi.tuna.tsinghua.edu.cn/simple)

2. 安装 Jupyter Notebook 扩展

在 Python 终端（命令行输入 python 进入）中运行以下代码以安装前端扩展：

import notebook.nbextensions
import urllib
import zipfile

# 下载扩展包
SOURCE_URL = 'https://github.com/ericjang/tdb/releases/download/tdb_ext_v0.1/tdb_ext.zip'
urllib.urlretrieve(SOURCE_URL, 'tdb_ext.zip')

# 解压并安装
with zipfile.ZipFile('tdb_ext.zip', "r") as z:
    z.extractall("")
notebook.nbextensions.install_nbextension('tdb_ext', user=True)

注：如果使用 Python 3，可能需要将 import urllib 改为 import urllib.request 并调整 urlretrieve 的调用方式，或者手动下载 zip 包后解压安装。

基本使用

TDB 的使用方式与 TensorFlow 原生的 Session.run() 非常相似，但增加了断点和步进功能。

1. 启动调试 (Debug)

使用 tdb.debug() 替代 session.run()。如果命中断点，执行会暂停并返回状态 'PAUSED'。

import tdb
import tensorflow as tf

# 定义简单的计算图
a = tf.constant(2)
b = tf.constant(3)
c = a + b

# 启动调试
# evals: 需要计算的节点列表
# breakpoints: 可选，设置断点的节点名称列表
status, result = tdb.debug(evals=[c], feed_dict=None, breakpoints=None)

if status == 'PAUSED':
    print("调试已暂停")
else:
    print("计算结果:", result)

2. 继续执行 (Continue)

当调试暂停时，使用 tdb.c() 继续运行直到下一个断点或结束。

status, result = tdb.c()

3. 单步执行 (Step)

使用 tdb.s() 执行下一个节点并立即暂停，适合逐节点排查问题。

status, result = tdb.s()
# result 包含刚刚执行过的节点的值

4. 查看当前队列与数值

• 查看剩余待执行节点：

  queue = tdb.get_exe_queue()
  

• 获取特定节点的值：

  val = tdb.get_value(node_name_or_tensor)
  

5. 自定义绘图监控

你可以定义函数来实时监控训练指标（如 Loss），并将其作为节点插入图中。

import matplotlib.pyplot as plt
import tdb

def watch_loss(ctx, loss_val):
    if not hasattr(ctx, 'loss_history'):
        ctx.loss_history = []
    ctx.loss_history.append(loss_val)
    
    plt.clf() # 清空画布
    plt.plot(ctx.loss_history)
    plt.ylabel('loss')
    plt.pause(0.01) # 短暂暂停以刷新图像

# 假设 loss 是一个 TensorFlow Tensor
# ploss = tdb.plot_op(watch_loss, inputs=[loss])
# 将 ploss 加入你的 fetch 列表中进行调试

更多详细示例请参考项目自带的 MNIST Visualization Demo。