Feast 中的 Couchbase Columnar 数据源接入 Capella Columnar 集合的完整指南【免费下载链接】feastThe Open Source Feature Store for AI/ML项目地址: https://gitcode.com/GitHub_Trending/fe/feastCouchbase Columnar 数据源CouchbaseColumnarSource是 Feast 中一个由社区贡献contrib实现的批量数据源类型它允许将 Couchbase Capella Columnar 及其底层源码实现系统讲解该数据源的定义方式、全部配置参数、类型映射规则与底层工作原理并给出可直接复制运行的示例帮助你快速在 Feast 项目中接入 Couchbase Columnar。背景什么是 Couchbase Columnar 数据源Couchbase Columnar 数据源将Couchbase Capella Columnar中的集合作为特征数据的来源。Couchbase Columnar 是 Couchbase 提供的分析型列式存储能力通过 Couchbase Capella 云平台提供支持使用 SQL 查询语言进行数据访问。在 Feast 中这类数据源属于批量数据源batch source的一种可用于为FeatureView提供底层特征数据通过get_historical_features执行历史特征检索point-in-time correct join通过pull_latest_from_table_or_query拉取每个实体键的最新特征值通过pull_all_from_table_or_query拉取时间范围内的全部特征行。注意事项与稳定性说明原文档明确指出该集成由社区贡献维护未达到完整的测试覆盖率不能假定其完全稳定。这一点在源码中也有印证CouchbaseColumnarOfflineStore的所有检索方法如pull_latest_from_table_or_query、get_historical_features、pull_all_from_table_or_query在调用时都会发出RuntimeWarning提示该离线存储仍处于 alpha 开发阶段的实验性功能部分功能可能不稳定未来可能发生变化。因此将其用于生产环境前建议先在测试环境中充分验证。安装与前置准备要使用 Couchbase Columnar 数据源需要安装带有couchbase扩展的 Feast Python SDKpip install feast[couchbase]随后可以通过feast init -t couchbase快速生成一个基于 Couchbase 模板的特征仓库。仓库中提供了对应的模板定义文件 feature_definitions.py可供参考。接入 Couchbase Capella Columnar 本身需要完成以下准备工作注册 Couchbase Capella 账号部署一个 Columnar 集群创建访问控制账户Access Control Account该账户应具备读写权限测试场景下建议为其分配全部角色以避免权限问题配置允许的 IP 地址必须放行运行 Feast 的机器所在 IP否则无法建立连接。从测试源码 data_source.py 可以看出运行时依赖以下三个环境变量来建立连接COUCHBASE_COLUMNAR_CONNECTION_STRING连接串以couchbases://开头COUCHBASE_COLUMNAR_USER访问控制账户用户名COUCHBASE_COLUMNAR_PASSWORD访问控制账户密码。定义 Couchbase Columnar 数据源原文档给出了一个最小可用的定义示例这也是仓库模板 feature_definitions.py 中实际使用的写法from feast.infra.offline_stores.contrib.couchbase_offline_store.couchbase_source import ( CouchbaseColumnarSource, ) driver_stats_source CouchbaseColumnarSource( namedriver_hourly_stats_source, querySELECT * FROM Default.Default.feast_driver_hourly_stats, databaseDefault, scopeDefault, collectionfeast_driver_hourly_stats, timestamp_fieldevent_timestamp, created_timestamp_columncreated, )该数据源随后可以像其他批量数据源一样被FeatureView引用from feast import Entity, FeatureView, Field from feast.types import Float32, Int64 from datetime import timedelta driver Entity(namedriver, join_keys[driver_id]) driver_stats_fv FeatureView( namedriver_hourly_stats, entities[driver], ttltimedelta(days1), schema[ Field(nameconv_rate, dtypeFloat32), Field(nameacc_rate, dtypeFloat32), Field(nameavg_daily_trips, dtypeInt64), ], onlineTrue, sourcedriver_stats_source, tags{team: driver_performance}, )关键参数详解CouchbaseColumnarSource的完整签名定义在源码 couchbase_source.py 中以下参数均有实际代码实现支撑参数类型默认值说明nameOptional[str]None数据源名称在一个 project 内应保持唯一。若未指定且collection也缺失会抛出DataSourceNoNameExceptionname缺省时自动回退使用collection作为名称queryOptional[str]None用于取数的 SQL 查询语句databaseOptional[str]DefaultColumnar 数据库名scopeOptional[str]DefaultColumnar scope 名collectionOptional[str]NoneColumnar 集合名timestamp_fieldOptional[str]事件时间戳字段用于特征值的时间点正确性连接point-in-time joinscreated_timestamp_columnOptional[str]记录行创建时间的字段用于行去重同一事件时间有多条记录时取最新创建的一条field_mappingOptional[Dict[str, str]]None字段名到特征名的映射字典仅作用于特征字段不影响实体字段和时间戳字段descriptionOptional[str]数据源的人类可读描述tagsOptional[Dict[str, str]]None任意键值对元数据ownerOptional[str]数据源负责人通常是维护者邮箱connection_refOptional[ConnectionRef]None连接引用用于凭证管理场景表与查询两种取值方式的取舍query与database/scope/collection是互斥互补的两种取数方式其选择逻辑实现在get_table_query_string()方法中couchbase_source.py当database、scope、collection三者都提供了则直接生成三点式限定名database.scope.collection此时query参数不生效否则回退为使用query中给出的完整 SQL 查询语句作为子查询包裹在括号中使用。原文档示例中同时给出了query与三个位置参数此时实际生效的是集合三点式路径。在测试源码 data_source.py 中可以看到测试创建数据源时同样会同时传入query如SELECT VALUE v FROM Default.Default.\collection v和database/scope/collection 三个参数两者保持语义一致。底层实现Feast 如何理解 Couchbase 集合数据源的序列化与注册CouchbaseColumnarSource继承自 Feast 的DataSource基类。由于它尚未在DataSourceProto.SourceType枚举中拥有独立类型源码中留有 TODO 注释其source_type()返回的是CUSTOM_SOURCE即自定义数据源类型见 couchbase_source.py。在序列化到 protobuf 时_to_proto_impl它将记录数据源类的完整路径feast.infra.offline_stores.contrib.couchbase_offline_store.couchbase_source.CouchbaseColumnarSource以便反序列化时定位类通过CouchbaseColumnarOptions.to_proto()将name、query、database、scope、collection五个字段以 JSON 字符串形式写入custom_options.configuration保留timestamp_field、created_timestamp_column、field_mapping、description、tags、owner等通用字段。对应的from_proto静态方法负责从 protobuf 还原数据源对象并从tags中恢复ConnectionRef。__eq__与__hash__的实现保证了数据源在注册/比较时的语义正确性。模式推断自动识别集合字段与类型在feast apply注册特征视图时Feast 需要知道数据源有哪些列、各列什么类型。CouchbaseColumnarSource.get_table_column_names_and_types()couchbase_source.py实现了这一能力其核心流程是使用config.offline_store中的user与password构造Credential并以connection_string创建 ColumnarCluster实例连接、分发超时固定为 120 秒查询超时取自offline_store.timeout构造一条 SQL 查询利用 Couchbase 内置函数get_object_fields与OBJECT_PAIRS提取集合首条记录的所有字段名与字段类型对结果逐字段处理跳过uuid类型的字段注释说明是为了保证 schema 与 dataframe 一致并对复合类型调用_infer_composite_type做类型收敛。_infer_composite_type对复合类型的处理非常严格array仅允许原始类型的一维数组数组元素为object、或嵌套的array/multiset都会抛出ValueErrorobject直接抛出ValueError提示Feast 不支持复杂对象类型multiset同样拒绝。换言之Feast 只接受原始类型与同质一维原始数组其他嵌套结构在 schema 推断阶段就会被明确拒绝。支持的数据类型Couchbase Capella Columnar 数据源支持BOOLEAN、STRING、BIGINT、DOUBLE四种原始类型。在 type_map.py 中cb_columnar_type_to_feast_value_type()定义了从 Couchbase 类型字符串到 FeastValueType的完整映射Couchbase Columnar 类型Feast ValueTypebooleanBOOLstringSTRINGbigintINT64doubleDOUBLEnullNULLmissingUNKNOWNobjectUNKNOWN源码注释暂不支持原始类型数组待办事项arrayUNKNOWNmultisetUNKNOWNuuidUUID该映射函数通过CouchbaseColumnarSource.source_datatype_to_feast_value_type()暴露给 Feast 类型系统使用。与 Couchbase 离线存储的配合CouchbaseColumnarSource需要与CouchbaseColumnarOfflineStore类型标识为couchbase.offline配套使用。离线存储的配置类CouchbaseColumnarOfflineStoreConfig定义在 couchbase.py 中完整的feature_store.yaml配置如下来自 offline-stores/couchbase.mdproject: my_project registry: data/registry.db provider: local offline_store: type: couchbase.offline connection_string: COUCHBASE_COLUMNAR_CONNECTION_STRING # 在 Capella Columnar 控制台的 Settings Connection String 页面复制以 couchbases:// 开头 user: COUCHBASE_COLUMNAR_USER # Couchbase 集群访问账户名来自 Settings Access Control 页面 password: COUCHBASE_COLUMNAR_PASSWORD # Couchbase 密码来自 Settings Access Control 页面 timeout: 120 # Columnar 操作超时秒可选参数 online_store: path: data/online_store.db其中timeout为可选参数默认值为 120 秒所有 Columnar 查询操作_execute_query都会将其作为QueryOptions.timeout传入。底层取数逻辑CouchbaseColumnarOfflineStore实现了 FeastOfflineStore接口的三个核心方法均以 SQL 查询的形式作用于数据源pull_latest_from_table_or_query构造带ROW_NUMBER() OVER (PARTITION BY join keys ORDER BY timestamp DESC)的分析查询为每个实体键取出事件时间及创建时间最新的那一行即最新特征值语义pull_all_from_table_or_query在指定时间范围内取出全部数据行使用get_timestamp_filter_sql生成时间过滤条件get_historical_features先将实体表Pandas DataFrame 会先上传为 Columnar 集合SQL 字符串则直接作为子查询落地再执行build_point_in_time_query生成的多特征视图时间点连接 SQL最终结果通过CouchbaseColumnarRetrievalJob返回。CouchbaseColumnarRetrievalJob支持将查询结果导出为 pandas DataFrame内部先转 PyArrow 再to_pandas()和 PyArrow Table并对时间戳字段做时区感知处理pd.to_datetime(value, utcTrue)对None值统一填充为np.nan。功能矩阵根据 offline-stores/couchbase.md 的功能矩阵当前实现支持能力如下离线存储层功能Couchbase Columnarget_historical_features时间点正确性连接✅ 支持pull_latest_from_table_or_query拉取最新特征值✅ 支持pull_all_from_table_or_query拉取已保存数据集✅ 支持offline_write_batch向离线存储批量写回❌ 不支持write_logged_features持久化日志特征❌ 不支持CouchbaseColumnarRetrievalJob层功能Couchbase Columnar导出为 dataframe✅ 支持导出为 arrow table✅ 支持导出为 arrow batches❌ 不支持导出为 SQL✅ 支持导出到数据湖S3、GCS 等✅ 支持导出到数据仓库✅ 支持导出为 Spark dataframe❌ 不支持Python 本地 on-demand 转换✅ 支持Python 远程 on-demand 转换❌ 不支持结果持久化到离线存储✅ 支持执行前预览查询计划✅ 支持读取分区数据✅ 支持从源码看结果持久化到离线存储由CouchbaseColumnarRetrievalJob.persist()实现它会将结果 DataFrame 通过df_to_columnar以CREATE COLLECTION ... IF NOT EXISTS PRIMARY KEY(pk: UUID) AUTOGENERATED加INSERT INTO的方式写入 Columnar 集合存储介质即SavedDatasetCouchbaseColumnarStorage。关于各离线存储的横向对比可参考 数据源功能矩阵 与 离线存储概述。实战演练从模板初始化到历史特征检索第一步初始化特征仓库feast init -t couchbase my_couchbase_project cd my_couchbase_project生成后的 feature_definitions.py 除数据源定义外还包含实体、特征视图、请求数据源、on-demand 特征视图、特征服务与推送数据源PushSource的完整示例其中PushSource以 CouchbaseColumnarSource 作为其batch_source支持先批量、后推送的混合特征供给模式。第二步配置连接信息并注册编辑feature_store.yaml填入couchbase.offline类型与三个连接参数connection_string、user、password然后执行feast applyfeast apply期间会调用get_table_column_names_and_types()自动推断集合 schema并将数据源序列化后写入 registry。第三步构建训练数据集from feast import FeatureStore store FeatureStore(repo_path.) training_df store.get_historical_features( entity_dfentity_df, # 可以是 pandas DataFrame也可以是 SQL 查询字符串 features[ driver_hourly_stats:conv_rate, driver_hourly_stats:acc_rate, driver_hourly_stats:avg_daily_trips, ], ).to_df()需要说明的是实体表支持两种形式Pandas DataFrame 会被上传为 Columnar 集合后参与连接SQL 查询字符串则会直接作为子查询参与。两种形式的实体时间戳范围都会在执行前通过_get_entity_df_event_timestamp_range计算作为时间点连接的时间窗约束。总结CouchbaseColumnarSource让 Feast 用户能够直接以 Couchbase Capella Columnar 集合作为特征数据的批量来源完整支持历史特征检索、最新值拉取与数据集持久化等核心离线能力。通过本文可以掌握数据源的定义方式与全部参数语义、表路径与 SQL 查询两种取数方式的取舍、feast apply阶段的 schema 自动推断规则、受支持的类型边界四种原始类型拒绝嵌套复杂对象以及配套离线存储的配置方法与功能边界。需要再次强调该集成仍处于 alpha 实验阶段测试覆盖不完整接入前务必结合 源码实现 与官方文档充分评估并在非生产环境先行验证。【免费下载链接】feastThe Open Source Feature Store for AI/ML项目地址: https://gitcode.com/GitHub_Trending/fe/feast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
