TensorBoard 通用数据 API 和实现

@wchargin, 2019-07-25

状态：使用 Python 指定；正在执行多个实现，这些实现处于不同阶段。

目的

TensorBoard 曾一直作为直接从磁盘读取数据的本地网络服务器运行。而 TensorBoard.dev 则在 App Engine 上运行并读取用户上传到我们的托管服务中的数据。此外，某些与 TensorBoard 类似的 Google 内部服务具有自己的数据库，并直接重新实现 TensorBoard HTTP API。

为了确保 TensorBoard 体验在所有后端之间统一，并让用户在所有环境下都能轻松地使用插件，我们需要一个 Python API（采用多种实现）来存储和访问数据。

本文档针对该 API 提出了读取方面的建议，并提供了针对每种实用后端实现该 API 的高级信息。

本体论

大多数 TensorBoard 插件都可以通过一种或多种关系模式自然表达：

  • scalars: (run, tag, step) → (value: f32)
  • images: (run, tag, step, image_index) → (image_data: blob)
  • 音频 (run, tag, step, audio_index) → (wav_data: blob)
  • text: (run, tag, step, text_index) → (text_data: blob)
  • histograms: (run, tag, step, bucket_index) → (lower_bound: f32, count: usize)
  • PR curves: (run, tag, step, threshold_index) → (tp, fp, tn, fn, precision, recall)
  • 网格：
    • 顶点：(run, tag, step, vertex_index) → (x: f32, y: f32, z: f32, color: u8)
    • 面：(run, tag, step, face_index) → (v1: usize, v2: usize, v3: usize)
  • graphs: (run, tag, kind: enum) → (graph: proto)
  • 超参数：
    • 实验配置：() → (experiment_info: proto)
    • 会话组：(session_group) → (session_info: proto)

我们可以允许插件直接定义这些表，并借助关系数据库对其进行自由操作。但是，做出这种重要承诺会限制我们实现这些 API 的灵活性，而我们已经知道我们至少需要三种实现。此外，当出现新颖的插件却无法有效适配这一模型时，那么在使用该模型时难免会存在诸多问题。

相反，我们在上述关系中观察总结出三种常见模式，并赋予它们特权：

  • 标量时间序列。
    • 主要由标量插件使用。
    • 在实验中由运行、标记和步骤键控。
  • 张量时间序列。
    • 包括直方图和 PR 曲线。
    • 在实验中由运行、标记和步骤键控。
    • 每个张量的大小均以一个常量为上界（直方图为 0.5 KB，PR 曲线为 5 KB），小于 Cloud Spanner 单元大小 (10 MiB)。
  • Blob 序列时间序列。
    • 包括图像、音频、文本、网格、计算图、超参数。
    • 潜在的未来用例：视频。
    • 可能是“概念上的张量”（例如图像、音频），但实际上是以压缩格式（例如 PNG、FLAC）编码。
    • 在实验中由运行、标记、步骤和索引键控。
    • 包括“序列”始终仅包含一个元素或“时间序列”始终仅包含一个步骤的简并用例。
    • 为何是 blob 序列而不是 blob 本身？每个图像和音频摘要在每个步骤均可包含多个图像/音频片段。赋予序列特权可有效实现这一目标，方法是在每个 GCS 对象中仅存储一个 PNG 文件并将其直接提供给浏览器。这种方法几乎没有弊端。
    • 大小可能不一。图像大小可达千字节（MNIST 输入）或千兆字节（组织切片图、TensorFlow 计算图和检查点）。
    • 实现可能对其进行特殊加密（例如，使用 GCS CMEK）：敏感数据通常需要包含在此类 blob 中，而不是标量或直方图中。
    • 序列长度通常具有较小的上界值。图像和音频的默认长度为 3，且网格始终为单例序列。

请注意，我们将标量与任意张量区分开。标量可以支持任意张量无法执行的某些运算（例如按区间内的最小/最大值进行聚合，或诸如“查找最近的 accuracy 至少为 0.9 的运行”之类的查询。标量信息中心也是使用最广泛的信息中心，因此我们想充分利用我们所能实现的任何额外的性能改进：例如，我们不必存储张量形状。

API 调用

每个存储类都有两种 API 调用：“list metadata”和“get values”。所有 API 调用都要求调用者按拥有数据的插件（例如“images”）进行筛选。所有 API 调用都需要使用“实验 ID”参数和身份验证令牌。有关签名的更多详细信息如下：

  • 标量时间序列：目前，与张量时间序列相同。以后可能会学习新的选项。
  • 张量时间序列：
    • 支持按运行集和标记集（跨积语义）进行筛选。
    • 支持按步骤范围或特殊的“最近的 k 个步骤”进行筛选。
    • 降采样到提供的步骤数。
    • 返回嵌套映射：
      • 针对数据请求：(run) → (tag) → list[(step, wall_time, tensor_value)]；
      • 针对元数据请求：(run) → (tag) → (max_step, max_wall_time, summary_metadata)。
  • Blob 序列时间序列：
    • 支持按运行集和标记集进行筛选。
    • 支持按步骤范围或特殊的“最近的步骤”进行筛选。
    • 支持按索引范围或特殊的“最近的索引”进行筛选。
    • 降采样到提供的步骤数。
    • 返回嵌套映射：
      • 针对数据请求：(run) → (tag) → list[(step, wall_time, list[(blob_key)])]；
      • 针对元数据请求：(run) → (tag) → (max_step, max_length, summary_metadata)。

