FinLab 模組架構與關係圖

本文透過視覺化圖表說明 FinLab 各模組的關係、資料流向、工作流程,幫助你快速理解系統架構。

---

整體架構圖

FinLab 採用分層架構,從底層的資料層到頂層的交易層:

graph TB
    subgraph "交易層 Trading Layer"
        portfolio[finlab.portfolio<br/>組合管理]
        online[finlab.online<br/>實盤交易]
    end

    subgraph "分析層 Analysis Layer"
        analysis[finlab.analysis<br/>策略分析]
        optimize[finlab.optimize<br/>參數優化]
        plot[finlab.plot<br/>資料視覺化]
    end

    subgraph "回測層 Backtest Layer"
        backtest[finlab.backtest<br/>回測引擎]
        report[finlab.report<br/>報告生成]
        market[finlab.market<br/>市場物件]
    end

    subgraph "策略層 Strategy Layer"
        ml_feature[finlab.ml.feature<br/>特徵工程]
        ml_label[finlab.ml.label<br/>標籤生成]
        ml_model[finlab.ml.qlib<br/>模型訓練]
    end

    subgraph "資料層 Data Layer"
        data[finlab.data<br/>資料存取]
        dataframe[finlab.dataframe<br/>FinlabDataFrame]
    end

    %% 資料流向
    data --> dataframe
    dataframe --> ml_feature
    dataframe --> backtest
    ml_feature --> ml_label
    ml_label --> ml_model
    ml_model --> backtest
    backtest --> report
    report --> analysis
    report --> optimize
    analysis --> portfolio
    optimize --> backtest
    portfolio --> online
    market --> backtest
    dataframe --> plot

    style data fill:#e1f5ff
    style backtest fill:#fff4e1
    style analysis fill:#e8f5e9
    style online fill:#fce4ec

---

核心工作流程

流程 1: 基礎策略開發

從資料載入到報告生成的基本流程:

sequenceDiagram
    participant User as 使用者
    participant Data as finlab.data
    participant DF as FinlabDataFrame
    participant Backtest as finlab.backtest
    participant Report as Report 物件

    User->>Data: data.get('price:收盤價')
    Data-->>User: DataFrame
    User->>DF: 計算指標 .average(20)
    DF-->>User: FinlabDataFrame
    User->>DF: 產生訊號 close > ma20
    DF-->>User: bool DataFrame
    User->>Backtest: sim(position, resample='M')
    Backtest->>Report: 建立 Report 物件
    Report-->>User: 回測結果
    User->>Report: report.display()
    Report-->>User: 顯示績效圖表

流程 2: 策略優化

使用 sim_conditions() 測試多個條件組合:

flowchart TD
    A[定義多個候選條件] --> B[組合成 dict]
    B --> C{使用 sim_conditions}
    C --> D[生成所有組合<br/>2^n - 1 種]
    D --> E[對每個組合執行回測]
    E --> F[收集所有 Report]
    F --> G[建立 ReportCollection]
    G --> H{選擇視覺化方式}
    H -->|熱力圖| I[plot_stats heatmap]
    H -->|棒狀圖| J[plot_stats bar]
    H -->|折線圖| K[plot_creturns]
    I --> L[找出最佳組合]
    J --> L
    K --> L
    L --> M[使用最佳組合重新回測]

    style C fill:#fff4e1
    style G fill:#e8f5e9
    style L fill:#fce4ec

流程 3: 機器學習策略

完整的機器學習策略開發流程:

flowchart TD
    A[載入原始資料<br/>finlab.data] --> B[特徵工程<br/>finlab.ml.feature]
    B --> C[標籤生成<br/>finlab.ml.label]
    C --> D[模型訓練<br/>finlab.ml.qlib]
    D --> E[預測持倉權重]
    E --> F[回測<br/>finlab.backtest.sim]
    F --> G{績效是否滿意?}
    G -->|否| H[調整特徵或模型]
    H --> B
    G -->|是| I[執行深度分析]
    I --> J[樣本外測試]
    J --> K{通過驗證?}
    K -->|否| H
    K -->|是| L[部署實盤]

    style B fill:#e1f5ff
    style D fill:#fff4e1
    style I fill:#e8f5e9
    style L fill:#fce4ec

流程 4: 實盤交易

從回測到實盤交易的完整流程:

sequenceDiagram
    participant User as 使用者
    participant Report as Report 物件
    participant Account as Account 物件
    participant Executor as OrderExecutor
    participant Broker as 券商 API

    User->>Report: report.upload(name)
    Report-->>User: 上傳成功
    User->>Report: report.position_info()
    Report-->>User: 持股清單
    User->>Account: 設定券商帳戶
    Account-->>User: 連線成功
    User->>Executor: OrderExecutor(report, account)
    Executor->>Executor: 計算買賣清單
    User->>Executor: executor.execute()
    Executor->>Broker: 發送買單
    Broker-->>Executor: 買單回報
    Executor->>Broker: 發送賣單
    Broker-->>Executor: 賣單回報
    Executor-->>User: 執行完成
    User->>Account: 查詢部位
    Account->>Broker: 取得部位資訊
    Broker-->>Account: 部位資料
    Account-->>User: 顯示實盤持股

