OpenAI API 기초 학습 가이드

1. API 키 발급 및 설정

API 키 발급 받기

1. OpenAI 웹사이트에 접속하여 계정을 생성하거나 로그인합니다.
2. 대시보드에서 우측 상단의 프로필 아이콘을 클릭하고 "View API keys"를 선택합니다.
3. "Create new secret key" 버튼을 클릭하여 새로운 API 키를 생성합니다.
4. 생성된 API 키를 안전한 곳에 복사하여 저장합니다 (생성 후에는 다시 볼 수 없으니 주의하세요).

API 키 설정 방법

환경 변수로 설정하기

# Linux/macOS
export OPENAI_API_KEY="your-api-key-here"

# Windows (명령 프롬프트)
set OPENAI_API_KEY=your-api-key-here

# Windows (PowerShell)
$env:OPENAI_API_KEY="your-api-key-here"

코드 내에서 설정하기

import openai

# API 키 설정
openai.api_key = "your-api-key-here"

.env 파일 사용하기 (권장)

# .env 파일 생성
OPENAI_API_KEY=your-api-key-here

# Python에서 사용
from dotenv import load_dotenv
import os
import openai

load_dotenv()  # .env 파일 로드
openai.api_key = os.getenv("OPENAI_API_KEY")

2. API 호출 기본 구조

OpenAI 클라이언트 라이브러리 설치

pip install openai

기본 API 호출 구조 (Python)

import openai

# API 키 설정
client = openai.OpenAI(api_key="your-api-key-here")

# ChatGPT 모델에 텍스트 요청 예시
response = client.chat.completions.create(
    model="gpt-3.5-turbo",  # 또는 "gpt-4" 등 다른 모델
    messages=[
        {"role": "system", "content": "당신은 유용한 AI 어시스턴트입니다."},
        {"role": "user", "content": "안녕하세요, 오늘 날씨에 대해 알려주세요."}
    ],
    temperature=0.7,  # 창의성 조절 (0: 결정적, 1: 창의적)
    max_tokens=150  # 응답 길이 제한
)

# 응답 출력
print(response.choices[0].message.content)

주요 파라미터 설명

• model: 사용할 OpenAI 모델 (gpt-3.5-turbo, gpt-4 등)
• messages: 대화 메시지 배열
  • role: 메시지 역할 (system, user, assistant)
  • content: 메시지 내용
• temperature: 응답의 무작위성/창의성 조절 (0~1)
• max_tokens: 생성할 최대 토큰 수
• top_p: 토큰 선택의 다양성 조절 (nuclear sampling)
• frequency_penalty: 반복 억제 (-2.0~2.0)
• presence_penalty: 새로운 주제 등장 촉진 (-2.0~2.0)

3. 요청/응답 처리 방법

기본 요청 처리

import openai

client = openai.OpenAI(api_key="your-api-key-here")

def get_ai_response(prompt):
    try:
        response = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[
                {"role": "user", "content": prompt}
            ]
        )
        return response.choices[0].message.content
    except openai.OpenAIError as e:
        return f"API 호출 오류: {str(e)}"

# 사용 예시
user_input = "인공지능의 발전 방향에 대해 설명해주세요."
ai_response = get_ai_response(user_input)
print(ai_response)

다중 메시지를 포함한 대화 이력 관리

import openai

client = openai.OpenAI(api_key="your-api-key-here")

# 대화 이력 저장용 리스트
conversation_history = [
    {"role": "system", "content": "당신은 유용하고 친절한 AI 어시스턴트입니다."}
]

def chat_with_ai(user_message):
    # 사용자 메시지 추가
    conversation_history.append({"role": "user", "content": user_message})
    
    try:
        # API 호출
        response = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=conversation_history
        )
        
        # AI 응답 저장
        ai_reply = response.choices[0].message.content
        conversation_history.append({"role": "assistant", "content": ai_reply})
        
        return ai_reply
    
    except openai.OpenAIError as e:
        return f"API 호출 오류: {str(e)}"

# 대화 예시
print(chat_with_ai("안녕하세요!"))
print(chat_with_ai("Python으로 간단한 웹 서버를 만드는 방법을 알려주세요."))

스트리밍 응답 처리

import openai

client = openai.OpenAI(api_key="your-api-key-here")

