Feast MongoDB Offline Store:基于单集合聚合管道的离线特征存储实战指南

原创2026-09-17 16:21:531,738 阅读
文章标签:MLOps后端数据工程

Feast MongoDB Offline Store:基于单集合聚合管道的离线特征存储实战指南

Feast 的 MongoDB Offline Store 是一个将 MongoDB 作为离线特征存储(Offline Store)的贡献型(contrib)实现,允许你直接基于 MongoDB 中的数据训练模型、运行批量打分(batch scoring),并在读取路径上采用 MongoDB 聚合管道与复合索引,将单实体查询成本控制在 O(log n) 量级。读完本文,你将掌握该离线存储的单集合数据模型、复合索引设计、feature_store.yaml 配置方式、pull_latest / get_historical_features 两条读取路径的实现原理(评分路径与服务端去重、训练路径与 merge_asof)、strict_pit 语义以及写入与内存行为,并了解其配套单元测试对关键行为的验证方式。

设计定位:单集合、共享 schema 的离线特征存储

该离线存储的完整实现位于 mongodb.py,模块文档对其设计做了三点概括:

  1. 单集合(single-collection)schema:所有 Feature View 共享同一个 MongoDB collection(默认名为 feature_history),通过文档中的 feature_view 字段区分彼此;
  2. 服务端去重(scoring path):当 entity_df 中实体 ID 唯一时,聚合管道追加 $group 阶段,每个 (entity_id, feature_view) 最多返回一条文档,传输量由 O(N×P×K) 降为 O(N×K)(N 为实体数,P 为每实体观测数,K 为 Feature View 数);
  3. 复合索引支撑整条管道:索引 (entity_id ASC, feature_view ASC, event_timestamp DESC, created_at DESC) 使单实体查询成本从 O(P) 降为 O(log P)。

数据模型:所有 Feature View 共享的 feature_history 集合

所有 Feature View 的观测数据写入同一个 collection(默认 feature_history),由 feature_view 字段做判别(discriminator)。README 给出了文档的 JSON 形态:

// Collection: feature_history
{
  "entity_id":       Binary("..."),           // Serialized entity key (bytes)
  "feature_view":    "driver_stats",          // Discriminator
  "features": {                               // Nested subdocument
    "trips_today":   5,
    "rating":        4.8
  },
  "event_timestamp": ISODate("2024-01-15T10:00:00Z"),
  "created_at":      ISODate("2024-01-15T10:00:01Z")
}

各字段的含义与实现对应关系如下:

字段 类型 说明 源码依据
entity_id Binary(bytes) 序列化后的实体键(entity key),由 Feast 的 serialize_entity_key 生成 mongodb.py 中 _serialize_entity_key_from_row 与 _ser
feature_view string 判别字段,即数据源 MongoDBSource 的 name MongoDBSource.feature_view_name 返回 self.name
features 嵌套子文档 特征名 → 特征值 的映射 offline_write_batch 逐列构造
event_timestamp ISODate 事件时间戳,Point-in-Time 连接的核心字段 默认 timestamp_field="event_timestamp"
created_at ISODate 写入时间戳,用于同事件时间下的冲突裁决(取最新) 默认 created_timestamp_column="created_at"

注意 entity_id 在 MongoDB 中是序列化后的字节串(不直接存可读的 join key 列),这正是读取时需要 _expand_entity_id_column 反序列化、把 join key 还原成独立列的原因。反序列化逻辑见 mongodb.py 的 _expand_entity_id_column,它调用 deserialize_entity_key 将字节展开为各 join key 列后再输出。

复合索引:一次懒创建支撑全部查询

存储层在首次使用时懒创建一个复合索引(源码中 _ensure_indexes 使用 create_index(..., name="entity_fv_ts_idx", background=True)),并通过模块级缓存 _indexes_ensured(集合 f"{conn_str}/{db}/{collection}" 去重)避免每次调用都重复建索引。索引定义如下:

