Photon 机器学习（Photon ML）

请查看我们的动手教程。

Photon ML 是一个基于 Apache Spark 的机器学习库。它最初由 LinkedIn 机器学习算法团队开发。目前，Photon ML 支持训练不同类型的广义线性模型（GLMs）和广义线性混合效应模型（GLMMs/GLMix 模型）：逻辑回归、线性回归和泊松回归。

• 功能特性
  • 广义线性模型
  • GAME - 广义加性混合效应模型
  • 可配置的优化器
  • 正则化
  • 特征缩放与归一化
  • 偏置训练
  • 特征汇总
  • 模型验证
  • 热启动训练
  • 部分重新训练
• 实验性功能
  • 平滑合页损失线性 SVM
  • 超参数自动调优
  • 热启动训练时按前一模型正则化
• 如何构建
• 如何使用
  • 驱动程序
  • API
  • Avro 模式
  • 其他格式呢？
  • 输入数据格式
  • 模型
  • 阴影 JAR
  • 试一试！
    • 安装 Spark
    • 获取并构建代码
    • 获取数据集
    • 训练模型
  • 在集群模式下运行 Photon ML
• 模块与目录
  • 源代码
  • 其他
• IntelliJ IDEA 设置
• 如何贡献
• 参考文献

功能特性

广义线性模型

• 线性回归
• 逻辑回归
• 泊松回归

GAME - 广义加性混合效应模型

GAME 算法使用坐标下降法，超越了传统的 GLM，进一步提供了针对每个实体（如用户、物品、国家等）的系数（在统计文献中也称为随机效应）。它能够在 Spark 框架内解决并扩展到包含数百亿个系数的模型训练问题。

例如，用于电影推荐的 GAME 模型可以表示为（固定效应模型 + 针对用户的随机效应模型 + 针对电影的随机效应模型 + 用户-电影矩阵分解模型）。有关 GAME 模型的更多详细信息，请参阅这里。

Photon ML 目前支持的 GAME 模型类型是 GLMM 或“GLMix”模型。LinkedIn 的许多核心产品都采用了 GLMix 模型：职位搜索与推荐、新闻推送排序、广告点击率预测以及“相关浏览”功能。有关 GLMix 模型的更多信息，请参阅这里。

可配置的优化器

• LBFGS
• TRON

正则化

• L1（LASSO）正则化
• L2（Tikhonov）正则化（仅 TRON 支持）
• 弹性网络正则化

特征缩放与归一化

• 标准化：均值为零、方差为一的归一化
• 按标准差缩放
• 按最大值缩放到 [-1, 1] 范围

偏置训练

这是一种典型的多层模型训练方法，用于将另一个模型的响应插入到全局模型中。例如，在进行二分类问题时，可以先用部分特征训练一个模型。然后，用该模型对数据进行评分，并将得分作为“偏置”值。这样，后续模型就可以在第一层模型残差的基础上进行学习，同时结合两个模型的优势。

特征汇总

提供每个特征的典型指标（均值、最小值、最大值、标准差、方差等）。

模型验证

在验证数据集上计算已训练模型的评估指标，例如 AUC、RMSE 或 Precision@k。

热启动训练

加载现有模型，并将其系数作为优化的起点。当连续训练多个模型时，可以使用前一个模型的系数。

部分重新训练

加载现有模型，但锁定其系数。这允许高效地重新训练 GAME 模型的一部分。

增量学习

加载现有模型，利用其系数和方差构建先验信息，从而实现增量式训练。增量训练的模型性能与同时使用历史数据和当前数据的模型相当。

实验性功能

Photon ML 目前包含一些尚未完全测试的实验性功能。

平滑合页损失线性 SVM

除了上述广义线性模型之外，Photon ML 还支持一种对优化器友好的线性 SVM 近似方法，具体描述见 Jason D. M. Rennie 在这里的文章。

超参数自动调优

自动探索 GAME 模型的超参数空间。有两种搜索方式：

