文件
開啟 Studio

完整流程

實盤覆盤

本頁內容6

回測報表看的是理論部位,實盤覆盤看的是你真的成交了什麼。TradeReview 用實際成交價、手續費、交易稅、除權息與入出金,重建每天的持股、現金與淨值,算出排除入出金影響的報酬率(時間加權報酬),並產生和回測同一套的 FinLab 報表。

做完這一頁,你會有:每天的持股與淨值、時間加權報酬、一份 FinLab 報表,以及實際部位和策略目標的差異表。

開始前你需要:

  • 一個用 finlab.online 連上的券商帳戶,設定方式見實盤下單。券商不在支援清單,或想用匯出的成交檔,看本頁最後一節「用自己的成交紀錄」。
  • 決定從哪一天開始覆盤。券商 API 查不到那麼早的資料時,覆盤只能從查得到的那天開始。

從券商帳戶覆盤

連上券商帳戶

以永豐為例,其他台股券商的支援程度見下方的表:

from finlab.online.sinopac_account import SinopacAccount

acc = SinopacAccount()

建立覆盤

from finlab.portfolio import TradeReview

review = TradeReview.from_account(acc, start="2026-01-01")

from_account 會依序做四件事:

  1. 依券商 API 抓 start 到今天的成交(各券商的差異見下方的表)。
  2. 由券商目前庫存倒推起始日的庫存(扣回期間成交、除回配股與分割),最後再把重建出的期末庫存和券商庫存對帳,不一致的代號會寫進 review.limitations。
  3. 套用除權息。台股自動套用 FinLab 公告的除權息:現金股利在除息交易日入帳,配股與 ETF 分割在除權交易日(分割為恢復買賣日)調整股數。嘉信與幣安用券商紀錄裡的股利。
  4. 以未還原收盤價每日估值。

先看資料限制

review.limitations  # 這次覆盤的資料限制,務必看過

對帳不一致的代號、被略過的融券與借券成交,都會列在這裡。先看過,再相信後面的數字。

看績效與明細

review.summary()  # 起訖淨值、外部淨投入、股利、費稅、損益、時間加權報酬
review.daily  # 每日現金、持股市值、淨值、流入流出、報酬率、累計損益
review.holdings  # 每日收盤持股股數
review.trades  # FIFO 配對的每段實際交易(含股利),未出清的部位 exit_date 為空
review.report.display()  # FinLab 報表:淨值曲線、績效指標、MAE/MFE、交易明細

和策略目標比對

compare 用「目標日收盤時」的實際部位和目標比,不會用到之後的成交。目標可以是股數,也可以是權重:

import pandas as pd

target = pd.DataFrame({"2330": [2000], "2454": [1000]}, index=["2026-03-02"])
review.compare(target)  # date, stock_id, target, actual, diff(股數)

weights = pd.DataFrame({"2330": [0.6], "2454": [0.4]}, index=["2026-03-02"])
review.compare(weights, kind="weight")  # 也可以比權重

在 Studio 看報表,明細另外保存

review.report 是一般的 Report,可以用公開的 review.report.upload(name=...) 上傳,再到 Studio 我的策略 查看。它保存的是報表,不是整份實盤帳本。以下為 finlab 2.3.4 的能力範圍:

你要看什麼Python 裡的資料上傳後的 Studio 原生報表
報酬曲線、績效指標review.report可查看
FIFO 配對交易review.trades報告交易最多保留最後 500 筆;不是原始成交筆數
每筆成交與費稅review.fills不保存完整 fills;交易列表不呈現逐筆股數、手續費與交易稅
每日持股股數review.holdings不保存每日股數表;期末持股以權重呈現
每日現金、淨值與入出金review.daily不保存完整每日帳本;報酬曲線不能代替現金紀錄

一筆成交可能拆成多段 FIFO 配對交易,因此 500 筆報告交易不等於 500 筆成交。費稅已依覆盤口徑計入報酬。

上傳前確認會存到哪裡

上傳可能更新既有策略;在 Studio 內執行時,即使傳入另一個 name,仍以目前策略為目標,並保留既有分享設定。參數、回傳值、權限核對限制與一般上傳範例見 Report.upload。

若你要求「只新增、一定私人、回傳 ID 並核對權限」,目前沒有符合全部條件的公開 API,請先保存在本機。

保存完整明細