db.feature_history.createIndex({
  "entity_id":       1,
  "feature_view":    1,
  "event_timestamp": -1,
  "created_at":      -1
})

从源码结构可以推断该索引的每一列都服务于具体管道阶段:

  • entity_id(升序)支撑 $match: {entity_id: {$in: [...]}} 的实体点查;
  • feature_view(升序)配合 $match 中的 feature_view 判别过滤;
  • event_timestamp(降序)支撑 $lte: max_ts 的时间窗口过滤以及 $sort 中的时间降序;
  • created_at(降序)支撑 $sort / $group $first 对同一事件时间下“最新写入”的选择。

配置:接入 feature_store.yaml

在 Feast 的 feature_store.yaml 中通过 offline_store 段启用该离线存储:

offline_store:
  type: feast.infra.offline_stores.contrib.mongodb_offline_store.mongodb.MongoDBOfflineStore
  connection_string: mongodb://localhost:27017
  database: feast
  collection: feature_history  # optional, default: feature_history

对应源码中的 MongoDBOfflineStoreConfig(FeastConfigBaseModel 子类),三个可配置项及默认值如下:

配置项 默认值 说明
type feast.infra.offline_stores.contrib.mongodb_offline_store.mongodb.MongoDBOfflineStore 离线存储实现类路径
connection_string mongodb://localhost:27017 MongoDB 连接 URI,支持带认证与多副本的 URI 形式
database feast MongoDB 数据库名
collection feature_history 所有 Feature View 共享的集合名

在 Feature View 定义中,batch source 需要使用 MongoDBSource,其 name 即文档判别字段:

from feast.infra.offline_stores.contrib.mongodb_offline_store.mongodb import MongoDBSource

driver_source = MongoDBSource(
    name="driver_stats",
    timestamp_field="event_timestamp",
    created_timestamp_column="created_at",
)

MongoDBSource 继承自 Feast 的 DataSource,source_type() 返回 CUSTOM_SOURCE,其 proto 序列化将 {"feature_view": self.name} 写入 custom_options.configuration(见 _to_proto_impl)。

读取路径一:pull_latest_from_table_or_query

pull_latest_from_table_or_query 返回时间窗口内每个实体最新一条观测,管道形如 $match → $sort → $group($first) → $project(见 mongodb.py):

  • $match:按 feature_view 判别 + event_timestamp 的 $gte/$lte 时间窗口;
  • $sort:entity_id 升序、event_timestamp 降序、created_at 降序——保证“最新写入”排最前;
  • $group:按 entity_id 分组取 $first,每个实体仅返回一条;
  • $project:展开 features 子文档的各特征列,并保留 event_timestamp(可选 created_at)。

与之配套的 pull_all_from_table_or_query 则只做 $match + $project,返回窗口内全部原始行、不去重,通常服务于离线特征物料(training data)的原始抽取。

读取路径二:get_historical_features 的评分路径与训练路径

get_historical_features 是训练/批量打分的主入口,源码根据 entity_df 的形态在两条路径间按 Feature View 逐条自动切换:

Scoring path(评分路径)——当 entity_df 中实体 ID 唯一,且(strict_pit=True 时)所有实体请求时间戳相同:

  • 管道为 $match + $sort + $group,在 MongoDB 服务端完成去重,每个 (entity_id, feature_view) 至多返回一条文档;
  • 复合索引使单实体成本为 O(log P),且避免了把每个实体的全部历史观测拉到 Python 侧;
  • Python 侧随后做一次向量化 left join,并施加 future_mask(严格 PIT 时把晚于请求时间的文档置 NULL)。