---

模組功能對照表

模組	主要類別/函數	用途	依賴模組
finlab.data	get()	從資料庫取得財經資料	(無)
finlab.dataframe	FinlabDataFrame	增強版 DataFrame,支援金融運算	pandas
finlab.backtest	sim()	回測引擎,模擬交易	data, dataframe, market
finlab.report	Report	回測報告,績效分析	backtest
finlab.optimize	sim_conditions(), ReportCollection	測試多個條件組合	backtest
finlab.analysis	LiquidityAnalysis, MaeMfeAnalysis, 等	深度策略分析	report
finlab.market	Market, TWMarket, USMarket	市場資料與特性	data
finlab.ml.feature	add_ta(), add_fundamental()	機器學習特徵工程	data
finlab.ml.label	cls_label(), reg_label()	機器學習標籤生成	data
finlab.ml.qlib	train()	模型訓練	ml.feature, ml.label
finlab.portfolio	Portfolio, PortfolioSyncManager	多策略組合管理	report
finlab.online	OrderExecutor, SinopacAccount	實盤交易執行	report, portfolio
finlab.plot	plot_creturns(), plot_heatmap()	資料視覺化	dataframe

---

資料流向圖

從資料來源到實盤交易的完整資料流:

flowchart LR
    A[資料來源<br/>GCS/BigQuery] --> B[finlab.data.get]
    B --> C[DataFrame]
    C --> D{用途?}

    D -->|技術指標| E[FinlabDataFrame<br/>運算方法]
    D -->|機器學習| F[ml.feature<br/>特徵工程]

    E --> G[產生訊號<br/>bool DataFrame]
    F --> H[ml.label<br/>標籤生成]
    H --> I[ml.qlib<br/>模型訓練]
    I --> J[預測權重<br/>float DataFrame]

    G --> K[finlab.backtest.sim]
    J --> K

    K --> L[Report 物件]
    L --> M{分析類型?}

    M -->|參數優化| N[optimize.sim_conditions]
    M -->|深度分析| O[analysis 模組]
    M -->|視覺化| P[plot 模組]
    M -->|實盤交易| Q[online.OrderExecutor]

    N --> L
    O --> R[分析報告]
    P --> S[互動式圖表]
    Q --> T[券商 API]
    T --> U[實盤部位]

    style B fill:#e1f5ff
    style K fill:#fff4e1
    style O fill:#e8f5e9
    style Q fill:#fce4ec

---

類別繼承關係

Market 繼承樹

classDiagram
    class Market {
        <<abstract>>
        +get_name() str
        +get_freq() str
        +get_price() DataFrame
        +get_benchmark() Series
        +get_asset_id_to_name() dict
    }

    class TWMarket {
        +get_name() "tw_stock"
        +get_benchmark() 加權指數
        +get_industry() dict
        +market_close_at_timestamp()
    }

    class USMarket {
        +get_name() "us_stock"
        +get_benchmark() S&P 500
        +market_close_at_timestamp()
    }

    class ROTCMarket {
        +get_name() "rotc_stock"
    }

    class CustomMarket {
        +get_name() "custom"
        +自訂資料來源
    }

    Market <|-- TWMarket
    Market <|-- USMarket
    Market <|-- ROTCMarket
    Market <|-- CustomMarket

Analysis 繼承樹

classDiagram
    class Analysis {
        <<abstract>>
        +calculate_trade_info() list
        +analyze() dict
        +display() Figure
        +is_market_supported() bool
    }

    class LiquidityAnalysis {
        +流動性風險檢測
        +漲跌停、成交量
    }

    class MaeMfeAnalysis {
        +波動分析
        +MAE/MFE 12 子圖
    }

    class PeriodStatsAnalysis {
        +時期穩定性
        +年度、月度表現
    }

    class InequalityAnalysis {
        +不等式因子
        +基尼係數
    }

    class AlphaBetaAnalysis {
        +Alpha/Beta 分析
    }

    class DrawdownAnalysis {
        +回撤分析
    }

    class CustomAnalysis {
        +自訂分析邏輯
    }

    Analysis <|-- LiquidityAnalysis
    Analysis <|-- MaeMfeAnalysis
    Analysis <|-- PeriodStatsAnalysis
    Analysis <|-- InequalityAnalysis
    Analysis <|-- AlphaBetaAnalysis
    Analysis <|-- DrawdownAnalysis
    Analysis <|-- CustomAnalysis

FinlabDataFrame 繼承關係

