企业官网建设流程全解析

• 数据可视化
• 人工智能
• 机器学习
• 数据分析

Facets 是面向机器学习数据集的理解与分析可视化套件，包含 Facets Overview 与 Facets Dive 两个核心组件：前者对数据集进行逐特征的统计概览与多数据集对比，后者则用于交互式探索数万条多维数据记录。本文以仓库根目录的 README.md 为主干，结合 facets_overview/README.md、facets_dive/README.md 以及对应的 proto 定义、Python 统计生成器与 TypeScript 组件源码，系统讲解两个可视化的原理、接入方式、配置参数与本地构建流程，帮助你在 Jupyter Notebook、Google Colab 或普通网页中快速落地使用。

UCI 人口普查数据的 Overview 可视化（来源：Lichman, M. (2013). UCI Machine Learning Repository）

UCI 人口普查数据的 Dive 可视化（来源：Lichman, M. (2013). UCI Machine Learning Repository）

项目概览：两个可视化与底层技术

Facets 项目包含两个用于理解、分析机器学习数据集的 Web 可视化组件：

• Facets Overview：对单个或多个数据集给出高层次的逐特征统计分析，可对比两个及以上数据集的统计差异，同时支持数值型与字符串型特征（含每个特征存在多个取值的情况）。
• Facets Dive：交互式探索最多数万条多维数据点，支持用户在"宏观概览"与"微观细节"之间无缝切换；每个样例以独立条目呈现，可通过多维度 faceting/bucketing 依据特征值对数据点进行定位。

从实现层面看，两个可视化均以 Polymer 与 facets-dive.ts），可方便地嵌入 Jupyter Notebook 或普通网页。构建系统采用 Bazel，根目录的 facets/BUILD 中通过tf_web_library与tensorboard_html_binary将两个组件的 HTML import 合并、经 Closure Compiler 压缩后产出可在浏览器中直接运行的单文件产物（facets_jupyter、facets_colab等目标）。

Facets Overview：逐特征统计分析与数据集对比

功能定位：能发现哪些数据问题

Overview 面向机器学习数据集的质量排查场景，官方明确给出的适用问题包括：

• 意外/异常的特征值（Unexpected feature values）
• 大量样本中特征值缺失（Missing feature values for a large number of examples）
• 训练/服务分布偏差（Training/serving skew）
• 训练集/测试集/验证集之间的分布偏差（Training/test/validation set skew）

可视化的关键能力是离群点检测与跨数据集分布对比：高比例的缺失数据、同一特征在多个数据集间分布差异悬殊等"值得关注的值"会以红色高亮；特征可按感兴趣的值排序，例如缺失值数量、数据集之间的偏斜程度等。

数据底座：feature statistics protocol buffer

Overview 的动力来源是特征统计 protocol buffer（定义见 feature_statistics.proto）。该消息用于存储一套输入数据中各个特征列的汇总统计量，虽为 ML 系统设计，但足够通用，可用于任意数据集的汇总统计。其消息层级如下：

• 顶层消息DatasetFeatureStatisticsList：一组DatasetFeatureStatistics的列表；
• 每个DatasetFeatureStatistics表示单个数据集的特征统计，除name、num_examples外还携带weighted_num_examples（仅在指定权重特征时有效，缺失权重按 0 处理）；
• 每个DatasetFeatureStatistics包含一组FeatureNameStatistics，对应单个数据集中单个特征的统计量。

统计量依特征数据类型（numeric、string、bytes）而不同：

• 数值特征：min、mean、median、max、standard deviation 等（proto 中对应NumericStatistics的num_stats字段，另有num_zeros、直方图与分位数信息）；
• 字符串特征：平均长度、唯一值数量、众数（mode）等（对应StringStatistics，含unique、top_values、avg_length、rank_histogram）；
• 原始字节特征由BytesStatistics承载（唯一值数量、平均/最小/最大字节数）。

此外，特征统计还支持两个可选扩展：

1. 加权统计（weighted statistics）：若数据集带有 example weight 特征，可为每个特征在标准统计之外额外计算加权统计量。proto 中若包含加权字段，可视化会优先展示加权统计，用户可按特征在"未加权/加权"图表之间切换；
2. 自定义统计（custom statistics）：团队希望跟踪与可视化的额外统计量可写入custom_stats字段（一个"自定义统计名 → 数值或字符串"的 map），它们会与标准统计并列展示。

