Wiki_FAQ

❓ 자주 묻는 질문 (FAQ)

🐍 Python & 개발 환경 (uv)

Q. 왜 pip 대신 uv를 사용하나요?

A. uv는 Rust로 작성되어 기존 도구보다 수십 배 빠르며, pyproject.toml 하나로 의존성과 파이썬 버전을 모두 안전하게 관리할 수 있기 때문입니다.

Q. 패키지를 새로 설치하려면 어떻게 하나요?

A. 터미널에서 uv add 패키지명을 입력하세요. 자동으로 pyproject.toml과 uv.lock이 업데이트됩니다. 개발용 도구라면 uv add --dev 패키지명을 사용합니다.

Q. venv를 직접 만들어야 하나요?

A. 아니요. uv sync를 실행하면 프로젝트 루트의 .venv 폴더에 최적화된 가상환경이 자동으로 구성됩니다.

---

🤖 AI & 데이터 관련

Q. 모델 웨이트(Weight) 파일도 깃허브에 올리나요?

A. 아니요. 대용량 파일(.pth, .bin, .h5 등)은 깃허브에 올리지 않는 것이 원칙입니다. 대신 공유 드라이브나 Hugging Face, 혹은 지정된 클라우드 스토리지에서 다운로드하는 스크립트를 사용하세요.

Q. 데이터셋 위치는 어디인가요?

A. 프로젝트 루트의 data/ 폴더 내에 배치하되, 보안을 위해 .gitignore에 등록되어 있는지 확인 후 로컬에서만 관리합니다.

Q. GPU가 꼭 필요한가요?

A. 학습(Training)에는 필수적이지만, 단순 추론(Inference)이나 코드 테스트는 CPU(mps/cpu) 환경에서도 가능합니다. device 설정 코드를 확인해 주세요.

---

💻 협업 및 오류 해결

Q. ImportError 혹은 ModuleNotFoundError가 발생해요.

A. uv sync를 통해 의존성이 최신화되었는지 확인하세요. 또한, IDE(VS Code 등)의 Python Interpreter 설정이 .venv로 되어 있는지 체크해야 합니다.

Q. 린트(Ruff) 에러 때문에 커밋이 안 돼요.

A. uv run ruff format . 명령어를 실행하여 코드를 자동으로 교정한 후 다시 시도해 보세요.

Q. .env 파일은 어디서 구하나요?

A. 보안 상 저장소에 올리지 않습니다. 팀 채널의 공지사항이나 담당자에게 env.example 형식을 참고하여 공유 요청을 하세요.