이 주차를 시작하기 전에

이것은 읽는 자료가 아니라 막히는 자리를 미리 치우는 준비물 점검표다. Day 1 실습에서 처음 API를 부르는 순간 걸리는 것이 있는데, 그 대부분이 코드 바깥에 있다. 여기서 15분을 쓰면 첫날 저녁을 통째로 날리지 않는다.

1. 이 과정이 전제하는 것

이 12주 과정에는 프로그래밍 입문 주차가 없다. 그런데 첫날부터 아래를 쓴다.

숨기지 않고 적는다. 파이썬 기본 문법과 터미널을 한 번도 다뤄 본 적이 없다면 Day 1에서 막히는 곳은 LLM이 아니라 환경이다. 그 경우 아래 두 가지를 먼저 훑고 오면 이번 주를 따라올 수 있다. 둘 다 무료이고, 이번 주에 쓰는 만큼만 보면 반나절이면 된다.

• 파이썬 공식 튜토리얼 한국어판 3~5장(자료형·제어문·함수): https://docs.python.org/ko/3/tutorial/
• Pro Git 한국어판 1~2장(저장소 만들기·커밋): https://git-scm.com/book/ko/v2

클래스는 Day 3에서 처음 나오므로, 튜토리얼 9장은 Day 2 저녁에 보태도 늦지 않다.

2. 준비물

# 파이썬 3.10 이상인지 먼저 확인한다
python --version

# 가상환경을 만들고 활성화한다
python -m venv mfg-ai
source mfg-ai/bin/activate        # macOS·리눅스
mfg-ai\Scripts\Activate.ps1       # 윈도우 PowerShell

# 이번 주에 쓰는 패키지를 한 번에 설치한다
pip install openai python-dotenv tiktoken streamlit

tiktoken은 Day 3의 토큰 세기와 Day 5의 비용 계산에 쓰고, streamlit은 Day 4부터 쓴다. 지금 함께 깔아 두면 중간에 멈추지 않는다. 제출용 requirements.txt 에도 이 넷이 들어가야 한다.

3. OpenAI 계정은 키를 만드는 것만으로 부족하다

결제 수단을 등록하지 않은 새 계정은 첫 호출에서 반드시 실패한다. 키는 정상으로 발급되지만 잔액이 0이라 호출이 거절된다. 이것이 첫날 이탈이 가장 많이 나는 자리이므로 아래 순서를 끝까지 밟는다.

1. platform.openai.com에 가입하고 로그인한다
2. Billing에서 결제 수단을 등록하고 크레딧을 충전한다. 선불이다. 선불 충전에는 최소 금액이 정해져 있으니 결제 화면의 안내를 따른다
3. API keys에서 새 키를 만든다. 화면을 닫으면 다시 볼 수 없으니 그 자리에서 복사한다
4. 사용량 한도(Usage limits)를 낮게 걸어 둔다. 실수로 반복 호출해도 그 금액에서 멈춘다

실습 자체의 비용은 크지 않다. 이번 주 과제를 GPT-4o-mini로 전부 돌려도 몇백 원 수준이며, 그 값을 직접 계산하는 것이 Day 3의 주제다.

실패하면 어느 쪽인지부터 가른다

Day 3은 429를 "기다렸다 재시도"로 다룬다. 잔액이 없어서 난 429는 몇 번을 기다려도 풀리지 않는다. 둘을 가르는 것은 오류 본문의 code 값이다. 오류 메시지를 끝까지 읽는 습관이 여기서 시작된다.

4. 윈도우에서 걸리는 두 곳

가상환경이 활성화되지 않는다. PowerShell이 서명 없는 스크립트 실행을 막아 Activate.ps1을 거부한다. 지금 쓰는 사용자 계정에만 실행을 허용하면 된다.

Get-ExecutionPolicy -List
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

명령 프롬프트(cmd)를 쓴다면 mfg-ai\Scripts\activate.bat로 대신할 수 있다.

