假设分析工具

假设分析工具（WIT）提供了一个易于使用的界面，用于深入理解黑盒分类或回归机器学习模型。通过该插件，您可以对大量示例进行推理，并以多种方式立即可视化结果。此外，还可以手动或通过编程方式编辑示例，然后重新输入模型以查看更改的效果。它还包含用于在数据集的子集上评估模型性能和公平性的工具。

该工具的目的是为用户提供一种简单、直观且强大的方式，通过可视化界面在不编写任何代码的情况下，对一组数据上的训练好的机器学习模型进行探索和实验。

该工具可以通过 TensorBoard 访问，也可以作为 Jupyter 或 Colab 笔记本中的扩展使用。

我不想阅读这份文档，可以直接体验演示吗？

请访问 假设分析工具官网的演示部分，那里提供了大量的网页版和 Colab 演示。

要自行构建网页版演示：

• UCI Census 数据集薪资预测二分类器
  • 数据集：UCI Census
  • 任务：根据人口普查信息预测个人收入是否超过 5 万美元
  • 从代码构建并运行演示： bazel run wit_dashboard/demo:demoserver 然后访问 http://localhost:6006/wit-dashboard/demo.html
• 图像微笑检测二分类器
  • 数据集：CelebA
  • 任务：预测图像中的人是否在微笑
  • 从代码构建并运行演示： bazel run wit_dashboard/demo:imagedemoserver 然后访问 http://localhost:6006/wit-dashboard/image_demo.html
• Iris 数据集多分类器
  • 数据集：UCI Iris
  • 任务：根据花朵的四维测量值，预测花朵属于三种鸢尾花类别中的哪一类
  • 从代码构建并运行演示： bazel run wit_dashboard/demo:irisdemoserver 然后访问 http://localhost:6006/wit-dashboard/iris_demo.html
• UCI Census 数据集年龄预测回归模型
  • 数据集：UCI Census
  • 任务：根据人口普查信息预测个人年龄
  • 从代码构建并运行演示： bazel run wit_dashboard/demo:agedemoserver 然后访问 http://localhost:6006/wit-dashboard/age_demo.html
  • 该演示模型除了预测之外，还会返回归因值（通过使用普通梯度），以展示该工具如何显示预测的归因值。

在 Jupyter 或 Colab 笔记本中使用它需要什么？

您可以在 Jupyter 或 Colab 笔记本中直接使用假设分析工具来分析以 TensorFlow Example 或 SequenceExample 协议缓冲区（数据点）为输入的 TensorFlow Estimator 分类或回归模型。

此外，假设分析工具还可以分析由 AI Platform Prediction 托管的分类或回归模型，这些模型接受 TensorFlow Example 协议缓冲区、SequenceExample 协议缓冲区或原始 JSON 对象作为输入。

您还可以将假设分析工具与自定义预测函数一起使用，该函数接收 TensorFlow 示例并生成预测。在这种模式下，只要您的自定义函数的输入和输出规范正确，就可以加载任何模型（包括不使用 Example 协议缓冲区作为输入的非 TensorFlow 模型）。

无论是 AI Platform 模型还是自定义预测函数，假设分析工具都可以显示并利用每个输入特征相对于每项预测的归因值。有关更多信息，请参阅下面关于归因值的部分。

如果您想从数据集训练一个机器学习模型，并探索该数据集和模型，可以参考 Colab 中的 What_If_Tool_Notebook_Usage.ipynb 笔记本，该笔记本从 CSV 文件开始，将数据转换为 tf.Example 协议缓冲区，训练一个分类器，然后使用假设分析工具展示分类器在该数据上的表现。

在 TensorBoard 中使用它需要哪些内容？

关于如何在 TensorBoard 中使用该工具的完整指南，包括预训练模型和测试数据集，可以在 TensorBoard 官网的 What-If 工具页面 上找到。

要在 TensorBoard 中使用该工具，只需提供以下信息：

