uplift-model-tuning

Name: uplift-model-tuning
Author: QFIN-tech

40stars16forks

How to install uplift-model-tuning?

qfin-tech/model-evo/uplift-model-tuning

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-tuning

Installs into the current project.

Summary

已有 successful S-Learner 或 T-Learner modeling_result_path 后，用于生成、确认并执行有边界的 LightGBM learner 调参 study。不要用于首次训练、多模型比较、最终报告或模型采用决策。

Files · 1

View on GitHub

SKILL.md

1	# 模型调参
2
3	## 1. 输入依赖
4
5	本 skill 只负责基于已完成的 baseline S-Learner 或 T-Learner 做有边界调参：
6
7	- `draft_plan` 生成调参计划草稿，不训练模型。
8	- `confirm_plan` 记录用户确认和必要风险确认。
9	- `execute` 基于 confirmed plan 真实训练候选 trial，复用 `trial_000` baseline 作为对照，并输出 study winner。
10
11	本 skill 不比较多个候选集合，不生成最终建模报告，不声明 primary/final/deployment model。
12
13	本 skill 是当前 bundle 中唯一调参入口；不要新增或调用 `uplift-t-learner-tuning`。
14
15	已有 successful S-Learner 或 T-Learner `modeling_result_path` 后使用。
16
17	## 2. 执行入口
18
19	统一 CLI：
20
21	```bash
22	python <skill-dir>/scripts/run.py --input - --output-dir <output_dir>
23	```
24
25	Windows 环境可按需将路径分隔符改为反斜杠。
26
27	`--output-dir` 必须是已存在的 `run_dir`；runner 不创建 run_dir，不扫描 `latest/current`。`draft_plan` / `confirm_plan` 输出到 tuning flow；`confirm_plan` 必须显式传入 `outputs.flow_dir` 复用该 flow。`draft_plan` 校验但不创建 `experiment_id`，`execute` 只能使用 confirmed tuning plan 内的 `experiment_id` 创建 winner experiment，目标 experiment 已存在时返回 `needs_input / EXPERIMENT_ALREADY_EXISTS`。
28
29	请求 JSON 必须通过 stdin 传入：
30
31	```json
32	{"action": "draft_plan", "payload": {"experiment_id": "exp-003-s_learner_tuned", "task_config_path": "...", "modeling_sample_spec_path": "...", "feature_plan_path": "...", "modeling_result_path": "..."}}
33	```
34
35	runner stdout 是 JSON object。调用方只读取 stdout 或 result JSON 中的 `outputs.*` 字段，例如 `outputs.tuning_plan_path`、`outputs.winner_model_result_path`、`outputs.model_candidate_path`、`outputs.report_path`。
36
37	只接受显式 `_path` / `_paths` 字段。收到旧的 `_ref` / `_refs` 输入时，runner 返回 `needs_input`，并在 `issues` 与 `next_steps` 中给出对应替代字段。
38
39	## 3. Actions 与参数说明
40
41	`draft_plan`
42
43	- 输入：`experiment_id`、`task_config_path`、`modeling_sample_spec_path`、`feature_plan_path`、`modeling_result_path`。
44	- 可选输入：`preferences.profile`、`preferences.selection_dataset_role`、`preferences.budget`、`preferences.fixed_parameters`、`preferences.search_space_overrides`、`preferences.candidate_grid`。
45	- 输出：`tuning_plan_path`。
46
47	`tuning_plan` 必须显式记录：
48
49	- `model_spec.model_type`
50	- `model_spec.base_estimators`
51	- `parameter_strategy`
52
53	v1 只支持 `parameter_strategy = "shared"`。收到 `parameter_strategy = "per_arm"`、`per_arm_parameters`、`component_parameters`、`treatment_parameters` 或 `control_parameters` 时，runner 返回 `needs_input`，`issues[].code = "UNSUPPORTED_PARAMETER_STRATEGY"`。
54
55	如果 execute 发现 confirmed plan 中的 `model_spec` 和 baseline result 暴露的 `model_spec` 不一致，runner 返回 `needs_input`，`issues[].code = "MODEL_SPEC_MISMATCH"`。
56
57	`confirm_plan`
58
59	- 输入：`source_plan_path` 或 `tuning_plan_path`、`warning_acknowledgements`、`confirmed_by`。
60	- 输出：confirmed `tuning_plan_path`。
61
62	`execute`
63
64	- 输入：confirmed `tuning_plan_path`。
65	- 输出：
66	- `experiment_id`
67	- `experiment_dir`
68	- `tuning_plan_path`
69	- `tuning_result_path`
70	- `trial_metrics_path`
71	- `leaderboard_path`
72	- `winner_result_path`
73	- `winner_model_result_path`
74	- `winner_metrics`
75	- `winner_metrics_path`
76	- `model_candidate_path`
77	- `evaluation_metrics_path`
78	- `model_artifact_path`
79	- `report_path`
80	- `tuning_report_path`
81
82	读取 baseline 时，selection split 必须存在 `outputs.split_evaluations.<split>.auuc_version = {"package": "scikit-uplift", "version": "0.5.1"}`；缺失或版本不一致时 runner 返回明确错误并提示重跑 baseline。
83
84	快速验收只能通过显式小 `max_trials`、小 `candidate_grid` 或窄搜索空间控制耗时；这仍是真实调参执行，不是 mock。
85
86	## 4. 输出产物
87
88	典型输出目录：
89
90	```text
91	{run_dir}/uplift-model-tuning/{timestamp}_model_tuning/
92	inputs/0001_draft_plan.request.json
93	results/0001_draft_plan.result.json
94	artifacts/
95	tuning_plan.draft.v1.json
96	tuning_plan.confirmed.v1.json
97	_flow_manifest.json
98	_flow_log.jsonl
99
100	{run_dir}/new-models/{experiment_id}/
101	inputs/0001_execute.request.json
102	results/0001_execute.result.json
103	artifacts/
104	trial_metrics.v1.json
105	leaderboard.v1.csv
106	winner_metrics.v1.json
107	winner_model_result.v1.json
108	model_candidate.v1.json
109	tuning_report.md
110	s_learner_tuned_model.v1.joblib
111	t_learner_tuned_model.v1.joblib
112	t_learner_tuned_treatment_model.v1.txt
113	t_learner_tuned_control_model.v1.txt
114	_experiment_manifest.json
115	_experiment_log.jsonl
116	report.md
117	```
118
119	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。下游比较优先通过 `experiment_ids` 进入 `uplift-model-result-comparison` 的 `draft_comparison_plan`。
120
121	如果 winner 是 `trial_000`，`model_artifact_path` 可指向 baseline 模型文件；`winner_model_result_path` 仍由本次 study 生成，便于下游比较。
122
123	T-Learner 的非 baseline trial 使用同一组 shared LightGBM 参数训练 treatment/control 两个子模型。`trial_000` 复用 baseline T-Learner model 和 baseline evidence，不重新训练。
124
125	## 5. 与其他 skill 的关联
126
127	\| 方向 \| Skill \| 关系 \|
128	\|---\|---\|---\|
129	\| 上游 \| `uplift-model-s-learner-modeling` / `uplift-model-t-learner-modeling` \| 提供 successful baseline `modeling_result_path` \|
130	\| 下游 \| `uplift-model-result-comparison` \| 消费 winner `experiment_id`、`winner_model_result_path` 或 `model_candidate_path` 参与模型比较 \|
131	\| 下游 \| `uplift-model-reporting` \| 可消费 `winner_model_result_path`、`model_candidate_path`、`tuning_result_path` 生成最终报告 \|
132
133	## 6. 执行约束
134
135	本 skill 不比较多个候选集合，不生成最终建模报告，不声明 primary/final/deployment model

