版本升級與結果重現

這頁整理 2.0.19 → 2.2.5 的累積影響：先找出哪些變更碰得到你的策略，再用同一份資料比較升級前後的訊號、部位、交易與報表，確認後才切換正式環境。單純鎖住 finlab 版本，無法固定 pandas 的計算方式或之後更正的資料，所以後半頁說明怎麼把環境、資料與設定都保存下來。

升級的做法

哪些策略結果會改變

財報與季度資料

回測與部位

因子分析、指標與權重

實單下單目標

這兩項只改變下單的目標部位，回測損益與交易紀錄不變。

如果要完全重現舊套件的錯誤計算，需要舊 wheel、同一組相依版本與同一份資料。修正項目通常沒有「沿用舊錯誤」的選項。

季報布林遮罩：dtype 與未知值

2.0.21 是季度布林遮罩修正開始生效的版本，2.2.16 仍保留此修正。季頻數值直接比較產生的 bool 遮罩，或原生 nullable boolean 遮罩，經 index_str_to_date() 轉為公布日後使用 nullable boolean：尚未公布的值保持 pd.NA，~ 取反也保持未知。與一般日頻 bool 遮罩以 & 合併時，結果為一般 bool，未知視為 False。

取反時出現 TypeError

這項修正不會自動把 object 遮罩轉回布林。若先 shift(1)，首列 NaN 可能讓遮罩變成 object；轉日期後仍是 object，~ 仍可能拋出 TypeError: bad operand type for unary ~: 'float'。先確認 mask.dtypes；對只有布林值與缺值的遮罩，明確轉成 nullable boolean 後再轉日期：

mask = (q > 6).shift(1)  # q 是季頻數值表；此路徑的 mask 為 object
dated = mask.astype('boolean').index_str_to_date()
inverted = ~dated  # 未知值仍是 pd.NA

需要一般 bool 或 np.where 時

含 pd.NA 的遮罩直接 astype(bool) 會報 ValueError，直接 np.where 會報 TypeError。只有策略決定「未知視為 False」時才先填值，而且填值與取反的順序會改變選股語意：

import numpy as np

m = (q > 6).index_str_to_date()
selected = (~m).fillna(False)  # 先取反再填值：尚未公布仍不選
opposite = ~m.fillna(False)  # 先填值再取反：尚未公布會變 True
plain_bool = selected.astype(bool)
weights = np.where(selected, 1, 0)

下載完整案例，在原始碼目錄外執行 python upgrade_results.py quarter_bool_object 可重現 object 的取反錯誤；python upgrade_results.py quarter_bool_dtype 示範轉型與填值順序。以 PyPI finlab 2.2.16、pandas 3.0.6、numpy 2.5.4 實跑，轉型後 dtype 為 boolean，8/2 取反為 [True, False]；5/1 尚未公布的 B 取反仍為 pd.NA，先取反再填值為 False，先填值再取反為 True。原本的 quarter_bool 案例仍為 [True, False]，不表示所有 2.2.16 遮罩都會報錯。

預設值、輸出與例外

若停損後希望保留現金，請在回測前明確使用浮點權重；五檔各 0.2 不等同布林部位自動等權重重分配。先排除缺少價格的股票，再計算權重，並確認 position_limit。

用最小案例比對兩個版本

下載完整案例。每個案例只呼叫受影響的計算，使用固定價格、財報與公布日期。季度、交易日曆與時鐘以 fixture 提供，不依賴日後更正的線上資料；sim() 使用真正的回測引擎。執行回測案例需要正常 FinLab 登入，見登入說明。這些合成輸出用來定位版本差異，不能代表真實策略績效。

先將下載的檔案放到原始碼目錄以外，再建立兩個環境，用同一個案例名稱各跑一次：

python3.13 -m venv before
python3.13 -m venv after
before/bin/python -m pip install "finlab==2.0.19" "pandas==2.2.3" "numpy==2.2.6" "TA-Lib==0.8.1" matplotlib
after/bin/python -m pip install "finlab==2.2.4" "pandas==2.2.3" "numpy==2.2.6" "TA-Lib==0.8.1" matplotlib
before/bin/python upgrade_results.py rank_ic
after/bin/python upgrade_results.py rank_ic

把最後的 rank_ic 換成下表的案例名稱，即可用同一段程式比較兩版。

