Pi 1.5 更新:Cloudflare 代理少寫資料庫,效能數字與升級代價怎麼看?
Pi 1.5整合Cloudflare Agents SDK,減少儲存寫入並改善排程。解析官方模擬基準、session.watch與continue、約一秒保存取捨,以及無法直接退回Pi 1.4的格式限制。
Pi 1.5 是 AI 代理執行框架的更新,Cloudflare 於 2026 年 11 月 3 日將它整合進 Agents SDK v0.33.0。這裡的升級對象是代理如何保存與執行工作,並非推出新的語言模型。
持久化指的是把工作狀態保存下來,讓程序重啟後能接續處理。但如果模型每吐出一小段文字就立刻存檔,資料庫也會承受大量寫入。
這次更新把串流顯示和持久化分開。使用者仍能立即看到文字,底層則在預設約一秒內合併儲存,並減少字串複製和排程器重掃。
Cloudflare 公布的 SQLite 基準顯示,長回答交易次數約降為原先的二十七分之一。在2,048個工作階段的測試裡,每秒執行次數則從88增至459。
原作者說明,基準中的模型與工具是模擬且立即回覆的,因此量到的是執行框架本身的開銷。這些數字描述特定測試的儲存與排程表現,不能直接換算成所有代理任務快五倍。呼叫模型與外部工具的等待,仍會影響整體完成時間。
對已有長時程代理服務的團隊,更新值得評估,但也要先處理儲存格式與恢復取捨。官方提醒新版跑過的對話無法直接交回 Pi 1.4 讀取。
要安排升級順序,先把何時讓使用者看見進度,以及何時把進度存進資料庫這兩件事分清楚。
持久化與即時顯示為何可以分開處理?
在一般的聊天機器人裡,如果網頁重新整理或後端容器重啟,正在跑的回答頂多就是斷掉重來。
但在需要接續多步驟工作的代理中,團隊會希望重新啟動後保留已完成進度,因為從頭重跑可能增加等待或重複操作。
持久化執行框架會在適當邊界保存狀態,讓恢復流程知道先前完成了什麼。執行外殼也就是管理模型呼叫、工具與狀態的程式。
在原作者示範的舊流程裡,代理會在各個狀態邊界提交資料,等待保存後再往下走。這解釋了為何模型和工具即使立即回覆,框架仍會累積資料庫往返開銷。
根據 原作者 Mario Zechner 在 X 公布的架構解析與測試圖,光是一個編程代理處理「修復失敗測試」的單輪對話,底下就會經歷五個階段並觸發約 12 次資料庫提交。
具體來說,當使用者送出「修好這個測試」的訊息時,系統要先寫入 2 次提交來保存訊息與啟動狀態。
接著第一次呼叫模型決定要執行測試工具時會寫入 3 次提交,實際在終端機跑完 npm test 並收回測試輸出又會寫入 3 次提交。
隨後模型根據測試結果開始撰寫修復說明時再寫入 3 次提交,最後標記該輪回合結束還要再補上 1 次提交。
如果每次資料庫往返要花 4 毫秒,光是一個對話回合就有將近 50 毫秒完全卡在等待磁碟寫入。
串流複製與排程器全量掃描造成的雙重放大效應
這 12 次提交還只是理想狀況下的基本開銷,一旦加上「即時文字串流」與「多對話併發」,儲存與排程的額外開銷就會變得明顯。
過去每當模型或工具串流吐出新的一小段文字,系統就會立刻觸發儲存更新,並把整段累積的文字重新複製一份放進記憶體。
依 Cloudflare 官方發布的更新日誌 列出的基準,過去串流傳輸一個 500 KB 的大型工具呼叫,反覆複製字串的動作就會吃掉約 20 秒的處理器時間,並在記憶體堆積出高達 100 MB 的空間佔用。
更糟的是,舊版排程器只要遇到任何一個對話完成資料庫提交,就會把目前系統裡所有的對話狀態從頭到尾重新檢查一遍。
當單一代理執行實例同時掛載上百甚至上千個工作階段時,重複檢查未變動對話的成本也會增加。
看清了密集寫入、字串複製與全量掃描這三種開銷後,接下來我們就能逐一檢視新版本如何從底層解開這些束縛。

