指南

結果與執行參考

一次執行向 HTTP 系統發送什麼、期望得到什麼，每個案例如何進入某個指標的分母，決策狀態以及解釋它們的原因代碼，結束代碼，以及哪些資料留在本機、哪些會轉移到託管工作區。它們背後的理念請閱讀核心概念；政策欄位請閱讀設定參考。

HTTP 系統契約

HTTP 系統（oloproof.yaml 中的 system.http）對每個案例呼叫一次，每個重複再呼叫一次。

方面	行為
請求	預設為 POST（也接受 GET 和 PUT）。請求體是案例的 input 值，以 JSON 形式發送。
請求頭和身份驗證	都無法設定。請求只帶有 HTTP 客戶端的預設值。需要密鑰的端點應放在一個負責添加密鑰的 Python 可呼叫物件系統之後。
響應	必須是 JSON。output_path 按點分路徑選取輸出，例如 result.answer；沒有它時，整個響應體就是輸出。缺少 output_path 欄位會被記錄為該案例的執行錯誤。
產物	每個 http.artifacts 條目從響應中讀取一個點分路徑。響應中缺少已宣告的欄位屬於契約錯誤，執行以結束代碼 2 停止。
超時	每個請求 http.timeout_s，預設 30 秒。
重試	超時、連接失敗以及 HTTP 408、429 和 5xx 會被重試，總共最多四次嘗試，採用帶抖動的指數退避，並遵循 Retry-After。其他 4xx 響應不會重試。
最後一次嘗試之後	該案例的執行被記錄為錯誤，該案例計為缺失（在 on_execution_error: fail 下計為失敗）。執行繼續。
併發	同時進行的請求最多 concurrency.system 個，預設 8。

URL、方法、輸出路徑和產物映射會計入系統的版本，但伺服器做了什麼不會。每當伺服器的行為發生變化時，修改 system.version；原因見設定參考。

三套不同的詞彙

一個結果有三種狀態，它們從不相互替代。

類型	取值	回答的問題
決策狀態	PASS、FAIL、INSUFFICIENT_EVIDENCE、MANUAL_REVIEW	證據對一條規則說明了什麼。
執行狀態	執行狀態 RUN_ERROR 或 CANCELLED；執行完整性 PARTIAL；案例執行 ERROR 或 TIMEOUT	執行或某個案例的呼叫發生了什麼。不是品質結果。
發布動作	ALLOW、WARN、BLOCK	你的政策如何處理每個決策：block_on 中的狀態阻止，warn_on 中的狀態警告，其餘放行。

正常結束的執行是 DECIDED，若由提前停止結束則是 DECIDED_EARLY。被 Ctrl-C 或任務取消打斷的執行是 CANCELLED；評測框架拋出異常的執行是 RUN_ERROR。兩者都會讓執行成為 PARTIAL，保留已完成的案例，並讓下一次執行復用它們的快取記錄。見錯誤。

對於最低門檻值 T 和區間 [L, U]，當 L >= T 時規則為 PASS，當 U < T 時為 FAIL，否則為 INSUFFICIENT_EVIDENCE。最高門檻值與之對稱。在讀取區間之前，規則會先檢查它是否應該作出決策：先檢查 MANUAL_REVIEW 的原因，再檢查 INSUFFICIENT_EVIDENCE 的原因。第一個有原因的層級作出決策，並列出它找到的每一個原因。

原因代碼

每個決策都帶有一個或多個原因代碼。

MANUAL_REVIEW

代碼	含義
policy_requires_review	規則設置了 requires_manual_review: true。
unsupported_method	在這種情況下，該指標沒有已認可的區間。見下文。
unsupported_dependence_structure	套件宣告瞭叢集（group_id），而對於該指標，沒有已認可的方法能處理它們。
approximate_method_not_permitted	唯一的區間是近似的，而政策沒有設置 allow_approximate_methods: true。
evaluator_retired	該指標背後的某個評估器已停用。

INSUFFICIENT_EVIDENCE

