Feast Spark Compute Engine 深度解析:DAG 驱动的批处理物化与历史特征检索
Feast Spark Compute Engine 深度解析:DAG 驱动的批处理物化与历史特征检索
本文围绕 Feast 开源特征仓库中 sdk/python/feast/infra/compute_engines/spark 包(对应 Sphinx 文档 feast.infra.compute_engines.spark.rst)展开,系统讲解 Spark Compute Engine 的模块划分、配置方式、DAG 执行原理与实战用法。读完本文,你将掌握:如何在 feature_store.yaml 或 Python 代码中启用 spark.engine 批量物化引擎、理解 compute / feature_builder / job / nodes / utils 五个子模块各自承担的角色,以及 Spark 引擎如何通过执行计划完成 materialize() 与 get_historical_features() 两大核心任务。
一、关联文档与源码模块总览
本包在 Sphinx 文档中由 5 个 automodule 指令构成(compute、feature_builder、job、nodes、utils),它们一一对应仓库中的真实实现文件:
| 文档章节 | 源码文件 | 职责 |
|---|---|---|
compute 模块 |
compute.py | 定义 SparkComputeEngineConfig 与 SparkComputeEngine 引擎主体,对外提供物化与历史检索入口 |
feature_builder 模块 |
feature_builder.py | 实现 SparkFeatureBuilder,把 FeatureView 定义翻译成可执行的 DAG |
job 模块 |
job.py | 定义 SparkDAGRetrievalJob(检索结果)与 SparkMaterializationJob(物化任务状态) |
nodes 模块 |
nodes.py | 定义 Spark 专属的 DAG 节点(读、聚合、连接、过滤、去重、变换、校验、写出)与类型映射 |
utils 模块 |
utils.py | 提供 SparkSession 创建、Arrow/Pandas 批量写入等工具函数 |
从整体架构看,Spark Compute Engine 是 ComputeEngine 抽象基类 的具体实现之一。正如 compute-engine 参考文档 所述,ComputeEngine 是 Feast 的可插拔计算抽象层,负责执行特征流水线(变换、聚合、连接、物化/历史检索),Spark 是其中面向大规模分布式数据处理的后端。
二、配置参数:SparkComputeEngineConfig 详解
在 compute.py 中,SparkComputeEngineConfig 继承了 FeastConfigBaseModel,提供 4 个配置项:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type |
Literal["spark.engine"] |
"spark.engine" |
计算引擎类型选择器,固定值,用于在配置中声明启用 Spark 引擎 |
spark_conf |
Optional[Dict[str, str]] |
None |
Spark 会话的配置覆盖层,以 key-value 形式透传给 SparkConf |
staging_location |
Optional[StrictStr] |
None |
批量物化任务的远程暂存路径 |
region |
Optional[StrictStr] |
None |
使用 s3 暂存位置时的 AWS Region |
partitions |
int |
0 |
写入在线存储时的分区数;0 表示不做重分区 |
其中 type 字段是引擎类型选择器,任何 Spark 引擎配置都必须以 spark.engine 作为 type 值,引擎才能在配置解析阶段被正确识别。
2.1 在 feature_store.yaml 中启用
根据 docs/reference/compute-engine/spark.md 中的示例,可在 batch_engine 段配置:
offline_store:
type: snowflake.offline
...
batch_engine:
type: spark.engine
partitions: 10 # number of partitions when writing to the online or offline store
spark_conf:
spark.master: "local[*]"
spark.app.name: "Feast Spark Engine"
spark.sql.shuffle.partitions: 100
spark.executor.memory: "4g"
2.2 在 Python 代码中启用
同样参考 spark.md,可以在 RepoConfig 中以字典形式传入 batch_engine 配置,与 SparkOfflineStoreConfig、DynamoDBOnlineStoreConfig 组合使用:
from feast import FeatureStore, RepoConfig
from feast.repo_config import RegistryConfig
from feast.infra.online_stores.dynamodb import DynamoDBOnlineStoreConfig
from feast.infra.offline_stores.contrib.spark_offline_store.spark import SparkOfflineStoreConfig
repo_config = RepoConfig(
registry="s3://[YOUR_BUCKET]/feast-registry.db",
project="feast_repo",
provider="aws",
offline_store=SparkOfflineStoreConfig(
spark_conf={
"spark.ui.enabled": "false",
"spark.eventLog.enabled": "false",
"spark.sql.catalogImplementation": "hive",
"spark.sql.parser.quotedRegexColumnNames": "true",
"spark.sql.session.timeZone": "UTC"
}
),
batch_engine={
"type": "spark.engine",
"partitions": 10
},
online_store=DynamoDBOnlineStoreConfig(region="us-west-1"),
entity_key_serialization_version=3
)
store = FeatureStore(config=repo_config)
SparkOfflineStoreConfig 中的 spark_conf 用于离线存储侧的 Spark 会话初始化;batch_engine 中的 spark_conf 则由计算引擎在创建物化/检索会话时使用。二者面向不同执行环节,需要时建议分别配置。
2.3 引擎配置的合并优先级
从 base.py 的 _get_feature_view_engine_config 可以看出引擎配置的合并规则:
- 仓库级默认配置
self.repo_config.batch_engine_config作为基线; BatchFeatureView上的batch_engine或StreamFeatureView上的stream_engine运行时覆盖优先级最高;- 最终以
{**default_conf, **runtime_conf}合并,运行时配置逐键覆盖仓库默认值。
这意味着同一仓库内可以为不同 FeatureView 指定差异化的 Spark 资源配置,实现细粒度的计算隔离。
三、引擎主体:SparkComputeEngine 的两大核心能力
SparkComputeEngine 在 compute.py 中实现,它直接继承 ComputeEngine 基类。基类在 base.py 中提供了 materialize() 的通用编排逻辑:将单个任务包装为列表后,逐个调用 _materialize_one() 并收集 MaterializationJob 结果。
3.1 批量物化:materialize()
SparkComputeEngine 的物化路径(_materialize_one,见 compute.py)遵循 "构建执行上下文 → 构造 FeatureBuilder → 构建并执行执行计划" 的三步流程:
get_execution_context(registry, task)从注册表中解析实体定义,生成类型化的ExecutionContext;SparkFeatureBuilder(registry, spark_session, task).build()将 FeatureView 定义翻译为ExecutionPlan;plan.execute(context)按依赖顺序执行各 DAG 节点,完成从源数据读取到在线/离线存储写入的完整流水线。
成功时返回 SparkMaterializationJob(status=SUCCEEDED),任何异常都会被捕获并包装为 SparkMaterializationJob(status=ERROR, error=e),不会让整个物化循环中断。
此外,compute.py 还保留了一条旧版物化路径 _materialize_from_offline_store:直接从离线存储调用 pull_latest_from_table_or_query() 拉取数据,再经 mapInPandas 写入在线存储。该路径会在运行时打印弃用警告("Materializing from offline store will be deprecated in the future. Please use the new materialization API."),新项目应优先走 DAG 物化 API。
3.2 历史特征检索:get_historical_features()
历史检索(compute.py)用于生成训练数据集,与物化共享大部分执行逻辑:
- 若
entity_df是 SQL 字符串,会抛出NotImplementedError("SQL-based entity_df is not yet supported in DAG"),当前 DAG 路径仅支持 DataFrame 形式的实体表; - 构建并执行计划后,返回
SparkDAGRetrievalJob(包含plan、spark_session、context、config与full_feature_names); - 执行失败时返回携带
error的SparkDAGRetrievalJob,供上层调用方统一检查。
3.3 检索任务与物化任务的返回对象
job.py 定义了两种任务对象:
SparkDAGRetrievalJob:继承自离线存储侧的 SparkRetrievalJob。to_spark_df()在首次调用时惰性执行执行计划并缓存结果 DataFrame(_ensure_executed);to_sql()尝试将整个计划渲染为 SQL(当前基类尚未实现完整 SQL 生成);error()暴露构建期异常。SparkMaterializationJob:一个@dataclass,承载job_id(格式为{feature_view.name}-{start_time}-{end_time})、status(SUCCEEDED/ERROR)与可选的error;should_be_retried()当前固定返回False。
四、DAG 执行原理:从 FeatureView 到执行计划
Spark Compute Engine 的精髓在于"逻辑 DAG → 物理 DAG → 执行计划"的二级建模。整体链路如下:
FeatureView 定义
│ FeatureResolver 解析依赖、拓扑排序
▼
逻辑 DAG(FeatureView 之间的依赖关系)
│ SparkFeatureBuilder 逐视图构建执行节点
▼
物理 DAG(SparkReadNode → Transform → Filter → Agg/Dedup → Join → Validate → Write)
│ topological_sort 排序
▼
ExecutionPlan(按序执行,中间结果缓存于 ExecutionContext.node_outputs)
│ plan.execute(context)
▼
DAGValue(携带 Spark DataFrame 与 DAGFormat.SPARK 元数据)
4.1 逻辑层的 FeatureResolver
FeatureBuilder 初始化时会创建一个 FeatureResolver(见 feature_builder.py),由它解析 FeatureView 的依赖关系并做拓扑排序,得到逻辑 DAG 的根节点。正如 compute-engine 参考文档 所展示,一个典型的多级派生 FeatureView 会被解析为类似下面的逻辑树:
- Output(Agg(daily_driver_stats))
- Agg(daily_driver_stats)
- Filter(daily_driver_stats)
- Transform(daily_driver_stats)
- Agg(hourly_driver_stats)
- Filter(hourly_driver_stats)
- Transform(hourly_driver_stats)
- Source(hourly_driver_stats)
4.2 物理层的节点构建顺序
FeatureBuilder._build()(feature_builder.py)为每个 FeatureView 按固定顺序组装执行节点:
- Source 或 Join/Transform:如果视图有物理数据源则先建读取节点,有派生输入则按需走用户自定义变换或默认 left join;
- Filter:按时间窗口与 TTL 过滤;
- Aggregate 或 Dedup:有聚合定义则聚合,否则按"历史检索任务或
only_latest"决定去重; - Validate:仅当
enable_validation=True时插入校验节点。
随后 build() 通过 topological_sort 得到最终有序的节点序列,包装为 ExecutionPlan(plan.py)。执行时每个节点的输出 DAGValue 会缓存在 ExecutionContext.node_outputs 中,下游节点按需读取,避免重复计算(context.py)。
五、节点实现细节:nodes 模块逐项拆解
nodes.py 是数据流核心,每个节点都继承通用 DAGNode,并在 execute(context) 中返回携带 Spark DataFrame 的 DAGValue。
5.1 类型映射:from_feast_to_spark_type
节点级类型映射函数将 Feast 类型系统映射为 PySpark 原生类型:
| Feast 类型 | Spark 类型 |
|---|---|
BYTES |
BinaryType |
STRING |
StringType |
INT32 |
IntegerType |
INT64 |
LongType |
FLOAT64 |
DoubleType |
FLOAT32 |
FloatType |
BOOL |
BooleanType |
UNIX_TIMESTAMP |
TimestampType |
MAP |
MapType(StringType, StringType) |
JSON |
StringType |
Struct |
递归映射为 StructType |
Array / Set |
递归映射为 ArrayType |
无法映射的类型返回 None,调用方(如 build_validation_node)会跳过该列的强类型校验。
5.2 各节点职责
SparkReadNode:调用create_offline_store_retrieval_job读取数据源。若返回的是SparkRetrievalJob则直接to_spark_df();若为其他离线存储(如 BigQuery、Snowflake)的检索任务,则先to_arrow()再createDataFrame,实现跨离线存储的通用读取。SparkAggregationNode:支持两种聚合模式。标准模式使用 Spark 原生groupBy与F.window实现时间窗口聚合(count_distinct特判为countDistinct);启用 tiling 时(enable_tiling=True且存在time_window)走锯齿波平铺(sawtooth tiling)路径:按窗口分组 →apply_sawtooth_window_tiling生成累积瓦片 →convert_cumulative_to_windowed转为窗口聚合 → pandas 外连接合并 →deduplicate_keep_latest去重 → 统一转回 Spark DataFrame。tiling 模式下所有聚合必须显式声明time_window,否则抛出ValueError。SparkJoinNode:将多个输入 DataFrame 以left方式按 join keys 连接,非 join key 列以{FeatureViewName}__{column}前缀命名以避免冲突;若ExecutionContext.entity_df存在,最后将实体表左连接进来(用于 point-in-time 检索)。SparkFilterNode:实现 point-in-time 过滤feature.ts <= entity.event_timestamp;若配置了 TTL,再追加下界feature.ts >= entity.event_timestamp - ttl;同时支持 FeatureView 上自定义的filter表达式。SparkDedupNode:基于 join keys 分区,按timestamp_column(可叠加created_timestamp_column)降序取row_number = 1,即每个实体键保留最新一条记录。SparkTransformationNode:执行用户 UDF。优先通过udf_string源码重建函数(resolve_udf),并以 dill 序列化的 callable 作为 fallback——源码注释指出,dill 反序列化出的函数在 Spark 4.0.1 上调用withColumn/__getitem__可能导致段错误(exit 139),源码重建是更安全的选择。SparkValidationNode:enable_validation=True时生效。校验三类问题:缺失列(抛ValueError)、列类型不兼容(经_spark_types_compatible宽容比较,如 Map↔Struct、Int32↔Int64、Float32↔Float64 视为兼容)、JSON 列格式(对前 1000 行抽样执行json.loads,发现非法 JSON 即抛出带行号的错误)。SparkWriteNode:物化出口。online=True时经mapInArrow写入在线存储;offline=True时若数据源非 SparkSource 也走mapInArrow,若为 SparkSource 则直接spark_df.write.format(file_format).mode("append").save(dest_path)追加写入目标路径。
六、会话管理与高效写入:utils 模块
6.1 会话创建与 S3A 事件日志占位
get_or_create_new_spark_session(utils.py)优先复用当前活跃会话,不存在时用 SparkConf().setAll() 批量注入 spark_conf 后 getOrCreate(),并在最后强制开启 spark.sql.execution.arrow.pyspark.enabled=true 以启用 Arrow 高效数据传输。
配套的 _ensure_s3a_event_log_dir(utils.py)解决了一个真实的坑:当 spark.eventLog.enabled=true 且 spark.eventLog.dir 指向 s3a:// 时,SparkContext 初始化会因 S3 前缀不存在而崩溃(S3 没有真实目录,空前缀返回 404)。该函数会在 SparkContext 构建前用 boto3 在对应桶前缀下写入一个零字节 .keep 占位对象。此逻辑仅在 spark.eventLog.enabled=true 且目录为 s3a:// 前缀时触发,失败仅告警不阻断。
6.2 mapInArrow / mapInPandas 批量写入
map_in_arrow(utils.py):在 Spark 执行器内反序列化SerializedArtifacts,按materialization_config.online_write_batch_size将表拆分为子批次(None时保持单批次以兼容旧行为),经_convert_arrow_to_proto转为 proto 行后调用online_store.online_write_batch();offline模式则调用offline_store.offline_write_batch()。map_in_pandas(utils.py):旧版物化路径的写入函数,逻辑与 Arrow 版类似,额外处理了batch_source.field_mapping字段映射,并最终 yield 一个 dummy DataFrame 以满足mapInPandas必须返回结果的约束。
七、实战:通过集成测试理解引擎行为
仓库中的集成测试 test_compute.py 是理解引擎行为的最佳样例:
历史检索测试(test_spark_compute_engine_get_historical_features):定义一个 mode="python" 的 BatchFeatureView,带 sum(conv_rate)、avg(acc_rate) 聚合与自定义 transform_feature UDF(把特征值翻倍),TTL 3 天。构造 HistoricalRetrievalTask 后调用 engine.get_historical_features(),最终通过 SparkDAGRetrievalJob.to_spark_df() 校验 driver_id 与聚合结果(如 sum_conv_rate 精确到 1e-6)。这印证了 Spark 引擎对"读取 → 时间过滤 → UDF 变换 → 聚合 → 实体表连接"完整 DAG 的端到端支持。
物化测试(test_spark_compute_engine_materialize):定义 online=True, offline=True 的 FeatureView,构造 MaterializationTask(start_time = now - 2天,end_time = now),调用 engine.materialize() 后断言任务 SUCCEEDED,并分别用 _check_online_features(在线存储读回 conv_rate=1.6,即原始 0.8 经 UDF 翻倍)与 _check_offline_features(离线存储校验)验证双写结果。测试注释清楚说明了预期执行计划:数据读取 → 按起止时间过滤 → 应用 UDF → 写入在线与离线存储。
其他相关测试位于 test_compute_dag.py(DAG 节点级行为)与 test_spark_materialization_engine.py。
八、适用场景与限制
适用场景:大规模批量物化(materialize / materialize-incremental)与训练数据集生成(get_historical_features)。由于读取节点支持将非 Spark 离线存储(如 Snowflake、BigQuery)的结果先转 Arrow 再建 DataFrame,Spark 引擎可以搭配多种离线存储使用,这正是 spark.md 强调的设计目标。
已知限制(均来自源码事实):
get_historical_features暂不支持 SQL 字符串形式的entity_df,仅支持 DataFrame;SparkMaterializationJob.should_be_retried()恒为False,引擎本身不负责任务重试;- 旧版
_materialize_from_offline_store路径已标记弃用,建议迁移到新的 DAG 物化 API; - 配置
spark.eventLog指向 S3A 时需依赖 boto3 预创建占位目录,未安装 boto3 或 S3 不可达时仅告警、不保证会话必然成功。
如果需要面向 Kubeflow Spark Operator 的集群提交模式,可进一步参考同目录下的 SparkApplicationComputeEngine,它与本文介绍的进程内 Spark 引擎是两种不同的部署形态。