Panda_quantflow源码分析之Panda Plugins模块参考手册

大道至简大道至简··412 浏览

Panda Plugins 模块参考手册

本此文档详细描述了 src/panda_plugins 下的所有内置节点。文档由工具自动生成,确保与代码实现保持同步。

1. 目录结构概览

src/panda_plugins/
├── base/                   # 插件系统基础框架 (BaseWorkNode, 注册机制)
├── internal/               # 内置节点库 (官方提供)
│   ├── models/             # 节点间数据交互模型 (Pydantic Models)
│   ├── ...                 # 各类功能节点 (CSV, ML, Factor, Backtest)
├── utils/                  # 插件加载与辅助工具 (Loader, ErrorCode)
└── custom/                 # 用户自定义节点目录 (示例与扩展)

2. 基础框架 (Base Framework)

src/panda_plugins/base 定义了节点开发的基类和核心装饰器。

BaseWorkNode

所有节点的基类。

  • run(self, input): 核心执行逻辑。
  • input_model(cls): 定义输入数据结构。
  • output_model(cls): 定义输出数据结构。

核心装饰器

  • @work_node(name, group, type): 注册节点。
  • @ui(...): 定义 UI 控件元数据。

3. 内置节点库 (Internal Nodes)

以下章节按照节点分组 (Group) 排列。

01-基础工具

Python代码输入

  • 文件: code_node.py
  • 类名: CodeControl

输入参数 (Input):

参数名 类型 描述 默认值
code str 策略代码 ''

输出数据 (Output):

参数名 类型 描述
code str 策略代码

02-特征工程

特征工程构建

  • 文件: feature_engineering_build_node.py
  • 类名: FeatureEngineeringBuildNode

输入参数 (Input):

输出数据 (Output):


特征工程构建(旧)

  • 文件: feature_engineering_node.py
  • 类名: FeatureEngineeringNode

输入参数 (Input):

参数名 类型 描述 默认值
formulas str 特征公式 ''
label str 标签公式 ''

输出数据 (Output):

参数名 类型 描述
feature_model FeatureModel 特征工程

公式输入

  • 文件: formula_node.py
  • 类名: FormulaControl

输入参数 (Input):

参数名 类型 描述 默认值
formulas str 公式 ''

输出数据 (Output):

参数名 类型 描述
formulas str 公式

03-机器学习

LightGBM模型

  • 文件: lightgbm_node.py
  • 类名: LightGBMControl

输入参数 (Input):

参数名 类型 描述 默认值
feature FeatureModel 特征工程 ''
start_date str 训练开始时间 '20250101'
end_date str 训练结束时间 '20250301'
n_estimators int 决策树数量 100
max_depth int 最大深度 3
learning_rate float 学习率 0.1
num_leaves int 叶子节点数量 31
subsample float 子样本比例 0.8
colsample_bytree float 列采样比例 0.8
reg_alpha float L1正则化 0
reg_lambda float L2正则化 1

输出数据 (Output):


GRU模型

  • 文件: ml_gru_node.py
  • 类名: GRUControl

输入参数 (Input):

参数名 类型 描述 默认值
factor pd.DataFrame 特征值
time_step int 时间步长 10
units int LSTM单元数 50
batch_size int 批大小 32
epochs int 训练轮数 10
dropout_rate float Dropout比例 0.2
learning_rate float 学习率 0.001

输出数据 (Output):


LSTM模型

  • 文件: ml_lstm_node.py
  • 类名: LSTMControl

输入参数 (Input):

参数名 类型 描述 默认值
factor pd.DataFrame 特征值
time_step int 时间步长 10
units int LSTM单元数 50
batch_size int 批大小 32
epochs int 训练轮数 10
dropout_rate float Dropout比例 0.2
learning_rate float 学习率 0.001

输出数据 (Output):


Xgboost模型

  • 文件: ml_xgboost_node.py
  • 类名: MLXgboostControl

