欢迎来到 TensorWatch

TensorWatch 是由微软研究院开发的一款专为数据科学、深度学习和强化学习设计的调试与可视化工具。它可以在 Jupyter Notebook 中运行，实时展示您的机器学习训练过程，并为您的模型和数据执行多种关键分析任务。

TensorWatch 设计灵活且可扩展，因此您也可以构建自己的自定义可视化、用户界面和仪表板。除了传统的“所见即所记”方式外，它还具备一项独特功能：可以对正在运行的机器学习训练过程执行任意查询，将查询结果以流的形式返回，并使用您选择的可视化工具来查看这些数据（我们称之为 懒加载模式）。

TensorWatch 目前正处于积极开发中，目标是提供一个易于使用、可扩展且可自由修改的平台，用于机器学习的调试工作。

如何获取

pip install tensorwatch

TensorWatch 支持 Python 3.x，并已在 PyTorch 0.4–1.x 上进行了测试。大多数功能也应适用于 TensorFlow 的 eager 张量。TensorWatch 使用 graphviz 来生成网络图，根据您的平台不同，有时可能需要手动 安装 它。

安全声明

⚠ 重要提示：TensorWatch 是一款开发和调试工具，不适用于生产环境、多租户环境或对抗性环境。

TensorWatch 具备若干功能，按设计可执行任意代码。用户在部署之前必须充分了解这些风险。

1. 懒加载 — 对网络提供的表达式进行 eval() 调用 (CWE-94)

懒加载功能 (create_stream(expr=...)) 会通过 ZeroMQ 将 Python 表达式从 WatcherClient 发送到 Watcher 服务器。服务器会通过 Python 的 eval() 函数执行该表达式（位于 evaler.py 文件中）。这是设计使然，它允许客户端使用任意 Python 表达式查询正在运行的训练过程，从而实现交互式调试。然而，任何能够连接到 Watcher 的 ZMQ 端口并经过身份验证的客户端，都可在 Watcher 进程中执行任意 Python 代码。

已采取的缓解措施：

• 所有消息均采用 HMAC-SHA256 签名；只有共享密钥的进程才能发送表达式。
• Watcher 默认绑定到 127.0.0.1（本地回环地址），从而阻止远程连接，除非明确配置为其他地址。

用户责任：

• 请勿将 TensorWatch 的端口暴露给不受信任的网络或用户。
• 在多进程设置中（即 Watcher 和 WatcherClient 分别运行在不同进程中），请在调用 initialize() 之前将 ZmqWrapper._hmac_key 设置为共享密钥，以确保跨进程的 HMAC 认证有效。
• 请勿在存在不受信任用户本地网络访问权限的机器上运行 TensorWatch。

2. Pickle 反序列化 — 网络 (CWE-502)

所有 ZeroMQ 消息均使用 Python 的 pickle 模块进行序列化和反序列化。如果收到精心构造的负载，Pickle 反序列化可能会执行任意代码。

已采取的缓解措施：

• 所有传入的 ZMQ 消息都会在反序列化 之前 进行 HMAC-SHA256 验证（位于 ZmqWrapper.verify_and_loads 中）。签名无效的消息将被拒绝，不会进行反序列化。
• RestrictedUnpickler 使用一个 允许列表 来限制可加载的模块范围（包括内置模块、collections、numpy、torch、pandas、tensorwatch 以及 pickle 内部模块），作为纵深防御机制。任何未明确批准的模块都将被阻止，这比之前的黑名单方法更为严格。
• 对于多进程设置，请将 TENSORWATCH_HMAC_KEY 环境变量设置为一个共享的十六进制编码密钥（例如：export TENSORWATCH_HMAC_KEY=$(python -c "import os; print(os.urandom(32).hex())")）。或者，您也可以在调用 initialize() 之前直接在代码中设置 ZmqWrapper._hmac_key。

用户责任：

• 确保 HMAC 密钥保持机密，仅与受信任的进程共享。
• 请勿将 ZMQ 端口暴露给不受信任的网络。

3. Pickle 反序列化 — 文件 (CWE-502)

FileStream（位于 file_stream.py 中）使用 pickle.load() 从文件中读取流数据。如果文件经过恶意构造，加载时可能会执行任意代码。

已采取的缓解措施：

• RestrictedUnpickler 使用一个 允许列表 作为纵深防御机制。只有 TensorWatch 所需的模块（内置模块、collections、numpy、torch、pandas、tensorwatch）才被允许加载；其他模块默认会被阻止。

用户责任：

• 请仅打开由您自己创建或来自完全可信来源的 TensorWatch 数据文件（.log、.pkl）。
• 处理 TensorWatch 数据文件时，请像对待可执行脚本一样谨慎。

4. YAML 反序列化

附带的 hiddenlayer 工具包含 YAML 加载函数。这些函数默认使用 yaml.SafeLoader，以防止从 YAML 文件中实例化任意 Python 对象。处理不受信任的 YAML 输入时，请勿将加载器替换为 yaml.Loader 或 yaml.UnsafeLoader。

