환경설정

패키지 설치하기

1장에서는 표를 다루고, 그래프를 그리고, 머신러닝 모델을 만드는 패키지 넷을 씁니다.

pip install numpy pandas matplotlib scikit-learn

2장부터는 신경망 라이브러리 PyTorch 를 씁니다. NVIDIA GPU 가 있는 PC 는 GPU 판을, 없는 PC 는 CPU 판을 설치합니다. GPU 판은 내려받는 파일이 2.6GB 쯤이라 시간이 걸립니다.

pip install torch --index-url https://download.pytorch.org/whl/cu126

pip install torch

위가 GPU 판(CUDA 12.6), 아래가 CPU 판입니다. 그냥 pip install torch 를 하면 Windows 에서는 CPU 판이 설치되어, GPU 가 있어도 쓰지 못합니다. PyTorch 는 Windows 의 Visual C++ 런타임을 함께 씁니다. 설치한 뒤 import torch 에서 오류가 나면 아래 "자주 나는 오류" 표를 봅니다.

3장부터는 남이 학습해 공개한 모델을 Hugging Face 에서 받아 씁니다. 모델을 불러오는 transformers 와, 번역 모델의 토크나이저가 쓰는 sentencepiece 를 설치합니다.

pip install transformers sentencepiece

모델 파일은 처음 불러올 때 인터넷으로 내려받아 C:\Users\사용자이름\.cache\huggingface 에 저장되고, 다음부터는 바로 불러옵니다. 3장에서 받는 모델은 번역 모델 300MB 쯤, 챗봇 모델 1GB 쯤입니다. 내려받을 때 "unauthenticated requests" 라는 안내가 나와도 그대로 진행됩니다(로그인 없이 받을 때 나오는 안내입니다).

4장에서는 데이터를 다루는 datasets 와, Trainer 가 GPU 를 쓸 때 필요한 accelerate 를 더 설치합니다. 4장에서 새로 받는 모델(Qwen/Qwen2.5-0.5B)도 1GB 쯤입니다.

pip install datasets accelerate

5장에서는 LoRA 를 붙이는 peft 와 DPO 를 하는 trl 을 더 설치합니다. 5장의 학습은 GPU 가 있어야 알맞은 시간 안에 끝납니다(GTX 1650 에서 실습 하나에 4~7분).

pip install peft trl

6장에서는 API 서버에 요청을 보내는 openai 라이브러리를 더 설치합니다. 외부 API 와 Ollama 를 같은 코드로 부를 때 씁니다. python-dotenv 는 API 키를 .env 파일에서 읽을 때 씁니다(6장 「외부 API 로 만드는 RAG」).

pip install openai python-dotenv

Ollama 설치(6장부터)

Ollama 는 파이썬 패키지가 아니라 따로 설치하는 프로그램입니다. ollama.com 에서 Windows 설치 파일을 내려받아 설치하거나, PowerShell 에서 winget 으로 설치합니다.

winget install --id Ollama.Ollama

설치하면 Ollama 서버가 백그라운드에서 켜집니다. 새 PowerShell 창을 열고 6장에서 쓰는 모델 셋을 내려받습니다. 합쳐서 3.3GB 쯤입니다. 4GB 보다 작은 GPU 나 GPU 가 없는 PC 는 qwen2.5:0.5b 와 qwen2.5:1.5b 만 받아도 실습 5까지 됩니다.

ollama --version
ollama pull qwen2.5:0.5b
ollama pull qwen2.5:1.5b
ollama pull qwen2.5:3b
ollama list

ollama version is 0.40.1
NAME                       ID              SIZE
qwen2.5:3b                 357c53fb659c    1.9 GB
qwen2.5:1.5b               65ec06548149    986 MB
qwen2.5:0.5b               a8b0c5157701    397 MB

