Manifold

本项目现已稳定，并处于长期支持的孵化阶段。

Manifold 是一款与模型无关的机器学习可视化调试工具。

鉴于机器学习算法本身的不透明性，理解模型性能和行为并非易事。诸如 AUC、RMSE 等性能汇总统计指标往往不足以帮助我们找出模型的问题所在或改进方向。

作为一款可视化分析工具，Manifold 使机器学习从业者能够超越整体汇总指标，定位出模型预测不准确的数据子集。同时，它还能通过比较表现较好与较差数据子集之间的特征分布差异，揭示模型性能不佳的潜在原因。

目录

• 准备您的数据
• 解读可视化结果
• 使用演示应用
• 使用组件
• 贡献代码
• 版本管理
• 许可证

准备您的数据

有两种方式可以将数据输入到 Manifold 中：

• 如果您使用的是 Manifold 演示应用，则可以通过 上传 CSV 文件；
• 如果您希望在自己的应用中集成 Manifold 组件，则可以采用 程序化转换数据 的方式。

无论哪种方式，直接输入到 Manifold 的数据都应遵循以下格式：

const data = {
  x:     [...],         // 特征数据
  yPred: [[...], ...]   // 预测数据
  yTrue: [...],         // 真实标签数据
};

这些数组中的每个元素代表评估数据集中的一个数据点，且 x、yPred 和 yTrue 中数据实例的顺序必须一致。建议每份数据集包含 10,000 至 15,000 个样本。如果您拥有更大的数据集，通常只需抽取其中的一个随机子集，即可揭示数据中的重要模式。

x: {Object[]}

包含特征的实例列表。示例（2 个数据实例）：

[{feature_0: 21, feature_1: 'B'}, {feature_0: 36, feature_1: 'A'}];

yPred: {Object[][]}

由多个列表组成的列表，其中每个子列表对应于某一模型对每个数据实例的预测结果。示例（3 个模型，2 个数据实例，2 个类别 ['false', 'true']）：

[
  [{false: 0.1, true: 0.9}, {false: 0.8, true: 0.2}],
  [{false: 0.3, true: 0.7}, {false: 0.9, true: 0.1}],
  [{false: 0.6, true: 0.4}, {false: 0.4, true: 0.6}],
];

yTrue: {Number[] | String[]}

真实标签的列表，每个数据实例对应一个标签。对于回归模型，标签必须是数值；而对于分类模型，标签则必须是字符串，且需与 yPred 中的对象键相匹配。示例（2 个数据实例，2 个类别 ['false', 'true']）：

['true', 'false'];

解读可视化结果

本指南将介绍如何解读 Manifold 的可视化结果。

Manifold 包含以下两部分：

• 性能对比视图，用于比较不同模型以及不同数据子集之间的预测性能；
• 特征归因视图，用于可视化不同性能水平数据子集的特征分布。

性能对比视图

该可视化展示了您的模型在数据不同分段上的整体性能概况，有助于识别表现欠佳的数据子集以便进一步检查。

图表说明

1. X 轴： 性能指标。可以是对数损失、平方误差或原始预测值。
2. 分段： 数据集会根据各实例在不同模型下的性能相似性自动划分为若干分段。
3. 颜色： 代表不同的模型。

1. 曲线： 某一模型在某一特定分段上的性能分布。
2. Y 轴： 数据数量/密度。
3. 十字标记： 左端、中心线和右端分别对应该分布的第 25、50 和 75 百分位数。

原理说明

Manifold 使用聚类算法（k-Means）基于性能相似性将预测数据划分为 N 个分段。

k-Means 算法的输入是每个实例的性能得分。默认情况下，对于分类模型，该得分是对数损失值；对于回归模型，则为平方误差值。对数损失或平方误差越低，模型性能越好。

如果您正在分析多个模型，所有模型的性能指标都将被纳入 k-Means 的输入中。

使用方法

• 查找误差较高的数据分段（位于图表右侧）。这些区域需要重点分析并尝试改进。
• 如果您在比较不同模型，请留意哪些分段中各模型的对数损失存在显著差异。如果两个模型在同一数据集上表现不同，可考虑针对该部分数据选用表现更优的模型以提升整体性能。
• 在发现分段中的性能模式或问题后，您可以切分数据来比较感兴趣的数据子集的特征分布。您可以创建两组分段进行对比（分别用粉色和蓝色标注），每组可以包含一个或多个分段。