• 模型服务器的主机名和端口，该服务器需使用 TensorFlow Serving 提供服务。模型可以使用 TensorFlow Serving 的分类、回归或预测 API。
  • 关于如何使用 Estimator API 创建保存模型，并使其能够与适当的 TensorFlow Serving 分类或回归 API 配合使用的说明，可在 保存模型文档 和这篇实用教程中找到。 使用这些 API 的模型是最容易与 What-If 工具配合使用的，因为除了设置模型类型外，无需在工具中进行额外配置。
  • 如果模型使用预测 API，则输入必须是序列化的 tf.Example 或 tf.SequenceExample 协议缓冲区消息，且输出应符合以下要求：
    • 对于分类模型，输出必须包含一个二维浮点张量，其中为每个推断示例列出所有可能类别索引对应的概率值。
    • 对于回归模型，输出必须包含一个浮点张量，其中为每个推断示例提供单个回归分数。
  • What-If 工具通过 gRPC API 而不是 RESTful API 查询已部署的模型。有关这两种 API 的更多信息，请参阅 TensorFlow Serving 的 Docker 文档。Docker 镜像默认使用 8500 端口提供 gRPC API，因此如果采用 Docker 方式部署，那么在 What-If 工具中指定的端口应为 8500。
  • 或者，您也可以不查询由 TensorFlow Serving 托管的模型，而是通过 --whatif-use-unsafe-custom-prediction 运行时参数向工具提供自定义的 Python 预测函数，具体说明见下文。
• 用于执行推理的 tf.Example 或 tf.SequenceExample 格式的 TFRecord 文件，以及从该文件中加载的示例数量。
  • 最多可处理数万个示例。具体数量取决于每个示例的大小（特征数量及特征值的大小）。
  • 该文件必须位于启动 TensorBoard 时提供的日志目录中。此外，您还可以通过 -whatif-data-dir=PATH 运行时参数指定其他目录，以允许从该目录加载文件。
• 指明模型是回归模型、二分类模型还是多分类模型。
• 可选的分类模型标签词汇表文件。该文件将模型预测返回的类别索引映射为类别标签。文本文件每行对应一个标签，按模型返回的类别索引顺序排列，从索引 0 开始。
  • 如果提供了此文件，仪表板将显示分类模型的预测标签；否则，将显示预测的类别索引。

或者，您也可以直接使用 What-If 工具从 CSV 文件中探索数据集。详情请参阅下一节。

上述信息可以在设置对话框中提供，该对话框会在打开此工具时自动弹出，也可通过工具右上角的设置图标按钮访问。此外，这些信息也可以直接通过 URL 参数传递。通过控件更改设置会自动更新 URL，以便与其他用户共享，使他们能够在 What-If 工具中查看相同的数据。

我只有数据集，在 TensorBoard 中能做什么？从哪里开始？

如果您只想使用 TensorBoard 中的 What-If 工具探索 CSV 文件中的信息，只需将示例路径设置为该文件（扩展名为 .csv），并将推理地址和模型名称字段留空即可。CSV 文件的第一行必须包含列名。此后每一行代表数据集中的一条记录，其值对应第一行定义的各列。对于某一特征的多个取值，各值之间用竖线字符 (|) 分隔。

为了充分利用该工具对模型的理解功能，您的数据集可以包含来自机器学习模型的输出列。例如，如果您的文件中有一列名为 predictions__probabilities，其值是以竖线分隔的概率分数列表（介于 0 和 1 之间），则工具会将其视为分类模型的输出概率。如果您的文件中有一列名为 predictions 的数值列，则工具会将其视为回归模型的输出。通过这种方式，该工具可用于分析任何数据集，以及针对该数据集离线运行的任何模型结果。请注意，在此模式下，示例不可编辑，因为当示例发生变化时无法获取新的推理结果。

它能做什么？

有关该工具功能的详细信息，包括引导式操作指南，可在 What-If Tool 官网 上找到。以下是其主要功能的简要概述：

• 可视化 TensorFlow Example 协议缓冲区数据集。

  • 主面板使用 Facets Dive 展示数据集，其中样本可按数据集中的任意特征进行组织、切片、定位或着色。
    • 样本也可按其推理结果进行组织。
      • 对于分类模型，这包括推断标签、推断标签的置信度以及推理是否正确。
      • 对于回归模型，这包括推断分数及推理误差（包括绝对误差或平方误差）。
  • 在侧边栏中可以详细查看选定的样本，显示该样本所有特征的特征值。
  • 对于在名为“image/encoded”的字节型特征中包含编码图像的样本，Facets Dive 会生成该图像的缩略图以直观展示，而完整尺寸的图像则会在侧边栏中针对选定样本显示。
  • 使用 Facets Overview，可以在侧边栏中查看所有已加载样本的汇总统计信息。

