第 8 章 · 01 FreqAI 总览与架构

第 8 章 · 01 FreqAI 总览与架构

本节摘要:FreqAI 是 freqtrade 最具差异化的模块——一个用于在实时行情上训练预测模型的「自适应建模沙箱」。它把「特征工程 → 模型训练 → 实时推理 → 持续重训练」串成一条闭环，让模型随市场演化而自我更新，而不是一次训练用到老。本节先讲清 FreqAI 的定位与价值，再拆解它的三大核心对象(IFreqaiModel、FreqaiDataKitchen、FreqaiDataDrawer)以及「训练-推理-重训练」闭环的数据流，最后对比 FreqAI 策略与普通策略的关系，为后续的特征工程、配置、模型开发打地基。

内容来源:原项目文档 docs/freqai.md、docs/freqai-developers.md，汉化并套用体系化模板。

⚠️ 风险提示:FreqAI 官方明确声明项目仅作教育用途，不存在官方代币、不卖信号。机器学习在金融市场的过拟合风险极高，回测好看不代表实盘能赚，务必先 Dry-Run 长时间验证。

学习目标

阅读完本节，你应当能够:

1. 说清 FreqAI 的定位(自适应预测建模沙箱)与它解决的问题。
2. 描述训练-推理-重训练闭环的工作流程。
3. 区分三大核心对象:IFreqaiModel、FreqaiDataKitchen、FreqaiDataDrawer。
4. 理解 FreqAI 策略与普通 IStrategy 的关系与差异。
5. 知道 FreqAI 的常见坑(如不能配动态 VolumePairList)。

一、FreqAI 是什么:从「写规则」到「学规律」

传统 freqtrade 策略靠人写规则——「RSI 低于 30 就买」「跌破布林下轨就卖」。这种方式直观，但规则是死的，市场是活的。FreqAI 换了个思路:你提供一批基础特征(指标)和标签(想预测的目标)，让机器学习模型从历史数据中自己学规律，再预测未来，而且每隔一段时间自动重训练以适应市场变化。

FreqAI 的核心卖点有这些:

• 自适应重训练:实盘运行时在后台线程持续重训练，让模型跟着市场走。
• 大规模特征工程:一套配置就能从几个基础指标裂变出成千上万个特征。
• 高性能:训练在独立线程(或 GPU)上跑，推理数据常驻内存。
• 逼真的回测:回测模块会模拟「滑动窗口重训练」，还原实盘行为。
• 可扩展:任何 Python 机器学习库都能接进来，内置 8+ 种示例模型。

💡 一句话心法:市场在变，模型也要跟着变——所以「持续重训练」比「一次训练」更重要。这是 FreqAI 区别于「训一次用一辈子」的传统 ML 方案的根本所在。

二、三大核心对象:引擎、厨房、抽屉

FreqAI 的架构围绕三个对象展开，理解它们的分工就理解了整个系统:

IFreqaiModel 是抽象基类，所有内置模型(LightGBM、XGBoost、PyTorch、强化学习等)都继承自它。它持有配置、训练队列、数据抽屉等全局状态，并定义了 train()、predict()、fit() 等抽象方法供子类实现。

FreqaiDataKitchen 名字很形象——它是「每个币对的临时厨房」。每训练或推理一个币对，就创建一个 DataKitchen，里面装着这个币对的特征列表、标签列表、训练/测试集切分、流水线对象等。它不是持久的，用完即弃。

FreqaiDataDrawer 是「持久抽屉」，负责把训练好的模型、历史预测、元数据存到磁盘(user_data/models/<identifier>/)，崩溃重启后能自动恢复。它还会自动检测损坏的预测文件并用备份替换。

三、训练-推理-重训练闭环

这是 FreqAI 的灵魂。整个流程是这样的:

1. 启动:策略在 populate_indicators() 里调用 self.freqai.start(dataframe, metadata, self)。
2. 首次训练:FreqAI 按 train_period_days 取历史数据，做特征工程，训练一个模型。
3. 实时推理:新 K 线到来时，用最新模型预测，把预测值(如 &-s_close)写回 DataFrame。
4. 后台重训练:独立线程按 live_retrain_hours 间隔重训练新模型，训练完无缝替换旧模型。
5. 持久化:每个模型存盘，历史预测存入 historic_predictions.pkl，崩溃可恢复。

关键参数控制这个闭环的节奏:

• train_period_days:每次训练用多少天的数据(滑动窗口宽度)。
• backtest_period_days:回测时每个模型负责预测多少天，之后滑动窗口前移并重训练。
• live_retrain_hours:实盘多久重训练一次(0 表示尽可能频繁)。
• expiration_hours:模型超过多少小时就不再用它预测。