示例

与第 1 和第 2 分段相比，第 0 分段的对数损失预测误差更低，因为其曲线更靠近左侧。

在第 1 和第 2 分段中，XGBoost 模型的表现优于深度学习模型；而在第 0 分段中，深度学习模型却优于 XGBoost。

特征归因视图

此可视化展示了您数据的特征值，并按用户定义的分段进行聚合。它有助于您识别任何可能与不准确预测输出相关的输入特征分布。

阅读图表

1. 直方图/热力图： 每个数据切片的数据分布，以对应的颜色显示。
2. 分段组： 表示您选择相互比较的数据切片。
3. 排名： 特征按照各切片之间的分布差异进行排序。

1. X轴： 特征值。
2. Y轴： 数据计数/密度。
3. 差异分数： 衡量各切片之间分布差异的指标。

解释

在您对数据进行切分以创建分段组后，此视图将显示两个分段组的特征分布直方图/热力图。

根据特征类型，地理特征可以以地图上的热力图形式展示，数值特征以分布曲线形式展示，而分类特征则以分布条形图形式展示。（在条形图中，x轴上的类别按实例数量差异排序。请在每个特征中寻找两种分布之间的差异。）

特征按照其KL散度进行排序——这是一种衡量两种对比分布之间_差异_的指标。差异越大，该特征就越有可能与区分两个分段组的因素相关联。

使用方法

• 查看每个特征中两种分布（粉色和蓝色）之间的差异。它们代表您在“性能比较视图”中所选两个分段组之间的数据差异。

示例

第0组和第1组的数据在特征0、1、2和3上存在明显差异；但在特征4和5上则不太相同。

假设第0组和第1组分别对应于低误差和高误差的数据实例，则这意味着误差较高的数据在特征0和1上的特征值往往_较低_，因为粉色曲线的峰值位于蓝色曲线的左侧。

地理特征视图

如果您的数据集中包含地理空间特征，它们将被显示在地图上。目前支持的地理特征类型包括经纬度坐标和h3六边形ID。

阅读图表

1. 特征名称： 当存在多个地理特征时，您可以选择在地图上显示哪一个。
2. 颜色依据： 如果选择了经纬度特征，则数据点会根据分组ID进行着色。
3. 地图： Manifold默认使用热力图来显示这些数据点的位置和密度。

1. 特征名称： 选择显示六边形ID特征时，具有相同六边形ID的数据点会以聚合形式显示。
2. 颜色依据： 您可以选择按以下方式为六边形着色：平均模型性能、第0分段组的百分比，或每个六边形的总数量。
3. 地图： 所有用于着色的指标也会在六边形级别的工具提示中显示。

使用方法

• 查找两个分段组（粉色和灰色）之间的地理位置差异。它们代表您先前选择的两个子集之间的空间分布差异。

示例

在上面的第一张地图中，第0组更明显地集中在旧金山市中心区域。

使用演示应用

要使用您的ML模型的静态输出进行一次性评估，请使用演示应用。 否则，如果您有一个能够程序化生成ML模型输出的系统，您可以考虑直接使用Manifold组件。

在本地运行演示应用

运行以下命令以设置环境并运行演示：

# 在根目录下安装所有依赖项
yarn
# 演示应用位于examples/manifold目录
cd examples/manifold
# 安装演示应用的依赖项
yarn
# 运行应用
yarn start

现在您应该会在localhost:8080看到演示应用正在运行。

将CSV上传到演示应用

应用启动后，您将看到上述界面，要求您将“特征”、“预测”和“真实值”数据集上传到Manifold。 它们分别对应于“准备您的数据”部分中的x、yPred和yTrue，您应相应地准备您的CSV文件，如下所示：

字段	x (特征)	yPred (预测)	yTrue (真实值)
CSV文件数量	1	多个	1
CSV格式示例	![][feature csv image]	![][prediction csv image]	![][ground truth csv image]

