第 1 章：什么是 FreqAI / 安装与首次运行
学习目标
- 用一句话说清 FreqAI 解决什么问题
- 理解 FreqAI 的"训练—预测—再训练"循环
- 完成 FreqAI 依赖安装
- 跑通一个最小可运行的 LightGBM 回归示例，看到 backtest 报告
1.1 FreqAI 是什么
官方原话：
FreqAI is a software designed to automate a variety of tasks associated with training a predictive machine learning model to generate market forecasts given a set of input features.
人话版：FreqAI 是给 Freqtrade 策略加上"机器学习预测能力"的官方框架。你只要在策略里写几个钩子说明"我要用哪些特征、要预测什么"，FreqAI 就自动负责：
- 拉数据、构造特征、对齐时间戳
- 切分训练/测试集
- 训练模型并保存到磁盘
- 推理出预测列（
&-开头）回填到 dataframe - 按时间窗口自动再训练适应市场漂移
你在策略里像用普通 indicator 一样使用预测列就行。
1.2 FreqAI 的工作循环
┌──────────────────────────────────────────────────────────────────┐
│ Freqtrade Pair Dataframe (OHLCV + base indicators) │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Strategy hooks (你写的): │
│ feature_engineering_expand_all ──▶ %- 特征（按period展开） │
│ feature_engineering_expand_basic ──▶ %- 特征（不随period展开）│
│ feature_engineering_standard ──▶ %- 特征（最终统一处理） │
│ set_freqai_targets ──▶ &- 标签（必须） │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ FreqAI 引擎自动完成： │
│ 1. 按 train_period_days 切训练窗口 │
│ 2. 标准化 / 异常值检测 / PCA（可选） │
│ 3. 调用模型 fit() 训练 │
│ 4. 保存模型到 user_data/models/<identifier>/ │
│ 5. 在 backtest_period_days 范围内做 predict() 回填到 df │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 策略 populate_entry_trend / populate_exit_trend： │
│ 用 df["&-s_close"] 或 df["do_predict"] 当作普通指标使用 │
└──────────────────────────────────────────────────────────────────┘
│
▼
下单 / 平仓
关键点：
-
%-前缀：模型用作输入的特征 -
&-前缀：模型要预测的目标（label） - 无前缀：中间计算列，不进入模型
- 窗口每滚动
backtest_period_days天就重新训练一次（实盘里改用live_retrain_hours）
1.3 安装
FreqAI 不在 Freqtrade 默认依赖里，需要单独装：
conda activate freqtrade
# 进入你的 freqtrade 源码或安装目录
pip install -r requirements-freqai.txt
这会装上：lightgbm、catboost、xgboost、scikit-learn、datasieve 等。
Docker 用户改用镜像
freqtradeorg/freqtrade:stable_freqai即可。
第 7 章的强化学习需要额外的 requirements-freqai-rl.txt（含 stable-baselines3 与 torch，大约 700MB，按需安装）。
1.4 最小可运行示例
我们要做的事情非常简单：预测未来 12 根 5m K 线的平均收盘价相对当前 close 的偏移。本质是一个回归问题，预测出来的值约等于 "未来一小时的预期回报率"。
策略文件：examples/ch01/FreqaiHelloStrategy.py
配置文件：examples/ch01/config_ch01.json
1.4.1 策略代码精读
class FreqaiHelloStrategy(IStrategy):
timeframe = "5m"
can_short = False
process_only_new_candles = True
startup_candle_count = 40 # >= indicator_periods_candles 最大值 * 2
def feature_engineering_expand_all(self, dataframe, period, metadata, **kwargs):
# 每个 period（10, 20）都会被自动展开一遍
dataframe[f"%-rsi-period_{period}"] = ta.RSI(dataframe, timeperiod=period)
dataframe[f"%-ema-period_{period}"] = ta.EMA(dataframe, timeperiod=period)
return dataframe
def set_freqai_targets(self, dataframe, metadata, **kwargs):
# 必须实现：定义 &- 开头的列作为预测目标
horizon = self.freqai_info["feature_parameters"]["label_period_candles"]
dataframe["&-s_close"] = (
dataframe["close"].shift(-horizon).rolling(horizon).mean()
/ dataframe["close"] - 1
)
return dataframe
def populate_indicators(self, dataframe, metadata):
# 把 freqai 引擎接进来——这是必须的一行
dataframe = self.freqai.start(dataframe, metadata, self)
return dataframe
def populate_entry_trend(self, dataframe, metadata):
# 预测值 > 0 且预测置信度 ok 就开多
dataframe.loc[
(dataframe["&-s_close"] > 0.002) & (dataframe["do_predict"] == 1),
"enter_long",
] = 1
return dataframe
def populate_exit_trend(self, dataframe, metadata):
dataframe.loc[dataframe["&-s_close"] < 0, "exit_long"] = 1
return dataframe
记住两个魔法字段：
-
do_predict：FreqAI 自动加在 dataframe 上的"这一行预测是否有效"标记（1 表示在 DI 阈值内可信） -
&-s_close：你定义的 label 在推理阶段会被同名列自动覆盖为预测值
1.4.2 配置文件精读
config_ch01.json 的 freqai 块：
"freqai": {
"enabled": true,
"identifier": "ch01_hello",
"train_period_days": 15,
"backtest_period_days": 5,
"live_retrain_hours": 0,
"purge_old_models": 2,
"feature_parameters": {
"include_timeframes": ["5m"],
"include_corr_pairlist": [],
"label_period_candles": 12,
"include_shifted_candles": 2,
"indicator_periods_candles": [10, 20]
},
"data_split_parameters": { "test_size": 0.2, "shuffle": false },
"model_training_parameters": { "n_estimators": 300 }
}
最小可运行配置：单时间框架、无相关币种、两个指标周期。
1.5 运行命令
conda activate freqtrade
# 1. 预下载数据（带 35 天 buffer，给 train_period_days=15 + startup=40 留余地）
freqtrade download-data \
--exchange binance \
--pairs BTC/USDT ETH/USDT \
--timeframes 5m \
--timerange 20240501-20240801
# 2. 跑回测
freqtrade backtesting \
--config freqai-tutorial/examples/ch01/config_ch01.json \
--strategy FreqaiHelloStrategy \
--strategy-path freqai-tutorial/examples/ch01 \
--freqaimodel LightGBMRegressor \
--timerange 20240601-20240731
期待输出（节选）：
=========== FREQAI ENABLED ===========
Found XX historical candles for BTC/USDT 5m
Training model for BTC/USDT
...
============================ BACKTESTING REPORT ============================
| Pair | Entries | Avg Profit % | ... |
| BTC/USDT | XX | X.XX | ... |
只要看到 "Training model for ..." 与最终的 BACKTESTING REPORT 表格，就说明跑通了。
1.6 常见错误
| 报错 | 原因 | 解决 |
|---|---|---|
KeyError: 'freqai' 或 freqai_info is None
|
配置里没启用 freqai 块 | 检查 freqai.enabled: true，且 freqaimodel 命令行参数已传 |
No model found in user_data/models/<identifier>/... |
训练窗口不够 / 数据没下载完 | 把 --timerange 起点往后挪到 train_period_days + startup 之后 |
KeyError: '&-s_close' 在 populate_entry_trend |
忘了在 populate_indicators 里调 self.freqai.start(...)
|
加上那一行 |
Cannot use VolumePairList with FreqAI |
用了动态币池 | 改成静态 StaticPairList 或 ShufflePairList
|
1.7 验证情况
✅ 本章示例在 conda activate freqtrade 环境下完整跑通了 backtesting（见教程仓库 README）。如果你的环境跑不起来，多半是数据没下全或 freqtrade 版本太老（建议 ≥ 2024.x）。
1.8 小结与下一章
你已经会跑一个最小 FreqAI 策略了。但很多配置字段是直接照抄的，第 2 章会逐项拆解 freqai 块每个字段的含义，让你能根据自己的需求改配置。
Top comments (0)