统计生成：从 pandas DataFrame 与 TFRecord 构建 proto

特征统计 proto 可由仓库提供的 Python 代码生成，通过pip install facets-overview安装。注意：TensorFlow 需要单独安装，且未作为 pip 依赖打入，以便用户按需选择tensorflow或tensorflow-gpu包；自 1.1.0 版本起，facets-overview要求protobuf版本不低于 3.20.0（当前仓库 setup.py 中的install_requires亦明确为numpy>=1.16.0、pandas>=0.22.0、protobuf>=3.20.0）。数据源支持两种形式：TFRecord 文件中的 TensorFlow Example proto，或pandas DataFrame。

从 DataFrame 生成（使用GenericFeatureStatisticsGenerator的ProtoFromDataFrames方法，实现见 generic_feature_statistics_generator.py，底层算法见 base_generic_feature_statistics_generator.py）：

from facets_overview.generic_feature_statistics_generator import GenericFeatureStatisticsGenerator import pandas as pd df = pd.DataFrame({'num' : [1, 2, 3, 4], 'str' : ['a', 'a', 'b', None]}) proto = GenericFeatureStatisticsGenerator().ProtoFromDataFrames([{'name': 'test', 'table': df}])

其中dataframes是字典列表，每项包含table（数据 DataFrame）与name（用于在 proto 中标识数据集）。该方法还支持histogram_categorical_levels_count参数，用于限制分类特征直方图展示的级别数量上限，防止 codes/IDs 类特征撑爆统计对象。在 base_generic_feature_statistics_generator.py 的实现中，DataFrame 的每一列会先经NdarrayToEntry归一化（剔除 None/NaN、统计缺失量与每行取值个数），再由GetDatasetsProto依据 numpy dtype 判定特征类型（float 型列 → FLOAT，int/bool/datetime/timedelta → INT，其余 → STRING）并分别计算数值统计（mean、std_dev、min、max、median、num_zeros、直方图与分位数直方图）或字符串统计（avg_length、unique、rank_histogram、top_values）。

从 TFRecord 生成（使用FeatureStatisticsGenerator的ProtoFromTfRecordFiles方法，实现见 feature_statistics_generator.py 与 base_feature_statistics_generator.py）：

from facets_overview.feature_statistics_generator import FeatureStatisticsGenerator # files: 字典列表，每项含 'path'（TFRecord 文件路径）与 'name'（数据集标识） proto = FeatureStatisticsGenerator().ProtoFromTfRecordFiles( files, max_entries=10000, features=None, is_sequence=False, iterator_options=None)

该方法的参数语义如下：

• files：字典列表，每项含path（磁盘上 TFRecord 文件的路径）与name（proto 中的数据集标识）；
• max_entries：从每个数据集加载用于生成 proto 的最大样例数，默认 10000；
• features：特征名白名单，只对这些特征生成统计；设为None则分析数据集中全部特征；
• is_sequence：输入为tf.SequenceExamples时为True，为tf.Examples时为False，默认False；
• iterator_options：传给读取样例的迭代器的选项，默认None。

两个生成器都依赖 numpy 与 pandas；FeatureStatisticsGenerator还要求安装 TensorFlow。仓库内的 Python 测试用例可作参考：feature_statistics_generator_test.py、generic_feature_statistics_generator_test.py。

关于大数据集：仓库内这套 Python 代码只适用于"能够装入本机内存"的数据集；面向大数据集的分布式特征统计生成，官方建议参考独立发展的 Facets Overview Spark 项目。

在 Jupyter Notebook 中可视化 proto

proto 生成后可通过已安装的 nbextension 在 Jupyter Notebook 中轻松可视化：将 protostringify（Base64 编码序列化二进制），作为输入提供给facets-overviewPolymer Web Component 的protoInput属性，组件即在输出单元格中渲染。

from IPython.core.display import display, HTML import base64 protostr = base64.b64encode(proto.SerializeToString()).decode("utf-8") HTML_TEMPLATE = """ <script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.3.3/webcomponents-lite.js"></script> <link rel="import" href="/nbextensions/facets-dist/facets-jupyter.html" > <facets-overview id="elem"></facets-overview> <script> document.querySelector("#elem").protoInput = "{protostr}"; </script>""" html = HTML_TEMPLATE.format(protostr=protostr) display(HTML(html))