已建立 review 後,可以在本機分別保存報表與帳本,不需上傳:

save_review.py
review.report.to_pickle("trade_review_report.pkl")
review.fills.to_csv("fills.csv", index=False)
review.trades.to_csv("fifo_trades.csv", index=False)
review.daily.to_csv("daily.csv", index_label="date")
review.holdings.to_csv("holdings.csv", index_label="date")

to_pickle() 保存的是 Report,不包含整個 TradeReview 的成交、每日現金與每日股數表。若要日後重建覆盤,也請保留原始成交檔、起始庫存/現金、入出金、除權息與價格等輸入;本機檔案不會因上傳報告而一起存進 Studio。

Studio 網頁產檔、下載與暫存限制

在 Studio 網頁請研究 AI 做簡報或試算表時,AI 的 Python 把 PowerPoint(.pptx)或 Excel(.xlsx)存在目前資料夾,例如 prs.save("報告.pptx")、df.to_excel("明細.xlsx"),那次執行的結果下方就會出現這個檔案,按「下載」存到你的電腦。雲端已預裝 python-pptx 與 openpyxl,不需要另外安裝。

項目限制
格式PowerPoint(.pptx)、Excel(.xlsx)
大小單檔 5 MB 以內;一次執行合計 6 MB、最多 10 個檔案
保存產生後 7 天內可下載,之後自動刪除
誰能下載只有執行時登入的帳號;未登入時不保存

檔案打不開(例如 ZIP 結構不完整)或超過上限時,結果下方會寫原因,不提供下載。其他格式(CSV、JSON、ZIP)沒有下載出口;Python 寫出這些檔案,只表示執行環境裡有檔案,不表示已下載到你的電腦。資料目錄的固定 CSV 下載是另一項功能,不能匯出研究產生的檔案。

執行環境檔案在哪裡、能保存多久
你電腦上的本機 Python寫到本機指定路徑,由你自行保存與備份;上方保存範例適用於此
Studio 網頁的瀏覽器 Python寫在瀏覽器執行環境中;沒有持久保存保證,不應依賴重新整理或重開後仍可取回
Studio 雲端 Python一次性執行的暫存檔,執行結束就刪除,不能在下一次執行讀回;只有上表的 .pptx/.xlsx 另外保存 7 天供下載

需要保留其他格式的完整原始檔時,請在本機 Python 產檔並自行保存。Report、Log 或畫面上的文字不能代替原始檔案的 bytes。

對實際檔案計算 bytes 與 SHA-256

檔案寫完並關閉後,在同一個 Python 執行環境執行以下程式,換成自己的檔名;雲端執行時,須與產檔程式放在同一次執行:

from pathlib import Path
import hashlib

for filename in ("fills.csv", "summary.json", "review.zip"):
    raw = Path(filename).read_bytes()
    print(filename, len(raw), hashlib.sha256(raw).hexdigest())

len(raw) 是 bytes 數,不是文字字數。CSV 的 BOM、換行方式、JSON 的編碼或 ZIP 的封裝內容不同,都可能改變 bytes 與雜湊;請直接對檔案計算,不先解碼或重新序列化。比較兩份檔案時,在兩邊各算一次,核對 bytes 數與 SHA-256。

這是你自行計算的校驗值;Studio 目前不提供這類研究檔案的平台校驗值。印出 bytes 或 SHA-256 不會建立下載出口,也不能證明已完成下載或平台已驗證檔案完整性。

報酬怎麼算:帳戶模式與持股模式

覆盤會依券商查得到哪些資料,選一種口徑算淨值:

口徑什麼時候用淨值外部資金流
帳戶模式券商 API 有完整入出金(嘉信、幣安),或你給了 initial_cash 與 cash_events現金+持股市值入金、出金
持股模式台股券商(交割戶是銀行帳戶,API 查不到入出金)持股市值買進金額視為開盤前投入;賣出淨額與股利視為收盤後取出

日報酬 r = (當日淨值 + 當日流出) / (前日淨值 + 當日流入) - 1,串接成累積報酬。報表的年化報酬、夏普、回撤都以此計算,不受入出金影響。帳戶模式下 pnl 是「淨值變化減去外部淨投入」。

在下面的帳戶按入金、出金,看哪個數字跟著跳、哪個不動:

互動關卡

入金、出金按下去:哪個數字變了,哪個沒變?

