scomp-link — 端到端机器学习工具包
概述
scomp-link 可自动化完整的机器学习工作流程:数据剖析 → 预处理 → 特征工程 → 模型选择 → 训练 → 验证 → 可解释性 → 监控 → 部署。
当你需要以下功能时,请使用 scomp-link 替代原始 sklearn:
- 通过 CLI 实现零代码机器学习(24 个命令)
- 基于数据特征的自动模型选择
- 持久化工件(
.scomp格式:模型 + 预处理器 + 配置 + 指标) - 嵌入交互式图表的 HTML 报告
- 生产监控(漂移 + 异常 + 公平性)
- 一键超参数调优(Optuna / Halving)
当你需要以下功能时,请使用原始 sklearn:
- 自定义模型架构(不在工厂模式中)
- 对每个预处理步骤的精细控制
- 需要完全灵活性的研究工作流
安装
pip install scomp-link
决策树:使用哪个命令
我有数据并希望...
├─ 快速理解数据 → scomp-link describe --data file.csv
├─ 完整质量报告(HTML) → scomp-link quality --data file.csv --output report.html
├─ 特征工程 → scomp-link engineer --data file.csv --target y --interactions --log-transform
├─ 训练模型
│ ├─ 回归 → scomp-link run --data file.csv --target y --task regression
│ ├─ 分类 → scomp-link run --data file.csv --target y --task classification
│ ├─ 文本分类 → scomp-link text --data file.csv --text-col msg --target label
│ ├─ 聚类 → scomp-link cluster --data file.csv --n-clusters 5
│ └─ 从 YAML 运行完整流水线 → scomp-link pipeline --config pipeline.yaml
├─ 调优超参数 → scomp-link tune --data file.csv --target y --task regression --method optuna
├─ 使用保存的模型进行预测 → scomp-link predict --artifact model.scomp --data new.csv
├─ 在测试数据上验证 → scomp-link validate --artifact model.scomp --data test.csv --target y
├─ 解释模型决策 → scomp-link explain --artifact model.scomp --data test.csv
├─ 监控生产
│ ├─ 仅漂移 → scomp-link drift --reference train.csv --current prod.csv
│ ├─ 完整监控 → scomp-link monitor --reference train.csv --current prod.csv --artifact model.scomp
│ └─ 异常检测 → scomp-link anomaly --data prod.csv --methods iforest,lof,tabnet,transformer
├─ 检查公平性/偏差 → scomp-link fairness --data preds.csv --target y_true --predicted y_pred --sensitive gender
├─ 预测时间序列 → scomp-link forecast --data series.csv --column value --horizon 30
├─ 比较模型 → scomp-link compare --artifacts v1.scomp v2.scomp
├─ 生成 HTML 报告 → scomp-link report --data file.csv --output report.html
├─ 作为 REST API 提供服务 → scomp-link serve --artifact model.scomp --port 8080
├─ 导出为 ONNX/pickle → scomp-link export --artifact model.scomp --format onnx
└─ 脚手架生成新项目 → scomp-link init my_project
推荐工作流
标准机器学习流水线
# 1. 剖析数据
scomp-link describe --data train.csv --format table
# 2. 检查数据质量
scomp-link quality --data train.csv --output quality_report.html
# 3. 特征工程
scomp-link engineer --data train.csv --target price --interactions --log-transform --output engineered.csv
# 4. 调优超参数
scomp-link tune --data engineered.csv --target price --task regression --method optuna --n-trials 100 --save-artifact best_model.scomp
# 5. 在留出测试数据上验证
scomp-link validate --artifact best_model.scomp --data test.csv --target price --report validation.html
# 6. 解释
scomp-link explain --artifact best_model.scomp --data test.csv
# 7. 部署
scomp-link serve --artifact best_model.scomp --port 8080
YAML 流水线(一体化)
# pipeline.yaml
data: train.csv
target: price
task: regression
engineer:
interactions: true
log_transform: true
tune:
method: optuna
n_trials: 50
validate:
test_data: test.csv
report: validation_report.html
save: models/price_model.scomp
scomp-link pipeline --config pipeline.yaml
可视化与报告
scomp-link 有三个可视化引擎。详情请参阅 visualization-guide.md。
快速参考
| 引擎 | 最佳用途 | 输出 | 交互性 |
|---|---|---|---|
| Plotly | 标准机器学习图表(直方图、散点图、条形图) | HTML(交互式) | 是 |
| RAWGraphs | 出版级图表(桑基图、树图、弦图) | SVG(静态) | 否 |
| Highcharts | 时间序列(流图、热力图、甘特图) | HTML(交互式) | 是 |
创建 HTML 报告(Python API)
from scomp_link.utils.report_html import ScompLinkHTMLReport
from scomp_link.utils.plotly_utils import histogram, barchart, linechart, area_chart
from scomp_link.utils.highcharts import streamgraphs, calendar_heatmap, calendar_gantt
from scomp_link.utils.rawgraphs import treemap, sankey_diagram, sunburst
# 1. 初始化
report = ScompLinkHTMLReport(title='我的分析报告')
# 2. 添加带内容的章节
report.open_section("数据概览")
report.add_title("数据集统计信息")
report.add_text("对 10,000 条客户记录的分析。")
report.add_dataframe(summary_df, "汇总统计")
report.close_section()
# 3. 添加图表
report.open_section("分布情况")
fig = histogram(df['age'].values, "年龄分布")
report.add_graph_to_report(fig, "年龄直方图")
report.close_section()
# 4. 添加 RAWGraphs SVG
report.open_section("层级视图")
svg = treemap(labels, parents, values, "按类别划分的收入")
report.add_rawgraphs_to_report(svg, "收入树图")
report.close_section()
# 5. 添加 Highcharts
report.open_section("时间趋势")
html_stream = streamgraphs("销售趋势", dates, series_dict, area=True)
report.html_report += html_stream # Highcharts 直接追加 HTML
report.close_section()
# 6. 保存
report.save_html('analysis_report.html')
report.save_pdf('analysis_report.pdf') # 需要 Playwright
可用图表(31 种 RAWGraphs + 5 种 Plotly + 3 种 Highcharts)
比较:barchart, barchartmultiset, barchartstacked, piechart, radarchart, voronoidiagram 分布:beeswarm, boxplot, violinplot 时间序列:bumpchart, gantt_chart, horizongraph, linechart, slopechart, streamgraph 相关性:bubblechart, contour_plot, convex_hull, hexagonal_binning, matrixplot, parallelcoordinates 层级:circlepacking, circular_dendrogram, dendrogram, sunburst, treemap, voronoi_treemap 网络:alluvial_diagram, arc_diagram, chord_diagram, sankey_diagram Plotly:histogram, multiple_histograms, barchart, linechart, area_chart Highcharts:streamgraphs, calendar_heatmap, calendar_gantt
链式调用模式
命令旨在链式使用——一个命令的输出是下一个命令的输入:
describe → (理解列) → engineer → (engineered.csv) → tune → (model.scomp) → validate → (指标)
↓
predict (新数据)
↓
serve (REST API)
关键模式:
--save-artifact model.scomp→ 在 predict/validate/explain/export/serve 命令中与--artifact model.scomp配合使用--output file.csv→ 在下一个命令中作为--data file.csv使用--report file.html→ 独立的 HTML 输出(可在浏览器中查看)--plot file.html→ 用于 forecast/drift/anomaly/cluster/compare 的图表输出
常见错误及修复
| 错误 | 原因 | 修复 |
|---|---|---|
ValueError: could not convert string to float | 数值模型中的分类列 | 使用 --engineer 标志或预处理分类变量 |
FileNotFoundError: artifact not found | .scomp 文件路径错误 | 检查路径是否存在,使用绝对路径 |
ImportError: torch required | 缺少 NLP/深度学习依赖 | pip install scomp-link 包含所有依赖 |
ArrowInvalid: 1-dimensional array | 预处理中的图像/数组数据 | 已在 v1.2.0 中修复——更新 scomp-link |
No module named 'click' | spaCy 依赖缺失 | pip install click(传递性依赖) |
WeasyPrint: cannot load gobject | PDF 所需的系统库缺失 | 使用 save_pdf()(Playwright)替代 WeasyPrint |
MCP 服务器
scomp-link 包含一个 MCP 服务器,用于智能体集成:
# 启动 MCP 服务器(stdio 模式,适用于 Claude Desktop / Kiro / Cursor)
scomp-link mcp
# 或直接运行
python -m scomp_link.mcp_server
完整工作流示例请参阅 workflow-patterns.md。