키를 넣었는데 읽지 못한다. PowerShell에서 echo "..." > .env로 파일을 만들면 UTF-16으로 기록된다. python-dotenv는 그 파일을 읽지 못해 키가 없는 것처럼 동작하고, 화면에는 401만 뜬다. .env는 명령으로 만들지 말고 편집기에서 만들어 UTF-8로 저장한다. VS Code 라면 오른쪽 아래 인코딩 표시를 눌러 Save with Encoding에서 UTF-8을 고른다.

OPENAI_API_KEY=sk-여기에-실제-키

만든 다음 .gitignore에 .env 한 줄을 넣는다. Day 3에서 다룰 키 유출은 이 한 줄로 막는다.

5. 회사 노트북에서 막힐 때

사내망이 외부 API를 막아 두는 곳이 많다. 코드가 아니라 망에서 막힌 것이라 증상이 다르다. 연결 자체가 되지 않거나(APIConnectionError) 오래 기다린 뒤 끊긴다.

• 브라우저로 platform.openai.com이 열리는지 먼저 본다. 열리지 않으면 방화벽이다
• 사내 프록시를 쓰는 환경이면 HTTPS_PROXY 환경변수를 설정해야 파이썬 요청이 나간다
• 회사 계정과 개인 계정을 섞지 않는다. 개인 카드로 결제한 키로 회사 문서를 보내면 비용과 자료 관리가 함께 꼬인다. 사내 도입 절차가 있으면 그것을 따른다
• 도면 치수·불량률·거래처명처럼 사외 반출이 제한된 정보는 실습에 넣지 않는다. 이번 주 과제는 공개된 일반 지식만으로 전부 통과한다

6. 결제 수단을 등록할 수 없다면

카드를 등록할 수 없거나 회사 규정상 외부 API를 쓸 수 없어도 이번 주를 끝낼 수 있다. 길이 셋 있고, 어느 쪽을 골라도 Day 1~5의 개념과 과제는 그대로 따라간다.

첫째, 이 사이트의 Prompt Lab 시뮬레이터. 키 없이 동작한다. 프롬프트를 바꾸면 응답이 어떻게 달라지는지 Day 2의 실습 목적 그대로 확인할 수 있고, 같은 입력에 같은 출력을 주므로 두 프롬프트를 견주는 실험에는 오히려 편하다.

둘째, 내 컴퓨터에서 돌리는 모델(Ollama). 모델을 내려받아 로컬에서 돌리므로 비용이 들지 않고 자료가 밖으로 나가지 않는다. OpenAI와 호환되는 주소를 열어 주므로 이번 주 코드에서 두 줄만 바꾸면 그대로 돈다.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",  # Ollama가 열어 두는 OpenAI 호환 주소
    api_key="ollama",                      # 아무 문자열이나 넣는다. 검사하지 않는다
)
# 이후 client.chat.completions.create(model="llama3.1", ...) 로 같은 코드를 쓴다
# model 에는 ollama pull로 내려받은 이름을 그대로 적는다

작은 모델은 답의 품질이 GPT-4o-mini보다 떨어지고 응답도 느리다. Day 3의 비용 계산은 토큰 수만 직접 세고 단가는 교재의 표를 쓰는 방식으로 대신한다.

셋째, 다른 공급자의 무료 한도. 무료 한도를 주는 공급자가 있으나 한도와 조건이 자주 바뀌므로 이 교재는 수치를 적지 않는다. 쓰기로 했다면 그 공급자의 요금 문서를 직접 확인하고, Day 1~5에 나오는 단가 표는 GPT-4o 계열 기준이라는 점을 기억한다.

준비가 끝났으면 Day 1을 시작한다. 여기서 막히면 다음 과제로 넘어가지 말고 이 문서의 해당 절로 돌아온다. 환경 문제를 안고 진도를 나가면 뒤로 갈수록 원인이 흐려진다.