가상환경 안 쓰고 그냥 pip install 했다가 패키지 충돌로 반나절 날린 적 있어요. 프로젝트마다 가상환경 만드는 거 귀찮은데, 한 번 꼬이면 더 귀찮아지더라고요. 처음부터 제대로 세팅하는 게 나중을 위해 좋아요.

오늘은 RAG 챗봇 개발을 위한 환경을 세팅할 거예요. Python 설치부터 시작해서 필요한 라이브러리까지 한 번에 설치해볼게요.

Python 설치

Windows

1. python.org에서 최신 버전 다운로드
2. 설치할 때 “Add Python to PATH” 반드시 체크!
3. 설치 완료 후 확인:

python --version

실행 결과:

Mac

Mac은 기본으로 Python이 깔려있는데, 버전이 낮을 수 있어요. Homebrew로 설치하는 게 편해요:

brew install python
python3 --version

가상환경 만들기

프로젝트별로 패키지를 분리하려면 가상환경을 써야 해요. 안 그러면 나중에 패키지 버전 충돌나서 골치 아파요.

프로젝트 폴더 만들기

mkdir rag-chatbot
cd rag-chatbot

가상환경 생성

python -m venv venv

가상환경 활성화

Windows:

venv\Scripts\activate

Mac/Linux:

source venv/bin/activate

활성화되면 프롬프트 앞에 (venv)가 붙어요:

실행 결과:

필수 라이브러리 설치

RAG 챗봇에 필요한 라이브러리들을 설치할게요.

requirements.txt 만들기

프로젝트 폴더에 requirements.txt 파일을 만들고 아래 내용을 넣어요:

langchain==0.1.0
langchain-openai==0.0.2
langchain-community==0.0.10
openai==1.6.1
chromadb==0.4.22
pypdf==3.17.4
python-dotenv==1.0.0
tiktoken==0.5.2
streamlit==1.29.0

한 번에 설치

pip install -r requirements.txt

설치하는 데 몇 분 걸려요. 커피 한 잔 하고 오세요.

실행 결과:

OpenAI API 키 발급

RAG에서 LLM을 쓰려면 API 키가 필요해요. OpenAI를 쓸 거예요.

API 키 발급 방법

1. platform.openai.com 접속
2. 로그인 (계정 없으면 가입)
3. 좌측 메뉴에서 “API keys” 클릭
4. “Create new secret key” 클릭
5. 키 이름 입력하고 생성
6. 키가 한 번만 보이니까 반드시 복사해서 저장!

환경 변수 설정

API 키를 코드에 직접 넣으면 깃허브에 올릴 때 노출될 수 있어요. .env 파일을 만들어서 관리해요.

프로젝트 폴더에 .env 파일 생성:

OPENAI_API_KEY=sk-your-api-key-here

중요: .gitignore에 .env 추가해서 깃에 올라가지 않게 해요!

# .gitignore
venv/
.env
__pycache__/

설치 확인

모든 게 잘 설치됐는지 확인해볼게요.

test_setup.py 파일 만들기

import os
from dotenv import load_dotenv

# 환경 변수 로드
load_dotenv()

# 패키지 임포트 테스트
print("1. 패키지 임포트 테스트...")
from langchain_openai import ChatOpenAI
from langchain_community.document_loaders import PyPDFLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
print("   ✓ 모든 패키지 임포트 성공!")

# API 키 확인
print("\n2. OpenAI API 키 확인...")
api_key = os.getenv("OPENAI_API_KEY")
if api_key and api_key.startswith("sk-"):
    print(f"   ✓ API 키 설정됨: {api_key[:10]}...")
else:
    print("   ✗ API 키가 설정되지 않았거나 형식이 잘못됨")

# 간단한 API 호출 테스트
print("\n3. OpenAI API 연결 테스트...")
try:
    llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
    response = llm.invoke("안녕하세요")
    print(f"   ✓ API 연결 성공!")
    print(f"   응답: {response.content[:50]}...")
except Exception as e:
    print(f"   ✗ API 연결 실패: {e}")

print("\n설정 완료!")

테스트 실행

python test_setup.py

실행 결과:

프로젝트 폴더 구조

지금까지 만든 파일들 정리하면 이래요:

rag-chatbot/
├── venv/                 # 가상환경 (git에 올리지 않음)
├── .env                  # API 키 (git에 올리지 않음)
├── .gitignore           # git 제외 파일 목록
├── requirements.txt     # 필요한 패키지 목록
└── test_setup.py        # 설치 확인 스크립트

자주 겪는 문제들

pip 명령어를 못 찾는 경우

Windows에서 pip가 안 되면 python -m pip로 해보세요:

python -m pip install -r requirements.txt

SSL 인증서 에러

회사 네트워크에서 자주 발생해요:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org -r requirements.txt

API 키 에러

.env 파일에 따옴표 넣지 마세요:

# 잘못된 예
OPENAI_API_KEY="sk-..."

# 올바른 예
OPENAI_API_KEY=sk-...

운영자 실전 노트

실제 프로젝트 진행하며 겪은 문제

• pip 충돌로 반나절 날림 → 처음부터 venv 사용. 귀찮아도 프로젝트마다 독립 환경 필수
• 회사 방화벽에서 SSL 인증서 에러 발생 → --trusted-host 옵션으로 해결
• .env 파일을 gitignore 안 하고 push → API 키 노출. 반드시 .gitignore 확인
• 다른 PC에서 작업할 때 패키지 버전 안 맞아서 에러 → requirements.txt로 버전 고정 관리

이 경험을 통해 알게 된 점

• venv 습관화가 가장 중요. 시스템 Python에 직접 설치하면 나중에 반드시 후회함
• .env 파일 관리는 보안의 기본 — API 키 노출되면 비용 폭탄 맞음
• requirements.txt는 버전까지 명시 (==1.0.0) — 버전 차이로 인한 오류 예방

마무리

환경 세팅이 귀찮다고 대충하면 나중에 더 큰 문제가 생긴다. 처음부터 제대로 해두면 개발하면서 삽질하는 시간이 줄어든다.

다음 편에서는 PDF 같은 문서 파일을 불러와서 텍스트를 추출하는 방법을 배운다.

---

RAG 챗봇 만들기 시리즈:

• 이전: RAG 챗봇 만들기 1 - RAG가 뭔데? 왜 필요한 거야?
• 다음: RAG 챗봇 만들기 3 - 문서 준비와 텍스트 추출

← 블로그 목록으로