evaluate-ml-pipeline

评估 ML 流水线

为一名学习器评分并保存报告。流水线、拆分器以及任何非默认评分 均已声明。skore.evaluate 是入口。不要手动编写 cross_val_score、cross_validate、classification_report， 也不要打印指标。

SkrubLearner 不实现 sklearn 的 fit(X, y)。 cross_val_score 会报错。调用 skore.evaluate(learner, data={...}) 并省略 splitter=，除非 translation.splitter 为 prefit。

面向用户的文案

详情：setup-workspace references/human_facing_prose.md。 实验 Markdown 和 # 注释用于描述此次评估。 问题和结尾使用相同的数据科学术语：不要使用技能 ID、 G-* 名称或包装器 CLI。 `` 是一个站点标记。

流程

1. python -m skore_skills status。如果 status.setup.pending 非空，且 status.skills.setup-ml-project 为 true， 则加载 setup-ml-project 并停止。不要启动此技能。 此技能返回后继续。本轮不要再次加载它。 如果未安装该技能，用一行列出待处理项并停止。 不要臆造 git init、脚手架或 env init。如果 status.setup.env 或 status.setup.workspace 为 declined，用一行说明并停止。git 或 editable 若已拒绝，则不再询问；继续。然后运行 python -m skore_skills frame show，不要加 --revise。如果 status.modeling_decisions 不是 locked，包括 draft，则返回 model-ml-pipeline 并停止。 不要征求同意或询问存储模式，也不要展示 skore.evaluate 调用，即使只是预览。任何非 proceed 的情况都加载 frame-ml-problem 并停止。 translation 为 null → 停止。不要编写评估调用。
2. 依赖历史的流水线（向后移位、滞后、滚动窗口、目标移位，或与带有侧向历史的数据联接）：如果缺少 tests/smoke/test_<stem>.py，或 pytest 未通过， 则停止并返回 build（§ 返回 build）。不要编写 skore.evaluate。只有不存在依赖历史的步骤时，才可记录 n/a。
3. python -m skore_skills evaluate consent --stem <stem>。
   • 若结果为 ask，且本轮尚未对 build-ml-pipeline 中的 Evaluate 作出回答：引用 JSON context，并提供 Evaluate (Recommended) / Modify / Stop 选项。然后停止。 首次运行时，“运行评估”不等于同意。
   • 如果用户本轮已回答 Evaluate，或 JSON 为 proceed（已存在有效 locator）：继续。
   • stop — 缺少 smoke 文件。返回 build（§ 返回 build）。
