PredictionIO 推荐引擎 Data Preparator 自定义实战:黑名单过滤与参数化配置
PredictionIO 推荐引擎 Data Preparator 自定义实战:黑名单过滤与参数化配置
导读
本文基于 Apache PredictionIO 的 Recommendation(基于 ALS 的协同过滤)模板,完整讲解如何通过修改 Data Preparator(数据准备器) 组件,为训练数据加入"排除黑名单物品"的过滤逻辑:先从硬编码路径读取黑名单文件并过滤 RDD[Rating],再通过 Params 与 engine.json 实现黑名单路径的运行时参数化,最后完成 pio build / train / deploy 全流程部署与查询验证。读完本文,你将掌握 PredictionIO 引擎模板 DASE 架构中 Data Preparator 的改造方法,并能将任意"训练前预处理"逻辑(去热门物品、黑白名单、数据清洗、采样等)以可配置方式接入引擎。
本文以仓库内文档 customize-data-prep.html.md 为核心骨架,并以完整可运行的示例 customize-data-prep 及其源码为佐证展开。
DASE 架构中的 Data Preparator 是什么
在深入代码之前,先回顾 PredictionIO 引擎模板的 DASE(DataSource / Algorithm / Serving / Engine) 架构。数据流依次经过以下两个组件:
- Data Source(数据源):从 Event Server 的数据存储中读取原始事件数据;
- Data Preparator(数据准备器):将 Data Source 产出的原始训练数据进一步加工,生成算法可直接消费的"准备好的数据"。
在推荐模板中,Data Source 产出 TrainingData(内部为 RDD[Rating]),Data Preparator 再将 TrainingData 加工成 PreparedData(同样承载 RDD[Rating])交给 ALS 算法训练。预处理的典型场景包括:
- 从训练数据中剔除某些过于热门的物品——它们对大多数用户都"人人皆爱",不利于算法区分个体口味;
- 维护一份黑名单,将违规、下架或测试用的物品在进入算法前排除;
- 数据采样、去重、按规则清洗等任何"训练前"逻辑。
PredictionIO 允许你修改模板中的任意组件来满足业务需求,本例即在 Data Preparator 中加入过滤逻辑。数据流关系可归纳为:
Event Server 数据 → DataSource.readTraining() → TrainingData(RDD[Rating])
→ Preparator.prepare() → PreparedData(RDD[Rating]) → ALS 算法训练
准备工作:创建 MyRecommendation 引擎
本教程假设你已经基于 Recommendation Engine Template: QuickStart 创建了一个名为 MyRecommendation 的引擎,并且:
- 应用(App)已创建,
appName与engine.json中的datasource.params.appName一致; - 示例数据已通过事件服务器导入(仓库中提供了导入脚本 import_eventserver.py,它会读取数据文件并把
rate/buy事件写入 Event Server,其中buy事件被映射为评分 4.0); - 一份待排除的黑名单文件已就位:仓库示例中即为
./data/sample_not_train_data.txt。
查看仓库中的黑名单示例 sample_not_train_data.txt,其内容为每行一个物品 ID:
3
4
10
22
34
54
65
89
这份文件将作为被排除的物品集合,后续所有过滤逻辑都围绕它展开。
第一步:修改 Data Preparator 加入过滤逻辑
Data Preparator 组件位于 MyRecommendation 目录下的 src/main/scala/Preparator.scala(完整示例见 Preparator.scala)。未修改的原始版本如下:
class Preparator
extends PPreparator[TrainingData, PreparedData] {
def prepare(sc: SparkContext, trainingData: TrainingData): PreparedData = {
new PreparedData(ratings = trainingData.ratings)
}
}
prepare 方法目前只是把 TrainingData.ratings 原样透传给 PreparedData。现在修改它:从文件读取黑名单物品集合,并将这些物品从训练数据中过滤掉。
import scala.io.Source // ADDED
class Preparator
extends PPreparator[TrainingData, PreparedData] {
def prepare(sc: SparkContext, trainingData: TrainingData): PreparedData = {
// MODIFIED HERE
val noTrainItems = Source.fromFile("./data/sample_not_train_data.txt")
.getLines.toSet
// exclude noTrainItems from original trainingData
val ratings = trainingData.ratings.filter( r =>
!noTrainItems.contains(r.item)
)
new PreparedData(ratings)
}
}
核心逻辑拆解:
Source.fromFile(...)读取黑名单文件,getLines.toSet将其转为Set[String],便于 O(1) 的成员判断;trainingData.ratings.filter(...)是 SparkRDD的转换操作,只保留item不在黑名单中的评分记录;- 过滤后的
ratings被包装进新的PreparedData,供下游 ALS 算法使用。
这里有一个需要留意的工程问题:黑名单路径 ./data/sample_not_train_data.txt 被硬编码在了源码里。本文后续将演示如何通过 Preparator Params 把它参数化。此外从源码可推断,prepare 返回的 PreparedData 是直接消费 RDD 的"惰性"转换,真正的计算发生在算法训练阶段。
源码印证:PPreparator 的契约
PredictionIO 对 Data Preparator 的抽象定义位于 PPreparator.scala:
abstract class PPreparator[TD, PD]
extends BasePreparator[TD, PD] {
override def prepareBase(sc: SparkContext, td: TD): PD = {
prepare(sc, td)
}
/** Implement this method to produce prepared data that is ready for model
* training.
*
* @param sc An Apache Spark context.
* @param trainingData Training data to be prepared.
*/
def prepare(sc: SparkContext, trainingData: TD): PD
}
可以看到:
PPreparator[TD, PD]泛型参数TD、PD分别是训练数据类型与准备后数据类型,对应本例的TrainingData与PreparedData;- 框架内部通过
prepareBase统一入口调用你实现的prepare,因此引擎只需知道组件的 Class 即可完成装配(见下文 Engine 装配); - 它是一个"并行 Preparator"(parallel preparator),可在集群上并行执行,产出的
PreparedData是分布式的 RDD。
对应的数据类定义同样在 DataSource.scala 中:
case class Rating(
user: String,
item: String,
rating: Double
)
class TrainingData(
val ratings: RDD[Rating]
) extends Serializable {
override def toString = {
s"ratings: [${ratings.count()}] (${ratings.take(2).toList}...)"
}
}
而 PreparedData 定义于 Preparator.scala:
class PreparedData(
val ratings: RDD[Rating]
) extends Serializable
TrainingData 与 PreparedData 都承载 RDD[Rating],且均实现 Serializable——这是分布式环境下 RDD 在集群节点间流转的前提。
组件装配:Engine 如何把 Preparator 接进去
引擎工厂 Engine.scala 把各组件按顺序装配起来:
object RecommendationEngine extends EngineFactory {
def apply() = {
new Engine(
classOf[DataSource],
classOf[Preparator],
Map("als" -> classOf[ALSAlgorithm]),
classOf[Serving])
}
}
engine.json 中的 engineFactory 字段(值为 org.apache.predictionio.examples.recommendation.RecommendationEngine)指向该工厂,PredictionIO 据此在 pio build 后实例化整条数据流水线。engine.json 中的 preparator.params 会与 Preparator 的构造函数参数一一对应,这正是下一节参数化的基础。
第二步:部署修改后的引擎并验证
配置 engine.json
部署前确认 engine.json 中的 appName 与你的 App Name 一致:
{
...
"datasource": {
"params" : {
"appName": "YourAppName"
}
},
...
}
仓库示例中 appName 为 MyApp1,同时给出了 ALS 算法的默认参数:rank: 10、numIterations: 20、lambda: 0.01、seed: 3。
构建、训练与部署
依次执行三条命令完成引擎的构建、训练与线上部署:
$ pio build
$ pio train
$ pio deploy
pio build:根据engine.json与engineFactory编译引擎代码;pio train:运行 Data Source → Data Preparator → Algorithm 的完整训练流水线,产出模型;pio deploy:将引擎作为 Web 服务部署,默认绑定http://localhost:8000。
部署完成后,可直接在浏览器访问 http://localhost:8000 查看引擎服务状态。
发起查询验证过滤效果
向已部署引擎发送推荐请求:为 ID 为 1 的用户推荐 4 部电影:
$ curl -H "Content-Type: application/json" -d '{ "user": "1", "num": 4 }' http://localhost:8000/queries.json
返回的 JSON 形如:
{
"itemScores": [
{"item": "22", "score": 4.072304374729956},
{"item": "62", "score": 4.058482414005789},
{"item": "75", "score": 4.046063009943821},
{"item": "68", "score": 3.8153661512945325}
]
}
itemScores 数组按分数降序给出推荐的物品与预测评分。从源码实现看,查询路径为:Serving 接收 Query(user, num),交给 ALSAlgorithm.predict,由 ALS 模型的 recommendProducts 计算 Top-N 物品,再通过 itemStringIntMap.inverse 把内部整数索引映射回字符串物品 ID。值得说明的是,本示例中"22"等 ID 出现在黑名单文件中,但因为训练数据中的热门物品被过滤后,模型仍可能对未见过的物品给出预测分数,具体结果取决于训练数据的分布——黑名单的作用在于不让这些物品参与训练,而非保证它们绝不出现于推荐结果。
第三步(进阶):将硬编码路径参数化到 engine.json
硬编码路径每次更换黑名单文件都要改代码、重新编译,显然不优雅。PredictionIO 提供的 Preparator Params 机制让你可以从 engine.json 读取变量值。
修改 Preparator 接收参数
再次修改 MyRecommendation 目录下的 src/main/scala/Preparator.scala:
import org.apache.predictionio.controller.Params // ADDED
// ADDED CustomPreparatorParams case class
case class CustomPreparatorParams(
filepath: String
) extends Params
class Preparator(pp: CustomPreparatorParams) // ADDED CustomPreparatorParams
extends PPreparator[TrainingData, PreparedData] {
def prepare(sc: SparkContext, trainingData: TrainingData): PreparedData = {
val noTrainItems = Source.fromFile(pp.filepath).getLines.toSet // CHANGED
val ratings = trainingData.ratings.filter( r =>
!noTrainItems.contains(r.item)
)
new PreparedData(ratings)
}
}
改动要点:
- 新增
CustomPreparatorParams(filepath: String) extends Params,作为构造参数的数据载体; Preparator构造函数接收CustomPreparatorParams,黑名单路径从pp.filepath读取,不再硬编码;Params是 PredictionIO 框架中所有参数类的基础 trait(定义于 Params.scala),要求实现Serializable,保证参数能在集群节点间安全传递。
在 engine.json 中声明 preparator 参数
在 engine.json 中加入 preparator.params:
{
...
"preparator": {
"params": {
"filepath": "./data/sample_not_train_data.txt"
}
},
...
}
PredictionIO 会把 params 下的键值对按名称绑定到 CustomPreparatorParams 的字段(此处为 filepath),从而在运行时注入。这正是引擎组件参数化的通用模式:任何 DASE 组件的参数类都可以这样从 engine.json 注入,无需改动代码即可调整配置。
重新构建部署,并验证参数生效
再次执行构建与部署:
$ pio build
$ pio train
$ pio deploy
此后,如果你想换一份黑名单文件,只需修改 engine.json 中的 filepath 值并重新 pio train/pio deploy,无需重新编译代码。这在需要频繁调整过滤名单(例如随运营策略更新的违规物品清单)的场景中极大提升了迭代效率。
参数化背后的框架机制
从源码层面看,Preparator Params 之所以能工作,依赖 PredictionIO 的两点设计:
-
组件即类 + 构造注入:
Preparator的构造参数pp: CustomPreparatorParams由框架在实例化时根据engine.json的preparator.params反射填充。engineFactory(Engine.scala)负责把 DataSource、Preparator、Algorithm、Serving 四类组件按固定顺序装配,参数类与 JSON 字段同名映射。 -
Params 契约:所有参数类(如
CustomPreparatorParams、DataSourceParams、ALSAlgorithmParams)都继承自 Params。这个 trait 本身只要求可序列化,是"引擎配置的传输协议",贯穿 DataSource、Preparator、Algorithm 全链路。
同样地,Data Source 侧的参数(appName、可选的 evalParams)与算法侧参数(rank、numIterations、lambda、seed)都遵循这套机制,读者可对照 DataSource.scala 与 ALSAlgorithm.scala 中的参数类定义验证。
一个容易被忽视的边界:空训练数据
在把过滤逻辑用于生产前,请务必关注一个边界情况:如果黑名单把训练数据过滤到空集,ALS 将无法训练。这一点在 ALSAlgorithm.scala 中有显式保护:
// MLLib ALS cannot handle empty training data.
require(!data.ratings.take(1).isEmpty,
s"RDD[Rating] in PreparedData cannot be empty." +
" Please check if DataSource generates TrainingData" +
" and Preparator generates PreparedData correctly.")
因此在实际项目中,建议在黑名单过滤后增加空集检查或阈值保护(例如过滤后记录数过少时告警),避免 pio train 阶段失败后才排查。
总结:Data Preparator 的自定义模式
通过本教程,你已完成一次完整的 Data Preparator 定制:
| 阶段 | 操作 | 关键产物 |
|---|---|---|
| 需求定义 | 确定要过滤的物品集合 | 黑名单文件(每行一个 ID) |
| 组件改造 | 修改 Preparator.prepare 加入过滤 |
Preparator.scala |
| 参数化(进阶) | 新增 CustomPreparatorParams,从 engine.json 注入路径 |
engine.json 的 preparator.params |
| 部署验证 | pio build → pio train → pio deploy + curl 查询 |
本地 8000 端口的推荐服务 |
这套模式完全可复用到其他预处理需求:去热门物品、白名单筛选、按事件类型/时间窗口清洗、负采样、特征构造等,只需替换 prepare 方法内部的转换逻辑,必要时再定义对应的参数类。PredictionIO 的 DASE 设计让每个组件都成为可插拔的"配置化模块",这正是其引擎定制能力的核心所在。
下一步可继续阅读 Customizing Serving Component,掌握对 Serving(服务层)的定制,从而完成推荐引擎前端逻辑的完整改造。