8.1 KiB
模型方法与固定接口
先确定目标、对象与粒度、数据和变量、评价指标及需要解释的结论。缺少会改变模型含义的权重、约束或时间粒度时确认；不要假定用户不会回复，也不要编造限制或训练数据。简单业务计算优先工作簿公式，不为求和、比率或格式整理启动机器学习。
通用调用
通过 execute_skill_script 调用 scripts/model_workbook.py：
--input '/usr/local/src/excel/tmp/task/source.xlsx' --spec '<JSON>' --output '/usr/local/src/excel/tmp/task/model.json'
--spec-file 与 --spec 二选一。仅 task: "optimize" 可省略输入文件，直接用已确认的系数建模。其他任务共享 数据分析 的 source 结构；建模数据上限 20000 行、100000 单元格。输出 JSON spec_path 再交给原 apply_workbook.py，不直接覆盖工作簿。
数值字段需有限；除监督学习的特征填补外，模型不自动填补缺失数据。保留异常值和来源行号，避免从数据缺口编造结论。图表可用 chart 字段（首结果表），或在原写入脚本中创建。
综合评价：task: "evaluate"
{
"task": "evaluate",
"source": {"sheet": "供应商"},
"entity": "供应商",
"directions": {"质量合格率": "benefit", "交货准时率": "benefit", "单价": "cost"},
"weighting": "user",
"weights": {"质量合格率": 0.5, "交货准时率": 0.3, "单价": 0.2}
}
directions：效益型benefit、成本型cost、中间最优型{"target": 7}。先统一正向化，之后 TOPSIS 的正理想解统一取大值；不能在已经正向化后再次反转成本方向。weighting：默认透明的equal；用户权重用user（全部指标、非负、总和大于零）；差异性赋权用entropy；用户给出比较矩阵时可用ahp。- 熵权高只说明样本差异性较大，不等于业务重要性。不要在没有用户偏好的情况下编造 AHP 比较矩阵。
- AHP 参数
comparison_matrix：按 directions 顺序，2–9 阶正数互反矩阵，对角为 1；CR 不小于 0.1 时拒绝输出排名，需修正比较判断。 - 空列、非数值、不可解释编码需先处理。常量指标没有区分度；所有对象相同则并列，得分为中性 0.5，不随行顺序强行选“第一”。
输出：综合排名（原值、得分、并列名次、来源行号）和指标权重（方向、权重、适用时的信息熵、无区分度标记）。解释优劣势时引用原始指标与权重；不把得分当作获胜概率。必要时在合理权重范围重新运行，观察排名是否稳定。
时序预测：task: "forecast"
{
"task": "forecast",
"source": {"sheet": "月度销量", "dates": {"月份": "%Y-%m-%d"}},
"by": ["城市"], "date": "月份", "value": "销量",
"frequency": "MS", "horizon": 3,
"methods": ["naive", "linear", "moving_average"], "holdout": 6
}
by可省略；每组独立建模。frequency支持 D（日）、W（周末为周日）、MS（月初）、QS（季度初）、YS（年初）。数据需按对应周期锚点记录、连续、无重复，至少 6 期；先按口径处理重复和缺期，不能默认缺期销量为零。horizon为 1–120 期。holdout默认最后四分之一且至少 2 期，需保留至少 3 期训练数据。naive延续最后值；linear线性趋势；moving_average递归最近最多三期均值；seasonal_naive需明确seasonal_period且训练长度足够。- 候选方法仅使用训练时段预测验证时段，按 MAE 选择后用全历史外推。该验证集参与选型，不能称为完全独立的最终测试集。
输出：各组×未来日期的预测值、验证 MAE/RMSE、历史数据。不要在未建区间模型时声称置信区间，不自动把负预测裁为零；检查趋势外推是否符合业务边界并披露限制。不能宣称已经运行 ARIMA、Prophet 或 XGBoost，本接口实际只运行列出的基线方法。
回归与分类：task: "regression" / "classification"
{
"task": "regression",
"source": {"sheet": "样本"},
"features": ["价格", "促销费用", "城市"],
"categorical": ["城市"], "target": "销量",
"algorithm": "ridge", "test_fraction": 0.2
}
- 至少 10 条记录，目标列不能缺失。
categorical显式列出分类特征，其余为数值特征。ID、目标列、目标派生字段不作为有效预测特征。 - 回归
algorithm：linear（默认）、ridge、forest。分类：logistic（默认）、forest。森林使用固定种子、100 棵树和最大深度 8；不接受任意估计器或任意模型代码。 test_fraction为 0.1–0.5，默认 0.2，留出集至少 2 条记录。普通样本固定随机划分，分类进行分层。时序/未来预测必须指定time_column或使用 forecast，按时间划分；相同时点跨切分边界会被拒绝。若同一实体的重复记录可能泄漏信息，应先设计实体隔离的数据集，不能把随机切分当作有效泛化证据。- 中位数填补、分类缺失标记、One-hot 与标准化都只在训练集拟合，再应用测试集。不会先在全数据预处理后假装留出测试。
- 回归输出训练/测试 MAE、RMSE、R²；分类输出 Accuracy、macro F1，并与均值/多数类基线对比。没有实际计算的 AUC、交叉验证、p 值不填入报告。
predict_source可指定另一个已下载文件的{path, …source参数}；先保留测试结果，再用全量训练数据重新拟合并预测新样本。缺少未来特征时不能凭空生成未来回归预测。
输出：留出样本实际值与预测值、模型指标、特征重要性/绝对系数、可选新样本预测。系数与重要性是关联说明，不能推断因果方向；有负 R² 或测试表现不如基线时明确说明，不以高训练分数宣传可靠性。
聚类和异常检测
task: "cluster"：features: [数值字段]；algorithm: "kmeans"默认，clusters默认 3，需至少为 2 且小于样本数；或algorithm: "dbscan"，eps默认 0.5，min_samples默认 5。task: "anomaly"：features，Isolation Forest；contamination默认 0.05，范围 (0,0.5]。该比例是假设，应与业务目的相符，不表示真实异常率。- 数值特征标准化后分析，不自动删除异常。输出原记录、来源行号和标签；-1 为异常候选或 DBSCAN 噪声，聚类数字不代表优劣。满足条件时报告排除噪声后的轮廓系数。
- 对类别本身或长文本的深层语义先参见文本指南；当前接口不假装运行主题模型、FP-Growth、SMOTE 或任意外部模型。相关性可用 analyze_workbook；需要额外算法时应新增明确的固定接口并单独评估依赖。
资源优化：task: "optimize"
{
"task": "optimize",
"variables": ["产品A", "产品B"], "objective": [30, 20], "sense": "max",
"bounds": [[0, 100], [0, 80]], "integer": [true, true],
"constraints": [
{"name": "可用工时", "coefficients": [2, 1], "relation": "<=", "rhs": 160}
]
}
- 明确变量、目标、资源限制、数量下限/上限及单位，不自动放松约束。
sense默认 min；bounds默认非负无上界，null 表示无界；0–1 决策使用[0,1]和整数标记。 objective是按 variables 顺序的线性系数。约束relation支持<=、>=、==。最多 200 个变量、1000 条约束。- 连续/整数/混合整数线性问题使用 SciPy 内置 HiGHS，时间上限 60 秒。仅成功状态、约束与整数性复核通过才输出方案；超时、无解、无界不能当作最优解。
- 可选
quadratic对称矩阵 Q，目标为c·x + 0.5*xᵀQx；只支持连续变量、线性约束、凸最小化或凹最大化。initial可指定初始点，使用 SLSQP。任意非线性函数不在接口范围内。
输出变量方案、目标值、约束左端值和余量。可用参数情景重新运行分析瓶颈；未求解的“增加资源收益”不能编造。所有结果是按给定系数得到的快照，不会自动随着源单元格更新。