4. G-SKORE-MODE。读取 status.policy.skore_mode。如果已设置， 则保留。如果未设置，询问用户选择 local（推荐）/ hub / mlflow，然后运行 python -m skore_skills policy set skore_mode <mode>。local：运行 mkdir reports（exist_ok）； 不要写入 reports/README.md。hub 或 mlflow：不要 创建 reports/。然后，如果已安装 add-python-package，则加载它；它会运行 env add-skore --mode <mode> --execute。 此处不要写出 skore[...]。此处不要运行 env add。 构造方式见：references/g_skore_mode.md。切换或迁移时，如果已安装 sync-ml-reports，则加载该技能。
5. 输出 Pre-flight，然后用 1–3 句话说明：这是使用已锁定方案进行的本地全数据集评估，包含报告指标、skore 检查项和 project.put。检查项会在本次运行中计算，并与报告一同存储。如果 translation.splitter 为 prefit，说明模型在训练表上拟合，并在随附的测试表上评分。注明 stem、已知的折数，以及 experiments/<stem>.py 和 scratch/results/<stem>/。 耗时取决于行数、折数、学习器和检查项。 不要臆造分钟数。如果仍待取得同意，则预览并停止。
6. 仅在 experiments/NN_*.py 中编写调用。参见下方的调用 形式。编辑后运行 python -m skore_skills style。 实验在 report.checks.summarize()、 project.put 和单独的 report 处结束。不要执行此文件。
7. 将 templates/materialize.py 复制到 scratch/results/<stem>/materialize.py。替换 Project 初始化代码。将 <CALL> 代码块替换为实验调用，参数及顺序保持一致。使用 env verify 中的 composed-dev Python 运行该文件一次。这是唯一一次 skore.evaluate 调用，也是唯一一次 project.put。读取 id.txt，生成 locator，并写入 locator.txt。当 policy.notebooks 为 true 时，运行 python -m skore_skills notebook fill experiments/<stem>.py， 仅当 policy.site 也为 true 时才添加 --html。不要对实验文件运行 notebook convert，也不要运行实验文件。当 notebooks 为 null 或 false 时，不要更改策略，也不要填充。当 policy.site 为 true 且已安装 export-ml-site 时，在 locator 写入后、审计/审阅或其他用户确认环节前，运行 python -m skore_skills site build --if-stale。这会立即展示结果查看器。它不能替代 record-outcome 后的结束时构建。然后结束本轮。 不要向实验文件添加 materialize 写入操作。 每次 Python 探测都写入 scratch/<ts>_<short>.py，并使用 env verify 中组合好的开发环境 Python 运行。不要内联使用 python -c。除非用户要求，否则不要使用 warnings.filterwarnings。未经确认的签名不得写入。以 BLOCKED: <class> signature needs an API lookup that cannot run this turn (<why>). 结束该探测。命中缓存即视为已完成查询。

调用

在 experiments/NN_*.py 中调用 skore.evaluate。省略 splitter=，让 skore 复用 DataOp 的 cv 和 split_kwargs，除非 translation.splitter 为 prefit。传入其他任何 splitter= 都会丢弃 split_kwargs。未传入 splitter= 且 DataOp 没有 cv 时，会使用 80/20 留出法；仅当 translation.report 为 EstimatorReport 且 translation.splitter 为 null 时才正确。接线方式见： references/metadata-routing.md。

当 translation.splitter 为 prefit 时，仅在训练表上拟合，然后对测试表评分。使用 api get 确认 fit 和 evaluate。不要将训练表传入 evaluate。此处省略 splitter= 会对测试表重新划分出一个 80/20 分割。不要拼接两张表。

learner = build_learner()
fitted = learner.fit({"table": train_df})
report = skore.evaluate(
    fitted,
    data={"table": test_df},
    splitter="prefit",
)

fit 签名为 (X, y) 的估计器也遵循相同规则：

fitted_model = LogisticRegression().fit(X_train, y_train)
report = skore.evaluate(
    fitted_model, X_test, y_test, splitter="prefit"
)

X / y 和 data 不能同时使用。

• SkrubLearner — skore.evaluate(learner, data={...})。键为 skrub.var 名称。互操作说明见： references/skrub_interop.md。
• fit 签名为 (X, y) 的估计器 — skore.evaluate(estimator, X, y)。如果锁定的 cv 已经是评估方案，仍应省略 splitter=。上述 prefit 调用是例外：估计器已经拟合，且 X 和 y 是测试表。

mark_as_X 上的 cv 应为 KFold、GroupKFold，或 build 中的基于日期的类。如果 translation 指定了 cv，而标记上没有，则返回 build（§ 返回 build）。此处不要接入 split_kwargs。split_kwargs 为空且可能存在分组列时 → 返回 build。不要默认使用 KFold。translation.splitter 的 prefit 不是标记上的 cv。

类别不平衡时不要使用 Stratified*。它会压缩跨折方差。

