0장. 실습 환경 구성

출처: 『RAG 마스터: 랭체인으로 완성하는 LLM 서비스』(브라이스 유·조경아·박수진·김재웅, 프리렉 2025) | 공식: https://www.langchain.com/

이 책은 구글 코랩 기반의 실습서다. 0장에서는 코랩 연결, 드라이브 마운트, 실습 코드 가져오기, OpenAI API 키 발급과 .env 설정, 필수 패키지 설치까지 한 번에 갖춘다. 환경이 제대로 잡혀야 이후 모든 장의 실습이 막힘 없이 진행된다.

실습 환경 — 책 공식 repo: langchain-kr/langchain-tutorial (0장 본문의 ZIP 다운로드·드라이브 업로드 절차 따라 준비). 이후 챕터마다 상응 폴더 노트북을 실행해 본다.

학습 목표

이 장을 끝내면 다음을 할 수 있다.

• 구글 코랩에서 드라이브를 마운트하고 실습 노트북을 실행한다.
• 깃허브 실습 코드를 드라이브에 업로드해 코랩에서 접근하는 절차를 수행한다.
• OpenAI API 키를 발급하고 월간 한도를 설정해 과금 위험을 차단한다.
• .env 파일과 python-dotenv를 사용해 API 키를 안전하게 관리한다.
• 이 책의 전 실습에 필요한 패키지를 설치하고 설치 결과를 검증한다.

전체 흐름도

구글 계정 하나로 코랩·드라이브·API 키를 연결해 실습 환경을 완성하는 흐름.

[ 구글 계정 준비 ]
       │
       ▼
[ 코랩 접속 & 드라이브 마운트 ]
       │  drive.mount('/content/drive')
       ▼
[ 실습 코드 ZIP → 드라이브 업로드 ]
       │  langchain-kr/langchain-tutorial
       ▼
[ OpenAI API 키 발급 & .env 작성 ]
       ├─ .env 위치: 드라이브(영구) 또는 /content(임시)
       └─ .gitignore에 .env 추가
       │
       ▼
[ 필수 패키지 설치 ]
       │  !pip install python-dotenv langchain langchain-openai ...
       ▼
[ 실습 준비 완료 ]

0. 사전 필수 용어

1. 구글 코랩 & 드라이브

코랩이란

구글 코랩(Google Colaboratory)은 별도 설치 없이 브라우저에서 Jupyter 노트북을 실행하는 클라우드 플랫폼이다. Python 환경과 CUDA GPU를 무료로 제공하므로, 이 책의 모든 실습 코드가 코랩 기반으로 작성되어 있다.

접속: https://colab.research.google.com

노트북 생성

1. 구글 계정으로 로그인.
2. 코랩 화면에서 [Google Drive] → 원하는 경로 → [새 노트] 클릭.
3. 생성된 노트 제목(UntitledO.ipynb)을 클릭해 이름 변경.
4. 코드 셀 작성 후 ▷ 버튼 또는 Shift + Enter로 실행.

구글 드라이브 마운트

코랩 세션에서 드라이브 파일에 접근하려면 먼저 마운트해야 한다.

from google.colab import drive
drive.mount('/content/drive')

실행 시 팝업이 열리면 [Google Drive에 연결] → 계정 선택 → [Select all] 체크 → [Continue] 클릭. 마운트가 완료되면 아래 메시지가 출력된다.

Mounted at /content/drive

이후 드라이브 파일을 다음 경로 형식으로 접근한다.

import pandas as pd
df = pd.read_csv("/content/drive/MyDrive/Colab Notebooks/데이터파일.csv")

주의 세션 휘발성 주의 — 코랩 세션을 종료하거나 런타임을 재시작하면 /content 아래 파일은 모두 초기화된다. .env 파일을 /content/.env에 두면 매번 재생성해야 한다. 영구 보관이 필요하면 /content/drive/MyDrive/에 저장하라.

2. 실습 코드 가져오기

깃허브에서 ZIP 다운로드

1. 브라우저에서 https://github.com/langchain-kr/langchain-tutorial 접속.
2. 초록색 [Code] 버튼 클릭 → [Download ZIP] 선택.
3. ZIP 파일이 로컬에 저장된다.

구글 드라이브에 업로드

1. https://drive.google.com 접속 (구글 계정 로그인 상태).
2. [My Drive] → 원하는 경로(예: Colab Notebooks/) 이동.
3. ZIP 파일을 드래그·드롭해 업로드.
4. 업로드된 ZIP에서 마우스 오른쪽 버튼 → [Open with] → [Google Colaboratory] 선택.

이 책에서는 /content/drive/MyDrive/langchain-tutorial/ 경로를 기준으로 실습한다. 각 장의 노트북은 Ch01, Ch02 등의 폴더 아래에 있다.

