Metadata-Version: 2.4
Name: wedata3-feature-engineering
Version: 0.2.4
Summary: Wedata Feature Engineering Library Development
Home-page: 
Author: meahqian
Author-email: 
License: Apache 2.0
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.0.0
Requires-Dist: feast[postgres,redis]==0.49.0
Requires-Dist: grpcio==1.74.0
Requires-Dist: tencentcloud-sdk-python
Requires-Dist: ipython
Provides-Extra: mlflow2
Requires-Dist: mlflow==2.17.2; extra == "mlflow2"
Provides-Extra: mlflow3
Requires-Dist: mlflow<3.11.0,>=3.10.0; extra == "mlflow3"
Provides-Extra: dev
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# wedata3-feature-engineering

WeData 3.0 特征工程与 Feature Store 客户端 SDK，封装 [Feast 0.49](https://docs.feast.dev/) 并对接 WeData 平台（Tclake、腾讯云 SDK、MLflow）。

> PyPI 包名：`wedata3-feature-engineering`
> Python 入口：`import wedata`

---

## 功能特性

- **Feature Store 客户端**：基于 Feast 的特征注册、查询、在线 / 离线特征获取（Redis / Postgres 后端）
- **特征工程客户端**：训练集构造、特征关联（feature lookup）、特征表管理
- **MLflow 集成**：以 `wedata.feature_store.mlflow_model` / `wedata.feature_engineering.mlflow_model` 形式将特征查询逻辑随模型一起持久化，预测时自动取在线特征
- **Spark 支持**：内置 Spark Client，离线特征通过 PySpark 处理
- **腾讯云生态**：通过 `tencentcloud-sdk-python` 与 Tclake、CAM 等平台能力集成

## 目录结构

```
feature-engineering/
├── README.md                       # 本文件
├── setup.py                        # 打包配置
├── build.sh                        # 本地构建 + 上传 PyPI 脚本
├── requirements.txt                # 运行依赖
├── test_valid.py                   # 冒烟测试入口
├── tests/                          # 单元测试
└── wedata/                         # 主包（顶层 import 名）
    ├── __init__.py                 # 暴露版本号
    ├── feature_store/              # Feature Store 客户端（与 MLflow 集成）
    │   ├── client.py
    │   ├── mlflow_model.py
    │   ├── feature_table_client/
    │   └── training_set_client/
    ├── feature_engineering/        # 特征工程客户端（封装 Feast）
    │   ├── client.py
    │   ├── mlflow_model.py
    │   ├── feast/
    │   ├── ml_training_client/
    │   └── table_client/
    └── common/                     # 公共能力
        ├── base_table_client/      # 表客户端基类
        ├── cloud_sdk_client/       # 腾讯云 SDK 封装
        ├── feast_client/           # Feast 适配
        ├── spark_client/           # Spark / PySpark 封装
        ├── entities/               # 领域实体
        ├── constants/              # 常量
        ├── protos/                 # protobuf 定义
        ├── log/                    # 日志
        └── utils/                  # 工具函数
```

## 环境要求

- **Python**：>= 3.10
- **PySpark**：3.5.0（与 `py4j==0.10.9.7` 配合）
- **Feast**：0.49.0（`extras=[redis,postgres]`）
- **MLflow**：根据使用场景二选一
  - `mlflow2` extra：`mlflow==2.17.2`（WeData 2.0）
  - `mlflow3` extra：`mlflow>=3.10.0,<3.11.0`（WeData 3.0）

## 安装

```bash
# 仅运行时，使用 MLflow 3.x（WeData 3.0 默认）
pip install "wedata3-feature-engineering[mlflow3]"

# WeData 2.0 场景
pip install "wedata3-feature-engineering[mlflow2]"

# 开发依赖（flake8 / pytest / python-dotenv）
pip install "wedata3-feature-engineering[dev]"
```

## 快速使用

```python
# 特征工程：构造训练集
from wedata.feature_engineering.client import FeatureEngineeringClient

fe_client = FeatureEngineeringClient()
training_set = fe_client.create_training_set(
    df=labels_df,
    feature_lookups=[...],
    label="label",
)

# Feature Store：在线特征查询
from wedata.feature_store.client import FeatureStoreClient

fs_client = FeatureStoreClient()
features = fs_client.get_online_features(
    feature_refs=["user_features:age", "user_features:city"],
    entity_rows=[{"user_id": "u_001"}],
)
```

## 构建与发布

```bash
# 本地打包并上传 PyPI（需要在 ~/.pypirc 配置好凭据）
bash build.sh
```

`build.sh` 会：

1. 清理旧的 `dist/` / `build/` / `*.egg-info/`
2. 读取 `wedata/__init__.py` 中的 `__version__`
3. 安装 `build` / `twine`
4. `python3 -m build` 生成 wheel + sdist
5. `twine upload` 推送到 PyPI 镜像

## 与本仓库其他子项目的关系

| 项目 | 关系 |
| --- | --- |
| [`../feast-server/`](../feast-server/) | 本 SDK 默认通过 Feast 的 `RemoteRegistry` 访问 `feast-server` 的 gRPC 接口，作为特征注册表 |
| [`../mlflow-server/`](../mlflow-server/) | `mlflow_model.py` 序列化的特征逻辑可被 MLflow Server 加载与下发 |
| [`../wedata-ml-runtime/`](../wedata-ml-runtime/) | Notebook Kernel 启动时会注入 Feast / MLflow 的网关代理与租户隔离逻辑，本 SDK 在其上层使用 |

## 许可证

Apache License 2.0
