指南

结果与执行参考

一次运行向 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 报告其结果，并以其门禁结果作为退出码。

在托管工作区中，引擎从不复用缓存的执行、评判结果或分析，因为推送可以写入这些缓存；它会重新计算它们。