请注意，输入文件中应排除索引列。 数据集上传完成后，您将看到由这些数据集生成的可视化效果。

使用组件

将Manifold组件嵌入您的应用程序中，可以让您程序化地生成ML模型数据并进行可视化。 否则，如果您有一些模型的静态输出，并希望进行一次性评估，您可以考虑直接使用演示应用。

以下是将Manifold导入您的应用并加载数据以进行可视化的基本步骤。您也可以查看示例文件夹。

安装Manifold

$ npm install @mlvis/manifold styled-components styletron-engine-atomic styletron-react

加载和转换数据

为了将您的数据文件加载到 Manifold 中，可以使用 loadLocalData 操作。您也可以使用 dataTransformer 将数据重塑为 Manifold 所需的格式。

import {loadLocalData} from '@mlvis/manifold/actions';

// 创建以下操作并传递给 dispatch
loadLocalData({
  fileList,
  dataTransformer,
});

fileList: {Object[]}

一个或多个 CSV 格式的数据集。这些数据可以由您的后端返回。

dataTransformer: {Function}

一个将 fileList 转换为 Manifold 输入数据格式 的函数。默认值如下：

const defaultDataTransformer = fileList => ({
  x: [],
  yPred: [],
  yTrue: [],
});

挂载 reducer

Manifold 使用 Redux 来管理其内部状态。您需要将 manifoldReducer 注册到应用的主要 reducer 中：

import manifoldReducer from '@mlvis/manifold/reducers';
import {combineReducers, createStore, compose} from 'redux';

const initialState = {};
const reducers = combineReducers({
  // 在您的应用中挂载 manifold reducer
  manifold: manifoldReducer,

  // 其他 reducer
  app: appReducer,
});

// 使用 createStore
export default createStore(reducer, initialState);

挂载组件

如果您在上一步中将 manifoldReducer 挂载到了除 manifold 之外的其他路径，则在使用 getState 属性挂载组件时，需要指定该路径。width 和 height 都需要显式指定。如果您有地理空间特征并且需要在地图上查看它们，还需要一个 Mapbox 令牌。

import Manifold from '@mlvis/manifold';
const manifoldGetState = state => state.pathTo.manifold;
const yourMapboxToken = ...;

const Main = props => (
  <Manifold
    getState={manifoldGetState}
    width={width}
    height={height}
    mapboxToken={yourMapboxToken}
  />
);

样式

Manifold 使用 baseui，而 baseui 则以 Styletron 作为样式引擎。如果您在应用的其他部分尚未使用 Styletron，请确保使用 styletron 提供者 包裹 Manifold。

Manifold 使用 baseui 的 主题化 API。Manifold 默认使用的主题被导出为 THEME。您可以扩展 THEME 并将其作为 Manifold 组件的 theme 属性来传递，从而自定义样式。

import Manifold, {THEME} from '@mlvis/manifold';
import {Client as Styletron} from 'styletron-engine-atomic';
import {Provider as StyletronProvider} from 'styletron-react';

const engine = new Styletron();
const myTheme = {
  ...THEME,
  colors: {
    ...THEME.colors,
    primary: '#ff0000',
  },
}

const Main = props => (
  <StyletronProvider value={engine}>
    <Manifold
      getState={manifoldGetState}
      theme={myTheme}
    />
  </StyletronProvider>
);

构建于

• TensorFlow.js
• React
• Redux

贡献

请在贡献之前阅读我们的 行为准则! 关于提交拉取请求的详细信息，请参阅 CONTRIBUTING.md 文件。请参考 issue 模板。

版本控制

我们会在变更日志中记录版本和更改内容——详情请参阅 CHANGELOG.md 文件。

许可证

Apache 2.0 许可证

Manifold 快速上手指南

Manifold 是一个与模型无关的机器学习可视化调试工具。它帮助开发者超越单一的汇总指标（如 AUC、RMSE），深入识别模型在哪些数据子集上表现不佳，并通过特征分布差异分析潜在原因。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Node.js: 建议安装 LTS 版本 (v14+)
• 包管理器: 推荐使用 yarn (原文示例基于 yarn)，也可使用 npm
• 浏览器: 现代浏览器 (Chrome, Firefox, Edge 等)