核心指标为 translation.metric。如果某个名称在 build-ml-pipeline 的 skore 默认列表中，则无需 scorer，multioutput-regression 除外：默认回归指标按输出分别计算，而锁定的聚合指标必须已经通过 .skb.with_scoring(...) 添加。其他任何名称都必须已经通过 .skb.with_scoring(...) 添加到预测 DataOp 上。如果尚未添加，则在调用 skore.evaluate 前返回 build（§ 返回 build）。不要调用 report.metrics.add。添加 scorer 后，该名称会作为一行出现在 report.metrics.summarize().frame() 中。对于 multioutput-regression，该 frame 还会为每个输出各列一行。不要在实验文件中对这些行求平均。结尾可以引用锁定的聚合指标；各输出的行仍保留在已存储的报告中。skore.evaluate 没有 scoring= 参数（references/custom-metrics.md）。如果已添加该名称，但它仍未出现在该 frame 中，说明预测器类不正确：必须先使用 mixin，再使用 BaseEstimator（首先是 RegressorMixin 或 ClassifierMixin）。返回 build（§ 返回 build）。单独使用 BaseEstimator，或将 BaseEstimator 放在 mixin 之前，都会失败。

锁定后用户要求的额外检查： references/custom-checks.md。在 experiments/NN_*.py 的模块级作用域中子类化 skore.Check，然后在 evaluate 之后、summarize 之前调用 report.checks.add(...)。add 会扩展 SKD 检查。不要杜撰检查。不要从 audit/ 注册检查。使用 api get 确认 Check 和 checks.add。

每次评估都要在 evaluate 之后以及任何 checks.add 之后调用不带参数的 report.checks.summarize()，然后调用 project.put。这样会将检查结果存储在报告中。不要传入 fast_mode 或 ignore。使用 api get 确认 checks.summarize。

report = skore.evaluate(...)
report.checks.summarize()
project.put(STEM, report)
report

只有在分发器粒度过粗时，才升级到 evaluate 之外（ references/reports.md）：单次留出拟合使用 EstimatorReport，逐折产物使用 CrossValidationReport。留出法使用 EstimatorReport。此循环使用一次 skore.evaluate、一次 report.checks.summarize() 和一次 project.put 为该学习器评分。

对于任何使用依赖历史的特征的流水线，交叉验证是必要条件，但并非充分条件。skore.evaluate 使用一个 env-dict 对图进行一次实例化，然后拆分索引。冒烟测试会在预测时使用一个全新的 env-dict。调用方在将状态切换为 done 前，仍必须通过冒烟测试。不要通过此技能将 JOURNAL.md History 或设计说明中的 Status 编辑为 done。

人工实验文件包含 skore.evaluate(...) 和 project.put(...)，且不会执行。相同调用会复制到 scratch/results/<stem>/materialize.py，这是唯一会运行的文件，因此 project.put 只会执行一次。审计文件、临时探测脚本或对实验文件执行的 notebook convert 都不得调用它们。读取已存储的报告时，先调用 project.summarize()，再调用 project.get(id)。由于 get 按 id 获取，get(key) 会引发 KeyError。不要通过重新运行 evaluate 来掩盖这个问题。

如果 skore 尚未绘制某些图表，且已安装该技能，则加载 plot-ml-figure。

put 之后

Project.put 返回 None。materialize.py 会将该键的最新 id 写入 scratch/results/<stem>/id.txt。根据该 id 构造一个定位信息，并在运行 loop locator 和 loop artifacts 之前，将其写入同一目录下的 locator.txt。不要将这些写入操作放入 experiments/<stem>.py。运行 python -m skore_skills loop locator --stem <stem>，并原样粘贴 JSON locator。定位信息缺失时为 n/a — backend did not expose a locator。

• local — local workspace: [reports/](../reports/) · id: <id>， 并附上 reports/ 的绝对路径。不要链接私有文件。
• hub — 使用原样的 Consult your report at … URL： [Open report](<url>) · hub · id: <id>。如果 Skore 未提供 URL，则链接项目主页，并标为 Open project。
• mlflow — 如有，则使用原样的 View run … URL。如果没有，且 tracking_uri 为 HTTP(S)，则使用 /#/experiments/<experiment-id>/runs/<run-id>。对于 file:、 sqlite:、databricks，或任何未提供 URL 的其他 URI： mlflow · tracking: <uri> · experiment: <id> · run: <run-id>。不要编造浏览器链接。