输入参数 (Input):

参数名 类型 描述 默认值
factor pd.DataFrame 特征值
n_estimators int 决策树数量 100
max_depth int 最大深度 3
learning_rate float 学习率 0.1
min_child_weight int 最小子权重 1
gamma float Gamma 0
subsample float 子样本比例 1
colsample_bytree float 列采样比例 1
reg_alpha int L1正则化 0
reg_lambda int L2正则化 1

输出数据 (Output):


多任务神经网络

  • 文件: mtl_nn_node.py
  • 类名: MTLNNControl

输入参数 (Input):

参数名 类型 描述 默认值
feature1 `FeatureModel None` 特征工程1
feature2 `FeatureModel None` 特征工程2
feature3 `FeatureModel None` 特征工程3
feature4 `FeatureModel None` 特征工程4
feature5 `FeatureModel None` 特征工程5
start_date str 训练开始时间 '20250101'
end_date str 训练结束时间 '20250301'
epochs int 训练轮数 100
hidden_dim int 隐藏层维度 64
lr float 学习率 0.001

输出数据 (Output):


随机森林模型

  • 文件: randomforest_node.py
  • 类名: RandomForestControl

输入参数 (Input):

参数名 类型 描述 默认值
feature FeatureModel 特征工程 ''
start_date str 训练开始时间 '20250101'
end_date str 训练结束时间 '20250301'
n_estimators int 决策树数量 100
max_depth int 最大深度 None
min_samples_split int 最小分裂样本数 2
min_samples_leaf int 叶节点最小样本数 1
max_features str 最大特征数 'sqrt'
bootstrap bool 自助采样 True
oob_score bool OOB评分 False
random_state int 随机种子 42
n_jobs int 并行任务数 -1

输出数据 (Output):


SVM模型

  • 文件: svm_node.py
  • 类名: SVMControl

输入参数 (Input):

参数名 类型 描述 默认值
feature FeatureModel 特征工程 ''
start_date str 训练开始时间 '20250101'
end_date str 训练结束时间 '20250301'
kernel str 核函数类型 'rbf'
degree int 多项式核函数次数 3
gamma str 核函数系数 'scale'
coef0 float 核函数独立项 0.0
C float 正则化参数 1.0
epsilon float SVR模型中的Epsilon值 0.1
shrinking bool 是否使用收缩启发式 True
cache_size int 核缓存大小(MB) 200
max_iter int 最大迭代次数 1000
tol float 停止准则容差 0.001

输出数据 (Output):


Xgboost模型(旧)

  • 文件: xgboost_node.py
  • 类名: XgboostControl

输入参数 (Input):

参数名 类型 描述 默认值
feature FeatureModel 特征工程 ''
start_date str 训练开始时间 '20250101'
end_date str 训练结束时间 '20250301'
n_estimators int 决策树数量 100
max_depth int 最大深度 3
learning_rate float 学习率 0.1
min_child_weight int 最小子权重 1
gamma float Gamma 0
subsample float 子样本比例 1
colsample_bytree float 列采样比例 1
reg_alpha float L1正则化 0
reg_lambda float L2正则化 1

输出数据 (Output):


04-因子相关

因子分析结果

  • 文件: factor_analysis_chart_node.py
  • 类名: FactorAnalysisChartControl

输入参数 (Input):

参数名 类型 描述 默认值
task_id str 分析结果 'error'

输出数据 (Output):

参数名 类型 描述
task_id str 图表绘制

因子分析

  • 文件: factor_analysis_node.py
  • 类名: FactorAnalysisControl

输入参数 (Input):

参数名 类型 描述 默认值
df_factor object 因子值
adjustment_cycle str 调仓周期 '1'
group_number str 分组数量 '5'
factor_direction str 因子方向(0:正向,1:负向) '0'

输出数据 (Output):

参数名 类型 描述
task_id str 分析结果

