【2026 最新】Timestral 新手教學：用 CSV 比較 AI 與照上週基準（CPU 首跑＋滾動驗收）

你手上有一份每天訂單數的 CSV，想知道下週該備多少貨。看到 AI 可以直接預測數字，很容易先問「怎麼安裝？」這篇 Timestral 新手教學先多問一步：它能否穩定勝過把上週數字照抄過來？

本文寫給第一次接觸時間序列、願意跟著複製幾行 Python 的讀者。你會懂 zero-shot、分位數與未來變數，並用同一份日資料建立公平考卷。這是一套依官方程式整理的評測流程；本文未執行 Timestral 權重推論，因此不提供模型勝率或速度的實測結果。

Mistral 在 2026 年 10 月 15 日公告推出 Timestral。以下功能與授權查核截至 2026 年 10 月 20 日；官方排行榜只是挑選候選模型的起點，你的訂單資料仍要另外考。

先說結論：Timestral 新手教學的把手是「預測＝模型＋公平考卷」

預測＝模型＋公平考卷。模型像請來的備貨顧問；基準像熟悉店務的老闆：「下個星期一，先照上個星期一備。」顧問要拿出比這個方法更有用的結果，才值得增加工作。

先固定三件事：每次向前看七天、每個方法只讀起點以前的數字、保留最後兩週驗收。誤差較小之外，還要看預測區間是否常常漏掉真值，以及為了保住涵蓋率，區間是否寬得難以備貨。

一、先懂四個零件：它預測的是數字，不是聊天答案

① 時序基礎模型：「先看過很多節奏的顧問」

時間序列就是按照時間排好的數字，例如每天訂單、每小時用電量。基礎模型先從大量序列學習可轉移的模式，再處理新序列。Mistral 說明其預訓練以合成資料為主，後續混合真實與合成資料；這支持跨資料使用的設計思路，不能替每一家店保證準確。想補預訓練背景，可讀 AI 模型如何學習。

② Zero-shot：「先不為這份 CSV 重新上課」

Zero-shot 在這裡指直接用預訓練權重推論，不先拿你的資料微調。歷史數字仍會作為輸入，幫助模型判斷最近的尺度與節奏。「不用重訓」與「不用資料整理」是兩件事。

③ 分位數：「把一個答案換成一段範圍」

q50 是中位數；q10 到 q90 組成名目中央 80% 預測區間。它描述模型給出的可能範圍，不是已獲保證的涵蓋率。官方推論程式提供 median 與 quantile 取值方法；我們會把它們與之後公布的真值逐日核對。

④ Covariates：「當時拿得到的提示紙條」

Past-only covariates 是只知道歷史的輔助欄位，例如已量到的來客數；known-future covariates 是預測當下就知道的未來欄位，例如已公告的休假日。天氣預報也可以是提示，但要用當時取得的那一版預報。把事後量到的下週降雨量放進去，等於讓顧問先看答案。

二、Timestral 新手教學：先準備一份可比較的 CSV

第一步「對齊尺子」：固定一天一列

先挑一個門市、一個單位，整理連續 112 天，存成 UTF-8 的 series.csv。這個 16 週長度是本教學的入門設計，並非模型最低要求。欄名用 date,y,is_holiday；date 是 YYYY-MM-DD，y 是當天訂單數，is_holiday 是稍後要用的 0／1 日曆欄。

例如 2026-06-01,120,0 只示範欄位格式，不是測試資料。請先畫折線圖，確認日期沒有重複、每天都有一列，數值採同一個時區與日結規則。零筆訂單填 0；未取得資料保留為缺值，兩者意思不同。

官方 API 可用 NaN 表示缺值，但本教學為了讓三個方法在完全相同的日期上計分，先選沒有缺值的連續區段。若有缺口，先追查紀錄；需要補值時，只用該預測起點以前已知的資訊，並把補值規則對所有方法固定下來。

第二步「先考老闆」：保留兩個簡單基準

第一個叫 naive：預測未來七天，每一天都等於最後一天的值。第二個叫 seasonal naive：把最近一個完整星期依序重播，星期一對星期一。對每天都有觀測的日資料，週期是 7；對交易日或不規則紀錄，不能直接把七列當成一週。

Forecasting: Principles and Practice 的基準方法章節把這類簡單方法當成正式比較對象。假設最近七天是 100、110、120、130、140、80、70，照最後一天就是七個 70；照上週則重播原來七個值。這只是算式示例，沒有宣稱哪個模型贏。

第三步「封住答案」：先驗證，再碰最後兩週

