LiteLLM agent_eval API 預覽:自己的任務怎麼比較代理,為何不能只看通過率?

LiteLLM agent_eval 是尚未發布的 API 預覽。解析任務、成功檢查、試次分母、評審費用與本機權限限制,說明為何不能將主分支實作當成 PyPI 已可安裝功能。

Share
LiteLLM官方評估預覽圖,左側為任務程式,右側為模擬通過率與JSON匯出
LiteLLM 官方預覽使用模擬回答展示評估報表,圖中通過率不是實際模型測試成績。 圖片來源:官方原文。

LiteLLM agent_eval 想把代理比較從展示回答,轉成同一份任務與成功條件。只看模型回應是否流暢,仍可能錯過檔案沒有改好、工具啟動失敗,或成本資料不完整等問題。

但官方社群寫著推出評估功能,不代表一般安裝的套件已能使用。2026 年 11 月 16 日發布的介紹頁,明確說這是即將提供的 SDK 介面,已發布的 PyPI 套件尚未包含它。

這次預覽把工作與成功檢查放在一個任務物件裡,再為不同模型和代理執行方式設定比較目標。每次嘗試使用新的工作空間,讓結果比較不會只依靠代理自己聲稱完成。

官方設計也把執行錯誤留在通過率分母裡。這能讓缺少執行環境、逾時或評審失敗繼續被看見,避免只挑成功跑完的案例,把部署問題從成績中消失。

正在建立代理測試的開發者,可以先參考它的資料結構和驗收方式。若需要立即可安裝的正式功能,則應等官方列出發布版本與安裝條件,不能把預覽程式當成現成部署保證。

要讀懂這項設計的價值,先要把任務、比較目標和判定成功的規則分開。

先定成功條件,再讓代理跑同一項任務

LiteLLM agent_eval 把一次比較拆成任務、目標與重複試次。任務描述要完成什麼,以及怎樣算成功。目標則指代理執行程式、模型與辨識標籤的組合。

這樣的安排,讓團隊能分辨自己到底比較了什麼,而不只是得到兩段看起來都合理的回答。

官方文章發布於 2026 年 11 月 16 日,本文依該日期說明這份 API,也就是供程式呼叫功能的介面預覽。

更重要的是,官方文件明確標示尚未發布的 API 預覽。

實作在主分支內,但已發布的 PyPI 套件尚未包含這項功能。因此目前適合研究介面與規劃測試,不宜照搬範例,宣稱一般安裝套件後就能執行。

先前單獨呼叫代理得到的一份結果,也不等於已經完成評估。評估程序會依任務、目標與試次另外執行,然後套用成功檢查。若團隊只把一次展示回答拿來比較,就少了重複執行、失敗紀錄與可重查的判定依據。

例如要測試代理能否修正日期排序,成功條件可以要求測試程式通過,並保留原本相同日期的相對順序。這比「請修好排序,看起來合理即可」更能區分成果。

此處是本文說明測試設計的例子,不是官方預覽已替讀者跑出的成績。

同樣地,若同時更換代理程式與模型,即使結果變好,也不能只歸功於新模型。代理程式決定如何讀檔、叫用工具與控制工作流程,模型只是其中一部分。先固定一個因素再改另一個,才比較容易找出改善來源。

每個試次會準備新的工作目錄,有助於避免前一輪留下的修改影響後一輪。不過乾淨目錄只是讓檔案起點一致,並不等於整個程式執行環境已被安全隔離。這項差異在接入本機工具時尤其需要注意。

LiteLLM官方評估預覽圖,左側為任務程式,右側為模擬通過率與JSON匯出
LiteLLM 官方預覽使用模擬回答展示評估報表,圖中通過率不是實際模型測試成績。 圖片來源:官方原文。

三種檢查方式,各自看得到哪些證據?

預覽提供三種判定方式,對應不同形式的成果。第一種是由程式檢查結果是否符合條件,例如回答中是否有指定欄位、工具是否被正確呼叫。它適合條件能明確寫成真或假的任務,但條件本身仍要由設計者定義。

第二種方式是在同一個工作環境內執行檢查命令,以成功結束的狀態判定。像修正程式或產生檔案,就可以用測試程式驗證實際產物。這比只問代理「你完成了嗎」更接近驗收,因為檢查直接面向結果。

不過測試若放在代理可任意修改的範圍,代理可能改變測試,而不是完成原任務。官方建議把重要斷言放在可編輯工作區之外。團隊仍需檢查工具權限,確保代理不能藉其他路徑改掉判定標準。

第三種方式交給另一個模型依評分規準判斷。這種評審會讀取任務提示、代理回答,以及回報的檔案差異,並依指定格式輸出結果。它適合難以完全寫成固定規則的答案,例如說明是否涵蓋必要理由。

評審模型不是擁有全部現場資料的觀察員。官方文件說明,它不會任意打開工作目錄中的其他檔案,因此不能假設它已看過產物的所有細節。若答案宣稱完成一份報告,卻沒有把必要內容交給評審,分數的證據就可能不足。

評審也會增加自己的用量與失敗方式。格式不正確、無法完成判定或逾時,都可能讓評估出錯。因此團隊應把代理執行費與評審費分開看,也為評審準備少量人工確認案例,檢查規準是否真的抓到工作需要。

這三種方法沒有一種能自動代表所有品質。可由測試直接檢查的結果,適合先用明確規則。需要主觀判斷的部分,再補上可說明的評分規準。分工清楚,比把整件事交給單一總分更容易追查。

通過、失敗與錯誤,分母為何要一起保留?

