환경설정

작업 폴더 정하기

실습을 시작하기 전에 이 과정에서 쓸 폴더 하나를 정합니다. 요리를 시작하기 전에 조리대 하나를 비워 두고 재료와 도구를 그 위에 모아 두는 것과 같습니다. 여기서 조리대가 작업 폴더이고, 재료가 실습 데이터(data), 도구가 가상환경(.venv)과 패키지 목록(requirements.txt)입니다. 이 교안은 작업 폴더를 C:\chatbot-course 로 정했다고 보고 경로 예시를 적습니다. 이 쪽과 각 장에서 말하는 "과목 폴더"가 이 폴더입니다.

이 경로를 예시로 쓰는 까닭

다른 경로를 써도 실습에는 지장이 없습니다. 그때는 이 교안의 C:\chatbot-course 를 내 폴더의 경로로 바꿔 읽습니다.

폴더 만들고 열기

PowerShell(Windows 의 명령 창)을 열고 아래를 실행합니다.

# 작업 폴더를 만든다. New-Item = 새 항목 만들기, -ItemType Directory = 폴더로, -Force = 이미 있어도 오류 없이 넘어간다
New-Item -ItemType Directory -Force C:\chatbot-course
# 그 폴더로 옮긴다. cd = change directory(폴더 옮기기)
cd C:\chatbot-course
# 지금 폴더를 VS Code 로 연다. code = VS Code 를 여는 명령, . = 지금 폴더
code .

교안을 만든 PC 에서는 C 드라이브 바로 아래에 폴더를 만들지 않았습니다. 같은 이름의 폴더(chatbot-course)를 임시 폴더 안에 만들어 New-Item -Force 가 두 번 실행해도 오류 없이 넘어가는 것만 확인했습니다. code . 는 VS Code 를 설치할 때 "PATH 에 추가" 항목이 켜져 있어야 동작합니다. 동작하지 않으면 VS Code 에서 파일 → 폴더 열기로 C:\chatbot-course 를 엽니다.

받은 파일 넣기

교안과 함께 받은 실습 파일을 이 폴더에 풀어 넣습니다. 받는 파일은 requirements.txt(패키지 목록), .env.example(API 키 파일의 견본), .gitignore(git 이 올리지 않을 파일 목록), data 폴더(실습 데이터), code 폴더(장마다의 실습 코드)입니다. .env.example 과 .gitignore 는 이름이 점으로 시작해서 파일 탐색기에서 숨겨져 보일 수 있습니다.

이 쪽의 순서를 다 마치면 작업 폴더는 아래 모양이 됩니다. .venv 는 "가상환경 만들기"에서, .env 는 "API 키 넣기"에서 생깁니다.

C:\chatbot-course
├─ .venv\              가상환경(설치한 패키지가 들어가는 곳)
├─ .env                API 키 파일(남에게 보내지 않는다)
├─ .env.example        .env 의 견본
├─ .gitignore          git 이 올리지 않을 파일 목록
├─ requirements.txt    패키지 목록
├─ data\               실습 데이터. 실습 코드는 여기서 실행한다
└─ code\               장마다의 실습 코드(ch01, ch02, …)

패키지 설치하기

과목 폴더에 있는 requirements.txt 로 과정 내내 쓰는 패키지를 한 번에 설치합니다. 이 파일에는 설치할 패키지와 판(version)이 한 줄에 하나씩 이름==판 꼴로 적혀 있습니다. 장보기 목록을 들고 가면 하나하나 떠올리지 않아도 같은 물건을 사 오는 것처럼, 누가 설치해도 교안을 만든 PC 와 같은 판이 들어옵니다. 판까지 맞춰 두어야 실습 출력이 원고와 같게 나옵니다.

가상환경을 켠 채로, 과목 폴더(requirements.txt 가 있는 곳, 예: C:\chatbot-course)에서 실행합니다.

# pip 를 먼저 새 판으로 올린다. -m = module(모듈로 실행), -U = upgrade(올리기)
python -m pip install -U pip
# requirements.txt 에 적힌 패키지를 적힌 판 그대로 설치한다. -r = requirement file(목록 파일)
pip install -r requirements.txt
# 설치된 패키지끼리 판이 서로 맞는지 점검한다
pip check

교안을 만든 PC 에서 새 가상환경을 만들어 실행했을 때 마지막 pip check 가 찍은 줄입니다. 이 줄이 나오면 설치가 끝난 것입니다.

No broken requirements found.

requirements.txt 는 아래처럼 장별로 묶여 있습니다. # 로 시작하는 줄은 설명이라 pip 가 읽지 않습니다.

# 1~4차시: LangChain, OpenAI 연결, 키 읽기, 토큰 세기, 표와 그래프
langchain==1.4.7
langchain-core==1.7.3
langchain-openai==1.7.3
openai==3.42.1
pydantic==2.14.2
python-dotenv==1.2.4
tiktoken==0.14.0
numpy==2.5.4
pandas==3.1.0
matplotlib==3.11.2

# 5차시: 도구 연동과 MCP 서버
mcp==1.30.0
langchain-mcp-adapters==0.3.2