用前 56 天作為第一個歷史窗口，預測第 57–63 天；接著起點移到 63，再預測第 64–70 天。依序用 56,63,70,77,84,91 六個起點挑設定，最後第 99–112 天留作一次最終驗收。每一輪都向前看七天，歷史窗口則逐步增加。

這就是滾動預測起點。TimeSeriesSplit 官方文件解釋了按時間拆分的必要性。這裡的切法模擬每週更新備貨：後一輪可讀到已經發生的前一週真值；不要把全份 CSV 隨機洗牌，再拿看過未來的訓練集來預測過去。

三、CPU 首跑：複製指令，先產出一輪結果

先確認已有 Python 3.10 以上版本與 Git，再開終端機。官方套件設定要求 PyTorch 2.4 以上；第一次安裝依賴與下載權重都需要網路，之後推論可在本機 CPU 進行。

安裝前先核對授權。程式碼是 Apache 2.0，權重另採 Modified MIT。目前條文明列：若你的公司或雇主前一個月全球合併月營收超過 2,000 萬美元，該權重授權不授予使用權，需另洽商用授權。部署到公司環境前，先把這項條件與保留授權通知的義務核對清楚。

以下以 macOS／Linux shell 為例，依序執行 python3 -m venv .venv、source .venv/bin/activate，再執行 python -m pip install "git+https://github.com/mistralai/timestral.git@a534bdbd244d64f3d9d743f46c7bf6fc330ed4ff" pandas。Windows 啟用虛擬環境的路徑是 .venv\Scripts\Activate.ps1。

把 CSV 放在目前目錄，執行 python 進入互動模式。接下來每個行內程式碼各貼一次；它們共用同一個 Python 工作階段。先貼 import numpy as np; import pandas as pd; from timestral import TimestralForecaster，再貼 df = pd.read_csv("series.csv", parse_dates=["date"]).sort_values("date").reset_index(drop=True)。

先守住資料格式：assert len(df) == 112 and df.date.is_unique and df.date.notna().all()，再貼 assert df.date.diff().iloc[1:].eq(pd.Timedelta(days=1)).all()。建立數字陣列 y = df.y.to_numpy(dtype="float32"); assert np.isfinite(y).all()。若出現 AssertionError，回去修資料，先不要刪掉檢查。

載入小尺寸權重：model = TimestralForecaster.from_pretrained("mistralai/Timestral-5M", device="cpu", revision="bdd20cfc15a3fea0e4cb5ccef37f8d3ca7aa335f")。這裡固定程式 commit 與權重 revision，日後比較才知道用的是哪一版；本機 CPU 速度與記憶體用量要另外記錄。

設定第一個起點並推論：c = 56; H = 7; f = model.forecast(y[:c], prediction_length=H)。y[:c]只把前 56 筆送進模型；未來七天的 y 留在外面當考卷答案。

先建立對照資料：result = pd.DataFrame({"date": df.date.iloc[c:c+H].to_numpy(), "actual": y[c:c+H], "last": np.repeat(y[c-1], H), "week": y[c-7:c]})。再貼 result["median"] = f.median[0,0].cpu().numpy(); result["q10"] = f.quantile(0.1)[0,0].cpu().numpy(); result["q90"] = f.quantile(0.9)[0,0].cpu().numpy()。

最後儲存 result.assign(origin=c).to_csv(f"result-{c}.csv", index=False)。你應得到七列結果，包含真值、照最後一天、照上週、中位數與區間。它比只看一張漂亮曲線更好核對。這段是單輪評測範例，尚未包含批次排程、例外重試與正式部署。

四、把單輪變成驗收：誤差、假日與區間分開看

①「換六個起點」：避免挑到剛好好猜的一週

把 c 依序換成 63、70、77、84、91，每次重新執行從推論到儲存的四段指令，保留六份 CSV。這六週用來決定模型與欄位；先寫下採用條件，例如關鍵週誤差不惡化、整體誤差改善足以抵銷維護成本，再看結果。

每一輪可貼 print(result[["last","week","median"]].sub(result.actual, axis=0).abs().mean()) 計算 MAE（平均絕對誤差）：每天「猜錯多少」取絕對值後平均，單位仍是訂單數。單一序列、相同七天比較才有意義；跨店鋪不要直接把不同量級混在一起。

例如真值 100、預測 90，絕對誤差是 10；七天誤差加總後除以 7。六輪同樣各七天，將六個 MAE 平均即可得到這 42 天的整體 MAE，也要保留逐週結果。若某方法 MAE 從 10 降到 8，改善為 20%；這是算式示例，不是 Timestral 成績。

