폴더 구조와 실습 데이터, 그리고 라이브러리 설치
한 줄 요약
실습 폴더 안에 무엇이 들어 있는지 훑어보고, requirements.txt 에 적힌 라이브러리를 한 번에 설치합니다. 데이터는 지금 외울 필요 없습니다 — 각 장에서 필요한 것만 다시 안내합니다.
1. 폴더 구조와 경로 규칙
①~⑤가 하나의 흐름으로 이어져 있습니다 — VS Code를 agentic_ai 에서 열면 터미널도 거기서 열리고, 거기서 python code/ch01_hello.py 를 치면 common.py 가 .env 와 data/ 를 정확히 찾아냅니다.
1장에서 가장 많이 나는 오류 세 개가 전부 이 그림에서 나옵니다.
오류 메시지 어긋난 곳 No module named 'common'code/안에common.py가 없음 (④)API 키 : 없음.env를code/안에 만듦 (③)폴더 존재 : Falsecode/와data/가 나란히 있지 않음 (⑤)오류가 나면 이 그림으로 돌아와 어느 번호가 어긋났는지만 확인하면 됩니다. 10절에서 다시 씁니다.
경로 규칙 하나만 기억하세요. 모든 실습 코드는 code/common.py 를 통해 데이터 위치를 찾습니다. 그 코드는 이렇게 생겼습니다.
아래는 제공된 code/common.py 의 일부입니다 — 고치지 않아도 됩니다.
ROOT = pathlib.Path(__file__).resolve().parent.parent # code/ 의 한 단계 위
DATA = ROOT / "data"
__file__ 은 "지금 이 파일의 위치"입니다. 거기서 한 단계 위로 올라가 data 를 찾습니다. 그래서 폴더 이름을 바꾸든 다른 곳으로 옮기든 상관없이 동작합니다. 대신 code/ 와 data/ 가 나란히 있는 구조는 유지해야 합니다.
두 줄에 쓰인 파이썬 표현 세 개를 짚어 둡니다. 이 표현들은 3장
pd.read_csv(DATA / "orders.csv")에서 또 나옵니다.
.resolve()— 줄임말이나 상대 경로가 섞여 있어도 하나의 완전한 경로로 바꿔 줍니다..parent— 한 단계 위 폴더입니다..parent.parent면 두 단계 위죠.code/common.py의 한 단계 위는code/, 두 단계 위가agentic_ai/입니다.ROOT / "data"의/— 나눗셈이 아니라 경로를 이어 붙이는 표시입니다.ROOT폴더 안의data를 가리킵니다. 이 방식으로 경로를 다루는 파이썬 표준 도구를pathlib이라고 부릅니다 — 윈도우(\)와 macOS(/)의 차이를 알아서 처리해 줍니다.
2. 라이브러리 설치
터미널에서 (agentic) 표시와 현재 위치가 agentic_ai 인 것을 확인한 뒤:
터미널에서 실행 — 프로젝트 폴더
agentic_ai에서,(agentic)표시를 확인한 뒤.
pip install -r requirements.txt
몇 분 걸립니다. 마지막에 Successfully installed ... 가 길게 나오면 성공입니다.
무엇이 깔리나
지금 이해할 필요는 없습니다. 어느 장에서 왜 쓰는지만 훑어 두세요.
| 라이브러리 | 무엇에 쓰나 | 장 |
|---|---|---|
google-genai |
Gemini를 직접 호출하는 구글 공식 SDK | 1~4 |
langchain |
에이전트 루프를 대신 돌려 주는 프레임워크 | 5~8 |
langchain-google-genai |
LangChain과 Gemini를 연결 | 5~8 |
langgraph |
상태·기억을 다루는 그래프 라이브러리 | 7~8 |
faiss-cpu |
벡터 검색 (문서에서 비슷한 조각 찾기) | 6·8 |
pypdf |
PDF 읽기 | 6·8 |
ddgs |
DuckDuckGo 웹검색 (API 키 불필요) | 4·8 |
pandas |
CSV를 표로 다루기 | 3·5·8 |
python-dotenv |
.env 파일에서 API 키 읽기 |
전 장 |
표에 나온 말 두 개를 풀어 둡니다.
- SDK(Software Development Kit, 소프트웨어 개발 키트) — 어떤 서비스를 쉽게 사용할 수 있도록 그 회사가 미리 만들어 배포한 코드 묶음입니다.
pip install로 깔아import해서 쓰는 라이브러리라고 보면 됩니다. 우리는 구글이 만든google-genai를 씁니다. 3장에서 "어디까지가 내가 쓴 코드이고 어디부터가 SDK인가" 가 중요해지니, 이름만 기억해 두세요.- 프레임워크(framework) — 라이브러리보다 한 단계 더 나아가, 일이 굴러가는 뼈대까지 미리 짜 둔 것입니다. 우리가 부품만 끼워 넣으면 나머지 진행은 프레임워크가 맡습니다. 5장의
langchain이 그렇습니다 — 4장에서 손으로 짤 루프를 대신 돌려 줍니다.벡터 검색 · 임베딩 은 1절에서 본 그대로, "문장을 숫자로 바꿔 두고 뜻이 가까운 것을 찾는" 6장의 기술입니다.
langchain버전이 중요합니다. 이 과정은 langchain 1.0 이상을 씁니다. 0.x 버전에는 5장에서 쓸create_agent가 아예 없습니다.requirements.txt로 설치하면 알아서 맞는 버전이 깔리니, 개별pip install langchain은 하지 마세요.
설치 확인
터미널에서 실행 — 프로젝트 폴더
agentic_ai에서,(agentic)표시를 확인한 뒤.
pip list | findstr langchain
macOS는 findstr 대신 grep 입니다.
터미널에서 실행 — 프로젝트 폴더
agentic_ai에서,(agentic)표시를 확인한 뒤.
pip list | grep langchain
langchain 1.3.15
langchain-community 0.4.2
langchain-core 1.6.0
langchain-google-genai 4.3.4
langchain-text-splitters 1.1.2
앞자리가 1. 이면 맞습니다.
3. 승승장구몰 데이터 둘러보기
표 데이터 5종
| 파일 | 규모 | 주요 열 | 쓰는 장 |
|---|---|---|---|
orders.csv |
2,400행 | 주문번호, 주문일, 고객ID, 상품ID, 수량, 금액, 상태 | 3·5·8 |
customers.csv |
200행 | 고객ID, 이름, 나이, 도시, 등급 | 3 |
products.csv |
40행 | 상품ID, 상품명, 카테고리, 가격, 평점 | 4·5 |
inventory.csv |
40행 | 상품ID, 재고, 창고, 재주문 기준 | 5·8 |
reviews.csv |
650행 | 리뷰ID, 상품ID, 평점(1~5), 리뷰 내용 | 5·8 |
orders.csv 를 열어 보면 이렇게 생겼습니다.
order_id,order_date,customer_id,product_id,product_name,category,quantity,unit_price,amount,channel,status
O002282,2024-01-01,C0156,P0009,장구 무선 핸디 청소기,가전,1,109650,109650,웹,배송완료
O000533,2024-01-03,C0064,P0030,리빙 대용량 식기건조대,생활용품,1,35000,35000,앱,배송완료
알아 두면 좋은 값들입니다.
- 기간: 2024-01-01 ~ 2026-05-31 (약 2년 5개월)
- 카테고리: 가전 · 도서 · 뷰티 · 생활용품 · 스포츠레저 · 식품 · 전자기기 · 패션의류
- 주문 상태: 결제완료 · 배송중 · 배송완료 · 취소 · 환불
- 고객 등급: 일반 · 실버 · 골드 · VIP
5장에서 중요해지는 규칙 하나 — 매출을 집계할 때는 취소·환불 건을 빼야 합니다. 안 그러면 실제보다 많이 나옵니다. 이런 "데이터를 아는 사람만 아는 규칙"을 에이전트에게 어떻게 알려 주는지가 5장의 관전 포인트입니다.
문서 데이터 (data/docs/)
| 파일 | 내용 |
|---|---|
환불교환정책.pdf |
환불·교환·반품 규정 |
멤버십정책.pdf |
등급별 조건과 혜택 |
직원핸드북.pdf |
사내 업무 안내 |
제품매뉴얼_스마트워치.pdf |
스마트워치 Fit 5 사양·사용법 |
제품매뉴얼_로봇청소기.pdf |
로봇청소기 사양·사용법 |
이 PDF들은 6장 RAG(문서검색) 의 재료입니다. 앞 절에서 LLM이 반품 기간을 지어냈던 것을, 이 문서를 근거로 답하게 바꿉니다.
4. 이 과정의 주인공 — P0003
앞으로 계속 나올 상품 하나를 미리 소개합니다.
P0003 · 승승 스마트워치 Fit 5 · 159,000원
지금은 이 정도만 알아 두세요. 각 장에서 이 상품을 다른 각도로 만나게 됩니다.
| 장 | 이 상품에 대해 알게 되는 것 |
|---|---|
| 3장 | 주문 O001203이 이 상품이고, 배송완료 상태다 |
| 5장 | 재고가 3개뿐인데 재주문 기준은 30개다 |
| 5장 | 리뷰 평균이 3.8점으로 낮은 편이다 |
| 6장 | 매뉴얼상 배터리는 일반 7일 / GPS 사용 시 18시간이다 |
| 8장 | 위 셋을 합치면 무엇을 해야 하는지가 나온다 |
리뷰를 미리 한번 볼까요. 같은 상품에 이런 리뷰들이 섞여 있습니다.
5점 심박이랑 수면 측정이 꽤 정확해요. 포장이 꼼꼼해서 파손 없이 받았습니다.
3점 알림만 받으면 며칠 가는데 운동 기록하면 확 줄어요. 앱 연동은 살짝 아쉽습니다.
2점 GPS를 켜면 하루도 못 갑니다. 일주일 간다는 설명과 너무 달라요
마지막 리뷰를 기억해 두세요. 8장에서 이 한 줄이 최종 판단의 결정적 근거가 됩니다.
5. CSV 인코딩 주의
data/ 의 CSV들은 한글이 깨지지 않도록 BOM이 붙은 UTF-8 로 저장돼 있습니다. pandas로 읽을 때는 이렇게 씁니다.
아래는 개념 설명용 코드입니다 — 실습 파일에 넣지 않습니다.
pd.read_csv("data/orders.csv", encoding="utf-8-sig")
utf-8-sig 의 sig 가 그 BOM을 처리하라는 뜻입니다. 이걸 빼면 첫 번째 열 이름이 order_id 처럼 이상해집니다. 실습 코드에는 이미 다 들어 있으니 직접 신경 쓸 일은 없지만, 나중에 직접 파일을 읽을 때 기억해 두면 좋습니다.
핵심 정리
- 프로젝트 루트는
agentic_ai이고, 그 안에code/와data/가 나란히 있어야 합니다. - 라이브러리는
pip install -r requirements.txt한 번으로 전부 깝니다. langchain은 반드시 1.x. - 데이터는 표 5종 + PDF 5종. 지금 외울 필요 없이 각 장에서 필요한 것만 씁니다.
- 매출 집계에서는 취소·환불을 뺀다 — 5장에서 다시 나옵니다.
- 주인공은 P0003 승승 스마트워치 Fit 5 입니다. 8장까지 계속 따라옵니다.
- 다음 절에서 API 키를 넣으면 준비가 끝납니다.