protoInput属性接受以下三种形式之一的DatasetFeatureStatisticsListprotocol buffer：

1. DatasetFeatureStatisticsListJavaScript 类的实例（protocol buffer 编译器生成的类）；
2. 包含序列化二进制 proto 的Uint8Array；
3. 包含 Base64 编码序列化 proto 的字符串（即上面代码示例中的形式）。

从源码看，facets-overview.ts 的_convertInputToProto会分别对Uint8Array（deserializeBinary）与字符串（atob解码后再deserializeBinary）进行反序列化处理，从而将三种输入统一为 proto 对象供数据模型使用。

完整的端到端示例可参考仓库根目录的 colab_facets.ipynb：先用 pandas 读取 UCI census 的 train/test 数据，再调用GenericFeatureStatisticsGenerator生成 proto 并 Base64 编码，最后通过 HTML 模板同时展示 Dive 与 Overview。另有 Overview_demo.ipynb 与 Dive_demo.ipynb 可作为 Notebook 内的演示起点。

理解可视化：两张表与异常高亮

可视化包含两张表：一张针对数值特征，一张针对分类（字符串）特征；每张表中每类特征各占一行，行内展示计算出的统计量以及该特征在数据集间的取值分布图。潜在的问题统计（例如某特征在大量样例中缺失）会以红色加粗显示。

全局控制（Global Controls）

可视化顶部是影响各张表的控制项：

• 排序下拉框（sort-by）：改变两张表中特征的排列顺序，选项包括：
  • Feature order：按特征在 feature statistics proto 中的自然顺序排列；
  • Non-uniformity：按取值分布的非均匀程度排序（基于熵）。源码中 utils.ts 的getNormalizedEntropy实现了归一化熵的计算：以各桶样本数占比为概率，先求香农熵再除以桶数的自然对数做归一化；
  • Alphabetical：按字母顺序；
  • Amount missing/zero：按特征缺失值数量与值为 0 的数量排序，最大者在前；
  • Distribution distance（仅在对比多个数据集时可用）：按各特征分布形状之间的最大差异排序（基于卡方形状检验）。对应实现是 utils.ts 中的getHistogramDistance：逐桶计算count/total比率差异并累计卡方距离，对离散特征（rank histogram）按相同 label 配对桶，对连续特征按桶索引配对；某数据集完全缺失该特征时返回Infinity作为最大距离。
• 名称过滤输入框（name filter）：按与输入文本匹配的特征名过滤两张表，当前设置的过滤器以searchString属性对外暴露（对应 facets-overview.ts 中的属性声明）。
• 特征复选框（feature checkboxes）：按特征取值类型（float、int、string 等）过滤。

图表选项（Charts）

每张表上方有一个下拉框控制图表类型。

数值特征的图表选项：

• 全部值的直方图，使用 10 个等宽桶（equal-width buckets）；
• 全部值的十分位数（deciles）可视化；
• 每个样例取值个数的十分位数可视化：对 pandas DataFrame 数据集，每个样例每特征只有一个值，因此该图退化为平凡情形（所有十分位都等于 1）；但对 tf.Examples，一个样例的某个特征可以有任意多个值，例如"地址"特征列出某人的全部已知地址（每个 Example 代表一个人）。

字符串特征的图表选项：

• 数据集中每个值计数的柱状图（当特征唯一值不超过 20 个时使用），可通过开关切换为计数表格；
• 每个特征值占整个数据集全部值百分比的累积分布函数图（当特征唯一值超过 20 个时使用），同样可切换为计数表格；
• 每个样例取值个数的十分位数可视化。

此外，feature statistics proto 允许为任意特征存储自定义图表：若输入 proto 包含自定义图表，它们也会出现在下拉框中。

下拉框旁的复选框控制图表其他行为：

• log：将 y 轴从线性切换为对数；
• expand：显示更大版本的图表；
• weighted（仅当数据集在常规统计之外还包含加权统计时显示）：展示图表的加权版本及统计量的加权版本；
• percentages（仅当可视化在对比多个数据集时显示）：将 y 轴从原始计数切换为各数据集总量的百分比，便于对比总量差异悬殊的数据集（如测试集与训练集）之间的分布。

运行与测试

功能测试（demos）：Overview 有多个可作为功能测试的 demo，全部位于 facets_overview/functional_tests 下（包含 simple、single、single_feature、many、weighted、stress 等场景）。运行方式（以 simple 为例）：

