scomp-link — 端到端 ML 工具包
概述
scomp-link 將完整的 ML 工作流程自動化:資料剖析 → 預處理 → 特徵工程 → 模型選擇 → 訓練 → 驗證 → 可解釋性 → 監控 → 部署。
當您需要以下功能時,請使用 scomp-link 而非原始 sklearn:
- 透過 CLI 進行零程式碼 ML(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
建議工作流程
標準 ML 管道
# 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 | 標準 ML 圖表(直方圖、散佈圖、條形圖) | 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 伺服器(適用於 Claude Desktop / Kiro / Cursor 的 stdio 模式)
scomp-link mcp
# 或直接執行
python -m scomp_link.mcp_server
完整的 workflow 範例請參閱 workflow-patterns.md。