代碼	含義
no_observations	該指標沒有觀測到任何案例。
missingness_exceeds_policy	符合條件的案例中缺失的比例超過了規則的 max_missing_fraction 所允許的範圍。
missingness_unbounded	該方法丟棄缺失案例而不是為它們設界，且規則沒有宣告 max_missing_fraction。
evaluator_not_validated	該指標背後的某個模型評審尚未對照人工標籤進行驗證，且 require_validated_evaluators 處於開啟狀態（預設）。
evaluator_recalibration_required	評審是在另一個所服務的模型上驗證的，而本次執行的結論並非來自該模型。
interval_unavailable	該指標沒有可讀取的區間。
insufficient_clusters	叢集數少於政策的 min_clusters。
interval_monte_carlo_uncertain	門檻值落在叢集界限的模擬不確定性之內。
interval_overlaps_threshold	區間包含門檻值。更多案例會讓它變窄。
interval_unbounded	區間在規則讀取的那一側沒有界限。
missing_could_change_outcome	一條 observed_count 規則：缺失的案例可能讓失敗數超過 max_failures。
interval_overlaps_zero、interval_overlaps_margin、interval_overlaps_margins	差異區間跨越零或邊際的比較。
insufficient_support	切片比較規則，其切片的案例數少於它的 min_support。
family_correction_withheld	families: 條目中的一條規則，Holm 校正在到達它之前就停止了。

PASS 與 FAIL

代碼	狀態
lower_bound_meets_minimum、upper_bound_meets_maximum	PASS
upper_bound_below_minimum、lower_bound_above_maximum	FAIL
observed_failures_within_limit	PASS
observed_failures_exceed_limit	FAIL
difference_above_zero、lower_bound_above_margin、interval_within_margins	PASS（比較）
difference_below_zero、upper_bound_below_margin、interval_outside_margins	FAIL（比較）
cost_ceiling_exceeded	與成本規則的狀態一同給出，表示某次記錄下來的執行超出了該規則宣告的上限

僅限託管工作區

自行對推送的執行作出決策的工作區，可以用 ppi_not_verified（它沒有驗證決策所依據的區間）、execution_not_verified（輸出並非來自已註冊的執行器）或 workspace_cannot_decide（它沒有保存政策的副本，或無法讀取證據）來暫緩決策。見閘門。

每個案例如何進入分母

每個指標都報告四個計數：n_total（套件中的案例）、n_eligible、n_observed 和 n_missing，且 n_eligible = n_observed + n_missing。n_eligible 之外的案例列在 exclusions 下，並附有原因。

案例發生了什麼	計為	是否在分母中
評估器返回了通過或失敗	已觀測，成功或失敗	是
評估器宣告自己不適用（例如沒有可比較的預期值）	排除，附原因	否
系統呼叫出錯或超時	缺失，在 on_execution_error: fail 下計為失敗	是
評估器拋出異常，或評審的回覆無法讀取	缺失	是
由於執行被中斷，該案例從未執行	缺失，且執行為 PARTIAL	是

缺失的案例會被設界，而不是被丟棄。對於通過率，區間的下界把每個缺失案例都視為失敗，上界則視為成功，所以缺失案例很多的執行區間很寬，無法通過要求嚴格的規則；有界均值也以同樣方式代入其宣告範圍的兩端。無法為缺失案例設界的方法（例如排序統計量）會丟棄它們並記錄這一假設，而基於它的規則會顯示 missingness_unbounded，直到它宣告 max_missing_fraction。

observed_count 規則統計已執行套件上的失敗數，不讀取區間。只有當觀測到的失敗數加上每一個缺失案例仍在 max_failures 之內時，它才通過。

沒有已認可區間的指標

規則只依據其方法已通過審計認可的區間作出決策。在不存在這種區間的地方，指標仍然會被計算並顯示，而基於它的規則不會借用未經驗證的方法：