• 随机搜索：使用 Sobol 序列随机但均匀地探索超参数空间
• 贝叶斯搜索：使用高斯过程在整个超参数空间中进行定向搜索

如何构建

注意：在构建之前，请确保环境变量 JAVA_HOME 指向 Java 8 JDK。Photon ML 不兼容 JDK < 1.8。 以下命令适用于 Linux/Mac 用户，Windows 用户请使用 gradlew.bat 代替 gradlew。

# 仅构建二进制 JAR 文件：
./gradlew assemble

# 构建并运行所有测试（单元测试和集成测试）：
./gradlew clean build

# 仅运行单元测试：
./gradlew clean build -x integTest

# 仅运行集成测试：
./gradlew clean build -x test

# 不运行任何测试：
./gradlew clean build -x test -x integTest

# 运行单元测试：
./gradlew test

# 运行集成测试：
./gradlew integTest

# 使用 Apache Rat 检查许可证：
./gradlew rat

# 检查 Scala 代码风格：
./gradlew scalastyle

# 检查所有内容
./gradlew check

使用方法

驱动程序

要从命令行使用 Photon ML，有 3 种默认驱动程序：用于 GLM 训练的旧版 Photon 驱动程序、GAME 训练驱动程序和 GAME 打分驱动程序。每种驱动程序都有各自的输入参数。我们建议使用 GAME 驱动程序，因为 GLM 是 GAME 模型的一种特殊情况。旧版 Photon 驱动程序已有一段时间未进行开发，现已弃用。

API

Photon ML 可以像 Spark ML 一样导入，并直接使用其 API 层。在可能的情况下，我们尽量使接口与 Spark ML 的接口保持一致。有关如何使用 Photon ML API 的示例，请参阅驱动程序源代码。

Avro 模式

目前可用的驱动程序以 Apache Avro 格式读取和写入数据。详细的模式声明位于 photon-avro-schemas 模块中。

其他格式呢？

LinkedIn 主要使用 Avro 格式的数据。虽然 Avro 提供了一种统一且严谨的方式来管理所有关键的数据表示形式，但我们认为允许其他数据格式也很重要，这样可以使 Photon ML 更加灵活。欢迎并鼓励为 Photon ML 贡献其他格式的数据读取器。

输入数据格式

Photon ML 在 Avro 输入数据中保留了以下字段名称：

1. response：double（必填）
   • 事件的响应/标签
2. weight：double（可选）
   • 某个样本相对于其他样本的相对权重
   • 默认值 = 1.0
3. offset：double（可选）
   • 由其他模型计算出的残差分数
   • 默认值 = 0.0
   • 计算出的分数总是采用 (x * B) + offset 的形式，其中 x 是特征向量，B 是系数向量
4. uid：string、int 或 long（可选）
   • 样本的唯一标识符
5. metadataMap：map: [string]（可选）
   • 样本的非特征元数据映射
6. features：array: [FeatureAvro]（旧版 Photon 驱动程序要求）
   • 用于训练或打分的特征数组

所有这些默认名称都可以通过 GAME 驱动程序覆盖。然而，它们是保留字段，不能用于除默认用途之外的其他目的（例如，不能将 response 指定为权重列）。

记录中可能还存在其他字段，事实上，某些功能确实需要这些字段（例如，必须有 ID 字段才能按随机效应模型或某些验证指标对数据进行分组）。

通过现有驱动程序加载的特征应遵循 LinkedIn 的命名规范。每个特征必须是一个包含以下字段的 Avro 记录：

1. name：string

• 特征名称/类别

2. term：string

• 特征子类别

3. value：double

• 特征值

为了说明 name 和 term 之间的区别，可以考虑以下分类特征：

  name = “age”
  term = “0-10”
  value = 1.0
  
  name = “age”
  term = “11-20”
  value = 0.0
  
  ...

模型

旧版 Photon 直接将模型系数输出到文本文件中：