classDiagram
    class DataFrame {
        <<pandas>>
        +基本 DataFrame 功能
    }

    class FinlabDataFrame {
        +average() 移動平均
        +is_largest() 排名
        +is_smallest() 排名
        +quantile() 分位數
        +hold_until() 進出場語法糖
        +and_then() 組合邏輯
    }

    DataFrame <|-- FinlabDataFrame

---

使用建議

新手學習路徑

flowchart TD
    A[開始] --> B[學習 finlab.data<br/>資料存取]
    B --> C[學習 FinlabDataFrame<br/>指標計算]
    C --> D[學習 finlab.backtest<br/>基礎回測]
    D --> E[學習 Report 物件<br/>績效分析]
    E --> F{想要深入?}
    F -->|是| G[學習 finlab.analysis<br/>深度分析]
    F -->|否| K[開始實盤交易<br/>finlab.online]
    G --> H[學習 finlab.optimize<br/>參數優化]
    H --> I[學習完整工作流程]
    I --> J{想用機器學習?}
    J -->|是| L[學習 finlab.ml<br/>機器學習模組]
    J -->|否| K
    L --> K
    K --> M[精通!]

    style A fill:#e1f5ff
    style D fill:#fff4e1
    style G fill:#e8f5e9
    style K fill:#fce4ec
    style M fill:#c8e6c9

進階開發路徑

flowchart TD
    A[熟悉基礎回測] --> B{開發需求?}
    B -->|多策略組合| C[學習 finlab.portfolio<br/>組合管理]
    B -->|自訂市場| D[繼承 Market 類別<br/>開發自訂市場]
    B -->|自訂分析| E[繼承 Analysis 類別<br/>開發分析模組]
    B -->|機器學習| F[學習 finlab.ml<br/>特徵、標籤、模型]
    C --> G[多策略實盤]
    D --> H[回測海外市場/加密貨幣]
    E --> I[客製化分析報告]
    F --> J[機器學習策略]
    G --> K[進階應用]
    H --> K
    I --> K
    J --> K

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style K fill:#c8e6c9

---

模組間的資料交換格式

主要資料格式

資料類型	格式	說明	範例
價格資料	pd.DataFrame	index: 日期, columns: 股票代號	data.get('price:收盤價')
選股訊號	pd.DataFrame(bool)	True 代表買入, False 代表不持有	close > ma20
持倉權重	pd.DataFrame(float)	0-1 之間,代表持倉比例	ML 模型預測
交易記錄	pd.DataFrame	逐筆交易的詳細資訊	report.get_trades()
績效指標	dict	策略的各種統計指標	report.get_stats()
對照指數	pd.Series	時間序列的價格資料	TWMarket.get_benchmark()

訊號轉換流程

flowchart LR
    A[條件判斷<br/>close > ma20] --> B[bool DataFrame<br/>True/False]
    B --> C{是否需要出場邏輯?}
    C -->|是| D[hold_until<br/>加入出場條件]
    C -->|否| E[直接作為 position]
    D --> E
    E --> F[finlab.backtest.sim<br/>執行回測]
    F --> G[Report 物件<br/>包含績效與交易]

    style B fill:#e1f5ff
    style D fill:#fff4e1
    style F fill:#e8f5e9

---

常見使用模式

模式 1: 快速驗證策略構想

# 最簡流程
close = data.get('price:收盤價')
position = close > close.average(20)
report = sim(position, resample='M')
report.display()

模式 2: 完整策略開發

# 完整流程
data → 指標計算 → 產生訊號 → 參數優化 → 深度分析 → 樣本外測試 → 實盤交易

模式 3: 機器學習策略

# ML 流程
data → feature engineering → label generation → model training → 預測 → 回測 → 分析

模式 4: 多策略組合

# 組合流程
策略 A report →
策略 B report →  Portfolio → PortfolioSyncManager → 實盤多策略
策略 C report →

---

效能優化建議

資料存取

flowchart TD
    A[需要使用資料] --> B{資料量大小?}
    B -->|小<br/>單一股票| C[直接使用 data.get]
    B -->|中<br/>數十個指標| D[一次載入<br/>避免重複呼叫]
    B -->|大<br/>大量回測| E[考慮使用<br/>本地快取]

    C --> F[執行策略邏輯]
    D --> F
    E --> F

    style C fill:#e8f5e9
    style E fill:#fff4e1

回測優化

瓶頸	優化方法
條件組合過多	先用單一條件篩選,移除差的條件
資料範圍過大	縮短回測區間或增加 resample 週期
計算複雜度高	使用向量化運算,避免迴圈
記憶體不足	分批處理或使用更長的 resample

---

參考資源

詳細文檔

• 策略參數優化完整指南
• 策略分析模組完整指南
• 自訂市場物件完整指南
• 完整策略開發流程

API Reference

• finlab.data API Reference
• finlab.backtest API Reference
• finlab.optimize API Reference
• finlab.analysis API Reference
• finlab.market API Reference

實用範例

• 台股實用範例
• FinLab GitHub