bazel run facets_overview/functional_tests/simple:devserver

然后在浏览器访问localhost:6006/facets-overview/functional-tests/simple/index.html查看可视化结果。

可视化单元测试：

bazel run facets_overview/common/test:devserver

然后在浏览器访问localhost:6006/facets-overview/facets-overview/common/test/runner.html，测试输出显示在开发者控制台中。

构建 facets-overview pip 包：

1. 更新 setup.py 中的版本号并提交；
2. 在 facets_overview 目录执行python setup.py bdist_wheel --universal；
3. 执行twine upload dist/*上传到 PyPI。

Python 单元测试：安装 python 包后运行python -m feature_statistics_generator_test与python -m generic_feature_statistics_generator_test。

Facets Dive：交互式多维数据探索

功能定位与数据格式

Dive 用于一次交互式探索大量记录——"一次数千条甚至上万条"。每条记录应是一个键值对对象，键值代表该记录的特征，值应为字符串或数字。例如一份食物清单数据：

[{ "name": "apple", "category": "fruit", "calories": 95 },{ "name": "broccoli", "category": "vegetable", "calories": 50 },{ ...Many more foods... }]

对象之间不必拥有完全相同的键集合：若某对象缺少其他对象中存在的键，该记录仍会在 Dive 中显示。目前 Dive 只处理数值与字符串值；若对象的值是复杂类型（数组、嵌套对象等），它们会在可视化前被强转为字符串。

提供数据给 Dive：data属性

<facets-dive>元素有大量可定制行为的属性，但唯一必须设置的是data——它是一个 JavaScript 对象数组，每个对象代表一条记录。在 TypeScript 接口 facets-dive.ts 中，data被声明为可选但"要做任何有用的事都必需"（Provided by upstream client）。

用 Sprite Atlas 渲染数据点

默认情况下，Dive 会在圆形上渲染文本代表每个数据点。你也可以提供 sprite atlas 供其使用。仓库提供了名为Facets Atlasmaker的工具（见 facets_atlasmaker/README.md）用于根据图像位置列表创建自己的 sprite atlas。

什么是 sprite atlas：一张包含大量微小图像、且各图像位于可预测坐标的大图。从图片左上角开始，sprite 从左到右、从上到下依次排布。以 10000 个数据点为例（从 0 开始索引），它们在 atlas 中的排布如下：

+---------+---------+---------+- - - - -+---------+ | | | | | | | 0 | 1 | 2 | ... | 99 | | | | | | | +---------+---------+---------+- - - - -+---------+ | | | | | | | 100 | 101 | 102 | ... | 199 | | | | | | | +---------+---------+---------+- - - - -+---------+ | | | | | | | 200 | 201 | 202 | ... | 299 | | | | | | | +---------+---------+---------+- - - - -+---------+ | | | | | | . . . . . | . | . | . | . | . | . . . . . | | | | | | +---------+---------+---------+- - - - -+---------+ | | | | | | | 9900 | 9901 | 9902 | ... | 9999 | | | | | | | +---------+---------+---------+- - - - -+---------+

要指定 atlas 的 URL，可在 JavaScript 中设置 Dive Polymer 元素的atlasUrl属性（HTML 中为atlas-url）。若 atlas 图片与可视化不在同一域名，图片必须支持 CORS 头才能使用；此时还需设置crossOrigin属性（HTML 属性为cross-origin）为anonymous或use-credentials，用法与<img>/<video>标签相同。为正确切割 sprite atlas，Dive 需要知道每个 sprite 的像素宽高，分别通过spriteImageWidth与spriteImageHeight属性设置（HTML 中为sprite-image-width、sprite-image-height）。

Atlasmaker 快速上手：Atlasmaker 是命令行工具兼库，依赖可通过 requirements.txt 安装（pip install -r requirements.txt）。先构建二进制：

bazel build :atlasmaker # 二进制位于 Facets 根目录 bazel-bin 下，即： ../bazel-bin/facets_atlasmaker/atlasmaker

运行时可先用--help查看全部 flag。一个从维基百科图片集合生成 atlas 与 manifest 的示例命令：

mkdir $PWD/outputs/ ../bazel-bin/facets_atlasmaker/atlasmaker --sourcelist=$PWD/testdata/wikipedia_images_16.csv \ --output_dir=$PWD/outputs/ --image_width=50 --image_height=50 \ --default_image_path=https://upload.wikimedia.org/wikipedia/en/d/d1/Image_not_available.png

常用图片设置 flag 包括：

• --image_width（必需）：最终输出图片的像素宽度；
• --image_height（必需）：最终输出图片的像素高度；
• --image_format：输出图片格式（png、jpeg 等），默认 png；
• --keep_aspect_ratio：是否保留图片纵横比，否则尽力缩放原图并裁剪；
• --bg_color_name或--bg_color_rgb：指定背景色（用于缩放后未填满 sprite 的图片以及 atlas 中无图片的位置），如'green'或'255,255,0'。

Atlasmaker 支持从本地文件与 URL（http/https）读取输入图片、取图或转换失败时使用默认图、多种缩放/转换选项以及图片抓取/转换的并行化（仓库对应实现见 atlasmaker.py、parallelize.py、convert.py）。生成的 manifest 每行是一个 JSON 对象，描述单张图片的元数据（在 atlas 中的位置以相对左上角的 (x, y) 像素偏移给出）及失败状态——取图/转换失败并被默认图替换的图片会带有error键及失败消息。使用已生成 sprite atlas 的 Dive Colab 示例见 colab_dive_atlas_demo.ipynb。

将 Dive 嵌入你的页面

项目用 Bazel 构建，需先安装 Bazel 并运行 BUILD 文件。加载<facets-dive>Polymer 元素后，可这样插入实例：

<facets-dive></facets-dive>

Facets Dive 使用 HTML imports，因此必须先加载 polyfill：

<script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.3.3/webcomponents-lite.js"></script>

随后用 JavaScript 获取 DOM 元素引用并给data赋值：

const vis = document.querySelector('facets-dive'); vis.data = [ ... your data ... ];

组件目录下的 test.html 与 test.ts 包含一个简单示例。

导航 Dive 控件

Dive 有三个区域：顶部控制工具栏、主可视化区与数据点信息面板。数据载入后，用户通过工具栏控件驱动探索；工具栏分四节，点击展开：Faceting（分面）、Color（颜色）、Display（显示）、Positioning（定位）。

Faceting 控件：Dive 的核心功能是把记录布局成网格，即 faceting，有可独立控制的垂直（行）与水平（列）两个方向。任选一个特征作为分面方向后，Dive 会按该特征对条目分桶：数值特征按取值区间划分为等宽数值段；字符串特征将相同字符串值归组，若值过多则归入标记为other的桶。此外，含空格的字符串值可视为无差别的词袋（bag of words）：勾选 Bag of Words 后，Dive 会按最常见的词将条目归组（例如 "toy store" 与 "pet store" 会因 "store" 而聚合，也可按桶数量拆分为独立组合）。该特性未来可能大幅改变或移除。

Positioning 控件：默认在网格每个单元格内按堆叠（stacked）方式排列条目，也可改为散点图（scatter）布局——当 Faceting 设为(none)时最有用。数值特征可用于散点定位；值非数字的条目仍会显示，但其值被强制为 0。

Color 控件：指定用于给各条目着色的字段。若未指定 sprite atlas，Dive 会自动挑选一个特征用于着色；选择算法优先考虑唯一值较少的特征（如分类特征）。

Display 控件：指定 Dive 在每个数据点上渲染的内容。若指定了 sprite atlas，默认展示各点对应的 sprite；否则 Dive 会挑选取值最独特的特征，将其字符串渲染在圆形背景上。无论是否使用 sprite atlas，都可通过 Display 下拉框交互式控制渲染到数据点上的特征。

Dive Polymer 元素 API

Dive 的属性既可在 HTML 中以<facets-dive>元素的属性（attribute）设置，也可在 JavaScript 中以FacetsDivePolymer 元素的属性（property）访问。注意：在 HTML 中设置属性时，必须使用短横线命名（dashed-names-like-this），而非驼峰命名（camelCaseNamesLikeThis）。

数据属性（Data Properties）：

• data-Array<{}>：要可视化的数据对象数组；
• filteredDataIndices-number[]：数据对象数组的索引数组（可选）。若非 null，则只可视化 data 数组中这些索引对应的条目。

Sprite 属性（Sprite Properties）：

• spriteImageWidth-number：sprite 底图的像素宽度。未提供时设置合理默认值（HTML 用sprite-image-width）；
• spriteImageHeight-number：sprite 底图的像素高度，未提供时设置合理默认值（HTML 用sprite-image-height）；
• atlasUrl-string：用于支撑 sprite 的 atlas 图片 URL，每个 sprite 按其在data数组中的索引映射到 atlas 图片的矩形区域（HTML 用atlas-url）；
• spriteUrl-string：单个默认 sprite 图片的 URL，每个 sprite 使用同一张图；未提供时使用一个通用圆点（HTML 用sprite-url）；
• crossOrigin-string：可选，应用于Image元素的crossOrigin属性，取值为anonymous或use-credentials；跨域使用 atlas 或 sprite 图片时必需（HTML 用cross-origin）。

样式属性（Stylistic Properties）：

• height-number：元素像素高度；未指定时元素会撑满父元素；
• gridFacetingVerticalLabelColor/gridFacetingHorizontalLabelColor-string：垂直/水平方向网格分面的标签颜色，未提供时设合理默认值（HTML 用grid-faceting-vertical-label-color、grid-faceting-horizontal-label-color）；
• itemPositioningVerticalLabelColor/itemPositioningHorizontalLabelColor-string：垂直/水平方向的条目定位标签颜色（HTML 用item-positioning-vertical-label-color、item-positioning-horizontal-label-color）；
• fitGridAspectRatioToViewport-boolean：设为 true 时，网格布局会尝试匹配可用屏幕空间的纵横比（如超宽屏上网格也变宽）；未设置时按默认纵横比——正方形——布局（HTML 用fit-grid-aspect-ratio-to-viewport）。

交互属性（Interactive Properties）——通常由用户控制，也可在数据加载后程序化设置：

• verticalFacet-string：垂直（行）分面所用的字段名；
• verticalBuckets-number：垂直分面使用的桶数量；
• verticalBagOfWords-boolean：多词字符串字段是否按词袋处理而非完整字符串（如 "toy store" 与 "pet store"：词袋模式会按 "store" 聚合，或依桶数量拆分为 "toy store"/"pet store"）；
• horizontalFacet-string：水平分面字段名；
• horizontalBuckets-number：水平分面桶数量；
• horizontalBagOfWords-boolean：水平分面字段是否按词袋处理；
• positionMode-string：网格单元格内条目定位模式，可选stacked（默认）与scatter；
• verticalPosition-string：散点模式下沿垂直轴定位条目的字段；
• horizontalPosition-string：散点模式下沿水平轴定位条目的字段；
• colorBy-string：给条目着色的字段；
• imageFieldName-string：当每个 sprite 没有独立图片（无 atlas）时，指定用于在 sprite 底图画布上绘制文字的字段名。例如数据是书籍集合、每本书有title属性，把imageFieldName设为"title"，则每本书的标题会被绘制到圆上代表该数据点；
• paletteChoice-string：用于生成数据专属调色板的源调色板，四个可识别值为standard、warm、cool、assist，各调色板使用 Material Design 风格指南中的颜色；
• selectedData-Array<{}>：只读。当前选中的数据对象（均为 data 数组中的元素），通过用户交互（点击 sprite）改变。

高级自定义属性（Advanced Customization Properties）：

• infoRenderer?-(dataObject: {}, containerElem: Element) => void：用于渲染数据对象信息面板内容的回调函数；未指定时使用FacetsDiveInfoCard.defaultInfoRenderer（相关实现见 info-renderers.ts）；
• comparedIndices-Array<number>：列出要与选中对象对比的数据对象索引；程序化设置后会自动更新comparedData；
• comparedData-Array<{}>：只读。要与选中对象对比的数据对象（均为 data 数组中的元素），随comparedIndices的改变自动更新。

运行 Dive 的单元测试与 Demos

Quick Draw Demo：与 Quick Draw 合作的数据集非常适合体验 Dive。在 facets 项目目录运行：

bazel run //facets_dive/demo

服务启动后访问http://localhost:6006/facets-dive/demo/quickdraw.html。demo 代码见 quickdraw.ts，它展示了verticalFacet、horizontalFacet、positionMode、colorBy等预设视图以及data、atlasUrl的赋值方式。

Dive 集成测试：

bazel run //facets_dive/components/facets_dive:devserver

启动后访问http://localhost:6006/facets-dive/components/facets-dive/runner.html。

Dive 单元测试：Dive 的lib目录（见 facets_dive/lib，包含 axis、grid、layout、sorting、sprite-atlas、sprite-material、sprite-mesh、stats、string-format、text、wordtree 等可视化核心库）承担了大部分渲染工作：

bazel run //facets_dive/lib/test:devserver

启动后打开浏览器访问http://localhost:6006/facets-dive/lib/test/runner.html，并打开浏览器开发者控制台查看所有测试的运行报告与汇总。Dive Polymer 元素由多个子组件组成（<facets-dive-info-card>、<facets-dive-controls>、<facets-dive-vis>，分别对应 facets_dive_info_card、facets_dive_controls、facets_dive_vis），每个子组件都有同形式的集成测试，用于确认代码增改能正确构建与加载。

环境搭建与构建

在 Google Colab / Jupyter Notebook 中使用

在 Colab 与 Jupyter 中使用 Facets 的完整示例见 colab_facets.ipynb，这类 Notebook 无需先下载/安装本仓库即可运行。由于两个可视化都依赖 HTML imports，必须先加载 polyfill：

<script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.3.3/webcomponents-lite.js"></script>

在 Jupyter 中使用 Facets Overview 有两个注意事项：

1. 需将加载 Facets Overview Python 代码的路径改为与 Notebook kernel 实际运行位置一致的路径；
2. 必须安装 Protocol Buffers Python 运行时库；若用 pip 或 anaconda 安装的 Jupyter，可用同一工具安装该运行时库。

当在 Jupyter Notebook 中可视化大量数据（如 Dive_demo.ipynb 的做法）时，需要提高 Notebook 服务器的 IOPub 数据速率限制：

jupyter notebook --NotebookApp.iopub_data_rate_limit=10000000

代码安装

git clone https://github.com/PAIR-code/facets cd facets

构建可视化

修改了可视化代码并希望重新构建时：

1. 安装 Bazel：https://bazel.build/；
2. 在 facets 顶层目录构建：bazel build facets:facets_jupyter。

构建产物的生成逻辑见 facets/BUILD：facets_jupyter是一个 genrule，它在 vulcanized 产物头部注入define=undefined的脚本，以避免在 Jupyter Notebook 中与 require.js 的依赖加载机制冲突。

在 Jupyter Notebook 中使用本地构建的可视化

1. 将构建出的 vulcanized html 文件移动到 facets-dist 目录：cp -f bazel-bin/facets/facets-jupyter.html facets-dist/；
2. 将可视化安装为 Jupyter 的 nbextension：
   • Jupyter 由 pip 安装：jupyter nbextension install facets-dist/；按用户安装：jupyter nbextension install facets-dist/ --user（均在 facets 顶层目录执行）。此扩展无需再执行任何jupyter nbextension enable命令；
   • 备选方案：手动找到 Jupyter 安装目录的share/jupyter/nbextensions文件夹，将 facets-dist 目录复制进去；
3. 在 Notebook 单元格中加载内置 facets html 的 HTML link 标签处，改为从/nbextensions/facets-dist/facets-jupyter.html加载，即上一步本地安装的 facets 发行版。

已知问题

• 当前 Facets 可视化只能在 Chrome 中工作（Issue 9）。
• 仓库内facets_overview/python与facets_overview/facets_overview目录下的旧版 Python 代码在使用时会发出 DeprecationWarning，提示改用facets-overviewpip 包。

结语

Facets 将"数据集质量诊断"与"数据点级交互探索"这两类互补的 ML 数据理解需求集成在同一套 Polymer/TypeScript 组件体系中：Overview 借助 feature statistics protocol buffer 提供了从 pandas DataFrame 或 TFRecord 到可视化统计的完整链路，支持缺失值、分布偏斜、多数据集对比等关键排查场景；Dive 则以 faceting、颜色、显示与定位四大控制面板及可选的 sprite atlas 机制，支撑起数万条记录的多维交互探索。结合仓库中的 proto 定义（feature_statistics.proto）、Python 生成器（generic_feature_statistics_generator.py、feature_statistics_generator.py）与前端实现（utils.ts、facets-dive.ts），你可以进一步深入理解其统计口径与渲染原理，并依照上文流程在 Colab、Jupyter 与网页中快速落地使用。

Disclaimer: This is not an official Google product

• 数据可视化
• 人工智能
• 机器学习
• 数据分析