因子构建节点

  • 文件: factor_build_node.py
  • 类名: FactorBuildControl

输入参数 (Input):

参数名 类型 描述 默认值
start_date str 因子开始时间 '20250101'
end_date str 因子结束时间 '20250301'
formulas str 因子公式 ''

输出数据 (Output):

参数名 类型 描述
factor DataFrame

综合因子构建节点

  • 文件: factor_build_node_pro.py
  • 类名: FactorBuildProControl

输入参数 (Input):

参数名 类型 描述 默认值
start_date str 开始时间 '20250101'
end_date str 结束时间 '20250301'
code str 因子代码 ''
market str 因子类型 '股票'
type str 编码方式 'Python'
direction str 因子方向 '正向'

输出数据 (Output):

参数名 类型 描述
factor DataFrame 因子值

因子相关性分析

  • 文件: factor_correlation_calculation_node.py
  • 类名: FactorCorrelationCalculationControl

输入参数 (Input):

参数名 类型 描述 默认值
factor `object None` 因子组

输出数据 (Output):

参数名 类型 描述
task_id str 分析结果

因子相关性分析结果

  • 文件: factor_correlation_chart_node.py
  • 类名: FactorCorrelationChartControl

输入参数 (Input):

参数名 类型 描述 默认值
task_id str 分析结果 'error'

输出数据 (Output):

参数名 类型 描述
task_id str 图表绘制

因子集合器

  • 文件: factor_to_group_node.py
  • 类名: FactorToGroupControl

输入参数 (Input):

参数名 类型 描述 默认值
factor1 `object None` 因子/因子组1
factor2 `object None` 因子/因子组2
factor3 `object None` 因子/因子组3
factor4 `object None` 因子/因子组4
factor5 `object None` 因子/因子组5

输出数据 (Output):

参数名 类型 描述
merged_factors object 因子组

因子权重调整(归一化)

  • 文件: factor_weight_adjust_node.py
  • 类名: FactorWeightAdjustControl

输入参数 (Input):

参数名 类型 描述 默认值
df_factor object 因子值
weight float 权重 1.0

输出数据 (Output):

参数名 类型 描述
df_factor object 因子值

因子构建(机器学习)

  • 文件: ml_factor_build_node.py
  • 类名: MLFactorBuildControl

输入参数 (Input):

参数名 类型 描述 默认值
model MLModel 机器学习模型
feature FeatureModel 特征工程
start_date str 开始时间 '20250101'
end_date str 结束时间 '20250301'

输出数据 (Output):

参数名 类型 描述
factor Any 因子值

多因子合并(5-1)

  • 文件: multi_factor_merge_node.py
  • 类名: MultiFactorMergeControl

输入参数 (Input):

参数名 类型 描述 默认值
factor1 `object None` 因子1
factor2 `object None` 因子2
factor3 `object None` 因子3
factor4 `object None` 因子4
factor5 `object None` 因子5

输出数据 (Output):

参数名 类型 描述
merged_factors object 因子值

05-回测相关

期货回测

  • 文件: backtest_future_node.py
  • 类名: FutureBacktestControl

输入参数 (Input):

参数名 类型 描述 默认值
code str 策略代码 ''
factors pd.DataFrame 因子值
start_future_capital int 初始资金 10000000
commission_rate int 佣金倍率 1
margin_rate int 保证金倍率 1
frequency str 回测频率 '1d'
start_date str 开始日期 '20241022'
end_date str 结束日期 '20241231'

输出数据 (Output):

参数名 类型 描述
backtest_id str 回测任务

策略回测结果

  • 文件: backtest_result_node.py
  • 类名: BackTestResultControl

输入参数 (Input):

参数名 类型 描述 默认值
task_id str 回测任务 'error'

输出数据 (Output):

参数名 类型 描述
task_id str 图表绘制

股票回测

  • 文件: backtest_stock_node.py
  • 类名: StockBacktestControl

输入参数 (Input):