# 6차시: PDF 읽기, 텍스트 나누기, FAISS 벡터DB, RetrievalQA
langchain-community==0.4.2
langchain-text-splitters==1.1.3
langchain-classic==1.0.8
pypdf==6.21.4
faiss-cpu==1.15.1

# 7차시: 웹 화면
streamlit==1.66.1

• 판을 고정했기 때문에 Python 판이 너무 새것이거나 오래되면 맞는 설치 파일이 없다는 오류가 날 수 있습니다. 교안은 Python 3.14.6 에서 위 목록이 오류 없이 설치되는 것을 확인했습니다. 다른 Python 판에서 설치가 막히면 아래 "자주 나는 오류"를 봅니다.
• 이 목록에는 직접 쓰는 패키지만 적었습니다. 그 패키지가 필요로 하는 다른 패키지(의존성)는 pip 가 알아서 함께 설치합니다.
• 내 PC 에 설치된 것을 목록으로 남기는 법(pip freeze)과 목록 파일의 꼴은 2장 "pip 와 패키지" 절에서 자세히 봅니다.

목록의 패키지가 쓰이는 곳은 아래와 같습니다.

VS Code 에서 가상환경 고르기

VS Code 가 .venv 의 파이썬을 쓰게 합니다. Ctrl+Shift+P 로 명령 창을 열고 Python: Select Interpreter 를 고른 뒤 .venv 가 들어간 항목을 고릅니다. 메뉴 이름은 VS Code 판에 따라 조금 다를 수 있습니다.

실습 코드를 실행하는 곳

실습 코드는 과목 폴더의 data 폴더(예: C:\chatbot-course\data)에서 실행한다고 보고 썼습니다. 파일 이름만 적어 읽기 때문입니다. 터미널에서 cd data 로 들어간 뒤 실행하거나, code/ch01/ 의 실습 파일을 data 폴더에서 실행합니다.

# cd = change directory(폴더 옮기기). 과목 폴더에 있다면 cd data 만 쳐도 된다
cd C:\chatbot-course\data
# 1장 실습 1의 코드를 실행한다
python ..\code\ch01\lab1.py

부록 1. uv 소개

지금까지는 파이썬에 들어 있는 venv 로 가상환경을 만들고 pip 로 패키지를 설치했습니다. 같은 일을 더 빠르게, 한 도구로 해 주는 것이 uv 입니다. 이 부록은 골라 쓰는 길입니다. 앞의 방법으로 이미 환경을 갖췄다면 건너뛰어도 실습에는 지장이 없습니다.

장보기에 빗대 보겠습니다. 앞에서 한 방법은 장바구니(venv)를 따로 챙기고, 장보기 목록(requirements.txt)을 들고 가게(PyPI)를 돌며 물건을 하나씩 담는(pip) 일입니다. uv 는 목록만 건네면 장바구니를 챙기는 일부터 물건을 담는 일까지 한꺼번에 해 주는 장보기 대행입니다. 한 번 산 물건은 집 창고(캐시, cache)에 쌓아 두었다가, 다음에 같은 물건이 필요하면 가게에 가지 않고 창고에서 꺼내 씁니다. 여기서 장바구니가 가상환경, 목록이 requirements.txt, 대행이 uv, 집 창고가 uv 의 내려받기 캐시입니다. 비유와 다른 점은, uv 는 물건을 사 오기 전에 목록의 물건끼리 서로 맞는지(판이 어긋나지 않는지)를 먼저 따져 본다는 것입니다.

왼쪽 파랑 상자가 앞에서 한 방법, 가운데 보라 상자가 명령 앞에 uv 만 붙이는 방법, 오른쪽 하늘 상자가 uv 의 프로젝트 기능으로 관리하는 방법입니다. 세 방법 모두 과목 폴더의 같은 requirements.txt 를 읽으므로 설치되는 패키지와 판은 같습니다.

uv 는 무엇인가

pip 와 uv 견주기

uv 를 쓰는 두 가지 방식

• uv pip 방식: 지금까지의 명령 앞에 uv 만 붙입니다. requirements.txt 를 그대로 쓰고 새로 익힐 것이 거의 없습니다. 이 과정에는 이 방식을 권합니다.
• uv 프로젝트 방식: uv init 으로 프로젝트 설명서 pyproject.toml 을 만들고, uv add 로 패키지를 더합니다. uv 는 설치한 모든 패키지의 정확한 판을 잠금 파일(lock file, 판을 잠가 두는 파일) uv.lock 에 적어 두고, 다른 PC 에서는 uv sync 한 번으로 똑같은 환경을 다시 만듭니다. 내 챗봇을 따로 저장소로 꾸려 배포할 때 알맞습니다.

주의할 점

• uv 가 만든 가상환경에는 pip 가 들어 있지 않습니다. 이 가상환경에서는 pip install 대신 uv pip install 을 씁니다. 교안을 만든 PC 에서 uv venv 로 만든 .venv\Scripts 를 보니 pip 파일이 하나도 없었습니다.
• 한 가상환경에 pip 와 uv 를 섞어 쓰지 않는 편이 안전합니다. 한 가지 방법을 정해 끝까지 씁니다.
• uv 는 파이썬과 따로 설치하는 프로그램입니다. 교실 PC 에 프로그램 설치가 막혀 있으면 앞의 venv 와 pip 방법을 씁니다.