# 对于文本文件中的每一行：
[feature_string]\t[feature_id]\t[coefficient_value]\t[regularization_weight]

GAME 模型则使用 BayesianLinearModelAvro Avro 模式输出。

打包后的 JAR 文件

photon-all 模块发布了一个打包后的 JAR 文件，其中包含了 Photon ML 的所有必要运行时依赖项，但不包括 Spark 和 Hadoop。打包是一种创建“胖”JAR 文件的可靠方法。它不仅将所有依赖项打包到一个单独的文件中，还会智能地重命名一些选定的类包，以避免依赖冲突。尽管 photon-all.jar 并不是必需品，用户也可以提供自己的依赖副本，但在系统 JAR 和用户 JAR 之间可能发生复杂依赖冲突的集群环境中，强烈建议使用此打包后的 JAR 文件。（有关打包的更多信息，请参阅 Gradle Shadow Plugin）。

以下是构建 photon-all JAR 文件的命令：

./gradlew :photon-all:assemble

试一试！

开始使用 Photon ML 的最简单方法是尝试我们创建的教程，该教程演示了如何应用 GLMix 模型来构建个性化的推荐系统。您可以在维基页面上查看说明：这里。

或者，您也可以按照以下步骤在本地机器上试用 Photon ML。

安装 Spark

此步骤取决于您的操作系统。在 OS X 上，您可以使用 Homebrew 通过以下命令安装 Spark：

brew install apache-spark

有关更多信息，请参阅 Spark 文档。

获取并构建代码

git clone git@github.com:linkedin/photon-ml.git
cd photon-ml
./gradlew build -x test -x integTest

获取数据集

在此示例中，我们将使用“a1a”数据集，该数据集来自 https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary.html。目前，Photon ML 数据集转换器仅支持 LibSVM 格式。

curl -O https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary/a1a
curl -O https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/binary/a1a.t

将数据转换为 Photon ML 驱动程序使用的 Avro 格式。

mkdir -p a1a/train
mkdir -p a1a/test
pip install avro
python dev-scripts/libsvm_text_to_trainingexample_avro.py a1a dev-scripts/TrainingExample.avsc a1a/train/a1a.avro
python dev-scripts/libsvm_text_to_trainingexample_avro.py a1a.t dev-scripts/TrainingExample.avsc a1a/test/a1a.t.avro

第一条命令可能会因您的系统配置而有所不同。如果失败，请尝试您所在平台的标准 Python 库安装方法。

训练模型

现在，我们已经准备好在本地开发环境中使用 Photon ML 训练模型了。从“photon-ml”目录运行以下命令：

spark-submit \
  --class com.linkedin.photon.ml.Driver \
  --master local[*] \
  --num-executors 4 \
  --driver-memory 1G \
  --executor-memory 1G \
  "./build/photon-all_2.10/libs/photon-all_2.10-1.0.0.jar" \
  --training-data-directory "./a1a/train/" \
  --validating-data-directory "./a1a/test/" \
  --format "TRAINING_EXAMPLE" \
  --output-directory "out" \
  --task "LOGISTIC_REGRESSION" \
  --num-iterations 50 \
  --regularization-weights "0.1,1,10,100" \
  --job-name "demo_photon_ml_logistic_regression"

或者，要使用 GAME 训练驱动程序运行完全相同的训练任务，可以使用以下命令：

spark-submit \
  --class com.linkedin.photon.ml.cli.game.GameTrainingDriver \
  --master local[*] \
  --num-executors 4 \
  --driver-memory 1G \
  --executor-memory 1G \
  "./build/photon-all_2.10/libs/photon-all_2.10-1.0.0.jar" \
  --input-data-directories "./a1a/train/" \
  --validation-data-directories "./a1a/test/" \
  --root-output-directory "out" \
  --feature-shard-configurations "name=globalShard,feature.bags=features" \
  --coordinate-configurations "name=global,feature.shard=globalShard,min.partitions=4,optimizer=LBFGS,tolerance=1.0E-6,max.iter=50,regularization=L2,reg.weights=0.1|1|10|100" \
  --coordinate-update-sequence "global" \
  --coordinate-descent-iterations 1 \
  --training-task "LOGISTIC_REGRESSION"

