FinRL-X 是 FinRL 的下一代版本，定位为面向生产环境的 AI 原生量化交易基础设施。它的核心设计是“以权重为中心”——策略层输出目标权重向量，回测和实盘执行共享同一套权重接口，从而保证部署的一致性。

下面是一份从环境准备到实盘接入的完整部署教程。

1. 环境要求

在开始之前，请确认你的系统满足以下条件：

要求 说明
Python 3.11 或 3.12（推荐）
Git 用于克隆代码仓库
API Keys 至少需要 Alpaca（模拟盘/实盘交易必需）；FMP（高质量数据源，可选）；WRDS（学术数据库，可选）

FinRL-X 已经现代化了配置体系，使用 Pydantic + .env 管理所有配置，不再依赖旧版 FinRL 的 config.py 硬编码方式。

2. 获取代码与安装

2.1 克隆仓库

1
2
git clone https://github.com/AI4Finance-Foundation/FinRL-Trading.git
cd FinRL-Trading

2.2 创建虚拟环境

1
2
3
python -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows

2.3 安装依赖

FinRL-X 提供了两种安装方式，按需选择：

方式一：仅安装核心依赖（跑回测够用）

1
pip install -r requirements.txt

方式二：可编辑安装 + 全量可选依赖（推荐，包含 ML、Web、开发工具）

1
pip install -e ".[all]"

核心依赖包括 numpy、pandas、scikit-learn、lightgbm、xgboost；回测引擎基于 bt；交易接口使用 alpaca-py；如果需要 DRL 策略，会用到 torch 和 stable-baselines3。

3. 配置 API Keys

3.1 创建 .env 文件

1
cp .env.example .env

3.2 编辑 .env

1
2
3
4
5
6
7
8
9
10
11
12
# Alpaca（模拟盘交易必需）
APCA_API_KEY=your_alpaca_key
APCA_API_SECRET=your_alpaca_secret
APCA_BASE_URL=https://paper-api.alpaca.markets
APCA_USE_PAPER_TRADING=True

# FMP（可选，优先级高于 Yahoo Finance）
FMP_API_KEY=your_fmp_key

# 数据存储
DATA_BASE_DIR=./data
DB_URL=sqlite:///data/finrl_trading.db

关于 Alpaca Key 的获取：前往 Alpaca 官网注册，在 Dashboard 中生成 Paper Trading 的 API Key 和 Secret。注意 APCA_BASE_URL 必须指向 paper-api.alpaca.markets（模拟盘），实盘时再切换。

关于数据源优先级：系统会自动按 FMP > WRDS > Yahoo Finance 的顺序选择可用数据源。Yahoo Finance 免费但数据质量一般；FMP 需要付费 Key，但基本面数据更完整。

4. 运行策略

FinRL-X 提供了三种运行方式，从最简单到最灵活。

4.1 一键部署脚本（推荐新手）

deploy.sh 会自动完成依赖检查、数据下载和策略执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 回测（默认自动下载数据）
./deploy.sh --strategy adaptive_rotation --mode backtest

# 自定义日期范围
./deploy.sh --strategy adaptive_rotation --mode backtest --start 2023-01-01 --end 2024-12-31

# 单日信号（生成某一天的调仓信号）
./deploy.sh --strategy adaptive_rotation --mode single --date 2024-12-31

# 模拟盘（先 dry-run 预览）
./deploy.sh --strategy adaptive_rotation --mode paper --dry-run
./deploy.sh --strategy adaptive_rotation --mode paper

# 查看所有选项
./deploy.sh --help

注意：如果手动运行 Python 脚本而不是用 deploy.sh，需要确保 data/fmp_daily/ 下已经存在 {SYMBOL}_daily.csv 文件。最省事的做法是先跑一次 deploy.sh 让它把数据下好。

4.2 手动运行 Python 脚本

如果你需要更细粒度的控制，可以直接调用策略入口：