참고 — ZIP을 드라이브에 올린 뒤 압축 해제하지 않으면 각 .ipynb를 직접 열어야 한다. 드라이브 내에서 ZIP을 우클릭 → 압축 해제 기능은 지원되지 않으므로, 로컬에서 먼저 압축 해제 후 폴더째 업로드하는 것이 편하다.

3. API 키와 .env 설정

OpenAI API 키 발급

1. https://platform.openai.com/docs/overview 접속 → 회원 가입(Sign up) 또는 로그인.
2. 로그인 후 [Billing] → [Add payment details]에서 신용카드 등록.
3. [Billing] → [Add to credit balance]에서 크레딧 충전($5~$75).
4. [Limits] 메뉴에서 월간 사용 한도 설정 — 설정 필수. 한도에 도달하면 자동으로 API가 중지된다. 이메일 알림 임계점도 함께 설정하면 과금 초과 전 경고를 받을 수 있다.
5. [Dashboard] → [API keys] → [Create new secret key]로 키 생성.
6. 생성된 키를 즉시 복사. 창을 닫으면 다시 볼 수 없다. 분실 시 새 키를 발급받아 사용한다.

주의 키 보안 — API 키가 유출되면 제3자가 비용을 발생시킬 수 있다. 절대 코드에 직접 하드코딩하거나 깃허브에 올리지 않는다. .gitignore에 .env를 추가하는 것을 잊지 말 것.

API 키를 코드에 적용하는 4가지 방법

책에서는 4번 .env 방법을 기본으로 사용한다. 코랩에서는 터미널 환경 변수 설정(1번)이 어려우므로 2~4번을 사용한다.

① 터미널 환경 변수 설정 (코랩에서 비권장)

# Unix/Linux/macOS
export OPENAI_API_KEY="여러분의 API 키"

# Windows
set OPENAI_API_KEY="여러분의 API 키"

터미널 세션이 종료되면 사라진다. 영구 보관은 ~/.bashrc 또는 ~/.zshrc에 추가.

② 파이썬 코드 내 직접 입력 (비권장 — 키 노출 위험)

from langchain_openai import OpenAI
llm = OpenAI(api_key="여러분의 API 키")

③ 구글 코랩 보안 비밀 관리 기능

from google.colab import userdata
api_key = userdata.get('OPENAI_API_KEY')

코랩 왼쪽 메뉴의 열쇠 아이콘 → [새 보안 비밀 추가]에서 OPENAI_API_KEY 이름으로 등록 후 노트북 액세스 활성화.

④ .env 파일 + python-dotenv (권장)

.env 파일을 생성하고 API 키를 작성한다.

OPENAI_API_KEY=여러분의 API 키

코랩에서 .env 파일 경로는 /content/.env (세션 초기화 시 사라짐) 또는 드라이브의 /content/drive/MyDrive/.env (영구).

파이썬에서 로드하는 방법:

from dotenv import load_dotenv
import os
from langchain_openai import OpenAI

# .env 파일에서 환경 변수 로드
load_dotenv("/content/.env")

# 환경 변수에서 API 키 가져오기
api_key = os.getenv("OPENAI_API_KEY")

# 오픈AI 언어 모델 초기화
llm = OpenAI(api_key=api_key)

참고 — load_dotenv()를 인자 없이 호출하면 현재 디렉터리의 .env를 자동 탐색한다. OPENAI_API_KEY라는 이름을 그대로 쓰면 OpenAI() 초기화 시 자동 탐지되므로 api_key= 인자를 생략할 수도 있다. 환경 변수 이름이 다르거나 다중 환경에서 키를 관리할 경우에는 os.getenv()로 명시 지정해야 한다.

4. 패키지 설치

필수 패키지

코랩 세션마다 런타임 초기화 시 패키지가 사라진다. 노트북 첫 셀에서 반드시 재설치한다.

!pip install python-dotenv langchain langchain-openai

책 전반에 걸쳐 쓰이는 주요 패키지:

!pip install python-dotenv \
             langchain \
             langchain-openai \
             langchain-community \
             langchain-chroma \
             chromadb \
             openai

버전 충돌 팁

• 특정 버전을 고정하려면 langchain==0.3.* 처럼 명시.
• 코랩에서 pip install 후 런타임 재시작이 필요할 수 있다 ([런타임] → [런타임 재시작]).
• 설치 확인:

import langchain
print(langchain.__version__)  # 0.3.x 이상 권장

핵심 개념 정리

한 문장 요약 — 구글 코랩에서 드라이브를 마운트하고, .env로 API 키를 안전하게 관리하며, 필수 패키지를 설치하면 이 책의 모든 실습 준비가 완료된다.

실무 체크리스트