Training path(训练路径)——当 entity_df 存在重复实体 ID 且位于不同时间戳(典型的 PIT 训练数据形态):

  • 省略 $group 阶段,将候选文档与实体表按实体键分组后在 Python 中执行 pandas.merge_asof(direction="backward")做逐行 Point-in-Time 连接,该操作由 pandas 底层的 C 实现优化;
  • 为正确处理“同一事件时间、不同写入时间”的冲突,fv_df 会先按 ["event_timestamp", "created_at"] 排序,保证 merge_asof 命中 created_at 最新的文档(对应测试 test_training_path_created_at_tiebreaker)。

路径选择的核心判定代码位于 get_historical_features 的 _run_single 中:

unique_entities = result[eid_col].nunique() == len(result)
scoring_path = unique_entities and (
    not strict_pit or result[event_timestamp_col].nunique() == 1
)

即:实体键唯一 + 请求时间戳一致(或 strict_pit=False)时走服务端 $group;否则回退 merge_asof。这保证了不同 Feature View 可以混合使用不同路径(见测试 test_mixed_join_key_cardinality:user_id 维度的 FV 走 merge_asof,而 (user_id, device_id) 维度的 FV 仍可走评分路径)。

strict_pit 参数语义

get_historical_features 接受 strict_pit 关键字参数,默认 True:

  • strict_pit=True(默认,训练/评估安全):文档时间戳严格晚于实体请求时间戳的观测被返回为 NULL,避免“未来泄漏”(future leakage);
  • strict_pit=False:用于实时推理(real-time inference)场景,始终返回该实体最新的观测,即使其时间戳晚于名义请求时间。

对应的测试用例覆盖了三种场景(见测试文件 test_mongodb.py):test_scoring_path_nulls_future_doc 验证未来文档被置 NULL;test_scoring_path_nulls_future_doc_chunk_size_1 验证在分块(_CHUNK_SIZE=50_000 默认值)边界下行为一致;test_strict_pit_false_returns_future_doc 验证 strict_pit=False 时未来文档会被返回。源码在 $match 阶段用 ts_filter = {"$lte": max_ts} if strict_pit else {} 做服务端过滤,Python 侧再用 future_mask 兜底置空。

查询折叠(Query-collapse):从 K 次往返降为一次

README 强调的核心优化是 Query-collapse:共享相同 join key 集合(join key signature)的多个 Feature View,会被分组成一次 MongoDB 聚合往返,而不是每个 Feature View 一次。往返次数从 K(Feature View 数)降为“唯一 join key 签名数”——在常见场景下即为 1。

从源码看,get_historical_features 先构造 fv_by_proj(按投影名 name_to_use() 索引 Feature View)、fv_mongo_name(投影名 → MongoDB 判别值)、fv_mapped_join_keys(投影名 → 映射后的 join key)等映射表,再对每个投影逐一遍历执行管道;同一 join key 集合的 Feature Views 共享一次 $match {entity_id: {$in: batch_ids}} 的实体 ID 批量查询,每个批次的实体 ID 上限由 _MONGO_BATCH_SIZE = 10_000 控制。测试 test_k_collapse_multiple_feature_views 验证了 driver_stats_k 与 vehicle_stats_k 两个共享 driver_id 的 Feature View 在同一次检索中被正确解析。

此外,当 entity_df 行数超过 _CHUNK_SIZE = 50_000 时,数据会被分块处理(_chunk_dataframe),各块结果按原始行号 _row_idx 排序拼接,保证输出顺序与输入一致。

写入数据:offline_write_batch 与 feast materialize

写入侧使用 offline_write_batch,它由 feast materialize 自动调用。README 给出直接调用方式:

store.write_to_offline_store(feature_view_name, df)

写入语义为纯追加(append-only),不做 upsert;冲突在读取时裁决——pull_latest 与评分路径均通过 $sort created_at DESC → $group $first(或 merge_asof 前的 created_at 排序)选择 created_at 最高的文档。