前置依赖安装： 如果您尚未安装 yarn，可以通过 npm 全局安装：

npm install -g yarn

提示：国内开发者若遇到网络延迟，可配置淘宝镜像源加速依赖下载：

yarn config set registry https://registry.npmmirror.com

安装步骤

Manifold 提供演示应用（Demo App）供快速体验，也支持作为组件集成到您的项目中。以下是运行本地演示应用的步骤：

1. 克隆仓库并安装根目录依赖

   git clone https://github.com/uber/manifold.git
   cd manifold
   yarn
   

2. 进入演示应用目录并安装其依赖

   cd examples/manifold
   yarn
   

3. 启动应用

   yarn start
   

启动成功后，请在浏览器访问 http://localhost:8080。

基本使用

1. 准备数据

Manifold 接收特定格式的数据输入。您可以直接上传 CSV 文件到演示应用，或在代码中构建数据对象。

数据格式要求： 数据需包含三个核心部分，且数组顺序必须一一对应：

• x: 特征数据 (Feature Data)
• yPred: 预测结果 (Prediction Data)
• yTrue: 真实标签 (Ground Truth)

推荐数据量：每个数据集建议包含 10,000 - 15,000 条实例。若数据量过大，随机抽样通常足以揭示关键模式。

JSON 数据结构示例：

const data = {
  x:     [...],         // 特征数据列表
  yPred: [[...], ...],  // 预测数据列表（支持多模型）
  yTrue: [...],         // 真实标签列表
};

• x (Object[]): 包含特征的实例列表。

  [{feature_0: 21, feature_1: 'B'}, {feature_0: 36, feature_1: 'A'}]
  

• yPred (Object[][]): 嵌套列表。外层列表代表不同模型，内层列表代表每个实例的预测概率/值。

  // 示例：2 个模型，2 个实例，分类问题 (classes: 'false', 'true')
  [
    [{false: 0.1, true: 0.9}, {false: 0.8, true: 0.2}], // 模型 1
    [{false: 0.3, true: 0.7}, {false: 0.9, true: 0.1}]  // 模型 2
  ]
  

• yTrue (Number[] | String[]): 真实标签。回归模型为数字，分类模型需与 yPred 中的键名匹配。

  ['true', 'false']
  

2. 上传数据 (演示应用)

在 localhost:8080 页面中，您将看到文件上传界面。需准备三个 CSV 文件分别对应上述字段：

字段	对应变量	文件数量	格式说明
Feature	x	1 个	每行一个样本，列为特征
Prediction	yPred	多个	每个模型一个文件，内容为预测概率或值
Ground Truth	yTrue	1 个	每行一个样本的真实标签

上传后，系统将自动处理并生成可视化图表。

3. 解读可视化结果

Manifold 主要包含两个核心视图，用于辅助调试：

A. 性能对比视图 (Performance Comparison View)

• 功能：概览模型在不同数据分段上的表现。
• 如何阅读：
  • X 轴：性能指标（如 log-loss, squared-error）。越靠左表现越好。
  • 曲线：代表某个模型在特定数据分段上的误差分布。
  • 分段 (Segments)：系统自动将数据聚类为 N 个分段（基于表现相似度）。
• 操作建议：寻找曲线靠右（误差高）的分段。如果不同模型在同一段落表现差异巨大，可考虑针对该数据子集切换模型。

B. 特征归因视图 (Feature Attribution View)

• 功能：对比不同表现分段（如“高分段”vs“低分段”）的特征分布差异。
• 如何阅读：
  • 系统会根据您在性能视图中选定的分段组（例如粉色组和蓝色组），展示各特征的分布直方图或热力图。
  • 排序：特征按 KL 散度（分布差异度）排序。差异越大，该特征越可能是导致模型表现不佳的原因。
• 操作建议：观察排名靠前的特征。如果某特征在“低性能组”的分布明显偏向特定值（例如数值偏小或集中在某类别），则表明模型在该特征取值范围内存在偏差。

C. 地理特征视图 (Geo Feature View)

• 若数据包含经纬度或 H3 Hexagon ID，系统将自动在地图上展示数据点的空间分布差异，帮助识别地理位置相关的模型偏差。