1
2
3
python src/strategies/run_adaptive_rotation_strategy.py \
    --config src/strategies/AdaptiveRotationConf_v1.2.1.yaml \
    --backtest --start 2023-01-01 --end 2024-12-31

单日信号：

1
2
3
python src/strategies/run_adaptive_rotation_strategy.py \
    --config src/strategies/AdaptiveRotationConf_v1.2.1.yaml \
    --date 2024-12-31

4.3 Jupyter Notebook 完整工作流

FinRL-X 提供了一个完整的交互式教程 Notebook，覆盖从数据获取、ML 选股、回测到 Alpaca 模拟盘交易的完整链路：

1
jupyter notebook examples/FinRL_Full_Workflow.ipynb

建议按 cell 逐个运行，边跑边理解每一步的数据流。

5. Python API 调用

如果你打算把 FinRL-X 集成到自己的系统中，可以通过 Python API 直接调用核心模块：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 数据获取
from src.data.data_fetcher import get_data_manager
manager = get_data_manager()
prices = manager.get_price_data(['AAPL', 'MSFT'], '2020-01-01', '2024-12-31')

# 策略生成权重
from src.strategies.ml_strategy import MLStockSelectorStrategy
strategy = MLStockSelectorStrategy(config)
result = strategy.generate_weights(data)

# 回测
from src.backtest.backtest_engine import BacktestEngine, BacktestConfig
engine = BacktestEngine(BacktestConfig(start_date='2020-01-01', end_date='2024-12-31'))
result = engine.run_backtest("My Strategy", weights, prices)

# 模拟盘交易
from src.trading.alpaca_manager import create_alpaca_account_from_env, AlpacaManager
alpaca = AlpacaManager([create_alpaca_account_from_env()])
alpaca.execute_portfolio_rebalance(target_weights={'AAPL': 0.3, 'MSFT': 0.7})

核心逻辑是：策略输出 target_weights，回测引擎和 Alpaca 执行器都接收同一格式的权重字典，保证“回测即实盘”的一致性。

6. 自定义策略

FinRL-X 的模块化架构允许你通过继承 BaseStrategy 快速接入自己的 alpha 逻辑：

1
2
3
4
5
6
7
from src.strategies.base_strategy import BaseStrategy, StrategyConfig, StrategyResult

class MyStrategy(BaseStrategy):
    def generate_weights(self, data, **kwargs) -> StrategyResult:
        # 你的选股/配置逻辑
        # 返回一个权重向量（dict 或 Series）
        pass

只要返回的权重向量符合约定格式，就可以直接接入回测引擎或 Alpaca 执行器，无需修改下游代码。

7. 常见问题排查

数据获取失败：检查网络连接；确认 .env 中的 API Key 有效且未超过速率限制；如果使用 Yahoo Finance，注意它偶尔会限流。

Alpaca 连接问题：确认使用的是 Paper Trading 的 URL（paper-api.alpaca.markets）；检查 API Key 是否在 Alpaca Dashboard 中正确生成；确认账户状态正常。

回测结果异常：检查日期范围是否覆盖了足够的数据；确认权重计算逻辑没有前视偏差（FinRL-X 在策略层面做了 no-lookahead 约束，但自定义策略时仍需自行注意）；审查交易成本设置。

8. 版本说明

你链接的仓库是 FinRL-X（FinRL-Trading），它是 FinRL 的下一代版本。旧版 FinRL（2020 年发布）以 DRL 训练为核心，采用 Gym 风格的 state/action 接口；FinRL-X 则转向了“权重中心”架构，支持 ML + DRL + LLM 的混合策略，并把回测和实盘执行统一在同一套接口下。

如果你之前用过旧版 FinRL，迁移路径大致是：

  • finrl/meta/data_processor.py → src/data/data_fetcher.py
  • finrl/train.py → strategy.generate_weights()
  • finrl/trade.py → TradeExecutor.execute_portfolio_rebalance()
  • config.py + config_tickers.py → src/config/settings.py（Pydantic + .env）