使用Lakeflow管道作为特征源

SdpSource 在触发的 Lakeflow 管道的输出表上定义特征视图,功能商店在每次物质化和回填前为你运行该管道。 用它来为需要连接、多步变换或自定义窗口的特征提供在线服务并用其训练模型,而无需自己调度或回填流水线。

何时使用 SdpSource

当你的特征所需的逻辑无法通过带 transformation_sql 的 DeltaTableSource 实现时,请使用 SdpSource。 你可以在 Lakeflow流水线中写入该逻辑,然后将特征视图指向流水线的某个输出表。

有了 SdpSource,Feature Store 协调管道,并管理与在线和离线存储的同步:

  • 每次实体化运行都会更新流水线,然后才读取输出表。
  • 实体化特征每次运行时都会同步到线上和线下存储,按你设定的触发或排程进行同步。
  • 回填会完全刷新输出表,然后在你经过的时间范围内回填所需的特征。
  • 你可以在一条流水线上注册多个特征视图,使用 ColumnSelection 或 聚合函数。

如果你自己调度流水线,或者流水线是连续运行的,就改为在流水线的输出表上使用 DeltaTableSource。 Feature Store 会读取表格,但不会运行流水线。

特征存储如何运行管道

针对 SdpSource 特征的每次具体化运行都会执行以下操作:

  1. 运行启动了流水线的更新。 如果更新已经在运行,运行会先等它完成。 如果该更新成功完成,是完整更新,且在运行开始前不超过10分钟开始,运行将重新使用该更新。 否则,该运行会启动自己的更新。 回填更新和部分或仅验证的更新不会被重复使用。 流水线一次运行一个更新,所以共享流水线的运行会轮流运行。
  2. 更新完成后,特征库读取输出表,并以与 DeltaTableSource 相同的方式将这些特征具体化。

如果流水线更新失败、被取消或4小时内未完成,物质化运行即失败,且该运行不会写入任何特征值。

回填不遵循这些步骤。 它会启动自己的输出表全量刷新,不会复用另一项更新。 参见 回填管道源特征。

重复使用的更新可能在启动该运行的那次提交之前读取了输入表。 该提交的行随后在下一次运行后出现在特征值中。 在同一条流水线上同时开始的运行不一定共享同一个更新,每个运行都可以连续运行自己的更新。

管道的输出表直到管道的第一次更新创建时才会存在,所以你可以在管道运行之前创建功能视图。 Feature Store 通过来源的 pipeline_state 跟踪此情况:

  • PENDING:流水线尚未运行,因此输出表不存在。 Feature Store 在流水线首次运行后验证该特征的列。
  • RESOLVED:输出表已存在,并且会根据该表验证特征的列。
  • ERROR:流水线运行或输出表验证失败。 先修复流水线或特征定义,然后再运行流水线。

特征存储在每次使用特征时都会解析其状态:当具体化运行时,以及调用 create_training_set、compute_features 或 refresh_sdp_source 时。

Requirements

  • 一个已经存在的触发Lakeflow管道。 不支持连续流水线。
  • 对该管道具有“可以运行”、“可以管理”或“是所有者”权限。 参见 管理流水线的标识、权限和特权。
  • 管道输出表存在后对其具有 SELECT 权限,同时具备创建和具体化特征所需的特征视图特权。
  • 输出表和任何输入表都必须是 Unity Catalog 表,并以三部分名称(catalog.schema.table)命名。
  • databricks-feature-engineering Python 软件包版本为 0.18.3 或更高。 其他要求请参见 要求。

从管道创建特征

要在管道的输出表上定义和具体化特征视图,请按照以下步骤操作。

查找管道ID

管道 ID 显示在 管道 UI 的流水线详细信息窗格中。

定义一个 SdpSource

指定管道和要读取的输出表。 使用 TableTrigger 时,还请在 input_tables 中列出流水线读取的表:

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import SdpSource

fe = FeatureEngineeringClient()

source = SdpSource(
    pipeline_id="1234abcd-5678-90ef-1234-567890abcdef",
    output_table="main.features.tutor_review_stats",
    input_tables=["main.raw.reviews", "main.raw.tutors"],
)

在源上创建特征视图

你可以在一个来源上创建多个特征视图。 以下示例为流水线计算的值创建 ColumnSelection 一个特征,以及特征存储在输出表上计算的聚合特征:

from datetime import timedelta
from databricks.feature_engineering.entities import (
    AggregationFunction,
    Avg,
    ColumnSelection,
    TumblingWindow,
)

avg_score_7d = fe.create_feature(
    source=source,
    entity=["tutor_id"],
    timeseries_column="window_end",
    function=ColumnSelection("avg_score_7d"),
    catalog_name="main",
    schema_name="features",
    name="tutor_avg_score_7d",
)

daily_review_count = fe.create_feature(
    source=source,
    entity=["tutor_id"],
    timeseries_column="window_end",
    function=AggregationFunction(
        Avg(input="review_count"),
        time_window=TumblingWindow(window_duration=timedelta(days=1)),
    ),
    catalog_name="main",
    schema_name="features",
    name="tutor_daily_review_count",
)

运行流水线

如果流水线还没运行,运行一次,这样输出表就会存在,特征即可解析。 refresh_sdp_source 为给定功能背后的每个流水线启动一次更新,等待更新完成,然后返回从流水线ID到更新ID的映射:

updates = fe.refresh_sdp_source(features=[avg_score_7d, daily_review_count], wait=True)

具体化特征

要将 ColumnSelection 特征实例化到在线存储中,请运行以下命令:

from databricks.feature_engineering.entities import OnlineStoreConfig, TableTrigger

fe.materialize_features(
    features=[avg_score_7d],
    online_config=OnlineStoreConfig(
        catalog_name="main",
        schema_name="features_online",
        table_name_prefix="tutor_",
        online_store_name="my_online_store",
    ),
    trigger=TableTrigger(),
)

在“目录资源管理器”中检查特征

该功能的 定义 部分显示流水线和输出表, 流水线状态 在流水线首次成功运行后显示 已解析 。 实体化特征部分展示了每次实体化运行的结果。 参见 探索 Unity Catalog 中的特征视图。

所有 SdpSource 参数请参见 SdpSource。

使用流水线源功能开发

训练、批量评分和 compute_features 不会运行管道。 要处理最新的流水线输出,请先使用 refresh_sdp_source 运行流水线:

fe.refresh_sdp_source(features=[avg_score_7d, daily_review_count], wait=True)

关于使用特征视图进行训练的更多信息,请参见 “使用流水线源特征训练”。

使用管道写入的特征表

如果 Lakeflow 管道已经写了 特征表,你可以在不更改流水线的情况下定义特征视图。 使用特征表作为 SdpSource 输出表,并为你想服务的每一列创建一个 ColumnSelection 特征。 ColumnSelection特征返回每个实体列的最新值,因此该特征不变地传递表的值。

将特征表映射到特征定义如下:

  • output_table特征表的三部分名称。 流水线必须写入这个表,因此对于由其他东西写入的特征表,应改为使用 DeltaTableSource。
  • entity:表主键中用于标识实体的列,例如 user_id。
  • timeseries_column:表中的一个时间戳列。 每个功能上 SdpSource 都要求一个,所以如果功能表没有时间戳列,就在流水线中添加一个。
  • input_tables:管道读取的表。 ColumnSelection 特征会基于表触发器进行具体化,因此需要它们。

以下示例提供由流水线写入的特征表的 country 列:

from databricks.feature_engineering.entities import ColumnSelection, SdpSource

source = SdpSource(
    pipeline_id="1234abcd-5678-90ef-1234-567890abcdef",
    output_table="main.features.user_profile",
    input_tables=["main.raw.users"],
)

user_country = fe.create_feature(
    source=source,
    function=ColumnSelection("country"),
    entity=["user_id"],
    timeseries_column="updated_at",
    catalog_name="main",
    schema_name="features",
    name="user_country",
)

要在线提供特征,请按照使用表触发器进行具体化中所述将其具体化。 特征存储会在每次具体化之前运行管道,因此在线值会遵循特征表。

使用表触发器进行物化

在 TableTrigger 特征上的 SdpSource 监视源的 input_tables,而不是输出表。 同一个输出表和触发器上的特征,你在一个 materialize_features 调用中实现的,共享一个作业,而该作业会监视所有这些特征的 input_tables。 对这些表的任何更新都会启动作业中每个功能的运行,并 TABLE_TRIGGER_CONDITION_ALL_UPDATED 等待所有这些表都更新完毕。 作业最多可监控25个表,只有在每个被监视表启用 文件事件 时才可监控超过10个。 参见 表格如何计入触发限制。 当输入表更新时,物化作业会运行该流水线,然后将特征物化。 ColumnSelection 特征在表触发时进行实体化,因此被 ColumnSelection 特征使用的 SdpSource 必须列出 input_tables。 聚合功能可以使用 CronSchedule 替代。