以下實跑環境為 macOS、CPython 3.13.3、pandas 2.2.3、numpy 2.2.6、PyPI 已發布的 FinLab wheel；TA-Lib 案例用 TA-Lib 0.8.1。日期案例採 UTC 主機、固定時鐘。重複欄位案例指定 PYTHONHASHSEED=0。小數在表內四捨五入，完整程式會印出原值。NaN 表示未知或缺值，舊版錯誤也是實跑結果。

讓結果可以重現

要重現一次回測，需要同一份程式、同一組套件版本、同一份輸入資料與同一組 sim() 參數，四樣都要另外保存。

鎖住執行環境

正式策略與新版本的比較環境分開安裝。先保存現有環境：

python -VV > python-version.txt
python -m pip freeze > requirements.lock.txt
python -m pip download --only-binary=:all: -r requirements.lock.txt -d wheels

重建時使用相同的 Python 版本、作業系統與 CPU 架構：

python -m pip install --no-index --find-links=wheels -r requirements.lock.txt

不要把驗證環境的版本號直接套到既有正式環境；先鎖住正式策略實際使用的 finlab、pandas、numpy、pyarrow、scipy、TA-Lib／pandas_ta 等完整相依版本。ML 策略另保存模型、亂數 seed、特徵欄位順序與模型套件版本。升級後重啟 Python／Jupyter kernel，避免記憶體裡仍載入舊套件。

pandas 的版本也會改變結果：pandas 2.2 的 pct_change() 預設仍會先往前填缺值，pandas 3 改為 fill_method=None。策略應明確選擇缺值處理，參見 pandas 2.2 文件與 pandas 3 文件。

import pandas as pd

s = pd.Series([100.0, None, 110.0])
print(s.pct_change().tolist())
# pandas 2.2.3：[nan, 0.0, 0.10000000000000009]
# pandas 3.0.6：[nan, nan, nan]
print(s.pct_change(fill_method=None).tolist())  # 明確保留缺值
print(s.ffill().pct_change(fill_method=None).tolist())  # 明確先填值

2.2.5 起，FinLab 內建的 position.weight.inverse_volatility() 等權重方法、event_study() 與 Position.from_weight() 會先沿用缺值前的價格再計算報酬，pandas 2 與 3 結果相同；策略裡自己呼叫的 pct_change() 仍需依上例明確選擇。

自動保存整支策略的資料輸入

2.2.22 起，data.snapshot() 可將完整一次執行中，data.get()、data.gets() 實際回傳的表格保存到新的本機目錄，包含財報與 sim() 內部讀取的價格、基準、分類等資料，也支援帶日期範圍或指定版本的讀取。請從第一次取資料開始包住整支策略，並在區塊內完成回測及需要的報告計算：

from finlab import data
from finlab.backtest import sim

def research():
    close = data.get('price:收盤價')
    position = (close > close.average(20)).loc['2020-01-01':]
    report = sim(position, resample='M', end_date='2025-12-31', upload=False)
    stats = report.get_stats()
    return report, stats

# 目錄必須尚未存在；成功離開區塊後才寫入完整清單。
with data.snapshot('research-baseline'):
    baseline, baseline_stats = research()

# 保持相同程式、參數、日期區間、Python 與套件版本。
with data.snapshot('research-baseline', mode='replay'):
    restored, restored_stats = research()

# 離開區塊就恢復一般讀取，可另存新資料結果作比較。
with data.snapshot('research-new-data'):
    latest, latest_stats = research()

同一個 Python 程式的工作執行緒也會參與保存／還原；請等所有平行工作完成後才離開區塊。同時只允許一個保存／還原區塊。

還原只讀保存的輸入：缺表、檔案讀不到、讀取範圍／股票母體不同時直接報錯，不會混入本機一般快取或雲端最新值。lazy=True 仍可使用，保存的是運算前的實際資料表。

manifest.json 記錄資料與檔名對照，以及 Python、finlab、pandas、numpy、pyarrow 版本；還原要求這些版本相同。保存的是本次真正用到的輸入，並非所有表在同一時刻的資料版本；不會找回已過期且未備份的舊資料，也不會自動增加新日期。需要額外本機空間，請保留整個目錄；pickle 僅讀取自己保存、可信任的檔案。

這些不會自動保存，需要另外處理：

• 程式碼、完整環境 lock、亂數種子、策略參數及固定的 end_date
• 區塊外已讀入的變數、自訂價格／Market 外部資料、第三方 API 與其他自訂檔案：請將資料讀取移入區塊或另外備份

歷史還原不代表當下可交易；sim() 的登入授權仍照常檢查，結果上傳請設 upload=False。