• 可视化推理结果

  • 默认情况下，主面板中的样本会根据其推理结果着色。
  • 主面板中的样本可以组织成混淆矩阵和其他自定义布局，以按多种不同特征分面展示推理结果，或按推理结果分面/定位，从而创建一维和二维直方图及散点图的小多图。
  • 对于选定的样本，侧边栏会显示详细的推理结果（例如预测类别及其置信度分数）。
  • 如果模型除了预测之外还返回了归因值，则会为每个选定样本显示这些归因值，并且这些归因值可用于控制自定义布局，以及作为切分数据集的维度，以便进行性能分析。

• 探索反事实样本

  • 对于分类模型，对于任何选定的样本，只需单击一下即可将其与最相似但被分类为不同类别的样本进行比较。
  • 相似性是基于所有已加载样本中特征值的分布来计算的，可以使用 L1 或 L2 距离来衡量。
    • 特征之间的距离会进行归一化处理：
      • 对于数值特征，使用各样本之间特征值之差除以所有样本特征值的标准差。
      • 对于分类特征，如果两个样本的特征值相同，则距离为 0；否则，距离即为所有样本中任意两个样本在该特征上取相同值的概率。
  • 在笔记本模式下，该工具还允许您使用 WitConfigBuilder 中的 set_custom_distance_fn 设置自定义距离函数，用以计算最近的反事实样本。与自定义 predict_fn 的情况类似，自定义距离函数可以是任何 Python 函数。

• 在浏览器中编辑选定的样本并重新运行推理，可视化推理结果的变化。

  • 查看自动生成的部分依赖图，这些图表会针对每个特征展示当该特征取不同的有效值时推理结果的变化情况。
  • 在侧边栏中编辑、添加或删除任意特征或特征值，并对编辑后的数据点重新运行推理。系统会显示该数据点在编辑和重新推理过程中的推理值历史记录。
  • 对于包含编码图像的样本，您可以上传自己的图像并重新运行推理。
  • 克隆现有样本以进行编辑或比较。
  • 撤销对已编辑样本的更改。

• 比较两个模型在同一输入数据上的推理结果。

  • 如果在设置过程中向该工具提供两个模型，它将使用提供的数据对这两个模型分别运行推理，然后您可以利用上述所有功能比较两个模型的推理结果。

• 如果使用二分类模型且您的样本包含描述真实标签的特征，您可以执行以下操作：

  • 在侧边栏中查看 ROC 曲线和数值混淆矩阵，包括在当前阳性分类阈值下您的模型所处的曲线上对应点。
  • 查看按数据集子集划分的独立 ROC 曲线和数值混淆矩阵，这些子集可根据数据集中的任意特征进行切片（例如按性别划分）。
  • 手动调整阳性分类阈值（或多个阈值，如果按某个特征切分数据集），并立即查看推理结果、ROC 曲线位置和混淆矩阵的变化。
  • 根据假阳性和假阴性的成本权衡，以及公平性指标（如机会均等或人口统计学平等）的要求，一键设置阳性分类阈值。

• 如果使用多分类模型且您的样本包含描述真实标签的特征，您可以执行以下操作：

  • 在侧边栏中查看所有分类和所有类别的混淆矩阵。
  • 查看按数据集子集划分的独立混淆矩阵，这些子集可根据数据集中的任意特征进行切片。

• 如果使用回归模型且您的样本包含描述真实标签的特征，您可以执行以下操作：

  • 查看整个数据集的平均误差、平均绝对误差和平均平方误差。
  • 查看按数据集子集划分的这些平均误差计算结果，这些子集可根据数据集中的任意特征进行切片。

适用于哪些人群？

我们设想 WIT 对各类用户都非常有用。

• 机器学习研究人员和模型开发者——研究您的数据集和模型，探索推理结果。通过操作数据和模型来获得洞察，例如调试异常结果或研究机器学习的公平性问题。
• 非技术利益相关者——了解模型在特定数据集上的表现。尝试使用您自己的数据进行体验。
• 普通用户——通过交互式地玩转数据集和模型来学习机器学习知识。

