Metadata-Version: 2.4
Name: preflight-gpu
Version: 0.1.0
Summary: 파인튜닝을 시작하기 전, 지금 환경이 실제로 준비됐는지 확인하는 진단 CLI
Project-URL: Homepage, https://github.com/plzHynx500/preflight
Project-URL: Repository, https://github.com/plzHynx500/preflight
Project-URL: Issues, https://github.com/plzHynx500/preflight/issues
Author: Preflight team
License: MIT
License-File: LICENSE
Keywords: bitsandbytes,cuda,diagnostics,fine-tuning,gpu,lora,qlora
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: nvidia-ml-py>=12
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# Preflight

> 파인튜닝을 시작하기 전, 지금 환경이 실제로 준비됐는지 확인합니다.

*오픈소스 · 파인튜닝 환경 진단 도구*

---

## 왜 만들었나

QLoRA 같은 경량화 기법 덕분에 개인 GPU 한 장으로도 LLM 파인튜닝이 현실적인 선택지가 됐습니다. 하지만 드라이버·CUDA·PyTorch·학습 라이브러리로 이어지는 버전 호환성과 VRAM 산정은 여전히 까다롭고, 무엇보다 **에러 없이 조용히 실패하는 경우**가 흔합니다.

- **조용한 실패** — GPU가 설치돼 있어도 실제로는 쓰이지 않고 CPU로만 연산이 도는 경우, 느리기만 할 뿐 에러가 없어 원인을 알아채기 어렵습니다. 실제로 `torch.cuda.is_available()`이 True이고 버전도 다 맞는데, 조용히 CPU로 폴백돼 RAM만 소모한 사례를 겪은 적이 있습니다.
- **VRAM 오판** — 학습은 가중치·그래디언트·옵티마이저 상태·활성값, 네 가지 메모리를 동시에 요구합니다. 앞의 셋은 모델 구조만 알면 정확히 계산되지만, 활성값과 그 부산물인 allocator fragmentation은 실행 시점의 선택에 따라 달라져 실행해봐야만 알 수 있습니다.
- **버전 체인** — 드라이버·CUDA·PyTorch·학습 라이브러리가 서로 맞물려 있어, 하나만 어긋나도 학습이 시작조차 안 됩니다.

---

## 우리의 접근 — 추측하지 않고, 실행합니다

Preflight의 핵심 아이디어는 하나입니다 — 상태를 추측하지 않고, 아주 작은 연산을 실제로 GPU에서 실행해 확정된 값을 봅니다. 탄광의 카나리아처럼요.

모델의 실제 가중치나 데이터셋은 필요 없습니다. GPU 메모리 점유량은 텐서의 값이 아니라 shape와 dtype으로 정해지기 때문에, 구조만 같은 랜덤 값으로도 진짜와 동일한 결과를 얻을 수 있습니다. 모델 config만 조회해(수 KB, 다운로드 없음) 같은 모양의 랜덤 모델을 구성하고, 작은 연산 하나를 실제로 돌려 device 배치·메모리 이동·실행 시간을 측정합니다.

```
드라이버·CUDA  →  Python·학습 라이브러리  →  [ Preflight ]  →  실제 학습 실행
  (OS 레벨)          (환경 구성)              (여기서 확인)
```

---

## 핵심 기능 — 확인 → 수정 → 재확인

이 한 루프를 끝까지 완성하는 것이 목표입니다.

**01. 확인 — Canary Check**
작은 텐서 연산 하나로 device 배치, GPU 메모리 이동, 실행 시간(CPU 대비 배수)을 함께 실측해 조용한 실패까지 잡아냅니다.

**02. 확인 — VRAM 실측**
모델을 지정하면 가중치 다운로드 없이 실제 구조로 canary를 구성해 메모리 사용량을 실측합니다. 계산이 아니라 실측이라, activation 메모리와 allocator fragmentation까지 반영됩니다.

**03. 수정 + 재확인**
감지된 문제에 맞는 수정 명령어를 제시하고, 동의 시 실행한 뒤 Canary Check를 재실행해 실제로 고쳐졌는지 확인합니다.

---

## 설치

```
pip install preflight-gpu
```

설치되는 의존성은 `typer`·`rich`·`nvidia-ml-py` 셋뿐입니다. **torch·transformers·bitsandbytes는 일부러 의존성에 넣지 않습니다** — 이 도구는 사용자 환경에 이미 설치된 버전을 그대로 불러와 검증하는 것이 목적이라, 진단 도구의 설치가 진단 대상을 덮어쓰면 안 되기 때문입니다.

설치 후 `preflight` 명령을 찾지 못하면(venv를 활성화하지 않았거나 `--user`로 설치한 경우 Windows에서 흔합니다) 모듈로 실행하면 됩니다.

```
python -m preflight check
```