위 출력은 교안을 만든 PC 의 것이고, 내려받은 시각 열과 6장에서 쓰지 않는 모델은 뺐습니다. 모델 파일은 C:\Users\사용자이름\.ollama\models 에 저장됩니다. 서버가 떠 있는지는 브라우저에서 http://localhost:11434 를 열어 "Ollama is running" 이 나오는지로도 봅니다.

7장에서는 임베딩 모델을 쓰는 sentence-transformers 와 벡터DB faiss-cpu, chromadb 를 설치하고, 비교할 오픈소스 LLM 둘을 Ollama 로 더 받습니다. 임베딩 모델(intfloat/multilingual-e5-small)과 재정렬 모델(cross-encoder/mmarco-mMiniLMv2-L12-H384-v1)은 처음 쓸 때 470MB 쯤씩 내려받습니다.

pip install sentence-transformers faiss-cpu chromadb
ollama pull gemma3:1b
ollama pull llama3.2:1b

10장에서는 MCP 서버와 클라이언트를 만드는 mcp 패키지를 설치합니다. 교안을 만든 PC 는 2.3.0 입니다. 1.x 와는 이름이 달라서(FastMCP 가 2.x 에서 MCPServer), 인터넷의 1.x 예제를 그대로 쓰면 오류가 납니다.

pip install mcp

11장에서는 서버 없이 도는 벡터DB 하나를 더 견주려고 qdrant-client 를 설치합니다. 교안을 만든 PC 는 1.20.0 입니다. 11장의 문서 읽기(html, docx, csv)는 표준 라이브러리만 쓰므로 더 설치할 것이 없습니다.

pip install qdrant-client

12장에서는 그림과 글을 함께 다루는 CLIP 모델 둘(clip-ViT-B-32 607MB, sentence-transformers/clip-ViT-B-32-multilingual-v1 543MB)을 처음 쓸 때 내려받고, 그림을 읽는 비전 언어 모델 qwen2.5vl:3b(3.2GB)를 Ollama 로 받습니다. 그림은 Pillow 로 읽습니다(torch 와 함께 설치되어 있다). 4GB GPU 에는 비전 모델이 다 올라가지 않아 일부를 CPU 에서 돌리므로, 그림 한 장 설명에 20초쯤 걸립니다.

ollama pull qwen2.5vl:3b

13장에서는 API 를 만드는 fastapi 를 설치합니다. 교안을 만든 PC 는 fastapi 0.162.0 입니다. 서버를 띄우는 uvicorn(0.54.0), 서버 없이 시험하는 TestClient 가 쓰는 httpx, 토큰을 만드는 PyJWT(2.15.1)는 앞 장의 패키지와 함께 이미 설치되어 있었습니다. 없으면 함께 설치합니다.

pip install fastapi uvicorn httpx PyJWT

14장에서는 웹 화면을 만드는 streamlit 을 설치합니다. 교안을 만든 PC 는 streamlit 1.66.1 입니다. compose 파일을 읽는 PyYAML(6.0.3)은 이미 있었습니다.

pip install streamlit

15장에서는 불러올 때 8비트·4비트로 줄이는 bitsandbytes 를 설치하고(교안을 만든 PC 는 0.50.2, NVIDIA GPU 가 있어야 한다), 같은 모델의 다른 양자화 단계를 Ollama 로 받습니다. GPTQ·AWQ 도구는 Windows 에서 설치가 어려워 설치하지 않았습니다.

pip install bitsandbytes
ollama pull qwen2.5:0.5b-instruct-q8_0
ollama pull qwen2.5:0.5b-instruct-fp16

16장은 새 패키지가 없습니다. 7장의 임베딩·재정렬 모델, 3장의 Qwen2.5-0.5B-Instruct, Ollama 의 qwen2.5:3b 를 다시 씁니다. vLLM 은 Windows 에서 바로 설치되지 않아 Linux 나 WSL2 의 우분투에서 설치합니다. 교안을 만든 PC 에는 설치하지 않았고, 아래 명령도 실행하지 않았습니다.

# WSL2 의 우분투 터미널에서
python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