• [ ] 구글 계정 로그인, 코랩에서 드라이브 마운트 성공 (Mounted at /content/drive 확인)
• [ ] langchain-kr/langchain-tutorial ZIP 다운로드 및 드라이브 업로드 완료
• [ ] OpenAI API 키 발급, 월간 한도 설정, 이메일 알림 임계점 설정
• [ ] .env에 OPENAI_API_KEY=... 저장, .gitignore에 .env 추가
• [ ] load_dotenv() 후 os.getenv("OPENAI_API_KEY")가 None 아닌 값을 반환하는지 확인
• [ ] 코랩 세션 재시작 후 재설치 루틴(!pip install ...)이 첫 셀에 있는지 확인
• [ ] langchain.__version__이 0.3.x 이상인지 출력으로 검증

연습문제

1. 개념. 코랩 세션을 재시작했더니 import langchain이 ModuleNotFoundError를 냈다. 원인과 해결책을 말하라.
2. 코드. .env 파일 경로가 /content/drive/MyDrive/.env일 때 load_dotenv()를 올바르게 호출하는 코드를 작성하라.
3. 보안. OPENAI_API_KEY를 깃허브 퍼블릭 리포에 실수로 커밋했다. 지금 당장 취해야 할 두 가지 조치는?
4. 적용. 코랩 세션이 매번 초기화된다면, .env 파일을 어디에 저장하는 것이 가장 편리한가? 이유와 함께 설명하라.
5. 비교. 코랩 userdata 보안 비밀 방식과 .env 파일 방식의 차이를 보안·편의성 두 가지 관점에서 비교하라.

최신 동향 (2026-05 기준)

• LangChain 0.3.x 계열이 안정 버전이며 파트너 패키지(langchain-openai, langchain-chroma 등) 분리 구조가 유지되고 있다. (검증 2026-05-21)
• OpenAI 무료 크레딧 정책이 변경되어 신규 가입자에게 일부 무료 크레딧을 제공하지 않는 경우가 늘고 있다. 발급 전 최신 정책 확인 권장. (검증 2026-05-21)
• Google Colab은 A100·L4 GPU 등 고성능 가속기를 Pro 플랜에서 제공한다. 8장 파인튜닝 실습처럼 VRAM이 많이 필요한 작업은 RunPod 등 별도 GPU 서버를 고려한다. (검증 2026-05-21)

부록 A. 용어 사전

부록 B. 핵심 비교표

API 키 적용 4가지 방법 비교

코랩 .env 저장 위치 비교

부록 C. 추천 참고 자료

검증된 외부 자료 (Tier 1 공식, 생존 확인 2026-05-21)

부록 D. 연습문제 풀이

1. (세션 휘발성으로 인한 패키지 초기화) 코랩은 런타임을 재시작하면 /content 아래 모든 파일과 설치된 패키지가 초기화된다(세션 휘발성). 따라서 import langchain은 ModuleNotFoundError를 낸다. 해결책은 노트북 첫 번째 셀에 !pip install langchain langchain-openai ... 재설치 루틴을 두어 매 세션마다 자동 실행되도록 하는 것이다.

2. (드라이브 경로 지정 load_dotenv 호출) 경로를 인자로 명시해야 한다.

python from dotenv import load_dotenv load_dotenv("/content/drive/MyDrive/.env")

인자 없이 load_dotenv()를 호출하면 현재 디렉터리의 .env를 탐색하므로, 드라이브 경로에 있는 파일은 찾지 못한다.

1. (깃허브 공개 커밋 후 키 유출 대응 두 가지 조치) 첫째, platform.openai.com/api-keys에서 해당 키를 즉시 삭제(Revoke)해 더 이상 사용할 수 없게 한다. 둘째, 새 키를 발급하고 .gitignore에 .env를 추가한 뒤 .env에 새 키를 저장해 재커밋한다. 이미 커밋된 기록은 깃 히스토리에 남으므로 키 삭제가 선행 조치로 가장 중요하다.

2. (세션 초기화 대비 .env 저장 위치) 구글 드라이브(/content/drive/MyDrive/.env)에 저장하는 것이 가장 편리하다. 코랩 임시 영역(/content/.env)은 세션 재시작마다 사라지므로 매번 재생성해야 하지만, 드라이브에 저장하면 drive.mount('/content/drive') 후 동일 경로로 영구 접근이 가능하다.

3. (코랩 userdata vs .env 파일 비교) 보안 측면에서 코랩 userdata는 구글이 암호화해 관리하고 노트북 단위로 접근을 제한하므로 키가 파일로 노출되지 않는다. .env 파일은 드라이브나 로컬에 평문으로 저장되어 파일 접근 권한에 의존한다. 편의성 측면에서 userdata는 코랩 전용이라 로컬 개발 환경에서 재사용하기 어렵지만, .env + python-dotenv는 코랩·로컬·CI 어디서나 동일하게 사용할 수 있어 범용성이 높다. 책에서 .env 방식을 기본으로 채택한 이유도 이 범용성 때문이다.