💡 模型年龄问题:FreqAI 是逐个币对串行训练的。如果你有 50 个币对、每个训练 5 分钟，最老的模型会「老」4 小时以上。如果你的交易周期短于 4 小时，可以用 expiration_hours 让老模型「过期」，避免用过时模型下单。

四、FreqAI 策略与普通策略的关系

FreqAI 策略仍然是 IStrategy 的子类，populate_entry_trend / populate_exit_trend 照写。区别在于:

• populate_indicators 里不手算指标，而是调用 self.freqai.start()，让 FreqAI 接管特征工程和预测。
• 特征定义搬到 feature_engineering_expand_all 等专用函数里，不能写在 populate_indicators 里(实盘会报错)。
• 预测列以 & 开头(如 &-s_close)，直接在 entry/exit 逻辑里当条件用。

看 FreqaiExampleStrategy.py 的核心结构:

class FreqaiExampleStrategy(IStrategy):
    startup_candle_count: int = 40
    can_short = True

    def feature_engineering_expand_all(self, dataframe, period, metadata, **kwargs):
        # 在这里定义基础特征，FreqAI 会自动按配置裂变
        dataframe["%-rsi-period"] = ta.RSI(dataframe, timeperiod=period)
        dataframe["%-mfi-period"] = ta.MFI(dataframe, timeperiod=period)
        return dataframe

    def set_freqai_targets(self, dataframe, metadata, **kwargs):
        # 标签决定模型学什么——这里是未来 N 根 K 线的收益率
        dataframe["&-s_close"] = (
            dataframe["close"]
            .shift(-self.freqai_info["feature_parameters"]["label_period_candles"])
            .rolling(self.freqai_info["feature_parameters"]["label_period_candles"])
            .mean() / dataframe["close"] - 1
        )
        return dataframe

    def populate_indicators(self, dataframe, metadata):
        dataframe = self.freqai.start(dataframe, metadata, self)  # FreqAI 接管
        return dataframe

    def populate_entry_trend(self, df, metadata):
        # 直接用预测值当信号
        df.loc[(df["do_predict"] == 1) & (df["&-s_close"] > 0.01),
               ["enter_long", "enter_tag"]] = (1, "long")
        return df
​

⚠️ 注意:self.freqai.start() 只能在 populate_indicators() 里调用，不能挪到别处。特征必须定义在 feature_engineering_*() 函数里，否则实盘/dry 模式会失败。

五、数据存储与崩溃恢复

FreqAI 把所有训练产物放在 user_data/models/<identifier>/ 下，结构清晰:

models/
└── unique-id/
    ├── historic_predictions.pkl          # 历史预测(带备份)
    ├── pair_dictionary.json              # 训练队列与最新模型位置
    └── sub-train-BTC_1662821319/         # 单次训练的文件夹
        ├── cb_btc_..._metadata.json      # 归一化参数、特征列表等元数据
        ├── cb_btc_..._model.joblib       # 模型文件
        ├── cb_btc_..._trained_df.pkl     # 训练用的特征数据
        └── ...
​

identifier 是你给本次实验起的唯一 ID。改了特征或模型，必须换 identifier(或删掉对应文件夹)，否则 FreqAI 会复用旧模型导致结果不一致。保持 identifier 不变则能享受崩溃恢复和回测加速。

💡 purge_old_models:长时间高频重训练会堆积大量模型文件。设 "purge_old_models": 4 可只保留最近 4 个模型，自动清理旧的。

本节要点回顾

1. 定位:FreqAI 是自适应预测建模沙箱，让 ML 模型随市场持续重训练，而非一次训练用到老。
2. 三大对象:IFreqaiModel(引擎，持久单例)、FreqaiDataKitchen(厨房，单币对临时)、FreqaiDataDrawer(抽屉，持久化存取)。
3. 闭环:启动 → 首次训练 → 实时推理 → 后台按 live_retrain_hours 重训练 → 模型无缝替换。
4. 策略关系:FreqAI 策略仍是 IStrategy，但特征定义搬到 feature_engineering_*()，populate_indicators 里调 self.freqai.start()，预测列以 & 开头。
5. 存储:user_data/models/<identifier>/ 存模型与预测，改特征/模型必须换 identifier。
6. 常见坑:FreqAI 不能配动态增删币对的 VolumePairList(数据来不及准备);模型会随币对增多而「变老」，可用 expiration_hours 控制。

下一节，我们看 FreqAI 的特征工程与标签设计——这是 ML 策略成败的关键，feature_engineering_expand_all 怎么让几个指标裂变成上千个特征，set_freqai_targets 怎么决定模型「学什么」。