从源码看 offline_write_batch 的处理流程:

  1. 使用原始(未映射)join key 名序列化实体键,确保与 get_historical_features 的序列化字节一致(源码注释明确说明该点,测试 test_offline_write_batch_round_trip 和 test_int32_entity_key 均验证了“写入字节 = 读取字节”);
  2. 时间戳列统一规范化为带 UTC 时区的 datetime;
  3. 特征值逐行提取:NaN 跳过、numpy 标量经 .item() 转为 Python 原生类型、非标量(list/dict)保留;
  4. created_at 缺省时取当前 UTC 时间;
  5. 按每批 10,000 条 insert_many(..., ordered=False) 写入,progress 回调在每批后上报行数。

文档判别值取自 feature_view.batch_source.feature_view_name,因此通过 push / write_to_offline_store 写入的数据与初始 ingest 落在同一集合分区。

内存行为:$match 先行,而非全量加载

README 明确指出存储的内存占用特性:存储按实体键在 $match 阶段过滤,而不是把整个集合加载到内存。因此内存占用上界为“唯一实体 ID 数 × 每实体文档数”,与集合总体积无关。这一特性对海量历史数据尤其重要——$match 配合复合索引在 MongoDB 服务端完成裁剪,Python 侧只接收与请求实体相关的候选文档。

结果持久化与类型推断

  • 结果落盘:MongoDBRetrievalJob.persist() 支持将检索结果写为 Parquet 文件,需配合 SavedDatasetFileStorage;目标文件已存在且未设置 allow_overwrite=True 时抛出 SavedDatasetLocationAlreadyExists(对应测试 test_persist_writes_parquet、test_persist_raises_if_file_exists、test_persist_allow_overwrite)。
  • 列类型推断:MongoDBSource.get_table_column_names_and_types 通过读取 feature_view 对应的一条样本文档来推断列名与类型——event_timestamp / created_at 映射为 datetime,features 子文档中的值按 Python 类型映射为 bool/int64/float64/string/list/dict/object。类型字符串到 Feast ValueType 的映射见 type_map.py 的 mongodb_to_feast_value_type(如 "int64"→INT64、"float64"→DOUBLE、"list[int]"→INT64_LIST,无法识别的类型映射为 UNKNOWN)。

测试验证与使用前提

该存储的单元测试位于 test_mongodb.py,使用 testcontainers.mongodb.MongoDbContainer(mongo:latest)起真实 MongoDB 实例,Docker 不可用时相关用例被 @_requires_docker 跳过。测试覆盖了本文涉及的几乎所有关键行为:pull_latest 每实体最新行、训练路径逐行 PIT 连接、created_at 平局裁决、评分路径服务端去重、pull_all 全量窗口、TTL 过期置 NULL、K-collapse 多 Feature View 合并、混合 join key 基数、异构时间戳回退训练路径、重叠特征名(full_feature_names=True 时的 fv__feature 列命名)、复合 join key、entity_df 额外标签列不污染实体键序列化、INT32 实体键字节一致性、persist 行为、offline_write_batch 写读往返以及 strict_pit 三态语义。

使用前请注意以下前提与限制(均以当前仓库源码为准):

  • 依赖 pymongo,未安装时会抛出 FeastExtrasDependencyImportError("pymongo", "mongodb");
  • get_historical_features 不支持 SQL 字符串形式的 entity_df,传入字符串会抛出 ValueError,请使用 pandas DataFrame;
  • entity_key_serialization_version 必须与写入侧一致,否则字节不匹配会导致查询结果为空(测试中统一使用 version 3);
  • TTL(Feature View 的 ttl)在读取侧执行:评分路径与训练路径都会把超过 TTL 的过期观测置 NULL(对应测试 test_ttl_excludes_stale_features);
  • 该离线存储位于 contrib(社区贡献)目录,属于自定义离线存储实现,可参考 adding-a-new-offline-store.md 了解 Feast 离线存储扩展点(OfflineStore 抽象类定义了 pull_latest_from_table_or_query、get_historical_features、offline_write_batch 等接口)。
登录后查看全文
feast