정리 & 자주 나는 오류 5가지
한 줄 요약
1장이 끝났습니다. 환경이 준비됐고, LLM의 빈틈 세 개를 눈으로 봤습니다. 이 절은 막혔을 때 돌아올 페이지입니다.
1. 1장에서 한 일
| 단계 | 명령/작업 | 몇 번 하나 |
|---|---|---|
| 미니콘다 설치 | 설치 파일 실행 | 한 번 |
| 가상환경 생성 | conda create -n agentic python=3.10 -y |
한 번 |
| VS Code 설치 | + Python 확장 | 한 번 |
| 폴더 열기 | agentic_ai 를 통째로 |
한 번 |
| 라이브러리 설치 | pip install -r requirements.txt |
한 번 |
| API 키 등록 | .env 에 GEMINI_API_KEY=... |
한 번 |
| 환경 활성화 | conda activate agentic |
터미널 열 때마다 |
앞으로 실습을 시작할 때의 세 줄입니다.
터미널에서 실행 — 어느 위치에서든 됩니다. 이 세 줄이 환경 활성화와 폴더 이동까지 해 줍니다.
conda activate agentic
cd ~/Documents/agentic_ai # macOS
cd %USERPROFILE%\Documents\agentic_ai # Windows
python code/ch01_hello.py
2. 자주 나는 오류 5가지
① ModuleNotFoundError: No module named 'google'
Traceback (most recent call last):
File "code/ch01_hello.py", line 17, in <module>
from common import get_genai_client, GEMINI_MODEL, DATA
...
ModuleNotFoundError: No module named 'google'
진짜 원인은 "설치 안 됨"이 아니라 "다른 방에서 실행함"입니다. 이 과정에서 가장 흔한 오류입니다.
터미널에서 실행 — 어느 위치에서든 됩니다.
(agentic)이 아닌 상태를 찾아내는 것이 목적이니까요.
# 1) 지금 어느 파이썬인지 확인
python -c "import sys; print(sys.executable)"
# 경로에 envs/agentic 이 없으면 ↓
conda activate agentic
(agentic) 을 확인했는데도 안 되면, 그때 비로소 설치를 의심합니다.
터미널에서 실행 — 프로젝트 폴더
agentic_ai에서,(agentic)표시를 확인한 뒤.
pip install -r requirements.txt
② 파일을 못 찾는다 — can't open file ... ch01_hello.py
실행 위치가 어긋난 것입니다.
터미널에서 실행 — 어느 위치에서든 됩니다. 이 블록이 바로 프로젝트 폴더로 가는 방법입니다.
# ✓ 프로젝트 루트에서
cd ~/Documents/agentic_ai # macOS
cd %USERPROFILE%\Documents\agentic_ai # Windows
python code/ch01_hello.py
지금 어디 있는지 모르겠으면:
터미널에서 실행 — 어느 위치에서든 됩니다. 지금 서 있는 곳을 알아내는 명령입니다.
pwd # macOS · Windows PowerShell 둘 다 됨
echo %cd% # Windows 명령 프롬프트
경로 끝이 agentic_ai 이어야 합니다.
cd만 단독으로 치지 마세요. 명령 프롬프트에서는 현재 경로가 찍히지만, PowerShell에서는 홈 폴더로 이동해 버립니다. 길을 잃었을 때 더 헤매게 됩니다.참고 —
cd code로 들어가서python ch01_hello.py를 해도 사실 동작합니다. 코드가 자기 위치를 기준으로 경로를 계산하기 때문입니다(07절 참조). 다만 이 교재의 모든 명령을 프로젝트 루트 기준으로 통일했으니 그 습관을 지키는 편이 헷갈리지 않습니다.
③ API 키 : 없음 또는 [설정 필요] Gemini API 키를 찾지 못했습니다
.env 파일 문제입니다. 앞의 것은 python code/common.py, 뒤의 것은 python code/ch01_hello.py 를 돌렸을 때 나오는 같은 원인의 메시지입니다. 네 가지를 순서대로 확인하세요.
- 위치 —
agentic_ai/.env여야 합니다.code/.env가 아닙니다. - 이름 — 정확히
.env. Windows 메모장으로 만들면.env.txt가 됩니다. VS Code로 만드세요. - 형식 —
GEMINI_API_KEY=AIzaSy...등호 양옆에 공백이 없어야 합니다. - 저장 —
Ctrl+S를 눌렀는지. VS Code 탭에 흰 점(●)이 있으면 저장 안 된 상태입니다.
확인 명령:
터미널에서 실행 — 프로젝트 폴더
agentic_ai에서,(agentic)표시를 확인한 뒤.
python code/common.py
API 키 : 찾음 이 나와야 합니다.
④ 429 RESOURCE_EXHAUSTED — 요청이 몰렸습니다
google.genai.errors.ClientError: 429 RESOURCE_EXHAUSTED
여러분 잘못이 아닙니다. 무료 API 키에는 분당 요청 한도가 있는데, 짧은 시간에 여러 번 연달아 실행하면 그 한도에 걸립니다.
- 1~2분 기다렸다가 다시 실행하세요.
- 특히 8장은 담당자 여러 명이 각자 도구를 쓰기 때문에 질문 하나에 LLM을 열 번 안팎 부릅니다. 한 번 실행한 뒤 1~2분 간격을 두고 다시 실행하세요. (계산은 2장 7절에서 다룹니다.)
⑤ 400 API key not valid
키 문자열 자체가 잘못됐습니다.
- 키를 복사할 때 앞뒤 공백이나 줄바꿈이 딸려 왔을 수 있습니다.
- 키 일부만 복사됐을 수 있습니다.
AIzaSy로 시작해 40자쯤 됩니다. - 키를 새로 발급받았다면
.env에도 새 키로 바꿔 넣었는지 확인하세요.
.env 를 지우고 다시 한 줄만 깔끔하게 적는 것이 가장 빠릅니다.
3. 이 장의 핵심 내용 — 말로 설명할 수 있어야 할 것들
각 장의 정리는 그대로 소리 내어 말할 수 있는 문장으로 씁니다. 아래를 남에게 설명할 수 있다면 이 장은 끝난 것입니다.
- 가상환경은 프로젝트마다 파이썬 방을 나누는 장치다. 라이브러리 버전 충돌을 막는다.
(agentic)표시는 "지금 그 방 안에 있다"는 신호다. 터미널을 새로 열면 사라진다.ModuleNotFoundError의 대부분은 설치 문제가 아니라 실행한 방이 다른 문제다.- API 키는 코드가 아니라
.env에 둔다. 유출·수정·공유 세 가지 이유 때문이다. - LLM 호출의 최소 단위는
generate_content(model, contents)이고, 답은.text로 꺼낸다. - LLM은 훈련 때 읽은 내용만 안다. 사내 데이터·최신 정보·사내 문서는 그 밖에 있다.
- 모르는 것을 모른다고 하지 않고 그럴듯하게 지어내는 것을 환각이라 한다. 반품 기간 답이 그 예다.
- 에이전트란 LLM에게 도구를 쥐여 주고 스스로 쓰게 만든 것이고, 도구는 그냥 파이썬 함수다.
4. 체크리스트
다음 장으로 넘어가기 전에 아래가 전부 되는지 확인하세요.
- [ ] 터미널에
(agentic)이 뜬다 - [ ]
python --version이3.10.x를 출력한다 - [ ]
python code/common.py가API 키 : 찾음을 보여 준다 - [ ]
python code/ch01_hello.py가 끝까지 돌아간다 - [ ]
code/안에common.py와ch01_hello.py두 개가 있다
5. 다음 장 예고
2장에서는 LLM을 제대로 다루는 법을 배웁니다. 아직 도구는 안 붙입니다.
- 시스템 지시 — 같은 질문에 상담원처럼 답하게, 혹은 무뚝뚝한 엔지니어처럼 답하게 만들기
- temperature — 매번 같은 답과 매번 다른 답 사이의 조절 손잡이
- 멀티턴 — LLM이 방금 한 말도 잊는다는 걸 확인하고, 대화를 손으로 쌓아 "기억하는 것처럼" 만들기
특히 마지막이 중요합니다. 2장에서 손으로 쌓는 그 일을, 7장에서 라이브러리에게 넘깁니다. 그 대비를 위해 일부러 한 번 손으로 해 봅니다.