任務 1 / 3 按「入金 10 萬」,讓帳面報酬比時間加權報酬高 10 點以上

帳戶淨值 不入出金的淨值
2025/042025/072025/10
review = TradeReview.from_account(
    acc, start="2025-01-02", initial_cash=500_000,
    cash_events=pd.DataFrame({
        "time": [],
        "amount": [],
        "type": [],
    }),
)
review.summary()
帳面報酬end_nav ÷ base_nav − 1 +28.6%
時間加權報酬time_weighted_return +28.6%
損益pnl 14.3 萬

每日報酬 r = (當日淨值 + 當日流出) ÷ (前日淨值 + 當日流入) − 1

帳戶 2025 年平均持有 8 檔大型股(真實股價,每月再平衡、不含費用);入金當天開盤前就投入、出金在收盤後取出,金額為示意。

台股券商查不到入出金,所以預設只覆盤持股。要算含現金的帳戶淨值,自己給起始現金與入出金:

import pandas as pd

review = TradeReview.from_account(
    acc,
    start="2026-01-01",
    initial_cash=500_000,
    cash_events=pd.DataFrame(
        {
            "time": ["2026-03-02"],
            "amount": [100_000],
            "type": ["deposit"],
        }
    ),
)

各券商支援程度

券商成交來源手續費/交易稅已平倉部位股利入出金預設口徑
永豐已實現損益+明細、未實現部位明細買進取自明細;賣出由已實現損益反推(合併記在 fee)可還原買進腿FinLab 自動無持股模式
口袋已實現損益、未實現部位明細無SDK 有明細查詢時同永豐;沒有時期間內賣出的股票視為起始日已持有FinLab 自動無持股模式
富邦filled_history(每次 30 天,需 fubon_neo 2.1.1 以上)API 無逐筆費稅,依 fee_ratio 與法定稅率估算可FinLab 自動無持股模式
台新(原元富)對帳單 account_statment逐筆實際值可FinLab 自動無持股模式
玉山(富果)get_transactions_by_date(每次 180 天)逐筆實際值可FinLab 自動無持股模式
嘉信交易紀錄 get_transactions淨額與成交金額的差可券商紀錄券商紀錄帳戶模式
幣安myTrades(逐幣別)以報價幣或該幣支付的手續費;以 BNB 支付的未計入只查目前持有與 symbols= 指定的幣別報價幣配發報價幣入出金帳戶模式

所有券商共同的限制:

  • 只覆盤現股與融資的多單;融券、借券成交會略過並列在 limitations。融資利息不計。
  • 台股成交大多只有日期;同一天先處理買進再處理賣出,每日收盤估值不受影響。
  • 減資、面額變更沒有完整的每股退還現金與換股比例資料,不自動處理;遇到時把事件放進 corporate_actions(欄位 stock_id, date, cash, ratio)。配股以「元/股 ÷ 面額」換算,零股以無條件捨去計算。
  • 券商 API 查不到時間範圍外的資料時,覆盤只能從查得到的那天開始。

用自己的成交紀錄

券商不在上表,或要用匯出的成交檔時,把檔案整理成標準欄位,直接建立 TradeReview。quantity 是股數,fee、tax 是該筆實際金額,沒有這兩欄時以 0 計。

台股可以用 tw_corporate_actions(stock_ids, start, end),從 FinLab 公告的除權息產生 corporate_actions 表:

import pandas as pd
from finlab.markets.tw import TWMarket
from finlab.portfolio import TradeReview
from finlab.portfolio.trade_review import tw_corporate_actions

fills = pd.DataFrame(
    {
        "time": ["2026-01-05 09:01", "2026-01-07 10:00"],
        "stock_id": ["1101", "1101"],
        "action": ["buy", "sell"],
        "quantity": [5000, 5000],  # 股數,不是張數
        "price": [35.2, 36.0],
        "fee": [250, 256],  # 該筆實際金額
        "tax": [0, 540],
    }
)
market = TWMarket()
review = TradeReview(
    fills,
    market.get_price("close", adj=False),
    start="2026-01-05",
    initial_holdings={"2330": 1000},
    corporate_actions=tw_corporate_actions(
        ["1101", "2330"], "2026-01-05", "2026-12-31"
    ),
    market=market,
)

建好之後,review 的用法和從券商帳戶建立的完全一樣。

下一步

↑↓ 選擇 Enter 開啟 Esc 關閉