进阶功能：FreqAI

要启用 FreqAI 功能，必须在 Freqtrade 的配置文件中将 freqai.enabled 参数设置为 true。这是启动 FreqAI 的最小必要条件。例如，在 config 文件中添加如下结构：

"freqai": {
    "enabled": true,
    ...
}

如果没有启用此参数，FreqAI 将完全不运行，即使其他参数配置正确也不会生效。此外，必须配合使用支持 FreqAI 的策略文件（如 FreqaiExampleStrategy.py），否则策略将无法调用 FreqAI 的核心功能。

identifier 是一个用户自定义的唯一字符串，用于标识一次特定的 FreqAI 运行。它的主要作用是帮助系统区分不同的模型训练和预测会话。当 identifier 保持不变时，FreqAI 会复用之前训练好的模型文件，从而实现崩溃恢复和加速回测。一旦你想要尝试新的特征、模型或参数组合，就必须更改 identifier 的值，或者手动删除 user_data/models/unique-id 文件夹以清除旧模型。否则，系统可能会错误地加载过时的模型，导致预测结果不准确。因此，为每次实验设置一个有意义的标识符（如 my_rsi_strategy_v1）是最佳实践。

一个 FreqAI 策略必须包含以下四个核心函数才能正常运行：

1. startup_candle_count: 定义策略启动所需的最少蜡烛数量，确保所有技术指标有足够历史数据计算，避免 NaN 值。
2. populate_indicators(): 在此函数中必须调用 self.freqai.start(dataframe, metadata, self)，这是 FreqAI 加载特征、训练模型并返回预测结果的入口点。
3. feature_engineering_expand_all(), feature_engineering_expand_basic(), 或 feature_engineering_standard(): 至少实现其中一个，用于定义用于训练的特征（以 % 开头）。
4. set_freqai_targets(): 必须实现此函数，用于定义模型要预测的目标变量（以 & 开头）。

所有这些函数都必须正确实现，否则 FreqAI 将无法训练或预测。此外，self.freqai.start() 只能在 populate_indicators() 中调用，不能在其他函数中使用。

在 FreqAI 中，特征（features） 是用于训练模型的输入变量，目标（targets） 是模型需要预测的输出值。

• 特征：必须在 feature_engineering_*() 函数中定义，并以 % 开头（如 %-rsi-period）。这些特征可以是技术指标（如 RSI、EMA）、价格变动、成交量等。FreqAI 会根据配置自动扩展这些特征（如不同时间帧、偏移蜡烛、相关币对），生成成千上万个特征。
• 目标：必须在 set_freqai_targets() 函数中定义，并以 & 开头（如 &-s_close）。目标通常是未来价格的变化率、涨跌方向等。例如，预测未来 24 根蜡烛的平均价格变化：

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
)

FreqAI 会利用这些特征和目标训练模型，并在后续预测中返回预测值到相同的 & 键中，供策略使用。

FreqAI 使用前缀（% 和 &）作为内部标识符来自动区分特征和目标，从而实现自动化处理。以 % 开头的列会被 FreqAI 识别为训练特征，系统会根据配置（如 include_timeframes, include_shifted_candles）自动扩展这些特征，生成多个变体（如 %-rsi-period_10_5m, %-rsi-period_10_15m），并用于模型训练。训练完成后，这些原始特征会被移除以节省内存，除非你使用 %% 前缀保留它们用于绘图或监控。

以 & 开头的列则被识别为训练目标（标签），FreqAI 会追踪这些目标的统计信息（如均值、标准差），并在预测时将预测结果写回相同名称的列，供策略在 populate_entry_trend() 或 populate_exit_trend() 中使用。这种命名约定使 FreqAI 能够无需人工干预即可管理复杂的特征工程和目标匹配流程。

FreqAI 支持多种基于梯度提升决策树（Gradient Boosted Decision Trees）的模型，包括：

• 回归模型：预测连续数值，如未来价格。例如：CatBoostRegressor, LightGBMRegressor, XGBoostRegressor。
• 分类模型：预测离散类别，如价格涨、跌、持平。例如：CatBoostClassifier, LightGBMClassifier, XGBoostClassifier。

所有模型都使用集成学习方法，通过组合多个决策树来提升预测稳定性。它们的主要区别在于算法实现和参数优化方式：

• CatBoost：擅长处理类别特征，对过拟合控制较好，适合中小数据集。
• LightGBM：训练速度快，内存效率高，适合大规模数据。
• XGBoost：泛化能力强，参数调节灵活，是广泛使用的基准模型。

使用时通过命令行参数 --freqaimodel CatBoostRegressor 指定模型类型。必须根据模型类型正确设置目标：回归模型用数值目标（如 &-s_close），分类模型用字符串标签（如 &-up_or_down = 'up'）。

此外，还支持自定义模型（如 PyTorch 神经网络），通过继承 IFreqaiModel 实现。

在 FreqAI 配置中，通过设置 include_timeframes 和 include_corr_pairlist，系统会自动将你在 feature_engineering_*() 中定义的特征扩展到多个时间帧和相关币对。

例如，配置如下：

"feature_parameters": {
    "include_timeframes": ["5m", "15m", "4h"],
    "include_corr_pairlist": ["ETH/USD", "LINK/USD"]
}

并在 feature_engineering_expand_all() 中定义一个特征：

dataframe["%-rsi-period"] = ta.RSI(dataframe, timeperiod=period)

系统会自动生成以下特征：

• %-rsi-period_10_5m
• %-rsi-period_10_15m
• %-rsi-period_10_4h
• %-rsi-period_10_ETH/USD_5m
• %-rsi-period_10_ETH/USD_15m
• ...（所有组合）