5. 预防措施总结

风险	缓解措施	用户行动
对客户端提供的表达式执行 eval()	HMAC 认证 + 绑定到本地回环地址	切勿将端口暴露给不受信任的网络
从 ZMQ 反序列化 pickle.loads()	HMAC + 允许列表 RestrictedUnpickler	保持 HMAC 密钥机密
从文件反序列化 pickle.load()	允许列表 RestrictedUnpickler（纵深防御）	仅加载受信任的文件
YAML 反序列化	默认使用 yaml.SafeLoader	不要替换为不安全的加载器
ZMQ 端口暴露	默认绑定到 127.0.0.1	在不受信任的环境中不要更改为 0.0.0.0

如何使用

快速入门

以下是一段简单的代码，每秒将一个整数及其平方以元组形式记录到 TensorWatch 中：

import tensorwatch as tw
import time

# 流数据将存储在 test.log 文件中
w = tw.Watcher(filename='test.log')

# 创建一个用于日志记录的流
s = w.create_stream(name='metric1')

# 生成 Jupyter Notebook 以查看实时流
w.make_notebook()

for i in range(1000):
    # 写入我们想要记录的 x, y 对
    s.write((i, i*i))

    time.sleep(1)

运行这段代码后，您会发现脚本文件夹中创建了一个名为 test.ipynb 的 Jupyter Notebook 文件。在命令提示符中输入 jupyter notebook，然后选择 test.ipynb。从菜单中选择 Cell > Run all，即可在脚本写入值时看到实时折线图。

以下是您将在 Jupyter Notebook 中看到的输出：

要深入了解其他各种功能，请参阅 教程 和 notebooks。

这究竟是如何工作的？

当您向 TensorWatch 流写入数据时，这些值会被序列化并通过 TCP/IP 套接字以及您指定的文件发送出去。在 Jupyter Notebook 中，我们会从文件中加载先前记录的值，然后监听该 TCP/IP 套接字以获取未来的值。可视化工具会监听该流，并在数据到达时将其渲染出来。

当然，以上只是一个非常简化的描述。实际上，TensorWatch 的架构要强大得多。TensorWatch 中几乎一切都是“流”。文件、套接字、控制台，甚至可视化工具本身也都是流。TensorWatch 流的一个很酷之处在于，它们可以监听任何其他流。这使得 TensorWatch 能够构建一个“数据流图”。这意味着一个可视化工具可以同时监听多个流，而每个流都可以是文件、套接字或其他类型的流。您可以递归地扩展这种结构，构建任意的数据流图。TensorWatch 将流与其存储方式和可视化方式解耦开来。

可视化

在上面的例子中，折线图被用作默认的可视化方式。然而，TensorWatch 还支持许多其他类型的图表，包括直方图、饼图、散点图、条形图，以及这些图表的 3D 版本。您只需记录数据并指定所需的图表类型，剩下的工作就交给 TensorWatch 来完成。

TensorWatch 的一大优势在于，它可以轻松地组合、构建和创建自定义可视化。例如，您可以选择在同一张图中可视化任意数量的流；也可以让同一个流同时出现在多张不同的图中；或者将任意一组可视化并排摆放。您甚至可以通过创建一个新的 Python 类并实现几个方法，来打造属于自己的自定义可视化组件。

比较多次运行的结果

每个 TensorWatch 流都可以包含您选择的指标。默认情况下，TensorWatch 会将所有流保存在一个文件中，但您也可以选择将每个流保存到单独的文件中，或者完全不保存（例如直接通过套接字或控制台发送流，从而避免对磁盘的任何写入）。之后，您可以打开这些流，并将它们导向一个或多个可视化工具。这种设计使您能够轻松地使用自己选择的可视化方式，快速比较不同实验的结果。

在 Jupyter Notebook 中进行训练

通常，您可能更倾向于在 Jupyter Notebook 中完成数据分析、机器学习训练和测试，而不是使用单独的脚本。TensorWatch 可以帮助您在 Jupyter Notebook 中无缝地执行复杂的实时可视化操作。

懒惰日志模式

TensorWatch 的一项独特功能是，它能够查询正在运行的进程，将查询结果作为流返回，并将该流导向您偏好的可视化工具。您无需事先记录任何数据。我们将这种新的调试和可视化方式称为“懒惰日志模式”。

例如，如下所示，我们在对水果数据集上的自编码器进行训练时，随机采样了输入和输出图像对，并进行了可视化。这些图像并未事先在脚本中记录下来。相反，用户通过一个 Python 匿名函数（lambda 表达式）发送查询，从而生成了一个图像流，并在 Jupyter Notebook 中显示出来：

请参阅 懒惰日志教程。

训练前与训练后任务

TensorWatch 利用多个优秀的库，包括 hiddenlayer、torchstat 和 Visual Attribution，将常见的调试和分析任务整合到一个一致的软件包和界面中。

例如，您只需一行代码即可查看带有张量形状的模型图：

您还可以查看不同层的统计信息，如浮点运算次数、参数数量等：