参数名 类型 描述 默认值
code str 策略代码 ''
factors pd.DataFrame 因子值
start_capital int 初始资金 10000000
standard_symbol str 基准指数 '上证指数'
commission_rate int 佣金率 1
frequency str 回测频率 '1d'
start_date str 回测开始时间 '20241001'
end_date str 回测结束时间 '20241231'

输出数据 (Output):

参数名 类型 描述
backtest_id str 回测id

06-线下课专属

因子IC计算

  • 文件: factor_ic_calculation_node.py
  • 类名: FactorICCalculationControl

输入参数 (Input):

参数名 类型 描述 默认值
df_factor object 因子值
adjustment_cycle str 调仓周期 '1'
group_number str 分组数量 '5'
factor_direction str 因子方向(0:正向,1:负向) '0'

输出数据 (Output):

参数名 类型 描述
ic_value str 因子权重列表

因子权重组合

  • 文件: factor_weight_calculation_node.py
  • 类名: FactorWeightCalculationControl

输入参数 (Input):

参数名 类型 描述 默认值
df_factor object 因子值
factor_weight str 因子权重列表 'error'

输出数据 (Output):

参数名 类型 描述
df_factor object 因子值

多因子构建(机器学习)

  • 文件: ml_multi_factor_build_node.py
  • 类名: MLMultiFactorBuildControl

输入参数 (Input):

参数名 类型 描述 默认值
model1 MLModel 机器学习模型1
features1 FeatureModel 特征工程1
model2 `MLModel None` 机器学习模型2
features2 `FeatureModel None` 特征工程2
model3 `MLModel None` 机器学习模型3
features3 `FeatureModel None` 特征工程3
model4 `MLModel None` 机器学习模型4
features4 `FeatureModel None` 特征工程4
model5 `MLModel None` 机器学习模型5
features5 `FeatureModel None` 特征工程5
start_date str 因子回测开始时间 '20250101'
end_date str 因子回测结束时间 '20250301'

输出数据 (Output):

参数名 类型 描述
factor Any

因子构建(机器学习-单模型多特征)

  • 文件: mtl_factor_build_node.py
  • 类名: MTLFactorBuildControl

输入参数 (Input):

参数名 类型 描述 默认值
model MLModel 机器学习模型
feature1 `FeatureModel None` 特征工程1
feature2 `FeatureModel None` 特征工程2
feature3 `FeatureModel None` 特征工程3
feature4 `FeatureModel None` 特征工程4
feature5 `FeatureModel None` 特征工程5
start_date str 因子回测开始时间 '20250101'
end_date str 因子回测结束时间 '20250301'

输出数据 (Output):

参数名 类型 描述
factor Any

PCA因子构建

  • 文件: pca_factor_build_node.py
  • 类名: PCAFactorBuildControl

输入参数 (Input):

参数名 类型 描述 默认值
model MLModel 机器学习模型
feature FeatureModel 特征工程
test_start_date str 因子回测开始时间 '20250101'
test_end_date str 因子回测结束时间 '20250301'
predict_start_date str 因子预测开始时间 '20250301'
predict_end_date str 因子预测结束时间 '20250501'

输出数据 (Output):

参数名 类型 描述
factor Any 复合因子得分
weights list 因子权重

Spearman因子构建

  • 文件: spearman_factor_build_node.py
  • 类名: SpearmanFactorBuildControl

输入参数 (Input):

参数名 类型 描述 默认值
model MLModel 机器学习模型
feature FeatureModel 特征工程
start_date str 因子回测开始时间 '20250101'
end_date str 因子回测结束时间 '20250301'

输出数据 (Output):

参数名 类型 描述
factor Any

4. 案例演示 (Example Scenarios)

本节展示代码如何在节点间流转并最终被执行。

核心概念:代码即数据