手動記錄資料版本

2.2.0 起，付費資料會員可用 data.versions() 列出仍保留的 generation、公布／取代時間、大小與 hash，再下載指定 generation。先選 generation，再讀取；不要先抓最新值、再用另一個請求的最新 metadata 當作它的版本。

import json
from pathlib import Path
from finlab import data

datasets = ['price:收盤價', 'etl:adj_close']  # 列出策略的所有輸入
manifest = {}
for dataset in datasets:
    versions = data.versions(dataset)
    if versions.empty:
        raise RuntimeError(f'{dataset} 沒有可用版本')
    row = versions.iloc[-1]
    generation = str(row['generation'])
    snapshot = data.get(dataset, version=generation)
    # 保存實際輸入；檔名與資料集名稱對照也留在 manifest
    filename = f'input-{len(manifest)}.pkl'
    snapshot.to_pickle(filename)
    manifest[dataset] = {
        'generation': generation,
        'hash': str(row['hash']),
        'time_created': str(row['time_created']),
        'file': filename,
    }
Path('data-versions.json').write_text(
    json.dumps(manifest, ensure_ascii=False, indent=2)
)

generation 固定單張表，不代表跨資料表的原子快照。還原價、公布日期、交易日曆、股票母體與產業分類也是輸入，請一併保存。自行保存資料限於你的使用權限；pickle 只讀取自己保存、可信任的檔案。

保存策略與回測設定

保存策略原始碼、實際執行時刻與時區、環境 lock、資料 manifest、經處理的輸入價格及 position，並把所有 sim() 參數明寫，不依賴預設值：市場、成交價、換股頻率／偏移、費率、稅率、停損停利、移動停利、觸價模式、持股上限、retain_cost_when_rebalance、stop_trading_next_period、開始／結束範圍與 upload。自訂 Market、價格矩陣與 benchmark 也需保存程式及輸入，不能只保存名稱。

import json
from pathlib import Path
from finlab.backtest import sim

settings = dict(
    resample='M',
    trade_at_price='close',
    market='TW_STOCK',
    fee_ratio=0.001425,
    tax_ratio=0.003,
    position_limit=1,
    stop_loss=None,
    take_profit=None,
    trail_stop=None,
    touched_exit=False,
    retain_cost_when_rebalance=False,
    stop_trading_next_period=True,
    end_date='2025-12-31',
    upload=False,
)
position.to_pickle('position.pkl')  # 保存你實際傳入的 position
Path('sim-settings.json').write_text(json.dumps(settings, indent=2))
report = sim(position, **settings)
report.to_pickle('report.pkl')
report.to_html('report.html')

report.pkl、HTML 或雲端報告可保存結果，但不會自動封存全部來源資料、相依環境、原始碼與自訂市場。回測報告也不是實際成交紀錄。驗證重現時，依序比較資料值與日期、訊號、position、交易日期與數量、報酬曲線，再比較 Sharpe 等摘要；先固定 end_date，再另外驗證最新一期的換股與實單目標。

用程式追蹤版本影響

公開 feed：JSON、Atom。兩者在文件建置時，從同一份更新日誌與逐項審閱的影響分類產生，涵蓋 2.0.19 起的已發布版本；Unreleased 不會當作已發布。

每個項目包含三個布林標記（results_may_change、behavior_change、experimental）、functions、trigger、references 與完整說明。results_may_change 指計算／選股／回測數字；只改實單目標則用 behavior_change，仍應閱讀說明。false 不代表資料從此不會更正。

下面的程式列出 2.0.19 之後、到 2.2.5 為止所有標記為可能改變結果或行為的項目：

import requests

version = lambda text: tuple(map(int, text.split('.')))
start, end = version('2.0.19'), version('2.2.5')
feed = requests.get('https://finlab.finance/docs/releases.json', timeout=30)
feed.raise_for_status()
for release in feed.json()['releases']:
    if start < version(release['version']) <= end:
        for item in release['items']:
            if item['results_may_change'] or item['behavior_change']:
                print(release['version'], item['functions'], item['trigger'])

區間排除起始版、包含目標版；不要用字串比較版本。兩個 yanked 版本仍列在 feed，避免漏掉曾升級至該版的歷史。分類保留每版當時的變更，所以需注意後續的還原：例如 2.2.1 的 hold_until 與 2.2.4 的快取檢查。文件與 feed 會先上線並驗證，再上傳新版至 PyPI。

下一步