笔记本模式详情

如示例笔记本所示，创建 WitWidget 对象是使“What-If 工具”在输出单元格中显示的关键步骤。WitWidget 对象以一个 WitConfigBuilder 对象作为构造函数参数。WitConfigBuilder 对象指定了“What-If 工具”将使用的数据和模型信息。

WitConfigBuilder 对象以一组 tf.Example 或 tf.SequenceExample 协议缓冲区作为构造函数参数。这些协议缓冲区将在工具中显示，并用于推断指定的模型。

工具用于推理的模型可以通过多种方式指定：

• 作为通过 set_estimator_and_feature_spec 方法提供的 TensorFlow Estimator 对象。在这种情况下，推理将在笔记本内部使用提供的 Estimator 完成。
• 作为通过 set_ai_platform_model 方法指定的由 AI Platform Prediction 托管的模型。
• 作为通过 set_custom_predict_fn 方法提供的自定义预测函数。在这种情况下，WIT 将直接调用该函数进行推理。
• 作为由 TensorFlow Serving 提供服务的模型端点，通过 set_inference_address 和 set_model_name 方法指定。在这种情况下，推理将在指定的模型服务器上进行。例如，要查询在主机 “localhost” 的 8888 端口上运行、名为 “my_model” 的模型，您可以在构建器上设置：builder.set_inference_address('localhost:8888').set_model_name('my_model')。

请参阅 WitConfigBuilder 的文档，了解您可以提供的所有选项，包括如何指定其他模型类型（默认为二分类）以及如何指定一个可选的第二个模型与第一个模型进行比较。

“What-If 工具”如何利用特征归因值和其他预测时信息？

特征归因值是针对机器学习模型每个输入特征的数值，用于指示该特征值对模型预测的影响程度。获取机器学习模型预测结果的特征归因值有多种方法，包括 SHAP、集成梯度、SmoothGrad 等。

它们可以作为一种强大的分析手段，帮助我们理解模型对特定输入值的反应，而不仅仅是像部分依赖图那样简单地研究单个特征值变化对模型预测的影响。一些归因技术需要访问模型内部结构，例如基于梯度的方法；而另一些则可以应用于黑盒模型。无论哪种情况，“What-If 工具”都可以在标准模型预测结果之外，可视化归因方法的结果。

有两种方法可以使用“What-If 工具”来可视化归因值。如果您已将启用了可解释性功能的模型部署到 Cloud AI Platform，并通过标准的 set_ai_platform_model 方法将其提供给工具，则工具会自动生成并可视化归因值，无需额外设置。如果您希望查看其他模型设置下的归因值，可以通过使用自定义预测函数来实现。

正如 WitConfigBuilder 中 set_custom_predict_fn 文档所述，此方法必须返回一个与传入示例数量相同大小的列表，其中每个列表条目代表对应示例的预测时信息。对于没有归因信息的标准模型，列表条目通常只是一个数字（回归模型）或一个类概率列表（分类模型）。

然而，如果存在归因或其他预测时信息，则列表条目可以改为一个字典，其中 predictions 键下包含标准模型的预测输出，attributions 键下包含归因信息，其他补充信息则放在各自的描述性键下。归因及其他补充信息的具体格式可在上述代码文档中找到。

如果向“What-If 工具”提供了归因值，它们可以以多种方式使用。首先，在“数据点编辑器”选项卡中选择某个数据点时，归因值会显示在每个特征值旁边，且特征可以按归因强度而非字母顺序排列。此外，特征值还会根据其归因值进行着色，以便快速直观地判断归因强度。

除了显示所选数据点的归因值外，每个特征的归因值还可以像数据点的其他特征一样在工具中使用。它们可以在数据点可视化控件中被选中，用于创建自定义散点图和直方图。例如，您可以创建一个散点图，展示两个不同特征的归因值之间的关系，并根据模型的预测结果对数据点进行着色。它们也可以在“性能”选项卡中用作切片依据，以比较不同切片的性能统计。例如，您可以快速比较模型在某特征低归因数据点上的整体表现，与该特征高归因数据点上的表现。