People who liked this also viewed

6 picks

Type

uplift-model-tuning

40stars16forks

View on GitHub

How to install uplift-model-tuning?

qfin-tech/model-evo/uplift-model-tuning

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-tuning

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# 模型调参
2
3	## 1. 输入依赖
4
5	本 skill 只负责基于已完成的 baseline S-Learner 或 T-Learner 做有边界调参：
6
7	- `draft_plan` 生成调参计划草稿，不训练模型。
8	- `confirm_plan` 记录用户确认和必要风险确认。
9	- `execute` 基于 confirmed plan 真实训练候选 trial，复用 `trial_000` baseline 作为对照，并输出 study winner。
10
11	本 skill 不比较多个候选集合，不生成最终建模报告，不声明 primary/final/deployment model。
12
13	本 skill 是当前 bundle 中唯一调参入口；不要新增或调用 `uplift-t-learner-tuning`。
14
15	已有 successful S-Learner 或 T-Learner `modeling_result_path` 后使用。
16
17	## 2. 执行入口
18
19	统一 CLI：
20
21	```bash
22	python <skill-dir>/scripts/run.py --input - --output-dir <output_dir>
23	```
24
25	Windows 环境可按需将路径分隔符改为反斜杠。
26
27	`--output-dir` 必须是已存在的 `run_dir`；runner 不创建 run_dir，不扫描 `latest/current`。`draft_plan` / `confirm_plan` 输出到 tuning flow；`confirm_plan` 必须显式传入 `outputs.flow_dir` 复用该 flow。`draft_plan` 校验但不创建 `experiment_id`，`execute` 只能使用 confirmed tuning plan 内的 `experiment_id` 创建 winner experiment，目标 experiment 已存在时返回 `needs_input / EXPERIMENT_ALREADY_EXISTS`。
28
29	请求 JSON 必须通过 stdin 传入：
30
31	```json
32	{"action": "draft_plan", "payload": {"experiment_id": "exp-003-s_learner_tuned", "task_config_path": "...", "modeling_sample_spec_path": "...", "feature_plan_path": "...", "modeling_result_path": "..."}}
33	```
34
35	runner stdout 是 JSON object。调用方只读取 stdout 或 result JSON 中的 `outputs.*` 字段，例如 `outputs.tuning_plan_path`、`outputs.winner_model_result_path`、`outputs.model_candidate_path`、`outputs.report_path`。
36
37	只接受显式 `_path` / `_paths` 字段。收到旧的 `_ref` / `_refs` 输入时，runner 返回 `needs_input`，并在 `issues` 与 `next_steps` 中给出对应替代字段。
38
39	## 3. Actions 与参数说明
40
41	`draft_plan`
42
43	- 输入：`experiment_id`、`task_config_path`、`modeling_sample_spec_path`、`feature_plan_path`、`modeling_result_path`。
44	- 可选输入：`preferences.profile`、`preferences.selection_dataset_role`、`preferences.budget`、`preferences.fixed_parameters`、`preferences.search_space_overrides`、`preferences.candidate_grid`。
45	- 输出：`tuning_plan_path`。
46
47	`tuning_plan` 必须显式记录：
48
49	- `model_spec.model_type`
50	- `model_spec.base_estimators`
51	- `parameter_strategy`
52
53	v1 只支持 `parameter_strategy = "shared"`。收到 `parameter_strategy = "per_arm"`、`per_arm_parameters`、`component_parameters`、`treatment_parameters` 或 `control_parameters` 时，runner 返回 `needs_input`，`issues[].code = "UNSUPPORTED_PARAMETER_STRATEGY"`。
54
55	如果 execute 发现 confirmed plan 中的 `model_spec` 和 baseline result 暴露的 `model_spec` 不一致，runner 返回 `needs_input`，`issues[].code = "MODEL_SPEC_MISMATCH"`。
56
57	`confirm_plan`
58
59	- 输入：`source_plan_path` 或 `tuning_plan_path`、`warning_acknowledgements`、`confirmed_by`。
60	- 输出：confirmed `tuning_plan_path`。
61
62	`execute`
63
64	- 输入：confirmed `tuning_plan_path`。
65	- 输出：
66	- `experiment_id`
67	- `experiment_dir`
68	- `tuning_plan_path`
69	- `tuning_result_path`
70	- `trial_metrics_path`
71	- `leaderboard_path`
72	- `winner_result_path`
73	- `winner_model_result_path`
74	- `winner_metrics`
75	- `winner_metrics_path`
76	- `model_candidate_path`
77	- `evaluation_metrics_path`
78	- `model_artifact_path`
79	- `report_path`
80	- `tuning_report_path`
81
82	读取 baseline 时，selection split 必须存在 `outputs.split_evaluations.<split>.auuc_version = {"package": "scikit-uplift", "version": "0.5.1"}`；缺失或版本不一致时 runner 返回明确错误并提示重跑 baseline。
83
84	快速验收只能通过显式小 `max_trials`、小 `candidate_grid` 或窄搜索空间控制耗时；这仍是真实调参执行，不是 mock。
85
86	## 4. 输出产物
87
88	典型输出目录：
89
90	```text
91	{run_dir}/uplift-model-tuning/{timestamp}_model_tuning/
92	inputs/0001_draft_plan.request.json
93	results/0001_draft_plan.result.json
94	artifacts/
95	tuning_plan.draft.v1.json
96	tuning_plan.confirmed.v1.json
97	_flow_manifest.json
98	_flow_log.jsonl
99
100	{run_dir}/new-models/{experiment_id}/
101	inputs/0001_execute.request.json
102	results/0001_execute.result.json
103	artifacts/
104	trial_metrics.v1.json
105	leaderboard.v1.csv
106	winner_metrics.v1.json
107	winner_model_result.v1.json
108	model_candidate.v1.json
109	tuning_report.md
110	s_learner_tuned_model.v1.joblib
111	t_learner_tuned_model.v1.joblib
112	t_learner_tuned_treatment_model.v1.txt
113	t_learner_tuned_control_model.v1.txt
114	_experiment_manifest.json
115	_experiment_log.jsonl
116	report.md
117	```
118
119	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。下游比较优先通过 `experiment_ids` 进入 `uplift-model-result-comparison` 的 `draft_comparison_plan`。
120
121	如果 winner 是 `trial_000`，`model_artifact_path` 可指向 baseline 模型文件；`winner_model_result_path` 仍由本次 study 生成，便于下游比较。
122
123	T-Learner 的非 baseline trial 使用同一组 shared LightGBM 参数训练 treatment/control 两个子模型。`trial_000` 复用 baseline T-Learner model 和 baseline evidence，不重新训练。
124
125	## 5. 与其他 skill 的关联
126
127	\| 方向 \| Skill \| 关系 \|
128	\|---\|---\|---\|
129	\| 上游 \| `uplift-model-s-learner-modeling` / `uplift-model-t-learner-modeling` \| 提供 successful baseline `modeling_result_path` \|
130	\| 下游 \| `uplift-model-result-comparison` \| 消费 winner `experiment_id`、`winner_model_result_path` 或 `model_candidate_path` 参与模型比较 \|
131	\| 下游 \| `uplift-model-reporting` \| 可消费 `winner_model_result_path`、`model_candidate_path`、`tuning_result_path` 生成最终报告 \|
132
133	## 6. 执行约束
134
135	本 skill 不比较多个候选集合，不生成最终建模报告，不声明 primary/final/deployment model

People who liked this also viewed

6 picks

Type