在 Panda Quantflow 中,CodeControl (Python代码输入) 节点本身不执行代码。它的作用是提供一个编辑器让用户输入代码,并将这段代码封装为字符串数据传递给下游节点。真正的执行发生在下游节点(如回测节点、特征构建节点)中

示例:如何运行自定义回测策略

假设你希望运行一段 Python 策略代码。你需要将 CodeControl 节点与 StockBacktestControl 节点连接。

1. 工作流配置

  1. 节点 A: CodeControl (Python代码输入)
    • 在 UI 编辑器中输入策略逻辑(例如 initializehandle_data 函数)。
  2. 节点 B: StockBacktestControl (股票回测)
    • 节点 A 的输出连接到 节点 Bcode 输入端口。

2. 代码流转模拟脚本

以下脚本模拟了上述两个节点在后台的交互过程:

import pandas as pd
from panda_plugins.internal.code_node import CodeControl, CodeInputModel
from panda_plugins.internal.backtest_stock_node import StockBacktestControl, StockBacktestInputModel

# 1. 用户在 CodeControl 节点中输入的策略代码
user_strategy_code = """
def initialize(context):
    g.security = '600519.SH'
    print("策略初始化完成")

def handle_data(context, data):
    # 简单的买入逻辑
    if context.portfolio.positions[g.security].amount == 0:
        order(g.security, 100)
        print(f"买入 {g.security}")
"""

# 2. 运行 CodeControl 节点
# 该节点仅负责封装和传递代码字符串
code_node = CodeControl()
code_input = CodeInputModel(code=user_strategy_code)
code_output = code_node.run(code_input)
print(f"CodeControl 输出类型: {type(code_output)}")
print(f"传递的代码长度: {len(code_output.code)}")

# 3. 运行 StockBacktestControl 节点
# 该节点接收代码字符串,并调用回测引擎执行
backtest_node = StockBacktestControl()

# 注意:这里将上一个节点的输出 (code_output.code) 作为输入
backtest_input = StockBacktestInputModel(
    code=code_output.code,          # <--- 核心:代码在此处传入
    factors=pd.DataFrame(),         # 实际使用时需传入因子数据
    start_capital=1000000,
    start_date="20240101",
    end_date="20240201"
)

# 触发回测 (模拟执行)
# backtest_node.run(backtest_input) 
# print("回测节点已接收代码并开始执行...")

3. 执行原理

  • CodeControl.run(): return CodeOutputModel(code=input.code)。单纯的数据透传。
  • StockBacktestControl.run(): 接收 input.code,内部调用 panda_backtest.start(code=input.code, ...)。此时代码才被解释器执行。

5. 用户自建节点 (Custom Nodes)

Panda Plugins 提供了强大的扩展能力,允许用户在 src/panda_plugins/custom 目录下创建自定义节点。系统会自动扫描并加载该目录下的所有节点,使其即刻在工作流编辑器中可用。

5.1 目录规范与加载机制

系统默认加载 src/panda_plugins/custom 目录下的所有 Python 文件。
推荐的目录结构如下:

src/panda_plugins/custom/
├── __init__.py
├── my_feature_nodes.py          # 您的特征处理节点
├── my_analysis_nodes.py         # 您的分析工具节点
└── examples/                    # (可选) 参考案例
    ├── example_basic.py
    └── example_advanced_input_control.py

5.2 开发流程

创建一个自定义节点仅需简单的 4 步:

  1. 定义输入模型 (InputModel): 使用 pydantic.BaseModel 定义节点接收的参数。
  2. 定义输出模型 (OutputModel): 定义节点返回的数据结构。
  3. 配置 UI (Optional): 使用 @ui 装饰器自定义输入参数在前端的控件类型(如文件选择器、下拉框等)。
  4. 实现核心逻辑: 继承 BaseWorkNode 并重写 run 方法。

5.3 进阶案例:模型上传节点 (Model Upload)

本案例展示如何开发一个带有文件上传功能的节点。该节点允许用户在前端界面选择本地的模型文件(如 .pkl, .pth),并在工作流中加载使用。