自定义预测函数返回的任何其他补充信息也会在工具中以字典键名命名的特征形式出现。它们同样可以用于驱动自定义可视化，或作为分析模型整体性能时的切片维度。

当编辑某个数据点并使用“运行推理”按钮重新通过模型进行推理时，归因值和其他补充信息会在工具中重新计算并更新。

有关从自定义预测函数返回归因值的示例（本例使用 SHAP 库获取归因值），请参阅WIT COMPAS with SHAP 笔记本。

如何在 Jupyter Notebook 中启用它？

首先，通过以下命令安装并启用适用于 Jupyter 的 WIT：

pip install witwidget
jupyter nbextension install --py --symlink --sys-prefix witwidget
jupyter nbextension enable --py --sys-prefix witwidget

然后，按照 What_If_Tool_Notebook_Usage.ipynb 笔记本 底部所示的方式使用。

如何在 Colab Notebook 中启用它？

通过运行包含以下内容的单元格，将该小部件安装到笔记本内核的运行环境中：

!pip install witwidget

之后，同样按照 What_If_Tool_Notebook_Usage.ipynb 笔记本 底部所示的方式使用。

如何在 JupyterLab 或 Cloud AI Platform Notebook 中启用它？

WIT 已在 JupyterLab 1.x、2.x 和 3.x 版本中进行了测试。

要为 JupyterLab 3.x 安装并启用 WIT，请运行包含以下内容的单元格：

!pip install witwidget
!jupyter labextension install wit-widget
!jupyter labextension install @jupyter-widgets/jupyterlab-manager

请注意，您可能需要根据自己的 JupyterLab 版本，在 https://www.npmjs.com/package/@jupyter-widgets/jupyterlab-manager 上指定正确的 @jupyter-widgets/jupyterlab-manager 版本。

此外，根据您的笔记本设置，您可能还需要运行 !sudo jupyter labextension ... 命令。

安装完成后，WIT 的使用方式与其他笔记本环境中的安装方法相同。

是否可以在 TensorBoard 中使用自定义预测函数？

可以。您可以通过定义一个名为 custom_predict_fn 的 Python 函数来实现，该函数接受两个参数：待进行推理的示例列表，以及包含模型查询相关信息的服务包对象。函数应返回一个结果列表，每个提供的示例对应一个条目。对于回归模型，结果仅为一个数字；而对于分类模型，则返回一个数字列表，表示每个可能类别的得分。

以下是一个仅返回随机结果的最小示例：

import random

# 函数名“custom_predict_fn”必须完全一致。
def custom_predict_fn(examples, serving_bundle):
  # 示例是 TFRecord 对象的列表，每个对象包含每个数据点的特征。
  # serving_bundle 是一个字典，包含传递给工具的配置信息，例如服务器地址、模型名称、模型版本等。

  number_of_examples = len(examples)
  results = []
  for _ in range(number_of_examples):
    score = random.random()
    results.append([score, 1 - score]) # 用于二分类
    # results.append(score) # 用于回归
  return results

将此函数定义在一个保存到磁盘的文件中。以本示例为例，假设文件保存为 /tmp/my_custom_predict_function.py。然后，使用 tensorboard --whatif-use-unsafe-custom-prediction /tmp/my_custom_predict_function.py 启动 TensorBoard 服务器，并在 What-If 工具的设置对话框中完成数据和模型的配置后，该函数便会自动调用。需要注意的是，“unsafe” 表示该函数未经过沙箱隔离，因此请确保您的函数不会执行任何破坏性操作，例如意外删除实验数据。

我如何参与开发？

请查看开发指南。

WIT 的最新动态有哪些？

请参阅发布说明。

What-If Tool 快速上手指南

What-If Tool (WIT) 是一款由 Google PAIR 团队开发的可视化工具，旨在帮助用户无需编写代码即可直观地探索和分析黑盒机器学习模型（分类或回归）。它支持在 TensorBoard、Jupyter Notebook 或 Google Colab 中运行，提供数据切片、性能对比、公平性分析及反事实推理等功能。

环境准备

系统要求

• 操作系统：Linux, macOS, Windows
• Python 版本：Python 3.6 或更高版本
• 浏览器：推荐使用最新版的 Chrome 或 Firefox