情況	基於它的規則顯示
沒有宣告範圍的分數（均值）指標，例如沒有 score_range 的自定義分數評估器	MANUAL_REVIEW，unsupported_method
在宣告瞭 group_id 的套件上的均值、分位數、排序或成本指標	MANUAL_REVIEW，unsupported_dependence_structure
叢集套件上的通過率	一個近似區間：除非 allow_approximate_methods: true，否則為 MANUAL_REVIEW，開啟後再進行上面的叢集檢查
replicates 大於 1 的分位數或排序指標	MANUAL_REVIEW，unsupported_method
同時帶有 group_id 和重複的套件上的任何指標	MANUAL_REVIEW，unsupported_dependence_structure
叢集套件上的比較	MANUAL_REVIEW
低於 min_slice_support 的切片	沒有區間，但切片從不進入閘門
human_score、human_preference 或 cost_per_accepted 指標	讀取檔案時即被拒絕，結束代碼 2

結束代碼

oloproof gate、帶政策的 oloproof run，以及其他作出決策的命令都使用相同的結束代碼。

代碼	含義
0	沒有出現任何政策要阻止的情況：每條規則都通過了，或者沒通過的規則不在 block_on 中。
1	block_on 中的一條規則失敗了。
2	設定或呼叫方式有誤，或某個系統違反了它的契約；什麼都沒有被決策。
3	block_on 中的一條規則顯示 INSUFFICIENT_EVIDENCE。
4	block_on 中的一條規則顯示 MANUAL_REVIEW。
5	執行沒有完成，且 block_on_partial_run 處於開啟狀態（預設）。

當多個情況同時適用時，報告的代碼是 1、5、4、3 中排在最前面的那個。不在 block_on 中的狀態無法改變結束代碼：在 block_on: [FAIL] 和 warn_on: [INSUFFICIENT_EVIDENCE] 下，一條未決的規則會發出警告，閘門以 0 結束。因此，結束代碼 0 只表示沒有出現任何你的政策要阻止的情況，而不表示每條規則都通過了。見閘門。

工作在哪裡執行，資料去往哪裡

本機，預設情況

oloproof run、oloproof gate 和 SDK 都在你的機器上執行。每條記錄（案例、輸出、產物、評判結果、指標和決策）都寫入 oloproof.yaml 旁邊的 .oloproof/store.sqlite，若設置了 OLOPROOF_HOME，則寫入其下。沒有任何東西會發送給 Oloproof。唯一的網路流量是你的設定引起的：對你的 HTTP 系統 URL 的呼叫，以及模型評審或模型分類器對其提供者的呼叫，提供者會收到它們所評判的案例內容，併為此向你收費。

推送到託管工作區

oloproof push 把一次執行的證據發送到你用 oloproof login 連接的工作區。預設情況下，它發送指標、區間、決策和聚合切片，以及每條記錄的身份、狀態、耗時和用量，但不發送其內容。原始內容在任何東西離開機器之前會被逐欄位脫敏，被脫敏的記錄會說明哪些類別被保留未發送。只有當 oloproof.yaml 中的 egress: 列出某個類別時，該類別才會被髮送：

類別	它涵蓋什麼
raw_inputs	場景輸入、預期值和案例元資料：即資料集的行
raw_outputs	被測系統對每個案例返回的內容
judge_rationales	評審為解釋結論而寫的文字，其中會引用輸出
artifacts	執行期間記錄的檢索上下文、引用和軌跡
error_detail	異常消息和詳情，其中常常原樣帶有輸入
system_config	被測系統及其評估器的宣告設定
label_notes	一個人在標籤旁寫下的備註，其中常常引用輸出
span_names	埋點記錄下來的追蹤、span、工具和代理名稱

脫敏之後不會重新計算記錄摘要，所以託管記錄仍然指向原始證據，而原始證據留在你的機器上。脫敏不是加密，而基於非常小的切片計算的指標仍可能識別出其背後的案例。

當審核者在託管審核佇列中標註案例時，他們的瀏覽器從在你這一側執行的 oloproof collect 取得案例內容；內容不會經過工作區。工作區使用的提供者密鑰用 oloproof credentials set 儲存，oloproof credentials list 會顯示它們的名稱，但從不顯示它們的值。託管作業在 Oloproof 運營的工作節點上執行，該節點不執行你的 Python 代碼；oloproof job 報告其結果，並以其閘門結果作為結束代碼。

在託管工作區中，引擎從不復用快取的執行、評判結果或分析，因為推送可以寫入這些快取；它會重新計算它們。