개발 환경 구성

사용하는 도구는 사고방식을 형성합니다. 한 번 설정할 때 제대로 설정합니다.

유형: Build 언어: Python, Node.js, Rust, Julia 선수 지식: 없음 예상 시간: 약 45분

학습 목표

• Python 3.13, Node.js 20+, Rust 툴체인(toolchain)을 처음부터 구성합니다.
• 재현 가능한 빌드(build)를 위해 가상환경(virtual environment)과 패키지 관리자(package manager)를 설정합니다.
• CUDA/MPS GPU 접근을 확인하고 테스트 텐서 연산(test tensor operation)을 실행합니다.
• 시스템(system), 패키지(packages), 런타임(runtimes), AI 라이브러리(AI libraries)로 이어지는 네 계층 스택(stack)을 이해합니다.

문제

이 과정에서는 Python, TypeScript, Rust, Julia를 사용해 200개 이상의 강의(lesson)를 학습하게 됩니다. 개발 환경이 깨져 있으면 모든 강의가 학습이 아니라 도구와 싸우는 시간이 됩니다.

많은 사람이 환경 설정을 건너뜁니다. 그리고 나중에 임포트 오류(import error), 버전 충돌(version conflict), CUDA 드라이버(CUDA driver) 누락 같은 문제를 디버깅하느라 몇 시간을 씁니다. 이 강의에서는 이 작업을 한 번, 제대로 해 둡니다.

PAI 기술부 OJT에서는 여기에 한 가지를 더 봅니다. 개인 컴퓨터에서만 우연히 실행되는 환경이 아니라, 멘토와 동료가 같은 기준으로 확인할 수 있는 재현 가능한 환경을 만드는 것이 중요합니다.

개념

AI 엔지니어링 환경은 네 계층으로 이해할 수 있습니다.

graph TD
    A["4. AI/ML 라이브러리<br>PyTorch, JAX, transformers 등"] --> B["3. 언어 런타임<br>Python 3.13, Node 20+, Rust, Julia"]
    B --> C["2. 패키지 관리자<br>uv, pnpm, cargo, juliaup"]
    C --> D["1. 시스템 기반<br>OS, shell, git, editor, GPU driver"]

설치는 아래에서 위로 진행합니다. 각 계층은 바로 아래 계층에 의존합니다.

직접 만들기

Step 1: 시스템 기반 확인

시스템을 확인하고 기본 개발 도구를 설치합니다.

# macOS
xcode-select --install
brew install git curl wget

# Ubuntu/Debian
sudo apt update
sudo apt install -y build-essential git curl wget

# Windows (WSL2 사용)
wsl --install -d Ubuntu-24.04

설치 후 Git이 잡히는지 확인합니다.

git --version

Step 2: Python과 uv 설치

이 과정의 Python 환경은 uv를 기본 도구로 사용합니다. uv는 Python 설치, 가상환경(virtual environment) 생성, 패키지 설치를 빠르게 처리하며 프로젝트별 환경을 분리하기 좋습니다.

curl -LsSf https://astral.sh/uv/install.sh | sh

uv python install 3.13

uv venv
source .venv/bin/activate  # Windows에서는 .venv\Scripts\activate

uv pip install numpy matplotlib jupyter

Windows PowerShell을 사용한다면 아래처럼 활성화할 수 있습니다.

.venv\Scripts\Activate.ps1

Python과 NumPy가 정상 동작하는지 확인합니다.

import sys
import numpy as np

print(f"Python {sys.version}")
print(f"NumPy {np.__version__}")

vector = np.array([1, 2, 3])
print(f"벡터: {vector}")
print(f"내적: {np.dot(vector, vector)}")

Step 3: Node.js와 pnpm 설치

TypeScript 강의에서 에이전트(agent), MCP 서버(MCP server), 웹 앱(web app)을 만들 때 Node.js와 pnpm을 사용합니다.

curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22
fnm use 22

npm install -g pnpm