当此命令执行完毕后，您应该会看到一个名为“out”的新文件夹，其中包含训练好的模型。

在集群模式下运行 Photon ML

一般来说，运行 Photon ML 并不不同于运行其他通用的 Spark 应用程序。因此，我们可以使用 Spark 的 bin 目录中的 spark-submit 脚本来在 不同的集群模式 上运行 Photon ML：

• Spark 独立模式
• Mesos
• YARN

以下是使用 YARN 运行逻辑回归训练作业的最小化设置模板。对于使用其他集群模式运行 Photon ML，可以根据 http://spark.apache.org/docs/latest/submitting-applications.html 中的说明修改 spark-submit 的相关参数。

spark-submit \
  --class com.linkedin.photon.ml.Driver \
  --master yarn \
  --deploy-mode cluster \
  --num-executors $NUM_EXECUTORS \
  --driver-memory $DRIVER_MEMORY \
  --executor-memory $EXECUTOR_MEMORY \
  "./build/photon-all_2.10/libs/photon-all_2.10-1.0.0.jar" \
  --training-data-directory "path/to/training/data" \
  --validating-data-directory "path/to/validating/data" \
  --output-directory "path/to/output/dir" \
  --task "LOGISTIC_REGRESSION" \
  --num-iterations 50 \
  --regularization-weights "0.1,1,10" \
  --job-name "demo_photon_ml_logistic_regression"

TODO：此示例应更新为使用 GAME 训练驱动程序。 此外，还有一个更复杂的脚本，展示了使用 Photon ML 的高级选项和自定义功能，位于 example/run_photon_ml.driver.sh。

详细用法可通过以下命令查看：

./run_photon_ml.driver.sh [-h|--help]

注意：当前脚本中并非所有配置都作为选项公开。如有任何自定义需求，请直接修改配置。

模块和目录

源代码

• TODO：Photon ML 模块需要重构。完成后，本节将进行更新。

其他

• build-scripts 包含 Gradle 任务的脚本
• buildSrc 包含 Gradle 插件的源代码
• dev-scripts 包含各种可能对开发有用的脚本
• examples 包含一个演示如何从命令行运行 Photon ML 的脚本
• gradle 包含 Gradle Wrapper JAR 文件
• travis 包含用于控制 Travis CI 测试执行的脚本

IntelliJ IDEA 设置

正确设置后，所有测试（单元测试和集成测试）都可以从 IntelliJ IDEA 中运行，这对于开发非常有帮助（IntelliJ IDEA 的调试器可用于所有测试）。

• 运行 ./gradlew idea
• 以“新建/从现有源代码导入项目”的方式打开项目，选择 Gradle 项目，并将 Gradle 设置为使用本地 Wrapper。

如何贡献

我们欢迎各位的贡献。以下是一些不错的入门方式：报告问题、修复现有问题或参与讨论。对于重大功能更改，强烈建议事先与评审人员交流想法和设计方案。沟通良好的更改最有可能被接受。

参考文献

• 张先兴、周一桐、马一鸣、陈必忠、张亮和迪帕克·阿加瓦尔。GLMix：用于大规模响应预测的广义线性混合模型。载于第22届SIGKDD知识发现与数据挖掘会议，2016年。

Photon ML 快速上手指南

Photon ML 是一个基于 Apache Spark 的机器学习库，由 LinkedIn 开发。它专注于训练广义线性模型（GLM）和广义线性混合模型（GLMM/GLMix），支持逻辑回归、线性回归和泊松回归等算法，能够处理高达数千亿系数的超大规模模型训练。

环境准备

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

• 操作系统: Linux 或 macOS（Windows 用户需使用 gradlew.bat 替代 gradlew 命令）。
• Java 版本: 必须安装 JDK 8。Photon ML 不兼容 JDK 1.8 以下的版本。
  • 请设置环境变量 JAVA_HOME 指向 JDK 8 安装路径。