特征存储不会检查管道是否从 input_tables 的表中读取。 如果你漏掉了流水线读取的表,对该表的更新不会启动运行。

当流水线读取多个不同时间更新的表时,使用 TableTrigger 设置来控制运行开始的时间:

from datetime import timedelta
from databricks.feature_engineering.entities import TableTrigger, TableTriggerCondition

trigger = TableTrigger(
    condition=TableTriggerCondition.TABLE_TRIGGER_CONDITION_ALL_UPDATED,
    wait_after_last_change=timedelta(minutes=10),
    min_time_between_triggers=timedelta(hours=1),
)
  • condition:当任何输入表更新时开始运行(TABLE_TRIGGER_CONDITION_ANY_UPDATED,默认),或仅在所有输入表都已更新后(TABLE_TRIGGER_CONDITION_ALL_UPDATED)开始运行。
  • wait_after_last_change:等到输入表在此时长内没有更新,这样一系列更新就会在运行开始前完成。
  • min_time_between_triggers:‌启动运行的最高频率不超过此间隔‌。

关于允许的值,请参见 TableTrigger。

回填管道源特性

流水线更新会拾取流水线源中较晚到达的行,因此下一次实体化运行时会发布这些行,且不会进行回填。 当普通流水线更新无法纠正输出时,回填 SdpSource 特征,例如,当你更改流式表的逻辑、纠正源数据中的行,或需要恢复因超过水印而被丢弃的行时。 回填会完全刷新输出表,然后在你经过的时间范围内回填所需的特征。 参见 从管道源回填特征。

注册特征后更改流水线

在你注册了Feature Views后,不要更改流水线的输入或输出表。 特征存储会在创建特征时记录 input_tables,并且在管道发生变化后不会更新它们。 如果输出表被移除或其架构不再适合该特征,下一次具体化运行将失败。 训练数据也可能与之前物化的结果不一致。

要更改流水线的输入或输出,请创建一个包含这些更改的新流水线,并在该流水线上注册新的功能视图。

删除功能视图并不会删除其流水线。 如果你删除了流水线,其特征的 materialization 运行将失败。 从现有的流程中创建新特征。

Troubleshooting

CAN_RUN permission is required on the pipeline

管道不存在,或者你对管道不具备“可运行”、“可管理”和“为所有者”权限。 你需要此权限才能从流水线创建特征并将其特征物化。 检查错误中的管道 ID,或者请求管道所有者授予该权限。

Pipeline '<id>' is continuous

SdpSource 仅支持触发的管道。 将流水线切换到触发模式,或在流水线的输出表中使用 a DeltaTableSource 。

output_table '<name>' is not an output of pipeline '<id>'

输出表存在,但该流水线不会向其中写入数据。 把表名和错误中列出的输出对照。

在管道更新时,实体化运行失败

运行错误会提到管道更新。 在管道运行历史中打开更新,看看为什么失败。 如果更新在4小时后仍在运行,运行失败但更新会继续运行。

A table trigger starts an SDP-sourced feature's materialization when its input_tables update

特征使用一个 TableTrigger,或是 ColumnSelection 特征,但它们的 SdpSource 没有 input_tables。 使用 a CronSchedule 进行特征聚合,或用 input_tables重建特征。

Limitations

  • SdpSource 特征仅支持批处理。 不支持流式具体化。
  • 只支持触发的流水线。 对于连续管道或你自行调度的管道,请对输出表使用 DeltaTableSource。
  • CustomUDF 功能不支持 SdpSource。
  • input_tables 最多可列出25个表格,且无重复。 每个表格在创建功能时都必须存在。 TableTrigger 会监视作业中每个特征的 input_tables,总共最多可监视 25 个表。 要监视超过10个表,请在每个被监视的表上启用文件事件。 当表格数量超过触发者能监控时, materialize_features 会被拒绝。
  • TableTrigger 可以等待任意输入表,或所有输入表更新。 它不能等待特定的子集。
  • 回填会完全刷新整个输出表,即使你传入了一个时间范围。 时间范围仅适用于聚合特征。