def stream_ai_response(prompt):
    try:
        # 스트리밍 활성화
        stream = client.chat.completions.create(
            model="gpt-3.5-turbo",
            messages=[{"role": "user", "content": prompt}],
            stream=True  # 스트리밍 활성화
        )
        
        # 응답 내용을 점진적으로 처리
        for chunk in stream:
            if chunk.choices[0].delta.content:
                # 실시간으로 텍스트 조각 출력
                print(chunk.choices[0].delta.content, end="", flush=True)
        
        print()  # 줄바꿈
        
    except openai.OpenAIError as e:
        print(f"API 호출 오류: {str(e)}")

# 사용 예시
stream_ai_response("웹 개발의 미래 동향에 대해 설명해주세요.")

에러 처리 및 재시도 로직

import openai
import time
import random

client = openai.OpenAI(api_key="your-api-key-here")

def call_openai_with_retry(prompt, max_retries=3, base_delay=1):
    retries = 0
    while retries <= max_retries:
        try:
            response = client.chat.completions.create(
                model="gpt-3.5-turbo",
                messages=[{"role": "user", "content": prompt}]
            )
            return response.choices[0].message.content
        
        except openai.RateLimitError:
            # 레이트 리밋 오류 처리
            if retries == max_retries:
                return "API 요청 한도를 초과했습니다. 나중에 다시 시도해주세요."
            
            # 지수 백오프 및 지터 적용
            delay = base_delay * (2 ** retries) + random.uniform(0, 0.5)
            print(f"레이트 리밋 도달, {delay:.2f}초 후 재시도 ({retries+1}/{max_retries})...")
            time.sleep(delay)
        
        except openai.APIError as e:
            # 일반 API 오류 처리
            if retries == max_retries:
                return f"API 오류 발생: {str(e)}"
            
            delay = base_delay * (2 ** retries)
            print(f"API 오류, {delay:.2f}초 후 재시도 ({retries+1}/{max_retries})...")
            time.sleep(delay)
        
        except Exception as e:
            # 기타 예외 처리
            return f"오류 발생: {str(e)}"
        
        retries += 1

# 사용 예시
response = call_openai_with_retry("인공지능 윤리에 대해 설명해주세요.")
print(response)

4. 실제 응용 예제

간단한 AI 챗봇 구현

import openai
import tkinter as tk
from tkinter import scrolledtext

client = openai.OpenAI(api_key="your-api-key-here")

class SimpleChatbot:
    def __init__(self):
        self.window = tk.Tk()
        self.window.title("OpenAI 챗봇")
        self.window.geometry("600x600")
        
        # 채팅 히스토리 표시 영역
        self.chat_display = scrolledtext.ScrolledText(self.window, wrap=tk.WORD)
        self.chat_display.pack(fill=tk.BOTH, expand=True, padx=10, pady=10)
        
        # 사용자 입력 영역
        self.input_frame = tk.Frame(self.window)
        self.input_frame.pack(fill=tk.X, padx=10, pady=10)
        
        self.user_input = tk.Entry(self.input_frame)
        self.user_input.pack(side=tk.LEFT, fill=tk.X, expand=True)
        
        self.send_button = tk.Button(self.input_frame, text="전송", command=self.send_message)
        self.send_button.pack(side=tk.RIGHT, padx=5)
        
        # Enter 키 바인딩
        self.user_input.bind("<Return>", lambda event: self.send_message())
        
        # 대화 기록
        self.conversation = [
            {"role": "system", "content": "당신은 유용하고 친절한 AI 어시스턴트입니다."}
        ]
    
    def send_message(self):
        user_message = self.user_input.get()
        if not user_message:
            return
        
        # 사용자 메시지 표시
        self.chat_display.insert(tk.END, f"나: {user_message}\n\n", "user")
        self.chat_display.see(tk.END)
        
        # 입력창 비우기
        self.user_input.delete(0, tk.END)
        
        # AI 응답 가져오기
        self.get_ai_response(user_message)
    
    def get_ai_response(self, user_message):
        # 사용자 메시지 추가
        self.conversation.append({"role": "user", "content": user_message})
        
        try:
            # API 호출 (비동기로 구현하는 것이 더 좋음)
            response = client.chat.completions.create(
                model="gpt-3.5-turbo",
                messages=self.conversation
            )
            
            # AI 응답 저장 및 표시
            ai_reply = response.choices[0].message.content
            self.conversation.append({"role": "assistant", "content": ai_reply})
            
            self.chat_display.insert(tk.END, f"AI: {ai_reply}\n\n", "assistant")
            self.chat_display.see(tk.END)
            
        except Exception as e:
            self.chat_display.insert(tk.END, f"오류: {str(e)}\n\n", "error")
            self.chat_display.see(tk.END)
    
    def run(self):
        self.window.mainloop()