请注意，仅在“步骤”轴上支持降采样。

每个“get values”API 调用都将对响应的最大大小应用上界（计算方法为 num_runs × num_tags × sample_size）。（回想一下，张量时间序列的元素预计较小。）

“blob 键”是用户可访问的绝对网址或不透明键的标记联合。具有不透明键的 blob 可以通过附加的 API 调用来读取：

  • Blob 读取：
    • 接受由 blob 序列查询返回的 opaque_key 输入。
    • 返回指定 blob 的内容。
    • 另外，对于想要直接使用 DOM API 呈现 <img>/<audio>/ 等元素的插件，作为核心 HTTP 端点 /data/blob/OPAQUE_KEY 公开。

最后，插件将从顶级 API 调用开始搜索：

  • 列表：
    • 接受插件标识符（例如“images”）。
    • 返回 (run) → (tag) → (kind, summary_metadata) 的映射，其中 kind 用于标识四个存储类之一。

请注意，这些 API 调用旨在由 TensorBoard 插件代码调用，因此会非常紧密地映射到那些预期的访问模式上。未来，我们可能会为最终用户提供其他 API，用于方便特殊浏览以及进行批处理分析或创建自定义信息中心（例如，直接导出到 pandas 数据帧以在 Colab 中使用）。这些 API 可以基于本文档所述的 API 实现。

存储实现

本部分内容介绍了这些 API 的可行实现。内容旨在提供信息，不可视为规范。

托管后端是我们对公共服务预期的稳定状态：

  • 上传时，所有数据都被提取到 Cloud Spanner 或 GCS 中。
  • 标量时间序列存储在将候选键 (run_id, tag_id, step) 映射至挂钟时间和浮点值的 Spanner 表中。
  • 张量时间序列存储在 Spanner 表中，该表将候选键 (run_id, tag_id, step) 映射至挂钟时间、打包的张量内容的字节串以及张量形状和数据类型。
  • Blob 序列时间序列存储在 GCS 上，并列在将候选键 (run_id, tag_id, step, index) 映射至 GCS 对象键的表中。（即使对于较小对象也是如此。）
  • 单独的表存储运行和标记名称以及摘要元数据（由 ID 键控）。
  • 可以在 SQL 中实现线性分桶降采样，如 PR #1022 中所述。
  • 如果需要，Cloud Spanner 的 TABLESAMPLE 算子将免费提供支持伯努利采样或蓄水池采样的均匀随机降采样。
    • TABLESAMPLE 是 SQL:2011 的一部分，也可由 PostgreSQL 和 SQL Server 实现，但无法由 SQLite 实现。（sqlite-users 邮寄名单中从未出现过“tablesample”和“downsample”。）Cloud Spanner 不会实现算子的 REPEATABLE(seed) 部分。

可以适时基于 TensorBoard 的数据库模式实现本地 SQLite 后端：

  • 在 --db_import 时，所有数据都被提取到 SQLite 中。
  • 标量/张量时间序列存储在与其 Cloud Spanner 对应项同构的表中。
  • Blob 序列时间序列存储在将 (run_id, tag_id, step, index) 映射至唯一 blob ID 的表中。
  • Blob 数据存储在将 blob_id 映射至实际 blob 数据的表中。（此为“GCS”。）
  • 单独的表存储运行和标记名称以及摘要元数据（由 ID 键控）。
  • 请注意，SQLite blob 的大小限制为 1 GB。我们将向 blob 数据表添加 chunk_index 列的选项设置为开启状态，以便能够存储任意大小的 blob。
  • 可以在 SQL 中实现线性分桶降采样，如 PR #1022 中所述。
  • 均匀随机降采样没有内置函数。如果需要，我们必须选择一个实现：朴素模型（不利于周期性数据或非序列步骤）、 ORDER BY random()（不利于重现性；可能很慢）、 WHERE random() < k（伯努利采样；不利于重现性；其他方面可能不错）、xs 的 WHERE rowid IN xs（在客户端上预先计算的索引列表，可能不错？）、与将步骤映射至均匀随机数并限制为前 k 个随机值的全局表 JOIN（可能不错？）。

作为 Google 内部用户的迁移路径，我们将提供一个后端，与现有 Google 内部存储系统对接以获取实验数据。（Google 员工请参阅本文档的内部版本以了解详细信息。）