• 构建工具: 项目自带 Gradle Wrapper，无需单独安装 Gradle。
• 运行依赖:
  • Apache Spark (建议最新稳定版)
  • Hadoop (集群模式下需要)

提示：国内开发者若下载 Spark 或 Hadoop 较慢，可使用清华大学或阿里云镜像源加速下载。

安装步骤

1. 获取源码

从 GitHub 克隆项目仓库：

git clone https://github.com/linkedin/photon-ml.git
cd photon-ml

2. 编译项目

进入项目目录后，使用自带的 Gradle Wrapper 进行编译。

• 仅构建二进制包（推荐快速尝试）：

  ./gradlew assemble
  

• 构建并运行所有测试（单元测试 + 集成测试）：

  ./gradlew clean build
  

• 构建包含所有依赖的 Fat Jar（适用于集群部署，避免依赖冲突）：

  ./gradlew :photon-all:assemble
  

  生成的 jar 包位于 photon-all/build/libs/ 目录下。

基本使用

Photon ML 提供了命令行驱动（Drivers）和 API 两种使用方式。最常用的是 GAME Driver，它同时支持标准的 GLM 和复杂的 GLMix 模型。

数据格式要求

Photon ML 默认读取 Apache Avro 格式的数据。输入数据必须包含以下保留字段：

• response (double, 必填): 标签或响应值。
• features (array, 必填): 特征数组，每个元素包含 name (特征名), term (子类别), value (数值)。
• weight (double, 可选): 样本权重，默认为 1.0。
• offset (double, 可选): 偏移量，用于多层模型训练，默认为 0.0。

最简单的使用示例

假设您已准备好 Avro 格式的训练数据 train_data.avro，以下是通过命令行训练一个逻辑回归模型的基本流程：

1. 准备 Spark 环境

如果您本地尚未安装 Spark，可以通过 Homebrew (macOS) 快速安装：

brew install apache-spark

2. 运行训练任务

使用 spark-submit 提交 Photon ML 的 GAME 训练驱动。以下命令展示了核心参数结构（具体类名和参数请参考编译后的 jar 包内容）：

spark-submit \
  --class com.linkedin.photon.ml.driver.GameTrainingDriver \
  --master local[*] \
  path/to/photon-all.jar \
  --input-path hdfs:///path/to/train_data.avro \
  --output-path hdfs:///path/to/output/model \
  --task-type LOGISTIC_REGRESSION \
  --regularization-type L2 \
  --regularization-weight 1.0

参数说明：

• --task-type: 指定模型类型，支持 LINEAR_REGRESSION, LOGISTIC_REGRESSION, POISSON_REGRESSION。
• --regularization-type: 正则化类型，支持 L1, L2, ELASTIC_NET。
• --input-path / --output-path: 支持本地文件系统路径或 HDFS/S3 路径。

3. 模型输出

• 传统 GLM 模型: 输出为文本文件，每行格式为 [特征字符串]\t[特征 ID]\t[系数值]\t[正则化权重]。
• GAME/GLMix 模型: 输出为符合 BayesianLinearModelAvro schema 的 Avro 文件，包含固定效应和随机效应系数。

4. 模型验证与评分

训练完成后，可使用 GameScoringDriver 对验证集进行评分，计算 AUC、RMSE 或 Precision@k 等指标：

spark-submit \
  --class com.linkedin.photon.ml.driver.GameScoringDriver \
  --master local[*] \
  path/to/photon-all.jar \
  --model-input-path hdfs:///path/to/output/model \
  --data-input-path hdfs:///path/to/validation_data.avro \
  --output-path hdfs:///path/to/scores

进阶建议：对于更复杂的个性化推荐场景（如结合用户、物品随机效应），建议参考官方提供的 Photon ML Tutorial 以获取完整的 GLMix 建模示例。