scomp-link — 엔드투엔드 ML 툴킷
개요
scomp-link는 전체 ML 워크플로를 자동화합니다: 데이터 프로파일링 → 전처리 → 피처 엔지니어링 → 모델 선택 → 학습 → 검증 → 설명 가능성 → 모니터링 → 배포.
다음과 같은 경우 raw sklearn 대신 scomp-link를 사용하세요:
- CLI를 통한 제로코드 ML (24개 명령어)
- 데이터 특성 기반 자동 모델 선택
- 지속형 아티팩트 (
.scomp형식: 모델 + 전처리기 + 설정 + 메트릭) - 대화형 차트가 포함된 HTML 보고서
- 프로덕션 모니터링 (드리프트 + 이상 + 공정성)
- 원클릭 하이퍼파라미터 튜닝 (Optuna/Halving)
다음과 같은 경우 raw 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)
비교: 막대차트, 다중집합막대차트, 쌓인막대차트, 원형차트, 레이더차트, 보로노이다이어그램 분포: 비즈와움, 상자그림, 바이올린그림 시계열: 범프차트, 간트차트, 호라이즌그래프, 꺾은선차트, 경사차트, 스트림그래프 상관관계: 버블차트, 등고선플롯, 볼록껍질, 육각형비닝, 매트릭스플롯, 평행좌표 계층 구조: 원패킹, 원형덴드로그램, 덴드로그램, 선버스트, 트리맵, 보로노이트리맵 네트워크: 알루비알다이어그램, 아크다이어그램, 코드다이어그램, 생키다이어그램 Plotly: 히스토그램, 다중히스토그램, 막대차트, 꺾은선차트, 영역차트 Highcharts: 스트림그래프, 캘린더히트맵, 캘린더간트
연결 패턴
명령어는 이전 명령어의 출력이 다음 명령어의 입력이 되도록 체이닝되도록 설계되었습니다:
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용 시스템 라이브러리 누락 | WeasyPrint 대신 save_pdf() (Playwright) 사용 |
MCP 서버
scomp-link는 에이전트 통합을 위한 MCP 서버를 포함합니다:
# MCP 서버 시작 (Claude Desktop / Kiro / Cursor용 stdio 모드)
scomp-link mcp
# 또는 직접 실행
python -m scomp_link.mcp_server
전체 워크플로 예제는 workflow-patterns.md를 참조하세요.