# 챗봇 실행
if __name__ == "__main__":
    bot = SimpleChatbot()
    bot.run()

API 사용량 및 비용 모니터링

import openai
import tiktoken

client = openai.OpenAI(api_key="your-api-key-here")

def estimate_token_count(text, model="gpt-3.5-turbo"):
    """주어진, 텍스트의 토큰 수를 추정합니다."""
    encoding = tiktoken.encoding_for_model(model)
    return len(encoding.encode(text))

def estimate_cost(prompt, response=None, model="gpt-3.5-turbo"):
    """API 요청에 대한 대략적인 비용을 계산합니다."""
    # 모델별 가격 (2023년 10월 기준, 변경될 수 있음)
    prices = {
        "gpt-3.5-turbo": {"input": 0.0015, "output": 0.002},  # 1K 토큰당 USD
        "gpt-4": {"input": 0.03, "output": 0.06},
        "gpt-4-32k": {"input": 0.06, "output": 0.12},
    }
    
    if model not in prices:
        return "지원되지 않는 모델입니다."
    
    # 입력 토큰 수 계산
    input_tokens = estimate_token_count(prompt, model)
    input_cost = (input_tokens / 1000) * prices[model]["input"]
    
    total_cost = input_cost
    output_tokens = 0
    
    # 응답이 있는 경우 출력 토큰 수도 계산
    if response:
        output_tokens = estimate_token_count(response, model)
        output_cost = (output_tokens / 1000) * prices[model]["output"]
        total_cost += output_cost
    
    return {
        "input_tokens": input_tokens,
        "output_tokens": output_tokens,
        "total_tokens": input_tokens + output_tokens,
        "cost_usd": total_cost,
        "model": model
    }

# 사용 예시
prompt = "인공지능에 관한 500단어 에세이를 작성해주세요."

# API 호출
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": prompt}]
)

ai_reply = response.choices[0].message.content

# 비용 계산
cost_info = estimate_cost(prompt, ai_reply)

print(f"AI 응답: {ai_reply[:100]}...")  # 응답 일부만 표시
print("\n비용 정보:")
print(f"입력 토큰: {cost_info['input_tokens']}")
print(f"출력 토큰: {cost_info['output_tokens']}")
print(f"총 토큰: {cost_info['total_tokens']}")
print(f"예상 비용: ${cost_info['cost_usd']:.6f} USD")

5. API 호출 시 주의사항

모범 사례

1. API 키 보안
   • API 키를 코드에 직접 포함하지 말고 환경 변수나 보안 저장소를 사용하세요.
   • 버전 관리 시스템(Git 등)에 API 키가 포함되지 않도록 주의하세요.
2. 요청 최적화
   • 불필요하게 큰 컨텍스트를 전송하지 마세요.
   • 요청 횟수를 최소화하고 가능한 경우 응답을 캐싱하세요.
3. 오류 처리
   • 레이트 리밋, 서버 오류 등에 대비한 재시도 로직을 구현하세요.
   • 지수 백오프 전략으로 재시도 간격을 점차 늘려가세요.
4. 비용 관리
   • 토큰 사용량을 모니터링하고 예산 한도를 설정하세요.
   • 개발 중에는 저렴한 모델(예: gpt-3.5-turbo)을 사용하고, 필요할 때만 고급 모델을 사용하세요.

일반적인 오류와 해결 방법

1. Rate limit exceeded (429 오류)
   • 원인: 짧은 시간 내에 너무 많은 요청을 보냄
   • 해결: 재시도 간격 늘리기, 요청 수 제한, 배치 처리
2. Context length exceeded
   • 원인: 토큰 제한보다 큰 컨텍스트
   • 해결: 메시지 요약/압축, 오래된 메시지 제거, 문서 분할
3. Invalid API key
   • 원인: 잘못된 API 키 사용
   • 해결: API 키 재확인, 새 키 발급
4. Content policy violation
   • 원인: 금지된 콘텐츠 요청
   • 해결: 정책 준수, 프롬프트 수정

6. 추가 학습 자료

1. OpenAI API 공식 문서
2. OpenAI Cookbook (예제 코드)
3. PyPI openai 패키지
4. OpenAI Community Forum