> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# automl

> AutoML, 시계열, 실험 자동화 중심의 데이터 사이언스 환경입니다.

## 문서 기준

* 기준일: `2026-02-23`
* Python: `3.12`
* 운영체제: macOS, Ubuntu, Windows
* 동기화 명령: `uv sync`

## 호환성 메모

| 환경             | `autogluon` | 기타 패키지   | 설명                           |
| -------------- | ----------- | -------- | ---------------------------- |
| macOS / Ubuntu | 설치됨         | 전체 사용 가능 | 전체 스택 동기화                    |
| Windows        | 제외됨         | 전체 사용 가능 | AutoGluon 대신 FLAML/Optuna 사용 |

<Note>
  `autogluon`은 Windows에서 일부 의존성 빌드 문제가 있어 환경 마커로 제외됩니다. Windows 사용자는 FLAML 또는 Optuna를 대안으로 사용합니다.
</Note>

## AutoML 프레임워크 비교

| 프레임워크     | 특징          | 장점                | 적합한 상황            |
| --------- | ----------- | ----------------- | ----------------- |
| AutoGluon | 앙상블 스태킹 자동화 | 코드 한 줄로 SOTA급 성능  | 정형 데이터 빠른 베이스라인   |
| FLAML     | 경량 AutoML   | 낮은 리소스 소모, 빠른 탐색  | 제한된 컴퓨팅 환경, 빠른 실험 |
| Optuna    | 하이퍼파라미터 최적화 | 유연한 탐색 공간 정의, 시각화 | 커스텀 모델 튜닝, 연구 실험  |

## 주요 패키지 역할

| 패키지             | 역할              | 비고                                  |
| --------------- | --------------- | ----------------------------------- |
| `autogluon`     | 엔드투엔드 AutoML    | Tabular, Multimodal, TimeSeries 지원  |
| `flaml`         | 경량 AutoML 프레임워크 | scikit-learn/LightGBM/XGBoost 자동 선택 |
| `optuna`        | 하이퍼파라미터 최적화     | TPE, CMA-ES 등 다양한 샘플러               |
| `ray`           | 분산 컴퓨팅 프레임워크    | AutoGluon/Optuna 분산 실행 백엔드          |
| `fastai`        | 고수준 딥러닝 래퍼      | 빠른 프로토타이핑, 학습률 탐색                   |
| `statsforecast` | 통계 시계열 예측       | ARIMA, ETS, Theta 등 고전 모델           |
| `spacy`         | 자연어 처리 파이프라인    | 토큰화, NER, 텍스트 전처리                   |

## pyproject.toml

```toml theme={null}
[project]
name = "automl"
version = "0.1.0"
description = "AutoML experimentation environment"
requires-python = "==3.12.*"
dependencies = [
  "autogluon==1.5.0; platform_system != 'Windows'",
  "ray==2.52.1",
  "fastai==2.8.7",
  "statsforecast==2.0.1",
  "spacy==3.8.11",
  "flaml==2.5.0",
  "optuna==4.7.0",
  "ipykernel==7.2.0",
  "pytest==9.0.2",
  "ruff==0.15.2",
]

[tool.uv]
package = false
```

## 설치

<Steps>
  <Step title="프로젝트 생성">
    ```bash theme={null}
    uv init automl
    cd automl
    ```
  </Step>

  <Step title="의존성 락 및 동기화">
    ```bash theme={null}
    uv lock
    uv sync
    ```
  </Step>

  <Step title="Jupyter 커널 등록">
    ```bash theme={null}
    uv run python -m ipykernel install --user --name automl --display-name "UV automl"
    ```
  </Step>
</Steps>

## 설치 확인

모든 OS 공통 확인:

```bash theme={null}
uv run python -c "import ray, fastai, flaml, optuna; print('ray', ray.__version__); print('fastai', fastai.__version__); print('flaml', flaml.__version__)"
```

macOS/Ubuntu에서 `autogluon` 확인:

```bash theme={null}
uv run python -c "import autogluon; print('autogluon', autogluon.__version__)"
```

## 기본 사용 예시

### AutoGluon (macOS/Ubuntu)

```python theme={null}
from autogluon.tabular import TabularPredictor

# 데이터 준비 (pandas DataFrame)
train_data = "train.csv"  # label 컬럼 포함

# 한 줄로 학습 (앙상블 스태킹 자동 수행)
predictor = TabularPredictor(label="target", eval_metric="accuracy").fit(
    train_data, time_limit=300  # 5분 제한
)

# 예측 및 리더보드
predictions = predictor.predict("test.csv")
leaderboard = predictor.leaderboard(silent=True)
print(leaderboard)
```

### Optuna 하이퍼파라미터 최적화

```python theme={null}
import optuna
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import cross_val_score
from sklearn.datasets import load_iris

X, y = load_iris(return_X_y=True)

def objective(trial):
    n_estimators = trial.suggest_int("n_estimators", 50, 300)
    max_depth = trial.suggest_int("max_depth", 3, 15)
    clf = RandomForestClassifier(n_estimators=n_estimators, max_depth=max_depth)
    return cross_val_score(clf, X, y, cv=5).mean()

study = optuna.create_study(direction="maximize")
study.optimize(objective, n_trials=50)
print(f"Best params: {study.best_params}, Best score: {study.best_value:.4f}")
```

<Tip>
  Optuna의 대시보드를 사용하려면 `optuna-dashboard` 패키지를 추가 설치합니다. `optuna-dashboard sqlite:///optuna.db` 명령으로 시각화할 수 있습니다.
</Tip>

## 트러블슈팅

| 증상                        | 원인               | 해결                                                |
| ------------------------- | ---------------- | ------------------------------------------------- |
| Windows에서 `autogluon` 미설치 | 환경 마커로 의도적 제외    | FLAML 또는 Optuna 사용                                |
| Ray 포트 충돌                 | 기존 Ray 프로세스 점유   | `ray stop` 후 다시 시작                                |
| AutoGluon 학습이 느림          | 시간 제한 미설정        | `time_limit` 파라미터 지정                              |
| Optuna study DB 잠금        | 동시 실행 시 SQLite 락 | `storage="sqlite:///optuna.db"` 단일 프로세스 사용        |
| spaCy 모델 누락               | 언어 모델 미다운로드      | `uv run python -m spacy download ko_core_news_sm` |
| `uv sync` 의존성 충돌          | 기존 락 파일과 버전 불일치  | `uv lock --refresh` 후 `uv sync`                   |

## 설치 점검 목록

* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: vllm-serving" icon="arrow-right" href="/setup/uv-env/vllm-serving">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>