脚本会将 report._repr_html_() 写入 scratch/results/<stem>/report.html，将 repr(report) 写入 report.txt，并生成 checks.html 和 metrics.html。它会根据内存中的学习器重新生成 Method 查看器： EstimatorReport 上的 report.estimator_， CrossValidationReport 上的 report.reports_[0].estimator_。 通过 api get 确认 DataOp.skb.report 上的 eval。 learner.report 会转发该值。当 eval 是一个参数时，调用 learner.report 时使用 eval=False、open=False、 overwrite=True，并将 output_dir 设为 scratch/results/<stem>/pipeline。不要传入 environment。这不会执行拟合。不要调用 full_report，也不要在未设置 eval=False 时调用 report。如果不存在 eval，或者为 skrub 重试一次 add-python-package 后 Graphviz 仍然失败，则使用 _repr_html_ 或 sklearn.utils.estimator_html_repr 生成 pipeline.html。

回合结束

当 model-ml-pipeline 派发此回合时，将 JSON locator 向上游传递，并在上面的实时执行与检查点预览后返回。不要运行关闭时的 loop notebooks、 loop artifacts、审计、record-outcome、另一次站点构建或 git end-turn。

否则，此技能负责收尾。首先运行 python -m skore_skills loop artifacts --stem <stem>。 stop / evaluate_incomplete → 指明缺少的文件，不要 审计。audit → 如果已安装，加载 audit-ml-pipeline。 record → 跳过审计。record 是该命令的操作，不是笔记本门控。不要在审计技能中进行转换。

然后按此顺序操作。不要调整顺序。loop notebooks 仅在 skip 时继续。

1. python -m skore_skills loop notebooks --stem <stem>。将 JSON action 视为权威信息。当 action 为 convert 时，不要执行 record-outcome、 site build 或 git end-turn。 not_evaluated 不会进行转换。
2. 遇到 convert 时，对每个 experiments/ 或 audit/ 条目运行 python -m skore_skills notebook fill <source>，当 html 为 true 时附加 --html。不要对这些文件运行 notebook convert。Fill 不会执行 put。只有当写入当前工件的那次运行之后，人工作出过更改时，才重新运行 materialize.py。 仅填充 audit/<stem>.py 并不算完成收尾。未拟合快照禁令不适用：即使实验脚本包含 skore.evaluate，也要填充该脚本。重复步骤 1，直到 action 为 skip。缺少 jupytext / nbformat / nbconvert → 用一行说明 add-python-package。
3. 仅在步骤 1 为 skip 后、站点构建前执行 record-outcome。如果运行了审计，而 manage-ml-backlog 已安装，则将其摘要和 G-AUDIT-FINDING 传给该技能；如果实验脚本已转换，还要传入步骤 2 中的 locator。 如果没有运行审计，则调用 record-outcome，并传入该 locator、用户的标题（如有）以及 n/a — audit not run。 缺少 backlog 技能 → 用一行说明。不要在此处写入 History。 smoke 为红色时，绝不要标记为 done。
4. 仅当 policy.site 为 true 且已安装 export-ml-site 时运行 site build： python -m skore_skills site build --if-stale。它会将 audit/<stem>.nb.html 嵌入 ## Notebooks 下；不要添加 ``。如果 site build 因 mkdocs-material is required 报错，则为 mkdocs-material（agent）加载 add-python-package，再构建一次。不要运行 pixi add / uv add。指出构建错误；不要因此使回合失败。
5. 检查点，见下文。当 policy.site 为 true 且检查点构建成功时，说明网站已更新，并链接 report.html 以便在浏览器中打开。不要提及设计说明 Markdown 文件。未构建站点时，不要声称站点已更新，也不要提及 Markdown 文件。
6. python -m skore_skills git end-turn --stage evaluate。如果 JSON action 为 invoke，则在已安装时加载 persist-ml-git 并停止。否则，在已安装时加载 triage-ml-task。此处不要运行 git commit。