查看笔记本。

您还可以使用 t-SNE 等技术，将数据集映射到低维空间进行可视化：

查看笔记本。

预测解释

我们希望提供多种工具来解释模型的预测结果，以帮助调试模型。目前，我们为卷积神经网络提供了几种解释器，其中包括 Lime。例如，以下示意图突出显示了导致 ResNet50 模型对 ImageNet 数据集中的第 240 类做出预测的关键区域：

查看笔记本。

教程

• 简单日志记录教程

• 延迟日志记录教程

• 使用 TensorWatch 进行深度学习训练（MNIST）

• 使用 TensorWatch 进行深度学习训练（Food360）

• 使用 T-SNE 探索数据

• 卷积神经网络的预测解释器

• 查看模型图和统计信息

论文

更多技术细节请参阅 TensorWatch 论文（EICS 2019 大会）。引用格式如下：

@inproceedings{tensorwatch2019eics,
  author    = {Shital Shah 和 Roland Fernandez 和 Steven M. Drucker},
  title     = {用于深度学习训练实时交互式分析的系统},
  booktitle = {ACM SIGCHI 工程交互计算系统研讨会论文集，EICS 2019，西班牙瓦伦西亚，2019年6月18日至21日},
  pages     = {16:1--16:6},
  year      = {2019},
  crossref  = {DBLP:conf/eics/2019},
  url       = {https://arxiv.org/abs/2001.01215},
  doi       = {10.1145/3319499.3328231},
  timestamp = {2019年5月31日，星期五，08:40:31 +0200},
  biburl    = {https://dblp.org/rec/bib/conf/eics/ShahFD19},
  bibsource = {dblp 计算机科学文献数据库，https://dblp.org}
}

贡献

我们非常欢迎您的贡献、反馈、问题和功能请求！请 提交 GitHub 问题 或发送拉取请求。请阅读 微软行为准则 并参阅 贡献说明。

联系方式

加入 Facebook 上的 TensorWatch 群组，以获取最新动态或提出任何问题。

致谢

TensorWatch 利用多个开源库实现其众多功能。其中包括：hiddenlayer、torchstat、Visual-Attribution、pyzmq、receptivefield、nbformat。最新列表请参阅 setup.py 中的 install_requires 部分。

许可证

本项目采用 MIT 许可证发布。更多详情请参阅 许可证文件。

TensorWatch 快速上手指南

TensorWatch 是由微软研究院开发的调试与可视化工具，专为数据科学、深度学习和强化学习设计。它能在 Jupyter Notebook 中实时展示机器学习训练过程，并支持自定义仪表盘和“懒日志”（Lazy Logging）模式，无需预先记录即可对运行中的模型进行任意查询。

环境准备

• 操作系统：支持 Windows, macOS, Linux。
• Python 版本：Python 3.x。
• 深度学习框架：
  • PyTorch 0.4 - 1.x（主要测试环境）。
  • TensorFlow Eager Tensors（大多数功能兼容）。
• 前置依赖：
  • Graphviz：用于绘制网络结构图。部分平台需手动安装。
    • Ubuntu/Debian: sudo apt-get install graphviz
    • macOS (Homebrew): brew install graphviz
    • Windows: 下载安装包或使用 choco install graphviz。
  • Jupyter Notebook：用于查看实时可视化图表。

安装步骤

推荐使用国内镜像源加速安装（如清华源或阿里源）。

pip install tensorwatch -i https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 安全提示：TensorWatch 是开发调试工具，严禁在生产环境、多租户环境或不可信网络中使用。默认情况下它绑定在本地回环地址 (127.0.0.1)，请勿将其暴露给外部网络，以防任意代码执行风险。

基本使用

以下示例演示如何每秒记录一个整数及其平方，并在 Jupyter Notebook 中实时查看折线图。

1. 编写记录脚本

创建 log_script.py，运行后将生成日志文件 test.log 和可视化笔记本 test.ipynb。

import tensorwatch as tw
import time

# 初始化 Watcher，数据将存储在 test.log 文件中
w = tw.Watcher(filename='test.log')

# 创建一个名为 'metric1' 的数据流
s = w.create_stream(name='metric1')

# 生成用于查看实时数据的 Jupyter Notebook 文件
w.make_notebook()

for i in range(1000):
    # 写入 (x, y) 元组数据
    s.write((i, i*i))
    time.sleep(1)

2. 查看实时可视化

1. 运行上述脚本后，当前目录下会生成 test.ipynb。
2. 在终端启动 Jupyter Notebook：

   jupyter notebook
   

3. 在浏览器中打开 test.ipynb。
4. 点击菜单栏的 Cell > Run all。
5. 你将看到实时的折线图，随着脚本不断写入新数据，图表会动态更新。

核心原理简述

TensorWatch 将数据同时写入文件和 TCP/IP Socket。Jupyter Notebook 首先加载历史文件数据，然后监听 Socket 接收新数据流，从而实现“文件回放 + 实时推送”的双重可视化机制。