②「只加一張提示紙」：比較有無台灣假日

若你的序列確實與台灣假日有關，可從 政府行政機關辦公日曆逐日對齊日期，將休假日編成 1、其他日編成 0，納入補班與調整放假。這是行政機關行事曆，不等於每家店的營業規則；門市實際休息、促銷與尖峰，應分別記錄。

先檢查 assert df.is_holiday.isin([0,1]).all()，再貼 known = df.is_holiday.iloc[:c+H].to_numpy(dtype="float32")[None,None,:]。它包含歷史與預測七天，維度是「一條序列、一個提示欄、時間」。重新推論 f = model.forecast(y[:c], prediction_length=H, known_covariates=known)，再建立 result、填入三個預測欄位，另存 result.assign(origin=c).to_csv(f"holiday-result-{c}.csv", index=False)。

同樣六輪各做一次，僅改變有無假日欄。若歷史回測使用後來修訂的日曆，仍可能偷看未來；請保留在各起點當時已公告的版本。其他地區可換成當地日曆。只有零星假日的短窗口，得到的是小樣本線索，還要另看多個假期及旺淡季。

③「量雨傘」：涵蓋率高，也要寬度可用

貼 print(((result.actual >= result.q10) & (result.actual <= result.q90)).mean()) 看實際涵蓋率，再貼 print((result.q90-result.q10).mean()) 看平均區間寬度。涵蓋率就是落在上下界之間的日數除以總日數；例如 10 天中 8 天落在區間內，就是 80%。

七天少一天命中，比例就變動約 14.3 個百分點，別用一週替區間校準下定論。把六週的命中數與總日數合併，再按預測第幾天、假日與非假日拆開看。區間即使全部命中，若寬到無法決定備貨量，也仍需要改善；可進一步用分位數損失評分，兼顧過高與過低的代價。

④「最後才拆封」：固定方案後考最後兩週

完成六週選擇後，固定是否加入假日、權重與其他設定。用 c＝98 驗收第 99–105 天，再於一週後的模擬起點 c＝105 驗收第 106–112 天；兩次都照前面指令保存結果。後一輪讀入前一週已發生的真值，符合每週更新的使用方式。看到最後成績後再改設定，這兩週就變成開發資料，需要另外保留新的最終考卷。

如果模型在多週及關鍵日都帶來可用改善，再評估放到流程裡；如果照上週表現接近，先保留便宜易懂的基準，也是一個完成評測的答案。若每次錯的都是缺貨日，先問 y 是否記錄了「賣出的量」，而不是「客人想買的量」；資料定義常比換大模型更早影響決策。

五、常見問題：八個直接答案

1. Timestral 可以像 ChatGPT 一樣對話嗎？

這裡用的是數值預測 API。輸入歷史陣列與輔助欄位，輸出未來各步的數字與分位數；這份流程不需要聊天提示詞。

2. Zero-shot 代表不用切資料嗎？

不代表。它省去的是為這份資料微調權重，公平驗收仍要把起點後的目標值留在模型外面。

3. 沒有 GPU 可以開始嗎？

可以。官方提供 CPU 推論；教學選小尺寸先驗證流程，實際耗時請在你的電腦與資料上記錄。

4. 模型支援缺值，就直接把所有空白填零嗎？

先分清原因。缺資料用缺值語意，真實零訂單才是 0；本教學的完整區段設計，是為了先把基準比較做對。

5. 加入未來假日，就一定比較準嗎？

不一定。已知資訊提供了條件，效益要靠同起點、有無欄位的比較，且行政機關休假不等於門市需求。

6. q10 到 q90 每次都會包住真值嗎？

這是名目中央 80% 的區間，不是每個點都命中的承諾。要在保留資料上同時計算涵蓋率與寬度。

7. 官方宣稱排行榜勝出，能直接取代照上週嗎？

先做自己的考卷。資料、預測長度與評分方式改變，排名的適用範圍也改變；本文沒有對你的 CSV 提供勝負結論。

8. 什麼時候值得往系統整合前進？

在你能說清楚固定哪個版本、在哪些週改善、失敗時用什麼基準接手之後。要理解模型以外的執行層，可接著看 Agent Harness 原理。

給新手的三個重點

第一，先把日期與真值整理好；第二，照最後一天與照上週都要考；第三，最後兩週留到方案固定後才拆封。模型中位數、假日欄與區間是不同問題，逐一增加，才知道改善從哪裡來。