功能亮点:

  • 使用 file_picker UI 控件。
  • 模拟模型加载过程。
  • 错误处理与状态返回。
from typing import Optional, Type
import os
# 导入基础组件
from panda_plugins.base import BaseWorkNode, work_node, ui
from pydantic import BaseModel, Field

# ---------------------------------------------------------------------
# 1. 定义输入模型
# ---------------------------------------------------------------------
# 使用 @ui 装饰器指定 model_path 字段在前端显示为文件选择器
@ui(
    model_path={"input_type": "file_picker", "placeholder": "请选择模型文件"}
)
class ModelUploadInput(BaseModel):
    # default="" 确保默认状态为空
    model_path: str = Field(default="", title="模型文件路径")
    load_mode: str = Field(default="safe", title="加载模式")  # 普通文本输入

# ---------------------------------------------------------------------
# 2. 定义输出模型
# ---------------------------------------------------------------------
class ModelUploadOutput(BaseModel):
    loaded_model_path: str = Field(title="已加载模型路径")
    status: str = Field(title="加载状态")
    message: str = Field(title="详细信息")

# ---------------------------------------------------------------------
# 3. 注册节点与实现逻辑
# ---------------------------------------------------------------------
@work_node(name="自定义模型加载器", group="用户自建", box_color="green")
class ModelUploadNode(BaseWorkNode):
    """
    用户自定义节点案例:
    用于演示如何通过 file_picker 上传并加载外部模型文件。
    """
    
    @classmethod
    def input_model(cls) -> Optional[Type[BaseModel]]:
        return ModelUploadInput

    @classmethod
    def output_model(cls) -> Optional[Type[BaseModel]]:
        return ModelUploadOutput

    def run(self, input: BaseModel) -> BaseModel:
        # 获取输入路径
        path = input.model_path
        mode = input.load_mode
        
        print(f"尝试加载模型: {path} (模式: {mode})")
        
        # 模拟:检查文件是否存在
        if not path or not os.path.exists(path):
            self.log_error(f"文件不存在或路径为空: {path}")
            return ModelUploadOutput(
                loaded_model_path="", 
                status="Failed", 
                message="File not found"
            )
            
        # 模拟:加载逻辑 (实际场景中可使用 joblib.load 或 torch.load)
        # model = joblib.load(path)
        
        self.log_info(f"模型加载成功: {path}")
        
        return ModelUploadOutput(
            loaded_model_path=path, 
            status="Success", 
            message=f"Model loaded in {{mode}} mode"
        )

# ---------------------------------------------------------------------
# 4. 本地测试代码 (If Name is Main)
# ---------------------------------------------------------------------
if __name__ == "__main__":
    # 实例化节点
    node = ModelUploadNode()
    
    # 模拟输入数据 (假设当前目录下有个 dummy.pkl)
    input_data = ModelUploadInput(model_path="./dummy.pkl", load_mode="fast")
    
    # 运行节点
    result = node.run(input_data)
    print("运行结果:", result)

5.4 UI 控件类型参考

@ui 装饰器中,input_type 支持以下控件类型,满足丰富的交互需求:

控件类型 (input_type) 描述 适用场景
text_field 单行/多行文本框 普通字符串、备注、名称
number_field 数字输入框 阈值、金额、数量 (int/float)
code_editor 代码编辑器 输入 Python/SQL 代码,带语法高亮
file_picker 文件选择器 上传本地文件、选择数据文件
combobox 下拉选择框 从预设选项中选择 (需配合 options 参数)
switch 开关 布尔值 (True/False)
slider 滑动条 范围数值选择 (需配置 min/max)
date_picker 日期选择器 选择年-月-日
time_picker 时间选择器 选择时:分:秒
password_field 密码框 敏感信息输入 (掩码显示)

评论

还没有评论,来说点什么吧
0 / 2000