检查点

仅限独立检查点。用 2–6 句话说明结果，并以标题为依据；若跳过审计，则以 report.txt 为依据。如果运行了审计，则以其中的 Checks 和 Metrics 为依据。不要编造指标。

链接：当 policy.site 为 true 且构建成功时，说明网站已更新，并链接 [report.html](<workspace>/report.html)，以便在浏览器中打开。 不要提及 html/<stem>.html 或 journal/<stem>.md。未构建站点时，不要声称站点已更新，也不要提及 Markdown 文件。

叙述之后的 Token：先写 JSON locator，再写 G-AUDIT-FINDING（跳过审计时为 n/a — audit not run）。

返回构建阶段

缺少 cv、缺少评分器、预测器类错误，以及缺少冒烟测试或测试未通过，都是应在 build-ml-pipeline 中修复的流水线问题。如何进入该流程取决于是谁加载了此技能：

• 由其他技能调度 — model-ml-pipeline 或 build-ml-pipeline 在本轮加载了此技能：停止并返回该循环，由它返回构建阶段进行修复。
• 直接进入 — 用户要求评估，或入口技能将流程路由到此处：当 status.skills.model-ml-pipeline 为 true 时，加载 model-ml-pipeline，并指出 stem。它会恢复已批准的设计，并在构建所声明的模型层级上重新进入构建阶段进行修复。请勿在此处加载 build-ml-pipeline：此技能加载的子步骤最多只能运行在此技能自身的层级。若缺少 model-ml-pipeline → 用一行说明流水线需要在构建阶段修复，然后停止。

无论哪种情况，本轮都不要编写 skore.evaluate。

停止条件

• 存在待处理的设置（status.setup.pending 非空）→ 加载 setup-ml-project。已拒绝的 git 不再询问。拒绝环境或工作区设置则停止。
• 依赖历史记录的流水线缺少冒烟测试或测试未通过 → 返回构建阶段（§ 返回构建阶段）。
• split_kwargs 为空且可能存在分组列 → 返回构建阶段（§ 返回构建阶段）。不要默认使用 KFold。
• import skore 失败 → 若未设置，则设置 G-SKORE-MODE，然后加载 add-python-package。不要退回到 cross_val_score。
• 超参数搜索、服务部署和多次运行跟踪不在范围内。
• 缺少的包若已安装，则加载 add-python-package。 不要在此处运行 env add。

预检 — 在任何代码之前输出

Pre-flight (evaluate-ml-pipeline):
- [ ] sklearn, skrub, skore import
- [ ] frame show is proceed; DataOp cv matches translation
      (or holdout / prefit, and the marker has no cv)
- [ ] skore_mode is set (local | hub | mlflow)
- [ ] evaluate consent is proceed, or the user answered Evaluate
- [ ] Call site is experiments/NN_*.py (not executed)
- [ ] The one run is scratch/results/<stem>/materialize.py
      (not cells in the experiment file)
- [ ] skore.evaluate omits splitter=
      (or splitter="prefit" and only the test table is passed)
- [ ] report.checks.summarize() then project.put
      (no fast_mode, no ignore; after any checks.add)
- [ ] Smoke: passing | n/a (no history-dependent step) | STOP

参考资料

• references/metadata-routing.md — 锁定的 cv 保留在 DataOp 上；evaluate 不传入 splitter=。
• references/skrub_interop.md — 环境字典与 (X, y)。
• references/g_skore_mode.md — Project 构造函数。
• references/reports.md — 何时 evaluate 过于笼统。
• references/custom-metrics.md — 通过 with_scoring 使用非默认指标。
• references/custom-checks.md — 用户要求的检查。
• templates/materialize.py — 唯一的评估运行。复制到 scratch/results/<stem>/materialize.py。