同样地，为了与磁盘上现有的 TensorBoard 数据兼容，我们将提供一个后端，使用与当前 TensorBoard（plugin_event_multiplexer 堆栈）相同的加载逻辑，并通过这些 API 公开数据。它将成为连通过去与未来的桥梁，并铺设一条持续的迁移路径，有效避免了全局转换所涉及的巨大工作量。

考虑的替代方案

将关系存储模型公开给插件

在“本体论”部分中已经讨论。我们在探索这种方式时提出了一个建议，允许插件以 (candidate_key) → (columns) 的形式声明零个或多个关系；这些是上方“本体论”部分中列出的关系。将基于一组固定类型绘制关系维度：标量类型 i64、f64 和 bool；元数据类型 run_id、tag_id 和 step；以及 blob 类型 bytes、string 和large_file。为每个主特性指定模式后，插件将能够查询：

  • “任意值”
  • “这些 values 之一”
  • 对于 step-type 特性：“降采样至 k”，相对于 run_id 和 tag_id 特性进行解释

…并指定在结果集中包含还是排除每个非主特性。例如：

  • 标量：
    • 关系 data：(run_id, tag_id, step) → (value: f64)
    • 查询 data (run_id in RUNS, tag_id in TAGS, step downsample 1000) → value
  • 图像：
    • 关系 data：(run_id, tag_id, step: image_index: i64) → (blob: large_file)
    • 查询 data (run_id in RUNS, tag_id in TAGS, step downsample 100, image_index ANY) → blob

如上所述，我们选择不采用此选项，因为它公开了我们势必要支持的诸多灵活性，并且具有很高的概念表面积（例如，自定义域特定的查询语言）。

对于本地后端，将 blob 存储在文件系统而非 SQLite 中

Blob 实际上没有大小限制。如果我们选择保留对原始 logdir 的引用（例如，“事件文件路径加上文件中的字节偏移量”），而非将数据复制到我们自己的存储空间中，那么将减少数据重复情况。如果瓶颈源于 SQLite 本身而非底层 I/O，那么这也可以缓解并发请求的压力。

文件将存储在什么位置？目前，TensorBoard 的数据库模式会将所有数据存储在单个数据库中，以单个文件形式存储在磁盘上。这是一种简单方便的模型。如果存储其他文件，意味着我们必须要求将这些文件与其余数据共同存放在同一位置中（这会造成系统难以复制、共享、备份等），或者要求提供一些全局 TensorBoard 数据目录，例如 ${XDG_DATA_HOME}/tensorboard/blobs/（这种重要承诺将要求后续工作更加慎重）。

请注意，某些 TensorBoard 插件（例如 projector）已经从其数据模型中的绝对文件路径执行读取。这会导致 logdir 不可移植，实属一个痛点。

如何存储文件？无论何种方式，我们最终都将建立某种微型数据库，并承担所有相关的存储任务。例如，如果我们使用像 ${run_id}/${tag_id}/${step}/${index} 一样的文件路径层次结构，那么读取运行中每个标记的最近 blob 将是标记数和步骤数的二次方程 (!)，因为 open(2) 需要线性扫描所含目录中所有文件名的列表。也许我们可以像 Git 的对象存储一样通过散列法和分片法来解决此问题，这会进一步提高复杂性。性能不佳的文件系统；网络文件系统；多用户系统和权限。需要声明的是，实现数据库超出了此项目的范围。

另外，假定的性能提升并不明确：SQLite 可比文件系统更快！

包括“非时序 blob”存储类

这里提出的三种存储类均为时间序列：标量、张量或 blob 序列。本文档的先前版本曾提出过针对非时序 blob 的第四种存储类，在实验中仅由运行和标记键控。其预期目的是用于“运行级元数据”。针对该用例的现有解决方案确实会使用摘要：例如，带有特殊标记名 _hparams_/session_start_info 的摘要指定超参数配置。但这一直不太正统。理想情况下，运行级元数据将成为更完整的系统的一部分。例如，它可以用于驱动运行选择（“在所有插件中仅向我展示使用 Adam 优化器的运行”）。首先，摘要就不适用于该数据。

这种存储类可以根据现有的存储类来实现，方法是将非时序 blob 表示为仅在步骤 0 处采样的单例 blob 序列。在 TensorFlow 2.x 中，即使计算图在运行过程中也可能不是静态的（trace_export 接受 step 参数），从某种意义上说，超参数也不一定为静态。鉴于鲜有实用的用例，而且后备效果甚佳，我们放弃了这种存储类。

更新日志

  • 2020-01-22：将 blob 序列 corresponding_max_index（最新基准的长度）更改为 max_length（任何基准的最大长度）以满足实际需求且更为自然。
  • 2019-08-07：基于设计评审反馈进行了修订：移除了非时序 blob（请参阅“考虑的替代方案”部分）。
  • 2019-07-25：初始版本。