前置依赖

根据使用场景不同，需准备以下环境之一：

1. Jupyter/Colab 环境（推荐初学者）：

   • 已安装 jupyter notebook 或可直接访问 Google Colab。
   • TensorFlow 2.x (可选，若需训练模型)。

2. TensorBoard 环境：

   • 已安装 tensorboard。
   • 模型服务：需有一个通过 TensorFlow Serving 运行的模型服务（gRPC 接口），或者准备好包含预测结果的 CSV/TFRecord 数据集。
   • 数据格式：tf.Example / tf.SequenceExample (TFRecord 格式) 或带有特定列名的 CSV 文件。

国内加速提示： 在安装 Python 包时，建议使用清华或阿里镜像源以提升下载速度： -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

场景一：在 Jupyter Notebook 或 Colab 中使用

这是最简单的使用方式，无需配置复杂的服务器环境。

1. 安装库 在 Notebook 单元格中运行以下命令：

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

   注：如果在 Colab 中运行，安装后可能需要重启运行时 (Runtime -> Restart runtime)。

2. 验证安装 导入库以确保无报错：

   import witwidget
   

场景二：在 TensorBoard 中使用

如果你已经在使用 TensorFlow 生态，WIT 通常随 TensorBoard 一起安装。

1. 安装/更新 TensorBoard

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

2. 准备数据与模型

   • 模式 A (连接在线模型)：启动一个 TensorFlow Serving 服务，记下 host 和 port (gRPC 默认端口为 8500)。
   • 模式 B (仅分析数据)：准备一个 .csv 文件或 .tfrecord 文件。若文件中包含名为 predictions (回归) 或 predictions__probabilities (分类) 的列，WIT 可直接分析离线预测结果。

基本使用

1. 在 Jupyter/Colab 中的最简单示例

以下示例演示如何加载一个预训练的 TensorFlow Estimator 模型并启动 WIT 界面。

from witwidget.notebook.visualization import WitConfigBuilder
from witwidget.notebook.visualization import WitWidget

# 假设你已经有以下对象：
# examples: 一个包含 tf.Example 协议的列表 (测试数据集)
# estimator: 一个训练好的 TensorFlow Estimator 模型

# 1. 构建配置
# 指定模型类型：'classification' (分类), 'regression' (回归)
config = WitConfigBuilder(
    examples, 
    estimator=estimator, 
    model_type='classification'
)

# 2. 启动可视化组件
WitWidget(config)

自定义预测函数模式（适用于非 TensorFlow 模型）： 如果你的模型不是 TF Estimator，可以提供一个自定义预测函数：

def custom_predict(examples):
    # 这里编写你的模型推理逻辑
    # 输入：examples (list of tf.Example)
    # 输出：predictions (list of scores or probabilities)
    return my_model.predict(examples)

config = WitConfigBuilder(
    examples, 
    custom_predict_fn=custom_predict,
    model_type='regression'
)

WitWidget(config)

2. 在 TensorBoard 中的使用步骤

1. 启动 TensorBoard 指向包含数据文件（.csv 或 .tfrecord）的目录：

   tensorboard --logdir=/path/to/your/data_directory
   

   若数据目录与日志目录不同，可添加参数：--whatif-data-dir=/path/to/data

2. 访问界面 在浏览器打开 TensorBoard 地址（通常为 http://localhost:6006），点击顶部的 "What-If Tool" 标签页。

3. 配置面板 首次进入会弹出设置对话框，根据情况填写：

   • Inference Address: 填入 TensorFlow Serving 的地址（如 localhost:8500）。若仅分析 CSV 中的离线结果，留空即可。
   • Model Name: 填入 TF Serving 中的模型名称。
   • Path to examples: 选择你的 .csv 或 .tfrecord 文件。
   • Model Type: 选择 Binary classification, Multi-class classification 或 Regression。

4. 开始探索 配置完成后，你将看到数据分布图（Facets Dive）。你可以：

   • 点击任意数据点查看详细信息。
   • 手动修改特征值（Edit），实时观察预测结果变化（反事实分析）。
   • 使用 "Performance & Fairness" 面板对比不同数据子集的表现。