3.1 Python SDK 설치 및 기본 예제

3.1 Python SDK 설치 및 기본 예제

이번 절에서는 OpenAI API를 연동하기 위한 가장 손쉬운 방법인 Python용 공식 SDK 설치와 함께, 이를 활용한 첫 API 호출 예제를 자세히 살펴보겠습니다. 먼저 Python 개발 환경에 필요한 필수 요소를 설치하고, OpenAI의 Chat Completions API를 호출하는 간단한 코드를 작성해 동작을 확인하는 것이 목표입니다.

3.1.1 OpenAI Python SDK 소개

OpenAI는 RESTful API를 제공하며 모든 주요 언어에서 HTTP 요청 방식으로 사용할 수 있지만, 가장 공식적으로 지원되고 문서화된 클라이언트 중 하나가 바로 Python SDK입니다.

OpenAI Python SDK는 다음과 같은 특징을 갖습니다:

• Pythonic한 문법으로 간편한 사용

• 비동기 호출 및 오류 처리 지원

• Playground 설정과 API 요청 간의 일관성 확보

SDK는 pip 명령어를 통해 설치할 수 있으며, PyPI의 공식 패키지 이름은 openai입니다.  

3.1.2 Python SDK 설치

먼저 시스템에 Python이 설치되어 있는지 확인합니다. 터미널(또는 명령 프롬프트)에서 다음 명령을 실행:

$ python --version

버전이 3.7 이상인지 확인합니다. 이후 venv로 프로젝트별 가상 환경을 만들면 의존성 관리가 쉬워집니다:

$ python -m venv openai-env  
$ source openai-env/bin/activate   # macOS/Linux  

또는

> openai-env\Scripts\activate.bat   # Windows

그리고 다음 명령어로 OpenAI SDK를 설치합니다:

$ pip install --upgrade openai

설치가 완료되면 다음 명령으로 버전 확인이 가능합니다:

$ pip show openai

버전 기록 예시:

Name: openai  
Version: 1.30.1  

Note: 2024년 기준, 1.x 버전의 SDK는 이전의 0.x와는 완전히 다른 구조로 재작성되었으므로, 기존 예제를 참조할 경우 버전에 유의해야 합니다.  

3.1.3 API Key 설정 및 보안 관리

OpenAI API를 호출하려면 인증용 API 키를 헤더에 포함해야 합니다. 이 키는 OpenAI 계정의 https://platform.openai.com/account/api-keys 에서 생성할 수 있습니다.

키는 단일 문자열이며, 환경변수로 설정하여 유지하는 것을 권장합니다. 다음과 같이 환경변수를 설정할 수 있습니다:

Linux/macOS:

$ export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

Windows:

> set OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

Python 코드에서는 환경변수에서 이를 읽어들이거나, 직접 문자열로 전달할 수 있습니다. 단, 소스코드 내에 키를 직접 적는 것은 피해야 하며 git 추적 제외가 필수입니다. (예: .env, .gitignore 사용)

또는 dotenv 라이브러리를 사용하여 .env 파일로 관리할 수도 있습니다:

📄 .env 예시:

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

Python 내에서 이를 불러오기 위해:

pip install python-dotenv

from dotenv import load_dotenv  
load_dotenv()  

 

3.1.4 첫 API 호출 예제 – Chat Completions

OpenAI Python SDK를 설치하고 API 키를 준비했으면, 이제 실제로 GPT 모델을 호출하는 예제를 만들어봅니다.

아래는 GPT-4 (또는 gpt-3.5-turbo)를 호출하여 간단한 대화를 시도하는 코드입니다.

📄 basic_chat.py

import os  
import openai  
from dotenv import load_dotenv  

# 환경변수 로드  
load_dotenv()  
api_key = os.getenv("OPENAI_API_KEY")

# 클라이언트 초기화  
client = openai.OpenAI(api_key=api_key)

# 모델 호출 – Chat Completions API 사용  
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "당신은 유용한 도우미입니다."},
        {"role": "user", "content": "파이썬이 무엇인지 설명해줘"}
    ],
    temperature=0.7
)

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

실행:

$ python basic_chat.py

출력 예시

파이썬은 간결하고 읽기 쉬운 문법을 가진 고수준 프로그래밍 언어입니다. 웹 개발, 데이터 과학, 인공지능 등 다양한 분야에서 사용됩니다.

 

주요 파라미터 해설

• model: 사용할 GPT 계열 모델 지정 (예: gpt-3.5-turbo, gpt-4 등)

• messages: 대화의 맥락을 정의, 시스템 역할(system), 사용자(user), 어시스턴트(assistant) 등의 순서 중요

• temperature: 생성 결과의 다양성 제어 (낮을수록 일관되고 높은 확률 응답, 높을수록 창의성 증가)

 

3.1.5 오류 처리 및 응답 구조 이해

SDK는 요청 중 네트워크 오류나 인증 실패, Rate Limit 초과 등의 예외를 발생시킬 수 있습니다. 기본적인 try-except 구조로 이를 처리할 수 있습니다.

예시:

import openai
from openai import OpenAIError

try:
    ...
    response = client.chat.completions.create(...)
    print(response.choices[0].message.content)
except OpenAIError as e:
    print(f"OpenAI 호출 중 오류 발생: {e}")

또한 응답 객체에는 다음과 같은 구조가 포함됩니다:

• choices: 생성된 응답 목록 (대부분 1개)

• message: 응답 내 대화 메시지 (role, content 포함)

• usage: 토큰 사용량 정보 (prompt_tokens, completion_tokens, total_tokens)

usage 정보는 비용 측정 및 프롬프트 최적화에 중요한 정보를 제공합니다:

print(response.usage)

출력 예시:

{
  "prompt_tokens": 22,
  "completion_tokens": 54,
  "total_tokens": 76
}