OpenAI API 입문 — 키 보관부터 스트리밍과 비용 관리까지 지금 동작하는 파이썬 코드로 실습하기

핵심 메시지

• OpenAI 가 2023년 11월 SDK 를 크게 다시 쓰면서, 그 이전에 작성된 튜토리얼과 AI 가 생성한 코드 조각 상당수가 첫 줄부터 오류를 낸다.
• API 키는 발급 직후 한 번만 볼 수 있고, 소스에 직접 적어 깃허브에 올리면 OpenAI 가 유출을 감지해 몇 분 안에 폐기한다. .env 와 .gitignore 조합이 기본이다.
• API 는 상태를 기억하지 않는다. 대화를 이어가려면 이전 기록 전체를 매번 다시 보내야 하고, 그만큼 비용이 누적된다.
• 50줄 남짓한 파이썬 코드로 거친 이메일 초안을 다듬어주는 앱을 만들 수 있으며, 핵심은 역할을 지정하는 시스템 프롬프트다.
• 초보자가 겪는 문제의 대부분은 옛 문법, 키 하드코딩, finish_reason 미확인 세 가지에서 나온다.

쉽게 이해하기

영상은 흔한 좌절 장면에서 시작한다. 검색으로 찾은 OpenAI API 튜토리얼의 코드를 복사해 실행했더니 모듈에 해당 속성이 없다는 오류가 나며 즉시 멈춘다. 원인은 실력이 아니라 시점이다. OpenAI 가 2023년 11월에 SDK 를 대대적으로 새로 쓰면서 그 이전 문법이 전부 무효가 됐고, 학습 데이터에 옛 코드가 잔뜩 남은 탓에 AI 가 만들어주는 예제도 같은 함정에 빠지기 쉽다.

첫 단계는 키 발급과 보관이다. 계정의 프로필 아이콘에서 API 키 메뉴로 들어가 새 시크릿 키를 만들되, 창을 닫는 순간 다시 볼 수 없으므로 그 자리에서 복사해 둔다. API 는 무료 구간이 없어 결제 수단 등록이 필요하지만 실습에 쓰는 GPT-4o mini 는 입력 기준 100만 토큰당 15센트 수준이라, 일반적인 대화 한 번에 드는 비용은 0.1센트에도 못 미친다. 키를 파이썬 파일이나 주피터 노트북에 직접 적는 것은 금물인데, OpenAI 가 깃허브를 상시 검사해 유출된 키를 자동 폐기하는 탓에 공개 저장소에 올린 개발자는 몇 분 만에 키를 잃기 때문이다. 확장자 없이 .env 파일을 만들어 키를 한 줄로 넣고 .env 를 .gitignore 에 추가한 뒤, 결제 설정에서 월 사용 한도를 5~10달러로 걸어두는 이중 안전장치까지 권한다.

코드는 단순하다. openai 와 python-dotenv 를 설치하고, load_dotenv 로 .env 를 읽어 환경 변수에 키를 올린 뒤 클라이언트를 만든다. 이때 키를 인자로 넘길 필요가 없는데, SDK 가 환경 변수를 알아서 읽기 때문이다. 모델과 메시지 목록을 넘겨 호출하면 응답 객체가 돌아오고, 딕셔너리가 아니라 점 표기법으로 접근한다. choices 는 목록이라 첫 항목을 꺼내 메시지 본문을 읽으면 되고, 사용량 정보와 실제로 답한 모델명, 그리고 응답이 끝난 이유를 알려주는 finish_reason 도 함께 확인할 수 있다.

가장 중요한 개념은 API 가 완전히 상태 없는 구조라는 점이다. 발표자는 이를 법정의 증인에 비유한다. 증인은 넘겨받은 자료만 알듯, 모델도 메시지 배열에 담아 보낸 내용만 안다. 역할은 시스템·사용자·어시스턴트 세 가지이고, 여러 차례 주고받는 대화를 만들려면 개발자가 직접 기록을 쌓아 매번 통째로 보내야 한다. ChatGPT 도 내부적으로는 같은 방식이며, 그래서 메시지가 50개까지 쌓인 대화는 한 번 호출할 때마다 갓 시작한 대화의 50배에 해당하는 비용이 든다.

실습 앱은 이메일 교정기다. "당신은 전문 이메일 편집자이며, 의도와 수신자를 유지한 채 간결하고 명확하게 다시 쓰고 설명 없이 결과만 반환하라"는 시스템 프롬프트를 앞에 두고 사용자의 거친 초안을 붙이면 끝이다. 여기에 스트리밍 옵션을 켜면 응답이 생성기로 바뀌어 조각 단위로 출력되는데, 이때 접근 경로가 message.content 가 아니라 delta.content 로 달라진다는 점을 놓치면 코드가 조용히 깨진다고 경고한다.

주요 인사이트

• 튜토리얼의 유효기간이라는 개념을 명시적으로 다룬 점이 유용하다. 라이브러리가 크게 갈아엎인 시점을 알고 있으면, 검색 결과나 AI 가 준 코드가 왜 안 되는지를 디버깅 없이 판별할 수 있다.
• 상태 없는 설계를 비용 구조와 연결해 설명한 부분이 핵심이다. 대화가 길어질수록 매번 전체 기록을 다시 보내므로 비용이 선형이 아니라 누적적으로 늘어난다.
• finish_reason 확인은 사소해 보이지만 품질 문제를 조용히 만든다. 값이 'length' 면 토큰 한도에 걸려 문장이 중간에 잘린 것이므로, 성공으로 처리하면 잘린 결과가 그대로 사용자에게 나간다.
• 모델 선택은 성능이 아니라 작업 난이도에 맞춰야 한다는 관점이 드러난다. 이메일 교정처럼 호출당 300토큰 남짓 쓰는 작업에는 17배 비싼 상위 모델을 쓸 이유가 없다는 것이다.
• 스트리밍 전환 시 응답 접근 경로가 바뀐다는 점은 오류 없이 빈 값이 나오는 형태로 나타나기 때문에, 기능을 켜기 전에 미리 알아두는 편이 낫다.

자주 묻는 질문

관련 AI 소식