Pi 1.5 做了哪些底層改造?三大效能指標與 pi-schema 全面拆解
為了解決上述瓶頸,Cloudflare 在 cloudflare/agents 官方開源儲存庫 發布的 Agents SDK v0.33.0 中,將內建的 PiHarness 正式升級至 Pi 1.5,並針對儲存、排程與記憶體管理調整了三種常見的處理路徑。
第一項改造是「串流期間的 1 秒批次持久化」。
現在當代理正在串流輸出回答或接收工具執行結果時,系統不再每收到一個字就立刻寫入資料庫,而是改為在每次更新後的 1 秒內分批打包寫入。
對前端使用者來說,畫面上的串流文字依然是即時跳出來的,儲存批次不要求前端一起等待。
但在底層的 SQLite 資料庫上,長篇回答產生的儲存交易次數在官方SQLite基準中約降為原先的二十七分之一,而同時呼叫多個平行工具的回合也減少了 5.7 倍的寫入交易,連帶讓整體處理器消耗降低了約 25%。
第二項改造是「排程器精準檢查與增量字串附加」。
新版的代理排程器不再於每次提交時傻傻重掃所有對話,因此在包含 2,048 個工作階段的 SQLite 基準測試中,單一代理外殼每秒能跑完的代理執行次數在該測試中從每秒88次增加到459次。
同時針對大型回答與工具輸出,底層改為直接在原有緩衝區後面「附加」新收到的文字片段,不再每次更新都重新配置並複製整塊記憶體,用來減少原先 500 KB 工具呼叫動輒吃掉 100 MB 記憶體與 20 秒運算時間的瓶頸。
不依賴 eval 的輕量級驗證器 pi-schema
除了儲存引擎的改造之外,Mario Zechner 也同步為這套生態系發布了名為 pi-schema 的底層函式庫。
在代理運作過程中,每當模型決定呼叫外部工具時,系統都必須密集檢查模型傳入的 JSON 參數是否符合工具定義的結構規範。
許多傳統的高速結構驗證器為了榨出效能,會在執行期呼叫 JavaScript 的 eval 或 new Function 動態生成檢查程式碼。
但像 Cloudflare Workers 這類高度重視安全隔離的邊緣運算環境,預設嚴格禁止在執行期動態生成程式碼,導致傳統驗證器無法運作或必須退回緩慢的逐欄比對模式。
根據 Mario Zechner 發布的 pi-schema 技術貼文,這套全新驗證器巧妙利用標準的 JavaScript 閉包組合技術,打造出一套不需要 eval 的輕量級即時編譯器。
不依賴動態生成程式碼,讓它適合這類受限執行環境。不過,具體支援範圍與效能仍應核對該函式庫文件。不能只憑這個特性推定所有邊緣環境都已驗證。
為了讓工程師一眼掌握這次升級的量化效益,以下我將官方公布的基準測試數據整理成對照表:
| 效能與資源測試維度 | 舊版 Pi 1.4 運作表現 | 新版 Pi 1.5 升級後表現 | 官方基準改善幅度與技術關鍵 |
|---|---|---|---|
| 長篇回答串流儲存交易數 | 每次串流更新皆觸發資料庫寫入 | 改為 1 秒內批次打包寫入資料庫 | SQLite 儲存交易次數約降為原先的二十七分之一 |
| 平行工具呼叫回合交易數 | 每個平行工具輸出頻繁觸發獨立提交 | 合併工具輸出批次提交並減少約四分之一處理器消耗 | 儲存交易次數減少 5.7 倍、處理器負擔降約 25% |
| 2,048 工作階段併發吞吐量 | 每次提交重掃全部對話,每秒 88 次執行 | 排程器不再全量重檢,每秒達 459 次代理執行 | 單一代理外殼高併發吞吐量提升超過 5.2 倍 |
| 500 KB 大型工具呼叫開銷 | 每次更新複製全文字串,耗時約 20 秒、佔 100 MB 記憶體 | 改為直接附加新文字片段,免除重複複製開銷 | 大幅消除大型工具串流的處理器卡頓與記憶體峰值 |
從上方表格可以看出,這次升級並非只靠微調參數,是把部分資料庫讀寫與字串處理換成批次及增量方式。但基準中的執行次數,和包含模型、網路與工具的端到端工作時間不同。
理解基準條件後,工程師在實際修改程式碼升級時,還必須面對幾個關鍵的介面變動與不可逆的部署限制。
從 session.watch 到單向升級限制,開發者改版前要注意什麼?
為了配合新的狀態管理架構,這次更新針對開發者日常呼叫的程式介面 API 進行了多項調整,其中包含三個必須修改既有程式碼的破壞性變更。
首先在工作階段監聽方面,全新的 session.watch 正式取代了舊有的 session.events 呼叫介面。
過去開發者只拿得到零碎的事件流,現在呼叫 session.watch 可以同時拿到最新的對話紀錄項目以及該工作階段的即時狀態。
這代表前端或監控系統可以直接從回傳結果中,讀取目前正在串流中的回答文字、正在執行中的工具清單,以及上一輪代理執行為何沒有產生最終回答就結束的具體原因。
其次,新版本加入了非常實用的 session.continue 呼叫介面與 defaults.maxTurns 回合上限設定。
過去當代理跑到一半遇到上游模型服務異常報錯,或是觸及工具呼叫回合上限而停下來時,開發者往往得塞入一條假的使用者訊息才能把代理重新叫醒。
現在只要先透過 session.wait 檢查結果,確認狀態為未回答且原因為模型錯誤,也就是 status === 'unanswered' 且 reason === 'model_error',就能在工作階段閒置時直接呼叫 session.continue。
系統會直接利用既有的對話紀錄重新啟動一輪執行,完全不會在對話歷史裡留下多餘的使用者催促訊息,而且如果該對話其實已經正常回答完畢,系統則會安全回傳 nothing_to_answer。
移除擱置狀態與必須事前規劃的兩大升級邊界
在異常任務處理與瀏覽器工具方面,新版外殼決定採取更乾脆的收尾策略。
過去當一個代理任務反覆崩潰並觸及重啟上限時,系統會將它標記為 parked 擱置狀態並允許呼叫 retry。
而在新版本中,只要任務觸及重啟上限就會直接結束,舊有的 retry 方法與 parked 狀態已被徹底移除。
另外在允許代理直接撰寫並執行腳本的 Code Mode 中,腳本現在可以直接呼叫 browserTool 開啟無頭瀏覽器,並將拍下的網頁截圖直接傳給 image 處理,而且一旦外殼中止該次呼叫,底層的瀏覽器工具也會同步停止運作,防止孤兒程序殘留。
最後,在把正式代理環境推上 Pi 1.5 之前,所有架構師都必須評估兩項硬性限制。
第一是「1 秒批次寫入的容錯取捨」,雖然批次寫入大幅減輕了資料庫壓力,但這也意味著如果伺服器在串流途中發生斷電或硬性崩潰,最多可能會遺失最後約 1 秒鐘尚未寫入磁碟的串流進度,對資料零遺失有極端要求的場景需要到 Recovery 設定中調整這個間隔。
第二項也是最關鍵的限制,就是「單向儲存格式變更」。官方明確警告,一旦某個對話工作階段在 Pi 1.5 上執行過,舊版的 Pi 1.4 就再也無法讀取該對話的資料結構。
這代表團隊在部署升級後如果遇到任何應用程式錯誤,應依官方建議向前修正部署問題,不能預設直接換回Pi1.4仍能讀取新版對話。若團隊另有舊資料備份,如何復原仍須事前測試。
恢復對話也不代表外部操作一定只會執行一次。若代理已呼叫其他服務修改資料,團隊仍須確認中斷時如何辨識既有操作,避免接續工作時產生重複副作用。這是應用流程的驗收問題,不能只用串流保存間隔推定已解決。
因此這套更新非常適合追求高併發吞吐與低記憶體開銷的活躍開發團隊,但升級前務必先在測試環境把所有 session.events 與 retry 呼叫清理乾淨。
Pi 1.5 常見問題
升級到 Pi 1.5 之後,如果發現問題可以直接退回 Pi 1.4 嗎?
不能假設可直接降級。
官方更新日誌明確提醒,一旦對話在 Pi 1.5 上執行過,舊版 Pi 1.4 就無法讀取它的儲存格式,因此升級後若遇到部署問題,必須採取向前修補的方式解決,不能直接退回舊版。
串流寫入改為批次處理後,使用者畫面上的打字機效果會變慢嗎?
不會變慢。串流更新在前端依然是即時顯示的,只是底層寫入 SQLite 資料庫的動作改為在 1 秒內批次完成,這裡的取捨,是預設設定下崩潰可能丟失約最後一秒的串流進度。不能據此推定所有資料與外部操作都具備同樣保證。
為什麼模型呼叫失敗時,改用 session.continue 比重發訊息更好?
因為重發訊息會在對話紀錄裡多塞入一筆重複的使用者提問,容易污染上下文,而 session.continue 可以在不新增使用者訊息的前提下,直接沿用既有對話紀錄接續執行未完成的回合。
舊專案裡的 session.events 與 retry 在升級後還能繼續用嗎?
不能。
session.events 已在本次更新中由功能更完整的 session.watch 取代,而 retry 方法與 parked 狀態則已直接移除,升級時必須一併更新這些呼叫程式碼。
先驗證恢復與格式,再放大併發量
已有持久化代理服務的團隊,可先用測試對話核對監聽、接續與中斷恢復,再量測自己的負載。因為新版格式不能直接退回舊版,恢復安排應在正式對話開始寫入前準備好。
想持續追蹤 AI 開發工具、代理架構與工程實務限制,歡迎免費訂閱 AI 郵報。
延伸閱讀
延伸閱讀:Vercel durable-harness 是什麼?程式代理雲端當機後如何接著做
延伸閱讀:Cloudflare 加速 AI 代理沙盒:啟動、快照與恢復,決定任務能否接著做