為路由器標註版本、監看其移交情形,並以人工作為後備
閱讀約需 37 分鐘 分鐘,8 節 中共有 4 個範例。
讀完本章後,你將能夠:依產生答案的各個部分為路由器命名;在路由載入這些部分之前先檢查它們;對照既定基準,計算每個訊息視窗的移交率;並說明每則被移交的訊息會送往何處。
第 8 章把路由器放在一個路由之後,每個答案都帶有一個團隊,或一個將訊息轉交給人員的旗標。當一個路由連續數月處理銀行的客服訊息時,會出現三個路由本身無法回答的問題。目前是哪個模型在回答?它的檔案是否就是已經檢查過的那些?被它移交出去的訊息是變多還是變少?本章為每個問題提供一項控制機制和一個列印出來的計數。這些控制機制是本書自行設計的。
本章涵蓋自行運行模型所額外帶來的事項:版本、以人工作為後備,以及重新訓練。一般服務的監看,包括儀表板、日誌與警報,屬於生產環境監控專書的範疇,本章不再重複。
以組成部分為路由器命名
路由器不只是模型本身。它包含基礎模型、在該基礎模型上訓練出的 adapter、將訊息轉交給真人的門檻值,以及產生該 adapter 的資料與訓練配方。這幾項只要有任何一項不同,兩個路由器對同一則訊息就可能給出不同的回應。一行只寫著「路由器」的日誌,無法分辨它們。
adapter 的檔案不包含基礎模型。PEFT checkpoint guide 指出,儲存下來的權重只有 adapter 模組的參數,不含基礎模型的任何內容。因此 adapter 必須指明自己是在哪個基礎模型上訓練的,而且這個名稱必須精確。本書以 commit 來指明基礎模型,也就是 examples/models.toml 中的釘選(pin),因為短的 commit 雜湊值不能用。Hugging Face download guide, at v2.4.0 規定,只要指定 commit,就必須使用完整長度的雜湊值。若未指定任何修訂版本,下載時會取得 main 分支目前的內容。分支名稱會隨分支移動,因此它不是釘選。第 5 章已將基礎模型的修訂版本,連同門檻值、資料 commit 與配方雜湊值,一併記錄在 adapter 的 manifest 中。
版本寫在名稱裡。banking77-lora-v1 是已記錄的 LoRA adapter,使用 dev 切分以外的訓練資料列訓練一個 epoch,為第一版。以相同配方重新訓練並記錄的新版本是 v2,它有自己的名稱與自己的 manifest。manifest 中沒有獨立的版本欄位,名稱本身就是版本,而第 8 章的路由會將 adapter 名稱的後綴回報為版本。對 banking77-lora-v1 而言,該後綴是 v1。第 7 章的 int8 副本是另一個模型 banking77-lora-v1-int8,此路由並不提供該模型。它的後綴會是 int8,所以以名稱提供服務的副本需要有自己的版本欄位。
第一項檢查會讀取 manifest,並將其中的基礎模型修訂版本與釘選值比對。它先印出 adapter 的名稱,再印出比對結果:
1"""Show what the adapter check does before a route loads an adapter, and what it does to two edited copies.2The point rests on the "route may load" line and on the two "refused by make_app" lines."""3import os45os.environ["HF_HUB_OFFLINE"] = "1"6os.environ["TRANSFORMERS_OFFLINE"] = "1"7import tempfile # noqa: E4028import warnings # noqa: E4029from pathlib import Path # noqa: E4021011import torch # noqa: E4021213torch.set_num_threads(2)1415import router_lib # noqa: E4021617router_lib.setup_runtime()18RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"19# check_adapter hashes the manifest, the outputs and the LoRA settings; pinned is the manifest's digest matching its pin20manifest, s_ok, s_n, f_ok, f_n, pinned = router_lib.check_adapter(RECORDED)21# the base pin in models.toml, compared with the manifest's base revision22base = router_lib.pinned_revision(manifest["model"]) == manifest["model_version"]23print(f"adapter: {manifest['adapter']}")24print(f"base revision matches pin: {'yes' if base else 'no'}")25print(f"manifest matches pin: {'yes' if pinned else 'no'}")26print(f"settings matching: {s_ok}/{s_n}")27print(f"files matching: {f_ok}/{f_n}")28print("route may load: " + ("yes" if base and pinned and s_ok == s_n and f_ok == f_n else "no"))29with tempfile.TemporaryDirectory() as tmp:30 # changes a manifest field that is neither a LoRA setting nor an output file, so only the manifest digest sees it31 threshold = router_lib.edited_copy(RECORDED, Path(tmp) / "threshold", "manifest.json", "handoff_threshold", 0.0)32 # adds a key that LoraConfig does not know, to the config the settings are read from33 extra = router_lib.edited_copy(RECORDED, Path(tmp) / "extra", "adapter/adapter_config.json", "future_key", 1)34 for label, folder in [("threshold copy", threshold), ("extra-key copy", extra)]:35 _, s_ok, s_n, f_ok, f_n, pinned = router_lib.check_adapter(folder)36 print(f"{label}: manifest matches pin {'yes' if pinned else 'no'}, settings {s_ok}/{s_n}, files {f_ok}/{f_n}")37 print(f"{label} refused by make_app: {'yes' if router_lib.refused_by_make_app(folder) else 'no'}")38 with warnings.catch_warnings(record=True) as caught:39 warnings.simplefilter("always")40 router_lib.load_classifier(extra / "adapter")41 named = [w for w in caught if "future_key" in str(w.message)] # only the warning about the extra key42 print(f"warnings naming the extra key while PEFT loads the copy: {len(named)}")43 # the warning's first sentence: the text up to the first ". " in its message44 print(f"that warning: {named[0].category.__name__}: {str(named[0].message).split('. ')[0]}.")
python adapter-manifest-check.pyadapter: banking77-lora-v1
base revision matches pin: yes
manifest matches pin: yes
settings matching: 3/3
files matching: 3/3
route may load: yes
threshold copy: manifest matches pin no, settings 3/3, files 3/3
threshold copy refused by make_app: yes
extra-key copy: manifest matches pin yes, settings 3/3, files 2/3
extra-key copy refused by make_app: yes
warnings naming the extra key while PEFT loads the copy: 1
that warning: UserWarning: Unexpected keyword arguments ['future_key'] for class LoraConfig, these are ignored.
名稱帶有版本 banking77-lora-v1,且基礎模型修訂版本與釘選值相符(yes)。讀者在讀取任何檔案之前,就能以釘選值核對這兩個部分。
實用原則: 以基礎模型修訂版本、adapter 名稱(版本包含在名稱中)、資料 commit、門檻值與配方雜湊值為路由器命名,並在路由提供服務之前,將這五項都寫入 adapter 的 manifest。每次載入 adapter 時,都要將 manifest 中的基礎模型修訂版本與 examples/models.toml 中的釘選值比對。釘選值若已移動,就代表基礎模型不同,adapter 在提供服務之前需要重新檢查。
對照介面卡的檔案與其資訊清單
載入並不等於版本檢查。PEFT checkpoint guide 指出,LoRA 設定中的大多數項目並非載入模型所必需,因此即使設定被人手動改過,載入仍可能成功。載入成功並不能證明該介面卡就是已釘選的那一個。下方的額外鍵值副本仍然能載入,而且載入時會產生一則點出該額外鍵值的警告。在研究用的探測中,基礎模型不相符確實會在載入時失敗,並出現 state-dict 錯誤;本範例不會印出這種情況。
因此,這項檢查把介面卡與其資訊清單分成三個部分來比對。第一,它自行計算 manifest.json 的 SHA-256,並與 examples/adapter-pins.json 中以該介面卡名稱釘選的雜湊值比對。這個釘選涵蓋資訊清單內的每個欄位,包括門檻值、基礎模型修訂版本與輸出檔的雜湊值。第二,它計算資訊清單所列每個輸出檔的 SHA-256,並與資訊清單記錄的雜湊值比對。第三,它讀取設定中的三項 LoRA 設定,也就是秩(rank)、決定縮放的 alpha 以及目標層,並與資訊清單比對。輸出的各行會給出每一項相符的數量,以及路由是否可以載入該資料夾。
對於已記錄的介面卡,其資訊清單與釘選相符(yes),3/3 項設定與 3/3 個檔案相符,因此路由可以載入它。
這項檢查也會對兩份經過編輯的副本執行,每一份各有一行輸出。第一份在資訊清單中將 handoff_threshold 改為 0,其輸出行為 manifest matches pin no, settings 3/3, files 3/3。它的設定與檔案仍然相符,因為門檻值不屬於設定,也沒有任何輸出檔被更動。只有資訊清單本身的雜湊值能察覺這項變更,所以這份副本會被拒絕。第二份在其設定中多加了一個額外鍵值,其輸出行為 manifest matches pin yes, settings 3/3, files 2/3。它的設定仍然相符,但檔案檢查會拒絕它,因為設定檔的雜湊值已不再相符。PEFT 仍會載入該副本,而載入時產生的警告中,1 點出了這個額外鍵值。完整內容如下:UserWarning: Unexpected keyword arguments ['future_key'] for class LoraConfig, these are ignored. 載入會傳回一個忽略該鍵值的模型,而這則警告就是 PEFT 對此事的全部說明。警告不是拒絕,拒絕該副本的是這項檢查。
第 8 章中的路由會執行這項檢查。它的 make_app 在載入模型之前先呼叫 check_adapter,同時也會將資訊清單的基礎模型修訂版本與釘選值比對。任何不符都會引發錯誤,因此未通過的副本在模型進入記憶體之前就會被拒絕。門檻值副本被 make_app 拒絕(yes),額外鍵值副本也一樣(yes)。這項檢查信任程式碼儲存庫。其釘選的雜湊值存放在 examples/adapter-pins.json,與程式碼放在一起,所以只修改資料夾而未修改釘選檔的讀者會被拒絕,兩者都修改的讀者則不會。因此,釘選檔應當與其他程式碼一樣接受審查。
實用原則: 在任何路由載入介面卡之前先執行這項檢查。將資訊清單的 SHA-256 與程式碼一起釘選,計算相符的設定與檔案數量,連同總數印出每一項計數,並在任一計數不足或資訊清單雜湊值不相符時拒絕載入。雜湊值取自磁碟上的檔案,而且檢查與載入須使用同一批檔案,期間不得有任何程序寫入這些檔案。
監看轉交率
轉交率是指一個時間窗內,信心低於門檻的訊息數除以該時間窗內的所有訊息數。第 2 章已定義過這個指標,本章則隨時間觀察它。要進行監看,需要三項要素:時間窗、基準線,以及判斷某個時間窗偏離基準線過遠的規則。
基準線是開發集在轉接器門檻下的轉交率。dev_handed_off 的算法是將所有開發集訊息各路由一次,再計算轉交的數量,結果為 148/1003 (14.8%)。第 5 章的門檻範例印出相同的計數 148/1003 (14.8%)。兩者一致,因此這個基準線就是該章用來選定門檻的那一個。
開發集的基準線並不是對收件匣的預測。開發集是從訓練資料列中,依團隊逐一抽取而來;測試樣本則取自測試集。兩者都不是收件匣流量的樣本,而且即時訊息中各團隊的組成比例也不得而知。因此,時間窗與基準線之間的差距只是一個要追問的問題,本身並不能回答這個問題。
偏離規則是本書自行訂定的選擇,並非來自某個資料來源的數字。當某個時間窗的轉交率與基準線相差超過指定的百分點數時(不論高於或低於),即視為偏離。印出的規則內容為 more than 10 points from the baseline。執行監看的人應自行選定一個數字,並在閱讀各時間窗之前先寫下來。
已提交的測試樣本 test_1001 沒有日期,因此各時間窗取自其前 100 則訊息。前兩個時間窗各有 25 則訊息,是樣本中最前面的訊息,依樣本順序排列。第 3 週與第 4 週是重播,並非新的流量。這兩週的做法是:範例取樣本接下來的訊息,依路由器的信心由低到高排序,再將排序後的清單分成兩半。範例在印出的那一行中將重播標示為模擬,即 simulated replay of sample messages 51 to 100。這段重播刻意產生分散的信心分布,用來呈現規則面對偏斜時間窗時的反應;和基準線一樣,它並不代表收件匣的實際情況。
1"""Watch the router's hand-off rate week by week on a fixed, ordered sample of test_1001, against the dev baseline.2The point rests on the "drift" lines and on the "lowest confidence" and "right" lines of weeks 3 and 4, which the output3labels as a simulated replay."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import json # noqa: E4021112import torch # noqa: E4021314torch.set_num_threads(2)1516import router_lib # noqa: E4021718router_lib.setup_runtime()19RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"20# the threshold is read from the manifest, not typed here21threshold = json.loads((RECORDED / "manifest.json").read_text())["handoff_threshold"]22tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")2324handed_dev, n_dev = router_lib.dev_handed_off(model, tokenizer, threshold)25base = 100 * handed_dev / n_dev26print(f"dev hand-off rate (baseline): {handed_dev}/{n_dev} ({base:.1f}%)")27print(f"drift rule: more than {router_lib.DRIFT_POINTS:.0f} points from the baseline")28print("weeks 3 and 4: simulated replay of sample messages 51 to 100")29test = router_lib.read_rows("test")30# simulated=True (the default) adds weeks 3 and 4: messages 51 to 100, lowest confidence first, ties by position31for w, (rows, preds, confs) in enumerate(router_lib.watch_weeks(model, tokenizer, threshold), 1):32 n = len(rows)33 handed = sum(router_lib.handoff(c, threshold) for c in confs)34 rate = 100 * handed / n35 # the messages the router keeps, each with its gold team: test row i holds (text, gold team)36 kept = [(p, test[i][1]) for i, p, c in zip(rows, preds, confs) if not router_lib.handoff(c, threshold)]37 right = sum(p == g for p, g in kept)38 print(f"week {w} messages: {n}")39 print(f"week {w} handed off: {handed}/{n} ({rate:.1f}%)")40 # abs makes the rule two-sided, so a fall in the rate drifts as a rise does41 print(f"week {w} drift: {'yes' if abs(rate - base) > router_lib.DRIFT_POINTS else 'no'}")42 print(f"week {w} lowest confidence: {min(confs):.3f}")43 print(f"week {w} right among messages not handed off: {right}/{len(kept)}")
python handoff-windows.pydev hand-off rate (baseline): 148/1003 (14.8%)
drift rule: more than 10 points from the baseline
weeks 3 and 4: simulated replay of sample messages 51 to 100
week 1 messages: 25
week 1 handed off: 6/25 (24.0%)
week 1 drift: no
week 1 lowest confidence: 0.479
week 1 right among messages not handed off: 17/19
week 2 messages: 25
week 2 handed off: 4/25 (16.0%)
week 2 drift: no
week 2 lowest confidence: 0.378
week 2 right among messages not handed off: 19/21
week 3 messages: 25
week 3 handed off: 9/25 (36.0%)
week 3 drift: yes
week 3 lowest confidence: 0.246
week 3 right among messages not handed off: 16/16
week 4 messages: 25
week 4 handed off: 0/25 (0.0%)
week 4 drift: yes
week 4 lowest confidence: 0.981
week 4 right among messages not handed off: 25/25
由於樣本很小,時間窗也很小:四個時間窗各有 25 則訊息。在這種大小的時間窗中,一則訊息就占轉交率的 4 個百分點,因此一則訊息就可能讓時間窗越過規則的界線。實際收件匣的監看需要夠大的時間窗,才不會讓單一訊息決定是否發出警示。時間窗的大小應寫入報告,並在閱讀各時間窗之前先行說明。
第 1 週與第 2 週都在規則範圍內,而重播的兩週則朝兩個方向偏離。四個時間窗的結果如下,各附計數與旗標。
- 第 1 週轉交 6/25 (24.0%),偏離旗標為 no。
- 第 2 週轉交 4/25 (16.0%),偏離旗標為 no。
- 第 3 週轉交 9/25 (36.0%),偏離旗標為 yes。
- 第 4 週轉交 0/25 (0.0%),偏離旗標為 yes。
第 4 週是讀者應仔細檢視的案例。在這條規則下,轉交率降到零也算偏離,因為規則把下降與上升同樣視為變化。轉交率為零,是因為第 4 週的最低信心為 0.981,高於門檻,所以該時間窗內沒有任何訊息被轉交。在路由器保留的訊息中,答對的有 25/25。這個時間窗中全是有信心且正確的回答,偏離旗標回報的是其轉交率已經改變,並不表示路由器出了錯。
第 3 週則是另一種時間窗。它的最低信心為 0.246,轉交數升至 9/25 (36.0%),而路由器在其保留的訊息中答對 16/16。轉交增加表示有更多訊息送到人的手上,但這本身並不能顯示是哪一種原因造成增加:是訊息有變化、出現的團隊有變化,還是模型有變化。路由無法判斷是哪一種,因為它的回答並未附帶訊息的紀錄,第 8 章對它所回傳的比率也說了同樣的事。
實用原則: 對每個大小相同的時間窗計算轉交數,連同分母一併印出每個計數,並將每個比率與開發集在轉接器門檻下的基準線比較。在閱讀各時間窗之前,先訂定偏離規則及其百分點數,並寫入報告。出現偏離的時間窗,應視為閱讀其訊息與所屬團隊的理由,而不是對路由器的定論。
轉交給人員的訊息抽樣
轉交監看會統計有多少訊息被交給人員處理。它留下兩個問題未答:路由器對轉交出去的訊息判斷是否正確,以及對自行保留的訊息判斷是否正確。本節說明第一個問題要如何回答。這是下一步的工作,本章不抽取樣本,不回報標籤,也不給出相關數字。
做法是由人員為轉交訊息的一份樣本標註,樣本以固定的種子抽取,標籤則表明人員為每則訊息選擇哪一個團隊。把這些標籤與路由器的模型原本會選擇的團隊相比,就能看出在路由器沒有把握的訊息上,兩者有多常不同。路由器沒有把握的訊息,正是人員最該檢查其選擇的訊息,因此這份樣本應當最先抽取。自行建立樣本的讀者,可以用公開資料集的標準標籤(gold labels)代替人員的標籤,並應在報告中說明這一點。
轉交訊息的樣本,無法說明路由器在自行保留的訊息上表現如何。保留的訊息是路由已經回覆答案的訊息,轉交機制不會把它們送給人員。只有在路由回覆之後,再由人員檢查其中一部分,才能估計它們的準確率。對保留訊息的檢查是第二份樣本,以相同方式抽取,並不是轉交訊息樣本的附帶產物。衡量指標是未轉交訊息上的準確率,需附上其計數與分母,與第 5 章的設定相同。
實用原則: 建立樣本時,以固定的種子抽取,印出已標註的訊息數量,並回報路由器所選團隊與人員所選團隊一致的頻率及其計數。以相同的進度標註一份保留訊息的樣本,並且只從該樣本讀取路由器在保留訊息上的準確率。切勿從轉交訊息的樣本推得保留訊息的比率。
退回由人工處理
如同第 8 章所建構的,路由對於轉交出去的訊息只回傳一個旗標,不回傳團隊。這則訊息仍然必須有後續處理。本章的規則是:轉交出去的訊息一律交給人工處理。代用模型 Qwen3-4B-Instruct-2507 的已記錄回答,可以作為建議隨轉交的訊息一併送出,並標明為代用模型的回答,由人員決定是否採用。代用模型在 test_1001 上的回答記錄於 standin-baseline(見第 2 章)。對於轉交出去的訊息,絕不回傳路由器所判定的團隊。
路由的 JSON 含有 team、confidence、handed_off、adapter 與 version,其中沒有任何欄位說明是誰作答。因此,退回處理所產生的回答絕不能以這種形式送出。若讀者希望在回應中附上建議,應自行刻意新增一個欄位,並在回應中說明該欄位的用途。
本書不教導以呼叫託管模型作為退回處理的方式,也不為代用模型設定門檻。它的回答來自一份記錄,由退回處理的腳本讀取。該腳本衡量建議正確的頻率,但不依據這項衡量結果做任何決定。
1"""Hand each handed-off message to a person, with the stand-in's recorded answer as a labelled suggestion.2The point rests on the "team returned for a handed-off message" line and the "suggestions right" line."""34import os56os.environ["HF_HUB_OFFLINE"] = "1"7os.environ["TRANSFORMERS_OFFLINE"] = "1"89import json # noqa: E4021011import torch # noqa: E4021213torch.set_num_threads(2)1415import router_lib # noqa: E4021617router_lib.setup_runtime()18RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"19# the threshold is read from the manifest, not typed here20threshold = json.loads((RECORDED / "manifest.json").read_text())["handoff_threshold"]21tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")22test = router_lib.read_rows("test")23standin = router_lib.standin_rows() # a dict from test row index to the stand-in's answer, for the rows it answered24rows, handed = [], []25# simulated=False keeps weeks 1 and 2 only: the replay belongs to the watch, not to this example26for weekly_rows, _, confs in router_lib.watch_weeks(model, tokenizer, threshold, simulated=False):27 rows += weekly_rows28 handed += [i for i, c in zip(weekly_rows, confs) if router_lib.handoff(c, threshold)]2930# the list of records stands in for the person's queue, which the book does not build31# the suggestion is None where the stand-in has no recorded answer, and the team is always None32queue = [{"index": i, "team": None, "suggestion": standin[i]["label"] if i in standin else None} for i in handed]33suggested = [r for r in queue if r["suggestion"] is not None]34right = sum(r["suggestion"] == test[r["index"]][1] for r in suggested) # index 1 of a test row is its gold team3536print(f"messages routed: {len(rows)}")37print(f"handed off by the router: {len(handed)}/{len(rows)} ({100 * len(handed) / len(rows):.1f}%)")38print(f"sent to a person: {len(queue)}/{len(handed)}")39print(f"suggestions attached: {len(suggested)}/{len(handed)}")40print(f"suggestions right: {right}/{len(suggested)}")41print(f"team returned for a handed-off message: {sum(r['team'] is not None for r in queue)}")
python fallback-to-larger-model.pymessages routed: 50
handed off by the router: 10/50 (20.0%)
sent to a person: 10/10
suggestions attached: 10/10
suggestions right: 4/10
team returned for a handed-off message: 0
此範例對前兩個視窗進行路由,共 50 則訊息,路由器轉交其中 10/50 (20.0%) 則。每則轉交的訊息各產生一筆記錄,輸出會統計送交人工的記錄數。凡代用模型有已記錄回答的訊息,記錄便將該回答作為建議附上。在這些記錄中,有 10/10 筆附有建議,而轉交訊息被回傳團隊的數量為 0。這份記錄清單用來代表人員的待處理佇列。本書並不建構該佇列;若讀者自行建構,應讓每筆記錄與其訊息保存在一起。
在附有建議的轉交訊息中,建議正確的訊息有 4/10 則。這不到一半,也正是建議只呈現給人員、絕不當作答案使用的原因。退回處理的腳本並未在路由器自行處理的訊息上衡量代用模型。此樣本中每則轉交的訊息都附有建議,本章並不主張收件匣整體也是如此。
實用原則: 將每則轉交的訊息送交人工處理。代用模型的已記錄回答可以隨附,並標明為建議。絕不為它回傳團隊,也絕不在沒有說明作答者欄位的情況下,把建議放進路由的回應形式。在讀者決定該給這些建議多少份量之前,先統計正確的建議數,並連同其分母一併列出。
依觸發條件重新訓練
視窗出現漂移,是提醒我們去檢查的訊號,本身並不會直接啟動重新訓練。本書設定了三個觸發條件,本節逐一說明。第一個是漂移,也就是將本章監測所用的規則套用在連續的視窗上。本書在連續兩個視窗都漂移時重新訓練;這個數字沒有任何來源可循,你也可以選擇其他數字,但必須事先載明。第二個觸發條件是在路由器所回傳的 77 個團隊之外新增一個團隊。路由器沒有該團隊的訓練資料列,而人工標註會顯示該訊息屬於這 77 個之外的團隊。第三個是路由器保留的訊息中,錯誤團隊增加,並由上一節的保留訊息樣本確認。這並不是已轉交訊息的樣本,因為已轉交訊息的團隊從不回傳,所以那裡出現錯誤團隊在預期之內,也不造成損害。下方的重新訓練腳本只演練第一個條件。記錄下來的資料中沒有新增的團隊,也沒有人工標註,因此第二與第三個條件在這裡只是沒有測試的規則。
1"""Decide whether to retrain, as a rule over the weekly drift flags from handoff-windows. The rule is the book's choice,2not a sourced threshold: retrain when two consecutive weeks drift, that is, their hand-off rate is more than3router_lib.DRIFT_POINTS from the dev baseline. The point rests on the "retrain trigger" line."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import json # noqa: E4021112import torch # noqa: E4021314torch.set_num_threads(2)1516import router_lib # noqa: E4021718router_lib.setup_runtime()19RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"20# the threshold is read from the manifest, not typed here21threshold = json.loads((RECORDED / "manifest.json").read_text())["handoff_threshold"]22tokenizer, model = router_lib.load_classifier(RECORDED / "adapter")23handed_dev, n_dev = router_lib.dev_handed_off(model, tokenizer, threshold)24base = 100 * handed_dev / n_dev2526drifting, run, longest = [], 0, 027# the default simulated=True: weeks 3 and 4 are the replay, the same four windows the watch reads28for rows, _, confs in router_lib.watch_weeks(model, tokenizer, threshold):29 rate = 100 * sum(router_lib.handoff(c, threshold) for c in confs) / len(rows)30 flag = abs(rate - base) > router_lib.DRIFT_POINTS # two-sided, as in the watch31 drifting.append(flag)32 run = run + 1 if flag else 033 longest = max(longest, run)34 print(f"week {len(drifting)} drift: {'yes' if flag else 'no'}")3536print(f"weeks drifting: {sum(drifting)}/{len(drifting)}")37print(f"longest run of drifting weeks: {longest}")38print("rule: retrain when two consecutive weeks drift")39print("retrain trigger: " + ("fired" if longest >= 2 else "not fired"))
python retrain-trigger.pyweek 1 drift: no
week 2 drift: no
week 3 drift: yes
week 4 drift: yes
weeks drifting: 2/4
longest run of drifting weeks: 2
rule: retrain when two consecutive weeks drift
retrain trigger: fired
重新訓練腳本將漂移規則依序套用在與監測相同的四個視窗上,找出有 2/4 個視窗發生漂移,最長連續段為 2。第 3 週與第 4 週促成了這個結果,因為它們就是監測中的重播資料。觸發結果為 fired,是因為重播的建構方式,所以這次執行顯示的是規則如所述般運作,而不是收件匣本身發生了什麼。
重新訓練真正啟動時,會沿用第一個轉接器(adapter)的相同路徑。它是存放在 recordings/ 中的一份記錄,與 banking77-lora-v1 相同,由該處的腳本寫出,並寫出欄位相同的資訊清單(manifest)。它會被命名為同一配方的下一個版本,因此重新訓練後的轉接器是 v2。它的門檻會依第 5 章的規則,在開發切分上重新選定,絕不使用測試樣本。接著,重新訓練後的資料夾必須將其資訊清單的摘要值加入 examples/adapter-pins.json,作為一項由他人審查的儲存庫變更。在此之前,make_app 會拒絕以它建置應用程式。舊的轉接器會保留原狀,直到 make_app 以新資料夾建置出應用程式為止。
實用原則: 在你所載明的觸發條件成立時才重新訓練,不要因為單一視窗漂移就重新訓練。將觸發條件、其數字與規則,和達成條件的視窗寫在一起。重新訓練後的轉接器是一份以下一個版本命名的記錄,其資訊清單摘要值已固定,門檻也在開發切分上重新選定。在新的轉接器通過 make_app 中的檢查之前,保留前一個轉接器。
正式環境中會出什麼問題
- 有人手動編輯了資訊清單(manifest)。 資訊清單的摘要值(digest)已被固定,因此檢查會拒絕它。若檢查信任儲存庫的內容,只有同時編輯固定檔(pins file)才能繞過它,而那是一項有人審查的變更。
- 某個固定版本(pin)改變了。
examples/models.toml中的基礎固定版本可能在某個配接器(adapter)之下改變,而該配接器的資訊清單仍然指向舊的修訂版本。make_app會比較兩者,並拒絕建置。 - 後備機制依錯誤的尺度進行路由。 來自從未針對該門檻校準之模型的信心值,並不能作為閘門。因此,本書的後備機制從不進行路由,建議只會隨著人員的訊息一併傳遞。
- 視窗太小。 在 25 則訊息的視窗中,一則訊息就占 4 個百分點。此時一個旗標只反映一兩則訊息,而依此採取行動的讀者,其實是在對雜訊做出反應。
- 比率變動卻無從解釋。 該路由的回答不帶有訊息的紀錄,因此比率的變動,是一個必須從訊息及其所屬團隊來回答的問題,並搭配本章在後續步驟中所說明的抽樣來進行。
第一類失敗在應用程式建置時就能察覺。遭拒絕的資料夾會在啟動時引發錯誤,因此在啟動時建置應用程式的部署,會在任何訊息失敗之前就發現有問題的資料夾。其他失敗則顯示在計數上。變動的交接率會顯示在視窗的計數中,而漂移規則會將它回報出來。對錯誤的訊息作出回答的後備機制,會顯示在建議的計數上,其餘的問題則由人工標籤的抽樣來揭露。
實用原則: 在啟動時以及每個視窗中,將各項控制的計數印在讀者看得到的地方,並把能揭露失敗的計數與它們所解釋的比率放在同一份報告中。
此部分尚未翻譯,因此以英文呈現。
The decisions this chapter made
- A handed-off message always goes to a person. The stand-in's answer, when there is one, is a labelled suggestion, and the chapter counts how often it is right.
- The version check pins the SHA-256 of each adapter's
manifest.jsoninexamples/adapter-pins.json, andmake_apprefuses to build on any mismatch or a moved base pin. - The drift rule is 10 points from the dev baseline, in either direction, on windows of 25 messages.
- A retrain is due when two consecutive windows drift. The second and third triggers are stated rules, not tested here.
Chapter 10 uses the same measures as this chapter.
All four are the book's choices; see the drift rule. Together the controls check which model answers, count what it hands off and send each handed-off message to a person. The fallback rule follows the rule from chapter 1 that a flagged message goes to a person. The pin rule trades a review of the repository for a check that a load alone cannot make.
Working rule: Write each decision above into the report with its number and whether it is the book's choice or a sourced figure. Change a decision only by changing the rule it names, and rerun the examples that print its counts.
本章,於本版次中
版次 2026.11.9範例於 2026年11 月 20 通過測試本章 4 個範例 個範例中有 4 個通過
譯自英文書,版次 2026.11.9。