預覽將結果區分為通過、失敗與執行錯誤。正常跑完且符合檢查的試次才算通過。結果未達要求或碰到回合限制,可以列為失敗。環境準備、執行、取消、逾時或評審格式異常,則可能成為錯誤。

這個分類有助於找到改善位置。若模型完成了工作卻沒符合測試,要檢查答案或成功標準。若程式根本沒有啟動,就不該先換模型。若評審輸出無效,問題又在另一條流程,不能通通用「代理不夠聰明」概括。

官方的通過率分母包含排定的試次,也包含錯誤。也就是說,不能把所有環境錯誤刪掉後,再拿剩餘結果宣稱整個系統通過率很高。另一方面,讀者也需要看到錯誤分類,才能知道低分來自能力還是部署問題。

一個假設例子是,某組測試排了十次,六次通過、兩次不符合要求、兩次啟動失敗。按排定試次計算,通過率是六成,而不是移除啟動失敗後的七成五。這只是用來說明分母,不是本文測得的官方成績。

重複試次則用來觀察同一任務是否穩定。一次成功可能碰巧選對路徑,多次成功才比較能顯示一致性。但試次增加仍需花費,且任務集合若過於簡單,穩定通過也不能證明可以處理尚未測過的工作。

文件也保留成本資料是否完整的標記。若某些用量或價格無法取得,數字可能只涵蓋已知部分。不能把缺失當成零,再宣告該目標最便宜。報告應保留完整性狀態,必要時暫停成本排名,只比較已確認的結果。

失敗與錯誤仍可能產生費用。代理已經呼叫模型,最後才撞上測試失敗,先前用量不會因為沒有成功而消失。評審也可能在失敗前消耗資源,因此比較每次成功的總投入,需要把未成功試次一起放回觀察。

時間也有相同道理。官方所列的平均執行時間,包含準備、設定、代理工作、評分與清理,與多個任務平行時整批等待多久不是同一個數字。挑選工具時應先說明要改善單件延遲,還是整批處理速度。

工作目錄乾淨,不代表本機工具已經隔離

每輪建立新的工作目錄,可以讓檔案測試更公平,但安全邊界仍取決於真正的執行環境。文件指出,本機工具會以程式所在程序的權限執行。複製一個目錄,並不會自動撤銷它存取其他檔案或服務的能力。

官方的目錄複製處理會排除版本控制資料,並拒絕符號連結。符號連結是指向另一個位置的檔案入口,若沒有妥善處理,測試可能不小心碰到目錄之外的內容。這些措施減少部分風險,但仍不能取代完整的沙盒設定。

因此試用時可先使用沒有敏感資料的小型專案,把代理所需的檔案與工具縮到明確範圍。若需要真正的隔離,應確認所選代理與環境如何提供,而不是看到「每輪新目錄」就推論任意程式碼都能放心執行。

接入命令列代理時,也要先確認對應執行程式已安裝,以及所選模型是否相容。失敗若發生在這些準備步驟,應保留為環境問題。不要因為範例能描述一個目標,就假設任意代理與任意模型的組合都能工作。

結果會提供可儲存的資料與識別碼,用來與既有紀錄對照,但不代表預覽替團隊建立了完整資料庫。需要持續保存費用與執行歷史的團隊,仍要安排自己的儲存與記錄流程,並確認哪些內容會被保留。

測試資料也需要分開管理。開發中的題目可以幫團隊修正提示與工具,但若每次都針對同一批題目調整,分數上升可能只是更熟悉題目。

保留另一組尚未拿來調整的工作,再檢查結果是否仍然穩定,會較容易發現過度配合測試的情況。這是本文建議的評估設計,並非預覽已自動提供資料切分。

任務取消後的清理也應納入驗收。官方描述整批取消時會處理清理程序,但團隊仍要核對自己的工具是否留下程序、暫存檔或外部工作。測試跑完沒有遺留影響,才適合反覆執行,而不是只看結果檔已出現就算結束。

若某一類題目持續失敗,先查看它需要的工具與檢查證據是否齊全,再判斷模型是否不足。把錯誤拆到具體階段,才能知道該改提示、環境、評分規準,還是換一個目標。

這也讓預覽中的分類能轉成實際修正工作,而不是只留下排行榜。

正式採用前,先等官方釋出可確認的套件版本,再固定版本、環境與小任務驗收。本文不提供尚未核實的安裝指令。研究預覽的價值,是先把成功定義、證據與失敗分類想清楚,等功能可用時便能做有意義的比較。

LiteLLM agent_eval 常見問題

現在能直接用 PyPI 安裝 agent_eval 嗎?

截至本次查核,官方標示為尚未發布的 API 預覽,已發布套件尚未包含。不能把主分支內的實作當成一般安裝版本已經可用,應等可確認版本與相對應文件。

評審模型會讀完整工作目錄嗎?

不會。文件限定評審取得任務提示、回答與回報的檔案差異,不會自動讀其他檔案。需要直接驗證產物時,應安排相對應的檢查證據。

比較兩個模型,成本最低的就是最適合嗎?

還要一起看任務是否通過、錯誤比例、成本是否完整,以及等待時間。便宜但無法完成工作,或缺少用量資料,都不能直接解釋成節省。

先把驗收寫清楚,再等可確認版本

這份預覽把代理比較從展示答案推進到可重複任務。團隊現在可以先準備一組接近日常工作的題目與成功條件,等釋出後固定環境試行,讓品質、時間與費用有共同的比較基礎。

延伸閱讀:AWS UAEF 統一 AI 代理評測:36 項指標如何比較不同框架?

延伸閱讀:promptfoo/promptfoo 開源 AI 紅隊測試與評測 CLI 教學:自動化抓出提示詞注入與模型回歸

資料來源