> **주의** — PyPI에 이름이 비슷한 다른 패키지 `preflight`(웹사이트 배포 점검 도구)가 있고, 그쪽도 `preflight`라는 콘솔 명령을 설치합니다. 둘을 같은 환경에 설치하면 나중에 설치한 쪽이 명령을 덮어씁니다. 이 도구의 패키지 이름은 **`preflight-gpu`** 입니다.

---

## 언제 쓰나요 — 학습 명령어 실행 직전

`git commit` 전에 `git status`를 확인하는 것처럼, 학습을 시작하기 전 한 줄이면 됩니다. 설치 직후, 드라이버 업데이트 직후, 팀 온보딩·CI 스크립트에 넣어두는 것을 권장합니다.

```
$ preflight check

✔ Canary 연산 실행              device=cuda · 메모리 이동 확인됨
✖ bitsandbytes 4bit 레이어      device=cpu 감지 → 조용한 CPU 폴백
⚠ 실행 시간 1.1배                CPU 대비 유의미한 가속 없음 (2배 미만)

FIX(제안): /home/user/venv/bin/python -m pip install bitsandbytes --upgrade --force-reinstall
```

제안하는 명령은 PATH에서 찾은 `pip`이 아니라 **지금 preflight를 실행 중인 파이썬**을 가리킵니다 — venv를 활성화하지 않았거나 pipx·전역 설치로 쓰는 환경에서 진단한 곳과 다른 환경에 설치되는 것을 막기 위해서입니다.

### CI/CD 연동 및 종료 코드 (Exit Code)

Preflight는 CI/CD 파이프라인이나 자동화 스크립트에서 프로그래밍 방식으로 결과를 판단할 수 있도록 규격화된 종료 코드를 반환합니다. `--yes` 옵션으로 수정 및 재확인을 수행하면, 재확인 결과로 교체된 전체 진단 결과를 다시 집계한 값을 기준으로 반환합니다(재확인하지 않은 항목의 판정도 그대로 반영됩니다). 실행할 수정 명령이 없었거나 그 명령이 실패해 재확인을 하지 못한 경우에는 1차 판정이 기준입니다.

| 종료 코드 | 판정 | 설명 |
|---|---|---|
| `0` | **PASS** | 모든 판정 항목이 정상 |
| `1` | **FAIL** | 최종 판정에 FAIL이 하나라도 포함된 경우 |
| `2` | **WARN** | FAIL 없이 WARN만 포함된 경우 |

> **CI 연동 시 주의사항**: GitHub Actions, Jenkins 등 대부분의 CI 도구는 `0`이 아닌 모든 종료 코드(`1`, `2`)를 파이프라인 실패(Error)로 간주합니다. WARN(`2`) 판정 시 파이프라인을 중단하지 않고 계속 진행하려면 아래와 같이 셸 스크립트에서 종료 코드를 분기 처리해야 합니다.
> ```bash
> preflight check || [ $? -eq 2 ]
> ```

---

## 누구를 위한 도구인가

- **설치가 막힌 사용자** — 파인튜닝 도구 설치 자체가 환경 문제로 실패해, 학습 도구 화면조차 보지 못한 초심자
- **확정값이 필요한 사용자** — "문제가 있을 수 있다"는 추정이 아니라, 실제로 문제가 있는지 확정된 답이 필요한 사용자
- **특정 생태계에 묶이고 싶지 않은 팀** — 여러 학습 도구 중 무엇을 쓰든, 그 전에 공통으로 거치는 검증을 원하는 연구팀
- **환경 변경 이후** — 드라이버 업데이트, GPU 교체, 더 큰 모델로 전환한 뒤 매번 실측으로 다시 확인하고 싶은 사용자

---

## 기대 효과

- 몇 시간 걸리는 학습이 환경 문제로 중간에 실패해 시간과 전력을 낭비하는 상황을 사전에 줄입니다.
- 버전 호환성이나 VRAM 계산처럼 스스로 진단하기 어려운 부분을 자동으로 검증해, 인프라 지식이 부족한 초심자도 안전하게 로컬 파인튜닝에 도전할 수 있도록 돕습니다.
- 어떤 학습 도구를 선택하든, 그 이전 단계에서 먼저 거쳐가는 공통 검증 관문으로 자리잡는 것을 목표로 합니다.

---

## 프로젝트 정보

| | |
|---|---|
| 라이선스 | MIT — 재배포·임베딩 제약 없음 |
| 지원 플랫폼 | Linux, Windows (네이티브) |
| 설치 | `pip install preflight-gpu` (실행 명령은 `preflight`) |
| 실행 | `preflight check` — 명령을 못 찾으면 `python -m preflight check` |

---

*기여, 이슈 제보, 피드백을 환영합니다. 자세한 개발 배경과 설계 문서는 저장소의 다른 문서를 참고해 주세요.*