21장도 새 패키지가 없습니다. 인젝션 시험과 요약은 Ollama 의 qwen2.5:3b, 개인정보 찾기는 파이썬의 re, 가명 처리는 hmac 과 secrets, GPU 메모리 확인은 PyTorch 의 torch.cuda.get_device_properties 와 Ollama 의 /api/ps 를 씁니다. 프로젝트의 CI 스크립트는 하위 프로세스로 돌리며, GitHub Actions 파일은 실행하지 않은 안내 코드입니다. garak, Presidio 같은 보안 도구는 설치하지 않았습니다.

20장도 새 패키지가 없습니다. 답 생성과 LLM 채점은 Ollama 의 qwen2.5:3b, 임베딩은 7장의 intfloat/multilingual-e5-small, KS 검정은 scikit-learn 과 함께 설치된 scipy(교안을 만든 PC 는 1.18.1), 대시보드는 14장의 streamlit 을 씁니다. 실습 1~4와 프로젝트는 Ollama 를 200번 가까이 부르므로 몇 분 걸립니다. 본문의 Prometheus 계기 코드는 실행하지 않은 안내 코드이고, prometheus_client 는 설치하지 않았습니다.

19장에서는 실험 기록과 모델 레지스트리를 맡는 mlflow 를 설치합니다. 교안을 만든 PC 는 mlflow 3.17.2 입니다. 기록은 SQLite 파일(out_mlflow.db)에 두므로 따로 서버를 띄우지 않아도 됩니다. 실행할 때 화면에 INFO, WARNING, DeprecationWarning 같은 안내가 나오지만 실습 결과와는 관계가 없습니다. Airflow 는 Windows 에서 바로 돌지 않아 설치하지 않았고, 19장의 Airflow DAG 와 Docker 명령은 안내 코드와 예상 출력입니다.

pip install mlflow
python -c "import mlflow; print(mlflow.__version__)"

18장도 새 패키지가 없습니다. 9장의 openai 라이브러리(Ollama 의 OpenAI 호환 tools), 7장의 e5 임베딩, 13장의 FastAPI 를 다시 씁니다. 모델은 qwen2.5:3b 와 견주기용 qwen2.5:1.5b 이고, 없으면 ollama pull qwen2.5:1.5b 로 받습니다(약 1GB).

17장도 새 패키지가 없습니다. 13장의 fastapi·uvicorn, 7장의 intfloat/multilingual-e5-small, scikit-learn, Ollama 의 qwen2.5:3b 를 다시 쓰고, compose 파일은 14장의 PyYAML 로 읽습니다. 프로젝트가 8171, 8172 번 포트에 서버를 띄웠다 끄므로, 다른 프로그램이 그 포트를 쓰고 있으면 번호를 바꿉니다. 프로젝트 3의 docker compose 명령은 실행하지 않은 안내 코드입니다. GPU 를 컨테이너에 주려면 Docker Desktop(WSL2)과 NVIDIA 드라이버가 필요합니다.

14장의 Docker 명령을 직접 실행해 보려면 Docker Desktop 이 필요합니다. Windows 에서는 WSL2 위에서 돌며, 관리자 권한으로 설치하고 재부팅해야 합니다. 직원이 많은 회사는 유료 구독이 필요할 수 있으니 조건을 확인합니다. 교안을 만든 PC 에는 설치하지 않았고, 아래 명령도 실행하지 않았습니다.

wsl --install
winget install -e --id Docker.DockerDesktop
docker run hello-world

뒤의 장에서 쓰는 패키지는 그 장의 첫머리에서 설치합니다. 버전과 설치 확인은 그 장을 만들 때 이 표에 더합니다.

실습 파일 놓기

실습 코드는 data 폴더를 작업 폴더로 삼습니다. 교안과 함께 받은 data 폴더를 과정 폴더 안에 두고, 코드 파일도 그 안에서 실행합니다. 파일 목록은 실습 데이터에 있습니다.