这使得模型能同时利用不同时间框架的趋势和相关币种的联动效应，提升预测能力。注意：扩展后的特征名会包含时间帧和币对信息，若需绘图，必须使用 %% 前缀并匹配完整名称。

在 FreqAI 中，模型的预测目标必须通过 set_freqai_targets() 函数定义，且该函数是强制性的。所有目标列的名称必须以 & 开头，这是 FreqAI 内部识别目标变量的唯一方式。例如，dataframe["&-s_close"] 表示一个目标变量，用于预测未来价格变化。目标通常基于未来价格计算，如使用 shift(-n) 向前移动价格数据，然后计算相对变化。示例中，&-s_close 是未来 24 个蜡烛的平均收盘价除以当前收盘价再减 1，即未来 24 根 K 线的平均收益率。目标可以是连续值（如收益率）或分类值（如上涨/下跌），但必须是数值类型。此函数在所有特征扩展完成后执行，因此可以基于已生成的特征来构造目标，例如用波动率调整目标阈值。

FreqAI 的特征扩展规模由配置文件中 freqai.feature_parameters 下的参数控制。关键参数包括：include_timeframes 指定要包含的时间帧（如 ["5m","15m","4h"]），include_corr_pairlist 指定要引入的相关币对（如 ["ETH/USD","LINK/USD"]），include_shifted_candles 指定要包含的前向蜡烛数量（如 2 表示当前蜡烛和前两个蜡烛），以及 indicator_periods_candles 指定要使用的指标周期列表（如 [10,20]）。这些参数的乘积决定了最终生成的特征总数。例如，3 个时间帧 × 3 个相关币对 × 2 个偏移蜡烛 × 2 个周期 × 3 个基础特征 = 108 个特征。这些参数与 feature_engineering_expand_all() 等函数配合，实现自动化、可配置的特征工程，无需手动编写重复代码。

FreqAI 的核心配置参数都位于 config.freqai 这个父字典中，是运行 FreqAI 模型所必需的。其中最关键的三个参数是 freqai、train_period_days 和 backtest_period_days，它们都标记为 Required（必需）。

• freqai 是整个 FreqAI 配置的根容器，所有其他参数都必须嵌套在其下。
• train_period_days 定义了用于训练模型的时间窗口长度（以天为单位），它决定了每次训练使用多少历史数据。
• backtest_period_days 则控制在回测过程中，模型训练完成后进行预测的时间跨度，之后系统会滑动窗口重新训练。这个值可以是小数，例如 0.5 表示每半天重新训练一次，但要注意它会影响回测所需的训练总次数。

这些参数共同决定了 FreqAI 如何管理数据窗口、训练频率和模型生命周期，是构建任何 FreqAI 策略的基础。

在实盘（live）或模拟（dry）运行中，FreqAI 通过 live_retrain_hours 参数控制模型重新训练的频率。该参数的单位是小时，表示每隔多少小时重新训练一次模型。默认值为 0，表示模型尽可能频繁地重新训练（例如，每次新数据到来时都训练）。

如果你希望模型每 24 小时训练一次，可以将此值设为 24。这有助于避免因市场突变导致模型过时，同时防止过于频繁的训练带来计算资源浪费或过拟合风险。

此外，expiration_hours 参数提供了一种安全机制：如果当前模型的年龄超过该设定值（以小时计），FreqAI 将拒绝做出预测，强制触发一次重新训练。默认值为 0，表示模型永不过期。这两个参数共同构成了 FreqAI 的模型生命周期管理机制，确保模型始终基于最新数据运行。

FreqAI 支持两种主要运行模式：实时交易（live/dry）和历史回测（backtesting）。

在实时或模拟交易模式下，FreqAI 会持续监控市场行情，自动下载所需数据，训练新的机器学习模型，并使用最新模型对每个新蜡烛进行预测。模型会定期重新训练，以适应市场变化，且始终使用最近期训练的模型进行预测。该模式下数据下载是自动完成的，无需手动干预。

而在回测模式下，用户需要提前手动下载覆盖整个回测时间段及额外训练窗口的数据（因为模型需要在回测起始前就有足够的历史数据用于训练）。回测会按设定的时间窗口（由 backtest_period_days 控制）滑动，为每个窗口训练一个独立模型，并使用该模型预测下一个窗口的走势。回测模式不会自动下载数据，且训练过程是离线执行的，主要用于策略验证和调优。

与实时模式不同，回测模式不自动下载数据，用户必须手动使用 download-data 命令提前下载足够的历史数据。

由于 FreqAI 模型在预测第一个回测蜡烛前需要一段历史数据进行训练，因此下载的数据起始时间必须早于回测时间范围。具体来说，需向前延伸至少 train_period_days（训练窗口天数）加上 startup_candle_count（启动所需蜡烛数）所对应的时间长度。例如，若 train_period_days=30、startup_candle_count=40、时间帧为 1h，则需在回测起始日（如 2021-05-01）前额外下载约 30 天 + 40/24 ≈ 31.7 天的数据，即从 2021-03-30 开始下载。否则，模型无法在回测开始时完成训练，导致失败。

FreqAI 是一个开源软件，专为自动化训练预测性机器学习模型以生成市场预测而设计，其输入为一组市场信号。它的主要目标是提供一个安全、灵活的沙盒环境，让用户能够轻松地在实时数据上部署强大的机器学习库，从而进行金融市场的预测建模。FreqAI 不以盈利为目的，不发行加密货币代币，也不出售交易信号，仅作为 Freqtrade 生态系统的一部分提供免费服务。