架構與設計
模組架構
本頁內容8
這一頁用圖說明 FinLab 的模組怎麼分工、資料怎麼在模組之間流動。想看懂 FinLab 的結構，或想自己擴充功能，從這裡開始。
整體架構：從資料層一路到交易層
FinLab 採用分層架構，底層是資料層，頂層是交易層，資料由下往上走：
- 資料層：
finlab.data下載資料，交給FinlabDataFrame做運算。 - 策略層：用機器學習產生持股時，依序經過特徵工程（
finlab.ml.feature）、標籤生成（finlab.ml.label）、模型訓練（finlab.ml.qlib）。一般的選股條件不經過這一層，直接交給回測。 - 回測層：
finlab.backtest依市場物件（finlab.market）模擬交易，產生回測報告（finlab.report）。 - 分析層：拿報告做深度分析（
finlab.analysis）或參數優化（finlab.optimize，會回頭重跑回測）；finlab.plot負責畫圖。 - 交易層：
finlab.portfolio管理多策略組合，finlab.online實際送單給券商。
完整資料流：從資料來源到實盤部位
每個模組負責什麼
點模組名稱可以看它的 API 參考。
| 模組 | 主要類別／函數 | 用途 | 依賴模組 |
|---|---|---|---|
| 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、USFundMarket | 市場資料與特性 | data |
| finlab.ml.feature | ta()、combine() | 機器學習特徵工程 | data |
| finlab.ml.label | return_percentage()、excess_over_mean() 等 | 機器學習標籤生成 | data |
| finlab.ml.qlib | LGBModel()、XGBModel() 等 | 模型訓練 | ml.feature、ml.label |
| finlab.portfolio | Portfolio、PortfolioSyncManager | 多策略組合管理 | report |
| finlab.online | OrderExecutor、SinopacAccount 等券商帳戶 | 實盤交易執行 | report、portfolio |
| finlab.plot | plot_candles()、StrategyReturnStats | 資料視覺化 | dataframe |
從資料到回測報告：最基本的流程
一個策略最少只要四步：下載資料、算指標、寫出持有條件、交給 sim() 回測。
from finlab import data
from finlab.backtest import sim
close = data.get('price:收盤價')
position = close > close.average(20)
report = sim(position, resample='M')
report.display()這段程式在模組之間的往返：
模組之間傳遞的資料
| 資料類型 | 格式 | 說明 | 範例 |
|---|---|---|---|
| 價格資料 | 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() |
條件算出來是一張 True／False 的表。需要出場條件時先用 hold_until 加上，否則直接當成 position 交給 sim()：
常見的工作流程
完整的策略開發大致依序經過：資料 → 指標計算 → 產生訊號 → 參數優化 → 深度分析 → 樣本外測試 → 實盤交易。下面是其中幾段各自的流程。
一次測試多個條件組合
把多個候選條件組成 dict 交給 sim_conditions()，它會產生所有組合（n 個條件共 2^n - 1 種）並各跑一次回測，收進 ReportCollection。用熱力圖、棒狀圖或折線圖比較後，用最好的組合重新回測：
詳細用法見策略參數優化。
用機器學習產生持股權重
依序做特徵工程、標籤生成、模型訓練，用模型預測持股權重後回測。績效不滿意就回頭調整特徵或模型；滿意後做深度分析與樣本外測試，通過驗證才部署實盤：
詳細步驟見機器學習策略流程。
把回測結果拿去實盤下單
用 report.upload(name) 上傳策略、report.position_info() 取得持股清單，設定好券商帳戶後交給 OrderExecutor，由它計算買賣清單並送單：
詳細設定見下單：單一策略。
把多個策略合成一個組合
多個策略的報告交給 Portfolio 組合，再由 PortfolioSyncManager 同步到實盤：
策略 A report →
策略 B report → Portfolio → PortfolioSyncManager → 實盤多策略
策略 C report →詳見多策略組合管理。
擴充 FinLab：從哪個類別開始
熟悉基本回測後，依你想加的功能選起點：
自訂市場：繼承 Market
Market 定義每個市場都要提供的方法：名稱、頻率、價格、對照指數、代號與名稱對照。台股、美股等市場都是它的子類別。完整做法見自訂市場物件。
自訂分析：繼承 Analysis
每種分析都實作 calculate_trade_info()、analyze()、display() 與 is_market_supported()。完整做法見策略分析模組。
FinlabDataFrame 在 pandas 上加了什麼
FinlabDataFrame 繼承 pandas 的 DataFrame，多了選股常用的方法：
想把改動貢獻回 FinLab，見擴充開發。
讓回測跑得更快
同一份資料一次載入、重複使用，不要每次回測都重新呼叫 data.get()；大量回測時可以考慮本地快取。快取怎麼運作見資料流程。
回測本身太慢時：
| 瓶頸 | 優化方法 |
|---|---|
| 條件組合過多 | 先用單一條件篩選，移除差的條件 |
| 資料範圍過大 | 縮短回測區間或增加 resample 週期 |
| 計算複雜度高 | 使用向量化運算，避免迴圈 |
| 記憶體不足 | 分批處理或使用更長的 resample |
下一步
第一次接觸 FinLab，建議照這個順序認識各模組：
更多範例在台股實用範例與 FinLab GitHub。
這一頁有幫到你嗎？