d01 - 1. 개발환경 구축

S0 · 개발 환경 구축 & 점검

Agentic RAG 실전 (14시간) · Day 1

이 과정은 Windows 11 + VSCode + uv + Python 3.12 로컬 환경에서 진행한다. 이 노트북에서는 uv init 기반 프로젝트를 부트스트랩하고, 키(.env)를 설정한 뒤, 설치와 핵심 import를 검증한다.

• 버전 기준(2026-06): langgraph 1.2.x · langchain 1.3.x · langchain-pinecone 0.2.x · pinecone SDK 7.x
• LLM 기본값: gpt-4.1-mini (교체 가능) · 임베딩: multilingual-e5-large(1024차원, 한국어)

 

0. 사전 요구사항

• Python 3.12 (uv가 관리하므로 시스템 설치는 선택)
• uv — Rust 기반 파이썬 패키지/프로젝트 매니저. 미설치 시 PowerShell에서:

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• VSCode + 확장: Python, Jupyter

uv를 쓰는 이유: 의존성 해석·설치가 빠르고, pyproject.toml + uv.lock 으로 재현 가능한 환경을 보장한다.

 

1. 프로젝트 부트스트랩 (uv init)

아래는 PowerShell 터미널에서 실행한다(노트북 셀이 아니라 프로젝트를 만드는 단계).

# 1) 프로젝트 생성 — Python 3.12 고정
uv init agentic-rag --python 3.12
cd agentic-rag

# 2) 의존성 추가 (.venv 자동 생성 + uv.lock 기록)
#    ipykernel: VSCode에서 이 환경을 노트북 커널로 쓰기 위해 필요
#    ipywidgets: 일부 라이브러리의 tqdm 진행바 렌더링용(미설치 시 'IProgress not found' 경고)
uv add langgraph langchain langchain-openai langchain-pinecone pinecone `
       langchain-text-splitters python-dotenv ipykernel ipywidgets

 

uv init 은 pyproject.toml, .python-version, .gitignore 등을 생성하고, uv add 는 .venv 를 만들어 의존성을 설치한다.

 

VSCode 연결

1. code . 로 agentic-rag 폴더를 연다.
2. 이 노트북(또는 새 .ipynb)을 열고 우측 상단 Select Another Kernel → Python Environments → .venv 를 선택한다.
3. 이후 셀은 모두 이 프로젝트의 .venv 에서 실행된다.

참고로 자주 쓰는 uv 명령: uv add <pkg> / uv remove <pkg> / uv sync(lock 기준 재현) / uv run <cmd> / uv lock --upgrade.

 

2. API 키 설정 (.env)

이 과정은 두 키가 필요하다: OPENAI_API_KEY(LLM), PINECONE_API_KEY(벡터 DB).

프로젝트 루트에 .env 파일을 만들고 키를 넣는다.

OPENAI_API_KEY=sk-...
PINECONE_API_KEY=...

.env 는 절대 커밋하지 않는다. .gitignore 에 .env 가 포함됐는지 확인하고, 없으면 추가한다.

 

아래 셀은 .env 를 로드하고, 없으면 입력을 받는다.

 

import os
from getpass import getpass

# 프로젝트 루트의 .env 를 환경변수로 로드
try:
    from dotenv import load_dotenv
    load_dotenv()
except ImportError:
    pass

# .env 에 없으면 입력으로 폴백 (값은 화면에 노출되지 않음)
for name in ["OPENAI_API_KEY", "PINECONE_API_KEY"]:
    if not os.environ.get(name):
        os.environ[name] = getpass(f"{name}: ")

print("키 설정:", {k: bool(os.environ.get(k)) for k in ["OPENAI_API_KEY", "PINECONE_API_KEY"]})

키 설정: {'OPENAI_API_KEY': True, 'PINECONE_API_KEY': True}

 

3. 환경 검증

설치된 버전과 핵심 import 를 확인한다. 이 셀이 오류 없이 끝나면 다음 교시로 진행한다.

import importlib.metadata as meta

for pkg in ["langgraph", "langchain", "langchain-core",
            "langchain-openai", "langchain-pinecone", "pinecone"]:
    try:
        print(f"{pkg:<22} {meta.version(pkg)}")
    except meta.PackageNotFoundError:
        print(f"{pkg:<22} (미설치)")

print("-" * 40)

# 1.x에서 위치가 갈리는 핵심 심볼 확인 (예제 마이그레이션 시 자주 걸리는 지점)
from langgraph.graph import StateGraph, START, END, MessagesState
from langgraph.graph.message import add_messages
from langchain.agents import create_agent              # 고수준 에이전트 → langchain.agents
from langgraph.prebuilt import ToolNode, tools_condition  # 그래프 프리미티브 → langgraph.prebuilt (유지)
from langchain_pinecone import PineconeVectorStore, PineconeEmbeddings, PineconeRerank
from langchain_openai import ChatOpenAI
print("핵심 import OK")

langgraph              1.2.5
langchain              1.3.9
langchain-core         1.4.7
langchain-openai       1.3.2
langchain-pinecone     0.2.13
pinecone               7.3.0
----------------------------------------
핵심 import OK

 

참고 — 버전·위치 주의

• 인터넷 예제 다수가 구버전 langgraph.prebuilt.create_react_agent 를 쓴다. 1.x 표준은 langchain.agents.create_agent 이며, ToolNode·tools_condition 같은 그래프 프리미티브는 여전히 langgraph.prebuilt 에 있다.
• 패키지명은 pinecone 이다. 구 pinecone-client 는 폐기되었으므로 설치하지 않는다.

 

4. 재현성

uv.lock 이 정확한 버전을 고정한다. 다른 머신에서는 저장소를 받은 뒤 한 줄로 동일 환경을 복원한다.

uv sync      # uv.lock 기준으로 .venv 재현

 

pip 기반 워크플로와의 호환이 필요하면 uv pip freeze > requirements.txt 로 내보낼 수 있다.

 

 

정리

• uv init → uv add 로 Python 3.12 프로젝트를 구성하고, VSCode 커널을 .venv 로 연결했다.
• 키는 .env 로 관리하고, 설치·핵심 import 를 검증했다.
• 다음(S1): Agentic RAG의 개념과 전체 아키텍처를 정리한다.