node -e "console.log('Node', process.version)"
pnpm --version

Step 4: Rust 설치

Rust는 추론(inference), 시스템 구성 요소처럼 성능이 중요한 강의에서 사용합니다.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

rustc --version
cargo --version

Step 5: Julia 설치 (선택)

Julia는 수학 중심 강의에서 강점을 보이는 언어입니다.

curl -fsSL https://install.julialang.org | sh

julia -e 'println("Julia ", VERSION)'

Step 6: GPU 사용 가능 여부 확인

NVIDIA GPU가 있다면 CUDA 상태를 확인합니다.

# NVIDIA
nvidia-smi

# CUDA 지원 PyTorch 설치
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

PyTorch가 CUDA GPU를 인식하는지 확인합니다.

import torch
print(f"CUDA 사용 가능: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU: {torch.cuda.get_device_name(0)}")

Apple Silicon macOS에서는 MPS를 확인합니다.

import torch
print(f"MPS 사용 가능: {torch.backends.mps.is_available()}")

GPU가 없어도 괜찮습니다. 대부분의 강의는 CPU에서 동작합니다. 학습량이 큰 강의에서는 Google Colab이나 클라우드 GPU(cloud GPU)를 사용할 수 있습니다.

Step 7: 검증 스크립트 실행

검증 스크립트를 실행합니다.

python phases/00-setup-and-tooling/01-dev-environment/code/verify.py

핵심 항목이 모두 PASS로 나오면 다음 강의로 넘어갈 수 있습니다. GPU 항목은 선택 사항입니다.

사용해보기

이제 이 과정의 모든 강의를 진행할 수 있는 기본 환경이 준비됐습니다. 언어별 사용 위치와 패키지 관리자는 아래처럼 나뉩니다.

개발 환경 문제가 생기면 무작정 재설치하지 말고 어느 계층에서 실패했는지 먼저 분리합니다.

PAI OJT에서는 환경 문제도 학습 기록의 일부로 봅니다. 실패한 명령어, 에러 메시지, 확인한 계층, 적용한 수정 명령을 함께 남기면 멘토가 빠르게 도울 수 있습니다.

산출물 만들기

이 강의는 누구나 자신의 환경을 확인할 수 있는 검증 스크립트를 산출합니다.

outputs/prompt-env-check.md에는 AI assistant가 한국어로 환경 문제를 진단하도록 돕는 prompt가 있습니다. 환경 진단이 어렵다면 이 prompt를 사용해 어느 계층이 깨졌는지 확인합니다.

PAI OJT에서는 아래 형식으로 실행 결과를 남깁니다.

# 개발 환경 점검 결과

- 날짜:
- OS:
- Python:
- Node.js:
- Rust:
- Julia:
- uv:
- pnpm:
- GPU:

## 실패 항목

- 항목:
- 에러 메시지:
- 추정 계층:
- 조치:

## 재검증 결과

- `verify.py` 결과:
- 남은 이슈:

연습문제

1. 검증 스크립트를 실행하고 실패 항목을 고칩니다.
2. 이 과정을 위한 Python 가상환경을 만들고 PyTorch를 설치합니다.
3. Python, Node.js, Rust, Julia에서 각각 "hello world"를 작성하고 실행합니다.
4. 환경 점검 결과를 멘토가 재현할 수 있는 형태로 정리합니다.

핵심 용어

더 읽을거리

• uv 공식 문서 — uv로 Python 버전, 가상환경, 의존성(dependency)을 관리하는 기준을 확인합니다.
• PyTorch 설치 안내 — CPU, CUDA, macOS 환경별 PyTorch 설치 명령을 확인합니다.
• pnpm 설치 문서 — TypeScript 실습에서 사용할 패키지 관리자 설치 방법을 확인합니다.
• rustup — Rust toolchain 설치와 업데이트 방법을 확인합니다.
• Julia 설치 안내 — 운영체제별 Julia 설치 방법과 juliaup 사용법을 확인합니다.